Scope: how a third-party
RemoteAdapteris signed, distributed, and admitted to a host — the signed-registry model, the ad-hoc distribution path and its trust implications, publisher trust levels, and the organization scope-policy controls. This is the trust layer on top of the Adapter SDK packaging format.Implemented in
libs/bellona/remote-adapters/src/distribution.ts(180.C.32.09), building on the signed packaging formatpackaging.ts(180.C.32.04) and reusing the organization-control deny-by-default semantics fromlibs/bellona/remote-protocol/src/organization-control.ts(180.C.27.06).
1. The two questions, and the two layers#
Before a host loads third-party code it must answer two questions:
- Is this package what it claims to be? Answered by the packaging format
(
180.C.32.04):verifyAdapterPackagechecks a trusted signing key + an HMAC over the canonical manifest, the contract MAJOR, the per-filesha256(tamper), and reconciles the manifest's declared namespaces/scopes/commands against the LIVE adapter (no undeclared command, no phantom namespace, no scope escalation). - Do we trust whoever produced it, and is what it asks for allowed here?
Answered by THIS module (
180.C.32.09): publisher identity + trust level, the org's scope policy, and the install path (signed vs ad-hoc).
verifyAdapterForInstall(input) is the single gate for question 2. It is
deny-by-default and returns a structured AdapterInstallDecision (never a
bare boolean): allowed, a verdict, a trustDowngrade flag, the
effectiveTrustLevel, the resolved publisherId, a human reason, loud
warnings, and the underlying 32.04 packageFindings for audit.
2. Publisher trust levels#
A publisher is a registered identity (AdapterPublisher): an id, a display name,
a trustLevel, and the signing key ids it is allowed to sign with. The levels,
most→least trusted (ADAPTER_PUBLISHER_TRUST_RANK):
| Level | Who | Rank |
|---|---|---|
first-party |
The platform's own adapters (Blender/Unreal/browser/file). | 3 |
trusted |
A vetted third-party publisher under a signed agreement. | 2 |
community |
A known publisher with a registered key but no vetting. | 1 |
untrusted |
A key on file that has been explicitly distrusted (revoked agreement, reported abuse) — present so a known-bad key is rejected with a specific reason rather than "unknown". | 0 |
A signing key id is a global identity: it belongs to exactly one publisher.
resolvePublisherForPackage attributes a package to a publisher only when
exactly one registered publisher claims the package's key — an unknown key OR
an ambiguous key claimed by two publishers both return undefined (treated as
unattributable → untrusted). This fails safe: attribution order can never silently
pick a more-trusted publisher and upgrade an install. AdapterSignedRegistry
additionally refuses to register a publisher whose key collides with an
existing publisher, so the ambiguity cannot arise through the registry at all.
3. The signed-registry model#
The signed path is the default, attested distribution channel.
- A publisher signs a package with a key the registry vouches for
(
buildAdapterPackage(input, signingKey)). - The registry stores it as an
AdapterRegistryEntry— the package bound to the publisher and the trust level recorded at publish time. The recordedpublishedTrustLevelis provenance only; the authoritative trust at install time is always re-derived from the live publisher record, so a publisher later distrusted is rejected even though the entry recorded a higher level. AdapterSignedRegistry.publish(...)is fail-loud: it refuses to publish under an unknown publisher, or a package whose signing key the named publisher did not register (the registry never lists an entry it cannot attribute).AdapterSignedRegistry.decideInstall(entry, ...)re-binds a stored entry to its recordedpublisherId(not the whole known set) before deciding, so a key later re-pointed to a more-trusted publisher cannot silently upgrade a stored entry's verdict.
A package from a publisher at or above the org's minimumTrustLevel whose
package verifies clean installs as install-signed — trustDowngrade: false,
no warnings.
4. The ad-hoc distribution path — and its trust implications#
An unsigned, self-signed, or untrusted/below-floor-publisher package (a developer's own build, a package off a mailing list) does not install on its own. It installs only when:
- the org's
allowAdHocInstallistrue(a locked-down org sets itfalse, and then there is NO ad-hoc path — only the signed registry installs); AND - an operator supplies an explicit
AdapterInstallOverridepinned to that exact package — adapter id + version + the manifest signature hex. An override for one build cannot silently authorize a differently-signed rebuild (refused-override-mismatch).
When both hold, the install proceeds as install-ad-hoc with
trustDowngrade: true and loud warnings that name precisely what was bypassed
(the unrecognized/missing signature, the operator who accepted it, their stated
reason and timestamp). The trust implication is surfaced, recorded, and never
silent. The decision also states that package integrity (file hashes, manifest
signature consistency, declared-scope reconciliation) WAS still verified — only
publisher trust was bypassed.
What the ad-hoc override can and cannot do#
The override is the ONLY way past a failed publisher-trust check. It cannot override:
- a forbidden scope — the org, not the operator, owns which scopes are
installable (§5). Hard refusal
refused-forbidden-scope. - a broken-integrity bundle — a tampered file, an altered manifest
(
signature-invalid= the HMAC did not match a key we DO hold), a mis-declared namespace/scope/command, a scope escalation, an adapter-id mismatch. Hard refusalrefused-package-integrity. - a contract-incompatible package. Hard refusal
refused-contract-incompatible.
An operator may accept "I do not recognize this publisher"; never "this bundle was
modified after signing" or "this org bans this scope". The integrity gate is
safe-by-default: the only finding an operator may accept is
signature-key-untrusted; every other 32.04 finding — present OR any future one —
is hard by default, because the tolerable set is an allowlist, not a denylist.
Tamper check always runs.
verifyAdapterForInstallREQUIRES the observed on-disk file bytes (observedFiles), so the 32.04 file-hash tamper check is never skipped for an install decision. A package with a valid manifest+signature but modified bytes is a tampered bundle and is refused on every path. (To verify a package descriptor without installed bytes, callverifyAdapterPackagedirectly.)
5. Organization scope-policy controls#
The org's AdapterRegistryPolicy is deny-by-default in the dimensions that
matter. The scope rules reuse the 180.C.27.06 organization-control semantics —
a forbidden-list (like 27.06's forbidden risk classes) and an allowlist with the
"empty = unrestricted" rule (27.06's allowlistPermits), specialized to adapter
permission scopes:
| Field | Meaning |
|---|---|
minimumTrustLevel |
The lowest publisher trust level that may install via the signed path (default trusted). Below it ⇒ only an ad-hoc override can still install. |
forbiddenScopes |
Permission scopes the org bans outright (e.g. code.execute.arbitrary). A package declaring ANY of these is refused — a HARD refusal an override cannot bypass. |
allowedScopes |
An optional scope ALLOWLIST. Empty ⇒ no restriction; non-empty ⇒ every declared scope must be a member. |
allowAdHocInstall |
Whether an operator override may install an unsigned/untrusted package AT ALL. false ⇒ no ad-hoc path. |
supportedContractMajor |
The host's supported contract MAJOR (defaults to the SDK's). A different MAJOR ⇒ refused-contract-incompatible. |
A scope refusal is checked before the trust branch, because the org — not an
operator — owns which scopes are installable here. So a package signed by a
first-party publisher that declares a forbidden scope is still refused.
6. The decision, end to end#
verifyAdapterForInstall runs a fixed, deny-by-default order:
- Package integrity (32.04) — signature, contract MAJOR, file hashes (always run), declared-vs-actual reconciliation.
- Contract compatibility — a MAJOR mismatch ⇒
refused-contract-incompatible. - Scope policy (org-owned, not overridable) — a forbidden scope ⇒
refused-forbidden-scope; a non-allowlisted scope ⇒refused-scope-not-allowlisted. - Hard integrity — any 32.04 finding other than an untrusted publisher key ⇒
refused-package-integrity(safe-by-default allowlist). - Signed path — a known publisher at/above the floor + a clean, trusted-key
package ⇒
install-signed(no downgrade). - Ad-hoc path — otherwise: ad-hoc disabled ⇒
refused-ad-hoc-disabled; no override ⇒refused-untrusted-publisher; non-matching override ⇒refused-override-mismatch; a matching override ⇒install-ad-hoc(trustDowngrade: true, loud warnings).
| Verdict | Installs? | Meaning |
|---|---|---|
install-signed |
yes | Trusted publisher, clean package, scopes permitted. |
install-ad-hoc |
yes (downgraded) | Installed only via an explicit operator override; publisher trust bypassed. |
refused-package-integrity |
no (hard) | Tampered / altered / mis-declared bundle. |
refused-forbidden-scope |
no (hard) | Org bans a declared scope. |
refused-scope-not-allowlisted |
no | A declared scope is outside the org allowlist. |
refused-contract-incompatible |
no | Contract MAJOR mismatch. |
refused-untrusted-publisher |
no | Below-floor / unknown publisher, ad-hoc enabled but no override. |
refused-ad-hoc-disabled |
no | Signed path failed and ad-hoc is disabled. |
refused-override-mismatch |
no | An override was supplied but does not match this package. |
7. Why HMAC (symmetric) today#
The packaging format signs with HMAC-SHA256 under a key the verifier holds —
the right scheme for a first-party-issued adapter registry where the registry both
issues the signing secret and verifies it. The format keeps algorithm explicit
(AdapterPackageSignature.algorithm) so an asymmetric scheme (publisher holds a
private key, the registry verifies a public key) can be layered later without a
manifest format change. The trust model above is independent of the signature
scheme: publisher trust levels, the org scope policy, and the signed/ad-hoc paths
all hold whether the underlying signature is symmetric or asymmetric.
8. Tests#
libs/bellona/remote-adapters/src/distribution.test.ts asserts the real
behaviour:
- a trusted-publisher signed package installs (
install-signed, no downgrade); - an unsigned/untrusted-publisher package is refused without an explicit override;
- an explicit, matching override installs it as
install-ad-hocAND flags the trust downgrade with loud warnings; - a forbidden scope is refused even when the package is signed by a trusted publisher, AND cannot be bypassed by an override;
- a non-allowlisted scope is refused; an empty allowlist imposes no restriction;
- a tampered bundle is a hard refusal (caught on every path, since
observedFilesis required); - an incompatible contract MAJOR is refused;
- the trust floor is a real threshold (a community publisher installs when the
floor is lowered to
community; is refused at thetrustedfloor); - an ambiguous signing key fails safe; the registry refuses a colliding key; and
decideInstallre-binds an entry to its recorded publisher.