Eve library

Adapter Signing & Distribution

Guide

Revision 1

On this page

Scope: how a third-party RemoteAdapter is 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 format packaging.ts (180.C.32.04) and reusing the organization-control deny-by-default semantics from libs/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:

  1. Is this package what it claims to be? Answered by the packaging format (180.C.32.04): verifyAdapterPackage checks a trusted signing key + an HMAC over the canonical manifest, the contract MAJOR, the per-file sha256 (tamper), and reconciles the manifest's declared namespaces/scopes/commands against the LIVE adapter (no undeclared command, no phantom namespace, no scope escalation).
  2. 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 recorded publishedTrustLevel is 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 recorded publisherId (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:

  1. the org's allowAdHocInstall is true (a locked-down org sets it false, and then there is NO ad-hoc path — only the signed registry installs); AND
  2. an operator supplies an explicit AdapterInstallOverride pinned 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 refusal refused-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. verifyAdapterForInstall REQUIRES 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, call verifyAdapterPackage directly.)

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:

  1. Package integrity (32.04) — signature, contract MAJOR, file hashes (always run), declared-vs-actual reconciliation.
  2. Contract compatibility — a MAJOR mismatch ⇒ refused-contract-incompatible.
  3. Scope policy (org-owned, not overridable) — a forbidden scope ⇒ refused-forbidden-scope; a non-allowlisted scope ⇒ refused-scope-not-allowlisted.
  4. Hard integrity — any 32.04 finding other than an untrusted publisher key ⇒ refused-package-integrity (safe-by-default allowlist).
  5. Signed path — a known publisher at/above the floor + a clean, trusted-key package ⇒ install-signed (no downgrade).
  6. 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-hoc AND 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 observedFiles is 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 the trusted floor);
  • an ambiguous signing key fails safe; the registry refuses a colliding key; and decideInstall re-binds an entry to its recorded publisher.