@spec sign_anchor(anchor_input(), key_handle(), anchor_opts()) ::
  {:ok, anchor_compact()} | {:error, anchor_sign_error()}

Signs a boundary anchor — a durable chain checkpoint a verifier checks via BoundedAuthorityProtocol.V1.verify_historical_anchor/3.

Returns {:ok, %{anchor: anchor_compact}}. The caller supplies the anchor's content (anchor_id, chain_id, sequence, chain_hash); BOTH key identifiers (public_key, key_id) are resolved from key_handle — never trusted from the caller — so the signed header's kid + key_fingerprint are consistent with the key sign/2 actually used.

Why both key identifiers come from the handle

BAP puts key_id in the anchor's SIGNED header (typ: ba+chain-anchor) and, at verify, binds it to the verifier's HistoricalPublicKey.key_id. Letting the caller supply key_id would let an anchor assert "kid K" while being signed by a different key. Deriving key_id from the same handle as public_key makes that inconsistency impossible by construction (the one thing NOT sign-enforced — that key_id names the key in any external registry — is verify-enforced by BAP).

Defense-in-depth — the atomic key_identity/1 snapshot

sign_anchor/3 resolves key_id AND public_key in a SINGLE key_identity/1 call, so a stateful handle cannot split them across a rotation race (the separate-callback design a cross-vendor review probe once exploited). The remaining surface — sign/2 signing with a key different from the snapshot's public_key — is caught by the verify_signature guard in the shared tail, so a post-snapshot rotation fails loudly as :signing_failed, never a silent false-success. The one thing still NOT sign-enforced — that key_id names the key in any external registry — is verify-enforced by BAP (verify_historical_anchor/3 binds key_id + public_key + key_fingerprint together via the verifier's HistoricalPublicKey).

Options

• :anchored_at — the anchor's timestamp (default: System.system_time(:second)). Pin this when the verifier's evaluation time is far from wall-clock so it falls inside the key's validity window.
• :bounds — resource ceilings forwarded unchanged to BAP's producer and bounds-aware compact assembler (default %{}).

Errors (closed-atom set — no key material or anchor content in errors)

• :invalid_anchor — a required content field is missing or malformed.
• :invalid_key_handle — the handle is malformed, lacks key_identity/1, or its public_key/1 / key_identity/1 rejected / returned an invalid value.
• :signing_failed — the sign/2 callback rejected, returned a non-64-byte signature, violated the {:ok, _} | {:error, _} contract, or the signature did not verify against the resolved public key.
• {:producer_error, :invalid} — BAP's producer or assembler rejected the anchor (the input violated a bound or field constraint).

@spec sign_grant(grant_input(), key_handle(), grant_opts()) ::
  {:ok, grant_compact()} | {:error, grant_sign_error()}

Signs a grant — the issuer's authority assertion. The issuer-role instantiation of the universal companion-signer tail (ADR-0006; this slice is recorded in ADR-0007). Returns %{grant: grant_compact}, verifiable via BoundedAuthorityProtocol.V1.verify_grant/3 and envelope-compatible with check_envelope/2 (it flows through the envelope when paired with a holder proof from sign_report/3).

C1 gate (ADR-0006 pre-commitment) — what it does and does NOT guarantee

sign_grant/3 resolves the handle's atomic signing identity {:issuer | :holder, key_id, public_key} from ONE signing_identity/1 call. If the resolved role is not :issuer (or the callback is absent), it returns {:error, :invalid_key_handle} BEFORE sign/2 is called — so a handle that declares :holder (or implements no signing_identity/1) cannot sign a grant through this API. That is the C1 pre-commitment realized structurally.

This is NOT cryptographic key-role separation. A handle that consistently mis-declares its role — whose signing_identity/1 returns {:issuer, holder_key_id, holder_public_key} while sign/2 holds the matching holder private key — signs a grant successfully, because every value is internally consistent. The adapter resolves only the handle's public_key and signs against it; it cannot prove key identity. Key-role separation (an issuer key and a holder key are cryptographically distinct custodied entities) is the key-custody boundary's job — the runtime / HSM / key server behind the handle (charter §4).

Key-identifier sourcing (ADR-0006 decision 3)

The grant's signed-header kid (key_id) comes from the atomic signing_identity/1 snapshot, NEVER from caller input — a caller-supplied :key_id in the grant map is ignored. holder_thumbprint IS caller-supplied (the grant's subject — the holder the capability is issued to; the issuer knows it at minting).

Options

• :bounds — resource ceilings forwarded unchanged to BAP's producer and bounds-aware compact assembler (default %{}).

Errors (closed-atom set — no key material or grant content in errors)

• :invalid_grant — a required grant field is missing or malformed.
• :invalid_key_handle — the handle is malformed, lacks signing_identity/1, the resolved role is not :issuer, or the snapshot returned an invalid value.
• :signing_failed — sign/2 rejected, returned a non-64-byte signature, violated the {:ok, _} | {:error, _} contract, or the signature did not verify against the snapshot's public_key.
• {:producer_error, :invalid} — BAP's producer or assembler rejected the grant.

@spec sign_key_transition(transition_input(), key_handle(), transition_opts()) ::
  {:ok, transition_compact()} | {:error, transition_sign_error()}

Signs a key transition — the current (retiring) key's assertion of its successor. The 4th instantiation of the universal companion-signer tail (ADR-0006; recorded in ADR-0009), mirroring sign_anchor/3: role-agnostic, the current key's identity resolved atomically via key_identity/1. Returns %{key_transition: compact}, verifiable via BoundedAuthorityProtocol.V1.verify_key_transition/4.

Role posture (why this mirrors sign_anchor/3, not sign_grant/3)

A key transition is a historical-key operation (an artifact of the key chain), verified via HistoricalPublicKey — the same role-neutral input verify_historical_anchor/3 takes. The transition's authenticity is guaranteed by the signature against current_key.public_key, not by a role binding; "the right key" is the current key (charter §5). The adapter signs for whichever party holds it, per ADR-0006's universal posture. The deployment reality (the retired key is an issuer key) is a custody property, not something a signing-side role gate adds to — the verifier-side HistoricalPublicKey check is the authority binding. See ADR-0009 §Decision.

Key-identifier sourcing (ADR-0006 decision 3)

current_{key_id, public_key} come from ONE atomic key_identity/1 snapshot (the signing key IS the retiring current key; same as sign_anchor/3's kid+pub). A caller-supplied :current_key_id / :current_public_key is ignored. next_{key_id, public_key} are caller-supplied (the successor).

Options

• :bounds — resource ceilings forwarded unchanged to BAP's producer and bounds-aware compact assembler (default %{}).

Errors (closed-atom set — no key material or transition content in errors)

• :invalid_transition — a required content field is missing, or next_public_key is not a 32-byte Ed25519 key.
• :invalid_key_handle — the handle is malformed, lacks key_identity/1, or its key_identity/1 rejected / returned an invalid value.
• :signing_failed — sign/2 rejected, returned a non-64-byte signature, violated the {:ok, _} | {:error, _} contract, or the signature did not verify against the snapshot's public_key.
• {:producer_error, :invalid} — BAP's producer or assembler rejected the transition (e.g. a self-transition where next_public_key == current_public_key, which BAP's distinct_fingerprints check rejects).

@spec sign_report(report(), key_handle(), opts()) ::
  {:ok, envelope()} | {:error, sign_error()}

Binds an issuer-signed grant to a CDC report by producing a holder proof.

Returns {:ok, %{grant: grant_compact, proof: proof_compact}} — the grant is the pass-through of report.grant_compact (issuer-signed, untouched); the proof is the holder's binding of that grant to the report, signed via the holder key behind key_handle.

The flow (design §2 Q5)

1. Resolve the holder public key from key_handle (callback).
2. Build the Proof struct: holder key + the report's request fields + grant_compact (BAP's proof_signing_input derives ath = grant hash from it, and ba_req = request digest from cast_arguments).
3. Produce the deterministic proof signing input via BAP.
4. Sign + assemble via the shared signing tail (sign_and_assemble/4) — the adapter signs ONLY the proof; the grant is never signed here.
5. Return %{grant: report.grant_compact, proof: proof_compact}.

Options

• :bounds — resource ceilings forwarded unchanged to BAP's producer and bounds-aware compact assembler (default %{}, BAP's maxima).
• :issued_at — the proof's iat (default: System.system_time(:second)). Pin this when the verifier's evaluation_time is far from wall-clock (e.g. tests) so the proof's time window overlaps the grant's.
• :proof_id — the proof's jti (default: a generated UUID v4).

Errors (closed-atom set — no key material or report content in errors)

• :invalid_report — a required report field is missing.
• :invalid_key_handle — the handle is malformed, or the handle's public_key/1 rejected / returned a non-32-byte key.
• :signing_failed — the holder's sign/2 callback rejected, returned a non-64-byte signature, violated the {:ok, _} | {:error, _} contract, or the signature did not verify against the resolved holder public key.
• {:producer_error, :invalid} — BAP's producer or assembler rejected the proof (the input violated a bound or field constraint).