Skarbiec and entitlements¶

Two boundaries own the secret material Brama uses and never stores: the Skarbiec capability broker, which redeems one capability at the final-use seam, and the entitlements router, which lists the shared subscription pool's resources and persists credentials into the vault. Brama owns neither; it owns the shape of the exchange.

Skarbiec capability broker¶

Outcome¶

Redeem one opaque capability for one expected purpose/resource tuple at the trusted final-use boundary.

Identity and data¶

Brama signs skarbiec.redeem.v1 with its owner-protected workload key. It reads one control line and exactly the secret length that line states, followed by EOF. Capability IDs are lowercase 64-character hexadecimal handles; local tuple validation prevents accidental use at another seam, while the broker remains authoritative.

Failure and removal¶

A missing socket, a missing registry, a missing proof key, invalid ownership or mode, a malformed response, or a tuple mismatch fails closed. The broker is the only place Brama obtains the secret: no environment variable and no remote vault is read in its place, and a refused acquisition is returned to the caller as a refusal.

Stopping the broker prevents credentialed inference. It must not prevent brama detect, brama version, or read-only MCP detection.

Entitlements router¶

Outcome¶

Discover the deployment's shared, non-deleted subscription pool and persist an OAuth refresh or authorized donation without placing plaintext in Brama state. Agent attribution records provenance; it does not restrict which caller may use a subscription.

Data and reliability¶

• live list output is validated as untrusted JSON;
• membership follows the recorded subscription metadata, not an agent-name prefix;
• successful live results are shared between concurrent readers; their reusable age comes from BRAMA_SUBSCRIPTION_LISTING_AGE_SECONDS. Without that declaration, each caller reads the vault unless it was already waiting for the same successful read;
• when the live list call fails, the trusted startup metadata snapshot is the only other source Brama reads, and it is read as metadata only: it authorizes nothing on its own;
• credential writes pass secret bytes through child stdin;
• donation metadata uses an owner-only atomic file replacement.

Vault executable selection checks ENTITLEMENTS_ROUTER_BIN, then SKARBIEC_BIN, then the existing executable-discovery locations. An explicitly empty or non-Unicode declaration is a configuration refusal naming the declaration and cause, not permission to choose a different executable. The refusal propagates through live pool discovery, authenticator inspection, route inspection and credential writes before launching a vault command. It does not become an empty pool or a successful write.

Qualify an actual invalid declaration through Brama's inventory API with cargo test --test credential-administration -- --ignored --exact inventory_refusal::invalid_vault_declaration_is_not_an_empty_subscription_pool. Supply TEST_SOURCE_REVISION, the actual isolated vault environment, EXPECTED_VAULT_DECLARATION and independently observed EXPECTED_VAULT_DECLARATION_CAUSE. The journey retains the refusal under target/real-tests/vault-declaration; it creates no substitute vault and submits no provider request. Use an isolated fixture: if the declared failure is absent, the normal inventory API will read the real configured vault.

Disable and removal¶

Stop new subscription selection, revoke router/vault access, preserve existing journal evidence, and remove only Brama-owned non-secret overlay state after its retention decision. Direct provider routes remain usable when configured; their contract is on Model providers.

What the caller sees¶

An alias whose route needs a credential Brama cannot obtain reports state capability_absent, and a completion naming that alias answers 503 alias_unserviceable carrying the state and the route in details. The alias still names exactly one destination route, so no other account or route is used in its place. brama aliases prints the alias, its state and its route; see CLI and Errors.

When the registry document on disk predates the current shape, bring it forward with brama routes migrate before reviewing alias state.