# Adapter Signing & Distribution

> 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](./adapter-sdk.md)**
> 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.
