Repository navigation
feat!: authorise provision and wake by the document's proof on every transport - #32
Merged
Merged
Conversation
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
marked this pull request as ready for review
September 26, 2026 21:51
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changes
push/provisionandpush/wakeare 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/wakeas its own operational documents. They carry anauthenticationproof,issuer= the VTA,recipient= the gateway,issuedAtand a uniqueid. 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:eddsa-jcs-2022and itsproofPurpose, parsed as a trust-tasks-proofProofPurpose, isauthentication.assertionMethodor any other purpose is refused (VTI-KEY-106);proof.verificationMethod==issuer, by exact match;controller==issuer, it is referenced or embedded underauthentication, and it is neitherrevokednor pastexpires. A resolved document over 64 KiB is refused;proofremoved.Steps 3–4 run through trust-tasks-proof 0.23's proof-purpose API. The gateway's
IssuerKeysimplementsProofPurposeResolver, and verification goes throughPurposeBound::new(&keys, ProofPurpose::Authentication). A key is therefore released only for the relationship the proof declares. The hand-rolledPinnedKeyresolver is gone.One delivery, once (
src/intake.rs,src/replay.rs)An
authenticationproof has no challenge, so the document itself binds it to one delivery (VTI-KEY-107):recipientis required and must be this gateway's DID. Otherwise the answer iswrongRecipient, ormalformedRequestifrecipientis missing.issuedAtis required and may be at most 5 min old and at most 60 s in the future (VTI-OPS-024). Otherwise the answer isexpiredormalformedRequest.expiresAtmust not have passed.id). The issuer is the one the proof established, never a transport claim.idgetsidConflict. A transient push failure releases the claim.Controllers served (
GATEWAY_ALLOWED_CONTROLLERS)Only listed controller VTA DIDs are served (exact match, no patterns):
*is an explicit open mode.push/provisionalso requires the proven issuer to be the handle'scontrollerVtaDid.push/wakerequires it to be on the handle's allowlist.Transports
GATEWAY_IDENTITY_FILEis set. The adapter passes the envelopefromto the intake only as a claim. If it is present and differs from the proven issuer, the answer isidentityMismatch.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 oldX-TT-Did/X-TT-Signaturebody-signature scheme (src/auth.rs) is removed, not kept alongside: it was did:key-only and had no recipient binding, freshness or replay protection.TSPTransportin its DID document, that hands unpacked documents tointake::receive. Authorisation would not change.recipient, so it accepts no signed document on any transport and servespush/registeronly. Startup warns about this.Dependencies
ProofPurpose/ProofPurposeResolver/PurposeBoundDeploy
GATEWAY_ALLOWED_CONTROLLERSto the DID(s) of the VTA(s) this gateway serves. Without it every registration is refused.GATEWAY_IDENTITY_FILE. Without a DID the gateway accepts no provision or wake on any transport.The
test-wake*helpers now sign their documents with anauthenticationproof, addressed to the gateway DID taken from the register response. They need a gateway with an identity, running in open mode.Breaking changes
proofRequired) on every transport.assertionMethodproof is refused (proofInvalid).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, 25tests/api.rs, 31tests/document_auth.rs).cargo clippy --workspace --all-targets -- -D warnings,cargo fmt --checkandcargo deny checkare clean.tests/document_auth.rs(wasdidcomm_auth.rs) drives the transport-neutral intake. Newevery_transport_*tests run the same documents through the DIDComm handoff and through the real HTTPS router:permissionDenied) or a controller's DID signed by another key (proofInvalid): refused;proofRequired;issuedAt:expired;assertionMethod:proofInvalid;identityMismatch,wrongRecipient, missingrecipient, the time window,idConflict, the refuse-not-evict and fair-share budgets, and allowlist admission.tests/api.rsnow signs provisions and wakes with document proofs. New tests:tampered_signed_document_is_refused;header_identity_authorises_nothing: a retiredX-TT-*header is ignored and the answer isproofRequired.src/proof.rs: VM controller,authenticationmembership (anassertionMethod-only key is refused), revoked/expired, oversized document, unlisted VM;src/intake.rs: retention outlives acceptance, expired document, missingissuedAt;src/replay.rs: keying and budgets.Scope notes
Pre-merge checklist