BETAv0.24.11
GitHub Install
Grants and the supply chain
Docs/Work safely/Grants and the supply chain

Grants and the supply chain

Edit on GitHub
docs-site/work-safely/supply-chain.md

Installing an extension means running someone else's code. This page says what Orrery checks, and what it does not.

Grants

An extension has no capability except through a token the policy engine issues for one specific call. Its manifest lists what it asks for ([requires]), and you decide at install:

 buildgraph 1.2.0 requests:
   read     $WORKSPACE/**
   spawn    java
  • Denying does not fail the install. The tools that need the denied capability are disabled and never offered to the model; the rest work. The ledger records degraded.
  • An upgrade shows a diff. A capability the old version did not ask for is marked new and defaults to deny.
  • Every call is checked and audited. File, process, network and credential access go through ctx, under your permission rules. orrery ledger --subject ext:<id> shows what an extension did and what was refused.

The runtime is the boundary

RuntimeWhat actually contains it
wasmA real sandbox. No file access except through the host, which the policy engine answers.
node · python · processCapabilities are withheld, not sandboxed. The extension runs as a child process with no handles, but a determined one can reach around the SDK: a native addon, a subprocess of its own.
nativeCompiled into the harness. No boundary.

If you are choosing a runtime because you do not trust the code, choose wasm.

Pinned and unpinned

SourceChecked
A bare name from a signed indexIndex signature, then the pinned sha256, then the manifest's requests against the index's copy. Nothing runs before the signature check.
npm:, crate:, github:, a git URL, a local path, --linkNo signature and no hash. Installed pinned: false, and the ledger says so.

The registry is how you trust an extension; the other sources are how you try one. A mismatch between what the index says an extension asks for and what its manifest asks for is a hard failure: it is a sign of tampering.

Not live yet: Orrery's public signed index, https://getorrery.dev/registry/index.toml, has no signing key and no entries yet. Until it does, every extension in the gallery is listed, not verified: no one has reviewed it. Read the code, and the grants it asks for, before you install.

What a pin does not cover

A verified pin does not cover an extension's transitive dependencies. The index pins the extension's own package by hash. The npm packages or crates it depends on are pinned only by its own lockfile, which is not part of the review. A malicious dependency deep in that tree is still a hole.

The wasm runtime closes it, because the dependency runs inside the same sandbox. node, python, process and native do not.

For an organisation

An administrator pins a version set with a signed index and turns everything else off, in the managed layer:

# managed.toml — not overridable by users
[registry]
index    = "https://registry.corp.internal/orrery/index.toml"   # or a path
key      = "<public key, hex>"
unpinned = "refuse"     # refuse | warn | allow
  • refuse: anything not in the index is refused at install and skipped at load, with the reason and the index in the ledger.
  • warn: installs, with a loud ledger entry.
  • allow: the default.

Make and sign the index with orrery registry init, add, sign and verify; all of them work offline. The signing key is a file and a secret.

Report a problem

When the gallery ships, every card links to an issue template in the index repository, kouji-dev/orrery-registry. A revoked version is removed from the index and listed as revoked; clients refuse to load it after their next index fetch.