Skip to content

feat!: authorise provision and wake by the document's proof on every transport - #32

Merged
stormer78 merged 7 commits into
mainfrom
fix/didcomm-signed-controller-ops
Sep 26, 2026
Merged

stormer78 merged 7 commits into
mainfrom
fix/didcomm-signed-controller-ops

Conversation

@stormer78

@stormer78 stormer78 commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

What changes

push/provision and push/wake are Trust Tasks, and they are now authorised by the document's own proof on every transport the gateway serves (DIDComm and HTTPS), with one set of rules. Each transport adapter only unpacks and hands the document to one intake (src/intake.rs). No transport's claim about its sender authorises anything.

This matches what the VTA now sends (VTI #1740; delivered by the durable push engine, VTI #1767): the VTA signs push/provision / push/wake as its own operational documents. They carry an authentication proof, issuer = the VTA, recipient = the gateway, issuedAt and a unique id. The push engine reaches the gateway over whichever transport the gateway's DID advertises (TSP > DIDComm > TrustTaskHTTPS), so the gateway has to authorise the same way on each.

The proof (src/proof.rs)

The caller is the document's issuer, and only when:

  1. the proof is eddsa-jcs-2022 and its proofPurpose, parsed as a trust-tasks-proof ProofPurpose, is authentication. assertionMethod or any other purpose is refused (VTI-KEY-106);
  2. the DID of proof.verificationMethod == issuer, by exact match;
  3. the issuer's DID document lists that method, its controller == issuer, it is referenced or embedded under authentication, and it is neither revoked nor past expires. A resolved document over 64 KiB is refused;
  4. the signature verifies over the raw document with proof removed.

Steps 3–4 run through trust-tasks-proof 0.23's proof-purpose API. The gateway's IssuerKeys implements ProofPurposeResolver, and verification goes through PurposeBound::new(&keys, ProofPurpose::Authentication). A key is therefore released only for the relationship the proof declares. The hand-rolled PinnedKey resolver is gone.

One delivery, once (src/intake.rs, src/replay.rs)

An authentication proof has no challenge, so the document itself binds it to one delivery (VTI-KEY-107):

  • recipient is required and must be this gateway's DID. Otherwise the answer is wrongRecipient, or malformedRequest if recipient is missing.
  • issuedAt is required and may be at most 5 min old and at most 60 s in the future (VTI-OPS-024). Otherwise the answer is expired or malformedRequest.
  • expiresAt must not have passed.
  • Replay protection (VTI-OPS-026):
    • Keyed on (proven issuer, document id). The issuer is the one the proof established, never a transport claim.
    • Bounded: 8192 records per issuer, 512 per handle, and a 65536 soft bound shared fairly with a hard cap at twice that.
    • Fail-closed: at any bound, or if the guard errors, the record refuses the document. It never evicts.
    • Claimed only after rate limiting and authorisation, so a refused caller leaves nothing.
    • Shared by the transports: a document accepted over DIDComm is a replay over HTTPS.
    • A duplicate gets the first response back and nothing is re-executed. A different document under a used id gets idConflict. A transient push failure releases the claim.

Controllers served (GATEWAY_ALLOWED_CONTROLLERS)

Only listed controller VTA DIDs are served (exact match, no patterns):

  • A registration naming any other controller is refused.
  • A provision by a controller that has since been delisted is refused.
  • Unset or empty means nothing is served.
  • * is an explicit open mode.

push/provision also requires the proven issuer to be the handle's controllerVtaDid. push/wake requires it to be on the handle's allowlist.

Transports

  • DIDComm: served when GATEWAY_IDENTITY_FILE is set. The adapter passes the envelope from to the intake only as a claim. If it is present and differs from the proven issuer, the answer is identityMismatch.
  • HTTPS (POST /trust-tasks): now authorised by the document proof exactly as on DIDComm. This matches how the VTA push engine's REST transport posts, which is the bare signed document. The old X-TT-Did / X-TT-Signature body-signature scheme (src/auth.rs) is removed, not kept alongside: it was did:key-only and had no recipient binding, freshness or replay protection.
  • TSP: not served yet. Adding it means one more adapter, a TSP listener under the gateway's identity advertised as TSPTransport in its DID document, that hands unpacked documents to intake::receive. Authorisation would not change.
  • A gateway without an identity has no DID for a document to name as recipient, so it accepts no signed document on any transport and serves push/register only. Startup warns about this.

Dependencies

  • trust-tasks-rs 0.23.2 (was 0.21/0.22)
  • trust-tasks-proof 0.23.2 (new), for ProofPurpose / ProofPurposeResolver / PurposeBound
  • affinidi-tdk 0.18, affinidi-messaging-didcomm-service 0.13, which bring in affinidi-messaging-sdk 0.28.1
  • affinidi-secrets-resolver 0.5.12
  • ed25519-dalek is now a dev-dependency only
  • vta-sdk is not a dependency of the gateway

Deploy

  1. Set GATEWAY_ALLOWED_CONTROLLERS to the DID(s) of the VTA(s) this gateway serves. Without it every registration is refused.
  2. Set GATEWAY_IDENTITY_FILE. Without a DID the gateway accepts no provision or wake on any transport.
  3. Recreate test deployments from scratch. There is no migration.

The test-wake* helpers now sign their documents with an authentication proof, addressed to the gateway DID taken from the register response. They need a gateway with an identity, running in open mode.

Breaking changes

  • Unsigned provision/wake is refused (proofRequired) on every transport.
  • An assertionMethod proof is refused (proofInvalid).
  • HTTPS header signatures are ignored.
  • A gateway without an identity serves register only.

The VTA side is already in place: VTI #1740 signs these documents, and VTI #1767 delivers them through the push engine.

Tests

cargo test --workspace: 133 passed (77 unit, 25 tests/api.rs, 31 tests/document_auth.rs). cargo clippy --workspace --all-targets -- -D warnings, cargo fmt --check and cargo deny check are clean.

  • tests/document_auth.rs (was didcomm_auth.rs) drives the transport-neutral intake. New every_transport_* tests run the same documents through the DIDComm handoff and through the real HTTPS router:
    • signed by a listed controller: provision and wake accepted and delivered;
    • wrong issuer, either a signed non-controller (permissionDenied) or a controller's DID signed by another key (proofInvalid): refused;
    • unsigned: proofRequired;
    • stale issuedAt: expired;
    • signed for assertionMethod: proofInvalid;
    • replayed: first answer returned, nothing sent again;
    • none of the refusals touch the allowlist.
  • Also new:
    • a replay across transports is still a replay;
    • a gateway without a DID accepts no signed document.
  • The earlier suite still passes: envelope-only sender, tampering, identityMismatch, wrongRecipient, missing recipient, the time window, idConflict, the refuse-not-evict and fair-share budgets, and allowlist admission.
  • tests/api.rs now signs provisions and wakes with document proofs. New tests:
    • tampered_signed_document_is_refused;
    • header_identity_authorises_nothing: a retired X-TT-* header is ignored and the answer is proofRequired.
  • Unit tests:
    • src/proof.rs: VM controller, authentication membership (an assertionMethod-only key is refused), revoked/expired, oversized document, unlisted VM;
    • src/intake.rs: retention outlives acceptance, expired document, missing issuedAt;
    • src/replay.rs: keying and budgets.

Scope notes

  • The replay record is in memory and per process. Per VTI-OPS-027 it would need to be shared across replicas; the gateway runs as one process. A restart forgets it, which the acceptance window makes safe.
  • The 64 KiB DID-document cap applies after resolution. The resolver's own network timeout bounds the download.

Pre-merge checklist

- [x] No new reqwest::Client::new() / bare fetch(); all clients have finite timeouts (R1.2) — proof resolver uses the tuned resolver timeout (test-wake helper is a dev CLI)
- [x] No lock held across a network await (R1.3)
- [x] No local state committed before its remote effect, or the flow is resumable with an idempotency key (R2.1) — replay claim released on a transient failure
- [x] Every retry is bounded + backed off; non-idempotent ops are not blind-retried (R1.4) — n/a
- [x] Accept/poll/listen loops survive transient errors (R1.5) — a failed resolve refuses the one document
- [x] Acks/deletes happen only after durable handoff (R1.6) — n/a
- [x] New/changed wire types: camelCase, deny_unknown_fields where security-relevant, schema registered, all consumers (incl. JS) updated (R3.*) — no new wire types; VTA already signs (VTI #1740)
- [x] Config absence = most restrictive; fail-closed if enforcement can't start (R5.*) — no controllers listed = none served; no identity = no signed documents; resolver build failure stops startup
- [x] Logs/status claim only what was verified; background-job failures are surfaced (R6.*)
- [x] "Process dies on the next line" answered for every mutation touched (R2.1)
- [x] Deviations from this guide flagged explicitly with rule numbers — none

The HTTPS adapter authenticates `push/provision` and `push/wake` by a
signature over the request body. The DIDComm adapter authorised them on
the envelope's `from`, so the two transports did not ask the caller for
the same evidence. They now do: over DIDComm the Trust Task document
carries an `eddsa-jcs-2022` Data Integrity proof, and the caller is the
document's `issuer` once that proof binds it to one of the issuer's own
keys (src/proof.rs):

- the proof is `eddsa-jcs-2022` with `proofPurpose: assertionMethod`;
- the DID of `proof.verificationMethod` is the `issuer`;
- the issuer's DID document lists that method, its `controller` is the
  issuer, and it is referenced (or embedded) under `assertionMethod`;
- the signature verifies over the raw document without `proof`.

`push/provision` then requires that issuer to be the handle's
controller VTA and `push/wake` requires it to be on the allowlist,
through the unchanged dispatch core.

The envelope sender is never authorising on its own. A document with no
proof reaches the core as anonymous, so `push/register` works as before
and provision/wake answer `proofRequired`. When the envelope does name a
sender it must be the proven issuer (`identityMismatch` otherwise), and a
document addressed to another `recipient` gets `wrongRecipient`.

Proof DIDs resolve through a resolver built from the same tuning and
host policy as the listener's, since inbound documents choose them.

BREAKING CHANGE: a controller VTA or trigger that sends
`push/provision` / `push/wake` over DIDComm without a document proof is
now refused with `proofRequired`. vta-service's `provision_gateway`
(trust_tasks/device.rs) and `trigger_gateway_wake`
(trust_tasks/step_up.rs) send them unsigned today and need to attach a
proof with the VTA's assertionMethod key (`attach_proof_in_place`) before
this ships. The HTTPS path is unchanged.

Signed-off-by: Glenn Gore <glenn.g@affinidi.com>
…ue and id

`push/provision` and `push/wake` are the caller's own operational
messages, not attestations. Per VTI-KEY-106 they are signed with the
caller's operational key under `proofPurpose: authentication`, and the
verification method must be listed under `authentication` in the
issuer's DID document. An `assertionMethod` proof — reserved for
attestation artefacts — is now refused. The exact
verificationMethod/controller/issuer binding is unchanged.

An `authentication` proof carries no challenge, so the document itself
binds it to one delivery (VTI-KEY-107):

- `recipient` is required on a signed document (and must be this
  gateway, as before);
- `issuedAt` is required and must lie within the acceptance window —
  at most 5 minutes old, at most 60 s in the future (VTI-OPS-024,
  `FreshnessPolicy::consequential`);
- the document `id` is claimed in a replay record held in `AppState`
  and retained for exactly that window (VTI-OPS-026). A second delivery
  of an accepted document is answered with the first response and not
  executed again; a different document under an accepted id gets
  `idConflict`; an unavailable record fails closed.

BREAKING CHANGE: the VTA must sign these messages with its operational
key under `authentication`, and include `recipient`, `issuedAt` and a
unique `id`. No dual acceptance of `assertionMethod`.

Signed-off-by: Glenn Gore <glenn.g@affinidi.com>
…ed document

Follow-ups to the document admission added in the previous commit:

- An already-expired document (`expiresAt` in the past, `issuedAt` in
  the window) was accepted, and because its record was retained only
  until `expiresAt` it re-executed on every delivery. `validate_basic`
  now refuses `expiresAt <= now` before anything is claimed.
- The record was claimed before authorisation, so any self-signed
  did:key could create entries and push legitimate ones out of the
  bounded record, making them replayable. The claim now runs inside the
  dispatch core (`AdmitOnce`), after the per-DID rate limit and after the
  controller/allowlist check (`Store::check_controller` for provision).
  A refused caller leaves no entry.
- The record (`src/replay.rs`, `ReplayRecord`) is keyed by (issuer, id)
  and partitioned per issuer: one issuer cannot evict another's entries
  or take an id another will use. At its bounds (8192 per issuer, 65536
  total) it refuses instead of evicting.
- A transient push failure releases the claim, so a retry of the same
  document is attempted instead of answered with the failure.
- Retention now runs to the last instant the window accepts the document
  (`issuedAt + max_age + skew`, or `expiresAt` if sooner) plus 1 s.
  Previously it stopped `skew` short of that.
- The proof's verification method is refused when `revoked` is set or
  `expires` has passed (or does not parse), and a resolved DID document
  over 64 KiB is refused.

Signed-off-by: Glenn Gore <glenn.g@affinidi.com>
`push/register` is anonymous and names its controller freely, so anyone
can become the "authorised" controller of handles naming DIDs they hold
and send them signed provisions. A handful of such controllers could fill
the replay record's global bound, after which every issuer was refused.
A registration-time proof from the controller would not prevent it (the
attacker is that controller), so the record's budgets now carry it:

- a provision that re-applies the stored allowlist changes nothing and
  is answered without spending a record (`Store::allowlist_is`);
- records are charged to the handle as well as the issuer, and one handle
  holds at most 512 in the window, shared by its controller and every
  trigger acting on it;
- at the global soft bound (65536) an issuer is admitted only while it
  holds less than its fair share (soft bound / issuers holding records),
  so invented controllers cannot lock out one that is not flooding; a
  hard bound of twice the soft bound caps memory;
- one controller DID holds at most 4096 live handles
  (`GATEWAY_MAX_HANDLES_PER_CONTROLLER`), and an unprovisioned handle is
  swept after 1 h instead of 24 h.

The reviewer's probe is a regression test (three self-registered
controllers flooding fresh provisions; a legitimate wake is still
admitted), with tests for the no-op provision, the per-handle budget,
the fair share and the per-controller cap. The README specifies who can
spend the record.

Signed-off-by: Glenn Gore <glenn.g@affinidi.com>
`push/register` is anonymous and names its `controllerVtaDid`, so any DID
a caller holds could be made the controller of a handle. The gateway now
serves only the controller VTAs its operator lists in
`GATEWAY_ALLOWED_CONTROLLERS` (comma/space separated DIDs, exact match):

- a registration naming an unlisted controller is refused with
  `permissionDenied`, before a sender is selected or anything stored;
- a provision by a controller no longer on the list is refused the same
  way, without spending a replay record (covers handles restored from a
  snapshot taken under a wider list);
- unset or empty lists nothing, so every registration is refused, and
  startup logs an error saying so;
- `*` alone is an explicit open mode: any controller may register, a
  startup warning is logged, and the per-controller, per-handle and
  fair-share limits all still apply;
- a malformed list (a non-DID entry, a fragment, a pattern, or `*`
  mixed with DIDs) stops startup. Patterns are deliberately not
  supported: one would admit every DID anyone can mint under it.

BREAKING CHANGE: a gateway must be configured with the VTAs it serves;
without `GATEWAY_ALLOWED_CONTROLLERS` it refuses every registration. The
`test-wake` helpers register under a throwaway controller and so need a
local gateway in open mode.

Signed-off-by: Glenn Gore <glenn.g@affinidi.com>
…ntroller-ops

Signed-off-by: Glenn Gore <glenn.g@affinidi.com>
…transport

push/provision and push/wake are Trust Tasks, so they are authorised by the
document's own proof whichever transport carried them. Every adapter now
hands the document to one intake (src/intake.rs): an eddsa-jcs-2022
authentication proof bound to the issuer, the issuer an allowed controller,
recipient = this gateway's DID, issuedAt inside the acceptance window, and a
replay record keyed on (proven issuer, id), bounded and fail-closed, shared
by the transports.

- HTTPS POST /trust-tasks now authenticates by the document proof, as the
  VTA push engine's REST transport sends it. The X-TT-Did/X-TT-Signature
  body signature (src/auth.rs) is removed.
- DIDComm is a thin adapter; the envelope sender is only a claim that must
  agree with the proven issuer.
- Proof verification uses trust-tasks-proof 0.23's ProofPurposeResolver and
  PurposeBound; only `authentication` is accepted.
- A gateway without an identity has no DID to be addressed to and serves
  push/register only.
- test-wake helpers sign their documents.
- Dependencies: trust-tasks-rs 0.23.2, trust-tasks-proof 0.23.2,
  affinidi-tdk 0.18, affinidi-messaging-didcomm-service 0.13 (messaging-sdk
  0.28), affinidi-secrets-resolver 0.5.12.

Signed-off-by: Glenn Gore <glenn.g@affinidi.com>
@stormer78
stormer78 marked this pull request as ready for review September 26, 2026 21:51
@stormer78 stormer78 changed the title feat(didcomm)!: authenticate provision and wake by the document's proof feat!: authorise provision and wake by the document's proof on every transport Sep 26, 2026
@stormer78
stormer78 merged commit b5aa9eb into main Sep 26, 2026
3 checks passed
@stormer78
stormer78 deleted the fix/didcomm-signed-controller-ops branch September 26, 2026 22:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant