@openvtc/trust-tasks 0.8.2 → 0.10.0

package/dist/task-consent/request/0.1/payload.d.ts

@@ -160,16 +160,558 @@ export type Payload = TaskConsentRequestPayload;
 export declare const RESPONSE_TYPE_URI: "https://trusttasks.org/spec/task-consent/request/0.1#response";
 /** Stable alias for this specification's success-response payload shape. */
 export type Response = TaskConsentRequestResponsePayload;
+/**
+ * This specification's payload schema, as a value.
+ *
+ * SPEC.md §7.2 item 2 is performed against this. It is shipped as data
+ * rather than only as a `.json` file because TypeScript types are erased
+ * at runtime: without a schema a consumer has nothing to validate, and
+ * every REQUIRED payload member is optional in practice. Cross-file
+ * `$ref`s are already inlined, so it needs no resolver.
+ */
+export declare const PAYLOAD_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://trusttasks.org/spec/task-consent/request/0.1";
+    readonly title: "Task Consent Request — payload";
+    readonly description: "The executor asks an enrolled approver device to authorize one pending privileged task, presenting the effects it computed by dry-running the real handler against its own prior state. The executor signs this document; the approver renders only what it verifies under that signature.";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["challenge", "taskType", "payloadDigest", "sideEffects", "exposure", "effects", "requester", "approverSet", "minApprovals", "excludeRequester", "expiresAt"];
+    readonly properties: {
+        readonly challenge: {
+            readonly type: "string";
+            readonly minLength: 16;
+            readonly description: "Per-request nonce (≥128 bits entropy) echoed and signed by the matching task-consent/decision. It is also the salt in `payloadDigest`, so a party that holds this request can re-derive the digest and a party that does not cannot invert it.";
+        };
+        readonly taskType: {
+            readonly type: "string";
+            readonly format: "uri";
+            readonly description: "Type URI of the task awaiting approval. It is bound into `payloadDigest`: without that binding, two tasks whose payloads canonicalize identically would share a digest, and an approval for a benign task would authorize a destructive one.";
+        };
+        readonly payloadDigest: {
+            readonly $ref: "#/$defs/DigestMultibase";
+            readonly description: "The binding between what the approver sees and what executes. Multibase-encoded multihash over the RFC 8785 (JCS) canonicalization of the payload, the task type, and the `challenge` as salt. The decision echoes it; the executor re-derives it from the payload it is about to run and refuses on mismatch. Salted because an unsalted digest over a low-entropy payload is a confirmation oracle for anyone who observes it in transit.";
+        };
+        readonly sideEffects: {
+            readonly type: "string";
+            readonly enum: readonly ["none", "mutating", "destructive"];
+            readonly description: "Authoritative SPEC §7.3 item 13 side-effect class of the pending task, derived by the executor from the compiled handler it is about to invoke. NEVER taken from the registry: a registry that decided this would be a consent kill-switch, downgradeable by publishing a new version with a weaker class.";
+        };
+        readonly exposure: {
+            readonly $ref: "#/$defs/Exposure";
+        };
+        readonly effects: {
+            readonly type: "array";
+            readonly description: "What executing this task will actually do, computed by dry-running the real handler against the executor's prior state. MAY be empty when the executor has no dry-run for this handler — in which case `consequences` carries the specification's static fallback text. When BOTH are empty the surface MUST tell the approver the consequences could not be determined, and MUST NOT present the task as though it had none.";
+            readonly items: {
+                readonly $ref: "#/$defs/Effect";
+            };
+        };
+        readonly consequences: {
+            readonly type: "array";
+            readonly description: "Static, human-facing second-order effects declared in the task's specification (SPEC §7.3 item 13). A fallback for handlers with no dry-run — per-task, not per-request, so it can say 'any document change rotates the update keys' but not which keys. Prefer `effects`.";
+            readonly items: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+        };
+        readonly subject: {
+            readonly type: "string";
+            readonly description: "OPTIONAL identifier the task acts on — the value at the specification's `subjectPath`, usually a DID. Absent for subjectless tasks.";
+        };
+        readonly requester: {
+            readonly type: "string";
+            readonly description: "DID that submitted the pending task. Shown to the approver, and compared against the approver when `excludeRequester` is set.";
+        };
+        readonly requesterDeviceId: {
+            readonly type: "string";
+            readonly description: "OPTIONAL enrolled device the task was submitted from.";
+        };
+        readonly origin: {
+            readonly type: "string";
+            readonly description: "OPTIONAL web origin that proposed the task, when it arrived via a relying party. This MUST be the origin the consumer's own runtime attested (e.g. the browser-supplied sender origin) — never a value the proposing page supplied, and never one the relying party could author.";
+        };
+        readonly note: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly maxLength: 500;
+            readonly description: "OPTIONAL requester-authored display text — the one member of this payload whose prose the executor did NOT author, carried verbatim for context ('why I am asking'). EXPLICITLY UNTRUSTED: it is written by the least trusted party in the system and MUST NOT be treated as a statement of the task's effects. A surface that renders it MUST attribute it to `requester`, MUST present it visually distinct from `effects`, and MUST NOT let it substitute for, reorder, or obscure them. The executor's signature on this document attests only that the requester supplied this text, never that it is true.";
+        };
+        readonly statePin: {
+            readonly $ref: "#/$defs/StatePin";
+        };
+        readonly approverSet: {
+            readonly type: "string";
+            readonly description: "Name of the approver set the policy's `requireConsent` named.";
+        };
+        readonly minApprovals: {
+            readonly type: "integer";
+            readonly minimum: 1;
+            readonly description: "Distinct approvals from the set required before the task may execute.";
+        };
+        readonly excludeRequester: {
+            readonly type: "boolean";
+            readonly description: "When true, `requester` may not count toward the threshold — so a single compromised device cannot both propose and approve. A surface MUST NOT offer to approve a request whose `requester` is its own subject when this is set.";
+        };
+        readonly expiresAt: {
+            readonly type: "string";
+            readonly format: "date-time";
+            readonly description: "After this instant the pending request lapses and no decision is accepted for it.";
+        };
+        readonly ext: {
+            readonly $ref: "#/$defs/Ext";
+        };
+    };
+    readonly $defs: {
+        readonly Response: {
+            readonly $anchor: "response";
+            readonly title: "Task Consent Request — response payload";
+            readonly description: "Synchronous acknowledgement from the approver device that a prompt was raised. The decision itself arrives separately as a task-consent/decision — a human is in the loop, so it cannot be a synchronous reply.";
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["status"];
+            readonly properties: {
+                readonly status: {
+                    readonly type: "string";
+                    readonly enum: readonly ["prompted", "refused"];
+                    readonly description: "`prompted` = the request was verified and an approval prompt raised. `refused` = the device will not prompt; `reason` MUST be set.";
+                };
+                readonly reason: {
+                    readonly type: "string";
+                    readonly description: "REQUIRED when status is `refused`.";
+                };
+                readonly ext: {
+                    readonly $ref: "#/$defs/Ext";
+                };
+            };
+        };
+        readonly Ext: {
+            readonly title: "Ext";
+            readonly description: "Vendor-namespaced extension object per SPEC.md §4.5.1. Each immediate key MUST be a reverse-DNS namespace; structure under each namespace is opaque to the framework.";
+            readonly type: "object";
+            readonly minProperties: 1;
+            readonly additionalProperties: true;
+            readonly propertyNames: {
+                readonly pattern: "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$";
+            };
+        };
+        readonly StatePin: {
+            readonly title: "StatePin";
+            readonly description: "The prior state the effects were computed against. A human in the loop makes the approval window minutes wide, so the state can move underneath a pending approval. The executor asserts this pin still holds at execution and refuses otherwise — without it, a lost update silently executes against state the approver never saw.";
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["resource", "version"];
+            readonly properties: {
+                readonly resource: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly description: "Identifier of the pinned resource (usually the subject DID).";
+                };
+                readonly version: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly description: "Opaque version identifier of the prior state (e.g. a did:webvh `versionId`). Compared for equality at execution; the executor MUST NOT attempt to order or interpret it.";
+                };
+            };
+        };
+        readonly Effect: {
+            readonly title: "Effect";
+            readonly description: "One consequence of executing the pending task, authored by the executor that is about to run it. An effect is produced by dry-running the real handler against the executor's own prior state — never by the requester, and never by re-implementing the handler's semantics elsewhere. A consent surface renders ONLY effects it received under the executor's signature.";
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["kind", "summary"];
+            readonly properties: {
+                readonly kind: {
+                    readonly type: "string";
+                    readonly pattern: "^[a-z][a-zA-Z0-9]*$";
+                    readonly description: "Machine discriminator for rich rendering. Well-known kinds are registered in the prose (`documentChange`, `keyRotation`, `preRotationRefresh`, `resourceDelete`, `disclosure`), but the set is OPEN: handlers evolve faster than this schema, and an executor MUST be able to describe a consequence this version does not name. A surface that does not recognise a `kind` MUST still render `summary`.";
+                };
+                readonly summary: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly description: "REQUIRED human-facing sentence describing this consequence, authored by the executor. This is the ONLY member a consent surface is guaranteed to be able to render, and it is what makes an unrecognised `kind` degrade to something truthful rather than something invisible. A surface MUST render it verbatim; it MUST NOT substitute its own prose.";
+                };
+                readonly path: {
+                    readonly type: "string";
+                    readonly description: "OPTIONAL RFC 6901 JSON Pointer locating the change within the subject resource (e.g. `/service/0`).";
+                };
+                readonly before: {
+                    readonly description: "OPTIONAL prior value at `path`, from the executor's authoritative state. ABSENT means there was no prior value (a creation); an explicit `null` is treated identically, so an executor MUST NOT rely on the two being distinguishable. Structured members are for rich rendering only — `summary` is what a surface is obliged to show, and it is where an executor states a distinction this shape cannot carry.";
+                };
+                readonly after: {
+                    readonly description: "OPTIONAL resulting value at `path` once the task executes. ABSENT means the value is removed (a deletion), under the same rule as `before`.";
+                };
+                readonly detail: {
+                    readonly type: "object";
+                    readonly description: "OPTIONAL kind-specific structured extras (e.g. `{ \"commitments\": 2 }` for `preRotationRefresh`).";
+                    readonly additionalProperties: true;
+                };
+            };
+        };
+        readonly Exposure: {
+            readonly title: "Exposure";
+            readonly description: "The authoritative SPEC §7.3 item 14 exposure class of the pending task, derived by the executor from the compiled handler it is about to invoke — never from the registry's declared value.";
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["discloses", "actsAsSubject"];
+            readonly properties: {
+                readonly discloses: {
+                    readonly type: "string";
+                    readonly enum: readonly ["none", "metadata", "secret"];
+                    readonly description: "Sensitivity of data the task returns to its caller.";
+                };
+                readonly actsAsSubject: {
+                    readonly type: "boolean";
+                    readonly description: "Whether execution exercises the subject's own authority to produce an attributable effect in the subject's name.";
+                };
+            };
+        };
+        readonly DigestMultibase: {
+            readonly title: "DigestMultibase";
+            readonly description: "A cryptographic digest as a multibase-encoded multihash — the encoding the W3C Verifiable Credentials Data Model 2.0 defines for `digestMultibase`, and the one `did:webvh` uses for its SCID and entry hashes.\n\nMultihash carries the hash algorithm in-band, so the value is self-describing and the wire format survives an algorithm change without a schema revision; multibase does the same for the base encoding, so a verifier never infers base58 from base64url by context. A bare hex string or a `sha-256:`-style prefix hard-codes one algorithm into the wire contract and is non-conforming here.\n\nThis definition constrains the *encoding only*. What the digest is computed over is stated by each referencing field, because it differs legitimately: a digest over a JSON document is taken over its RFC 8785 (JCS) canonicalization, while a digest over an opaque artifact is taken over its bytes. A field whose input is a JSON document and which does not name a canonicalization is not reproducible.\n\nRestricted to the two multibase headers W3C Controlled Identifiers 1.0 §2.4 normatively requires — `z` (base58btc) and `u` (base64url-no-pad). CID permits others but states that \"interoperability is not guaranteed between implementations using such values\", and a registry whose purpose is interoperability should not mint digests a conforming verifier may be unable to read. The alphabets are enforced rather than assumed: base58btc excludes 0, O, I and l, and an earlier permissive pattern let three published examples carry digests that were not valid base58 at all. base58btc is RECOMMENDED, for consistency with `did:key` and `did:webvh`.";
+            readonly type: "string";
+            readonly minLength: 16;
+            readonly pattern: "^(z[1-9A-HJ-NP-Za-km-z]+|u[A-Za-z0-9_-]+)$";
+            readonly examples: readonly ["zQmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR"];
+        };
+    };
+};
+/** As {@link PAYLOAD_SCHEMA}, for the success-response variant. */
+export declare const RESPONSE_PAYLOAD_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $ref: "#/$defs/Response";
+    readonly $defs: {
+        readonly Response: {
+            readonly $anchor: "response";
+            readonly title: "Task Consent Request — response payload";
+            readonly description: "Synchronous acknowledgement from the approver device that a prompt was raised. The decision itself arrives separately as a task-consent/decision — a human is in the loop, so it cannot be a synchronous reply.";
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["status"];
+            readonly properties: {
+                readonly status: {
+                    readonly type: "string";
+                    readonly enum: readonly ["prompted", "refused"];
+                    readonly description: "`prompted` = the request was verified and an approval prompt raised. `refused` = the device will not prompt; `reason` MUST be set.";
+                };
+                readonly reason: {
+                    readonly type: "string";
+                    readonly description: "REQUIRED when status is `refused`.";
+                };
+                readonly ext: {
+                    readonly $ref: "#/$defs/Ext";
+                };
+            };
+        };
+        readonly Ext: {
+            readonly title: "Ext";
+            readonly description: "Vendor-namespaced extension object per SPEC.md §4.5.1. Each immediate key MUST be a reverse-DNS namespace; structure under each namespace is opaque to the framework.";
+            readonly type: "object";
+            readonly minProperties: 1;
+            readonly additionalProperties: true;
+            readonly propertyNames: {
+                readonly pattern: "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$";
+            };
+        };
+        readonly StatePin: {
+            readonly title: "StatePin";
+            readonly description: "The prior state the effects were computed against. A human in the loop makes the approval window minutes wide, so the state can move underneath a pending approval. The executor asserts this pin still holds at execution and refuses otherwise — without it, a lost update silently executes against state the approver never saw.";
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["resource", "version"];
+            readonly properties: {
+                readonly resource: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly description: "Identifier of the pinned resource (usually the subject DID).";
+                };
+                readonly version: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly description: "Opaque version identifier of the prior state (e.g. a did:webvh `versionId`). Compared for equality at execution; the executor MUST NOT attempt to order or interpret it.";
+                };
+            };
+        };
+        readonly Effect: {
+            readonly title: "Effect";
+            readonly description: "One consequence of executing the pending task, authored by the executor that is about to run it. An effect is produced by dry-running the real handler against the executor's own prior state — never by the requester, and never by re-implementing the handler's semantics elsewhere. A consent surface renders ONLY effects it received under the executor's signature.";
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["kind", "summary"];
+            readonly properties: {
+                readonly kind: {
+                    readonly type: "string";
+                    readonly pattern: "^[a-z][a-zA-Z0-9]*$";
+                    readonly description: "Machine discriminator for rich rendering. Well-known kinds are registered in the prose (`documentChange`, `keyRotation`, `preRotationRefresh`, `resourceDelete`, `disclosure`), but the set is OPEN: handlers evolve faster than this schema, and an executor MUST be able to describe a consequence this version does not name. A surface that does not recognise a `kind` MUST still render `summary`.";
+                };
+                readonly summary: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly description: "REQUIRED human-facing sentence describing this consequence, authored by the executor. This is the ONLY member a consent surface is guaranteed to be able to render, and it is what makes an unrecognised `kind` degrade to something truthful rather than something invisible. A surface MUST render it verbatim; it MUST NOT substitute its own prose.";
+                };
+                readonly path: {
+                    readonly type: "string";
+                    readonly description: "OPTIONAL RFC 6901 JSON Pointer locating the change within the subject resource (e.g. `/service/0`).";
+                };
+                readonly before: {
+                    readonly description: "OPTIONAL prior value at `path`, from the executor's authoritative state. ABSENT means there was no prior value (a creation); an explicit `null` is treated identically, so an executor MUST NOT rely on the two being distinguishable. Structured members are for rich rendering only — `summary` is what a surface is obliged to show, and it is where an executor states a distinction this shape cannot carry.";
+                };
+                readonly after: {
+                    readonly description: "OPTIONAL resulting value at `path` once the task executes. ABSENT means the value is removed (a deletion), under the same rule as `before`.";
+                };
+                readonly detail: {
+                    readonly type: "object";
+                    readonly description: "OPTIONAL kind-specific structured extras (e.g. `{ \"commitments\": 2 }` for `preRotationRefresh`).";
+                    readonly additionalProperties: true;
+                };
+            };
+        };
+        readonly Exposure: {
+            readonly title: "Exposure";
+            readonly description: "The authoritative SPEC §7.3 item 14 exposure class of the pending task, derived by the executor from the compiled handler it is about to invoke — never from the registry's declared value.";
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["discloses", "actsAsSubject"];
+            readonly properties: {
+                readonly discloses: {
+                    readonly type: "string";
+                    readonly enum: readonly ["none", "metadata", "secret"];
+                    readonly description: "Sensitivity of data the task returns to its caller.";
+                };
+                readonly actsAsSubject: {
+                    readonly type: "boolean";
+                    readonly description: "Whether execution exercises the subject's own authority to produce an attributable effect in the subject's name.";
+                };
+            };
+        };
+        readonly DigestMultibase: {
+            readonly title: "DigestMultibase";
+            readonly description: "A cryptographic digest as a multibase-encoded multihash — the encoding the W3C Verifiable Credentials Data Model 2.0 defines for `digestMultibase`, and the one `did:webvh` uses for its SCID and entry hashes.\n\nMultihash carries the hash algorithm in-band, so the value is self-describing and the wire format survives an algorithm change without a schema revision; multibase does the same for the base encoding, so a verifier never infers base58 from base64url by context. A bare hex string or a `sha-256:`-style prefix hard-codes one algorithm into the wire contract and is non-conforming here.\n\nThis definition constrains the *encoding only*. What the digest is computed over is stated by each referencing field, because it differs legitimately: a digest over a JSON document is taken over its RFC 8785 (JCS) canonicalization, while a digest over an opaque artifact is taken over its bytes. A field whose input is a JSON document and which does not name a canonicalization is not reproducible.\n\nRestricted to the two multibase headers W3C Controlled Identifiers 1.0 §2.4 normatively requires — `z` (base58btc) and `u` (base64url-no-pad). CID permits others but states that \"interoperability is not guaranteed between implementations using such values\", and a registry whose purpose is interoperability should not mint digests a conforming verifier may be unable to read. The alphabets are enforced rather than assumed: base58btc excludes 0, O, I and l, and an earlier permissive pattern let three published examples carry digests that were not valid base58 at all. base58btc is RECOMMENDED, for consistency with `did:key` and `did:webvh`.";
+            readonly type: "string";
+            readonly minLength: 16;
+            readonly pattern: "^(z[1-9A-HJ-NP-Za-km-z]+|u[A-Za-z0-9_-]+)$";
+            readonly examples: readonly ["zQmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR"];
+        };
+    };
+};
 /**
  * SPEC.md §7.2 policy for the request variant, from this specification's
  * front matter. Pass to `consumeInbound` — items 5b, 7 and 8 are
- * per-specification and cannot be derived from the document alone.
+ * per-specification and cannot be derived from the document alone, and
+ * item 2 needs the schema this carries.
  */
 export declare const SPEC: {
     readonly typeUri: "https://trusttasks.org/spec/task-consent/request/0.1";
     readonly isBearer: false;
     readonly isProofRequired: true;
     readonly isRecipientRequired: true;
+    readonly payloadSchema: {
+        readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+        readonly $id: "https://trusttasks.org/spec/task-consent/request/0.1";
+        readonly title: "Task Consent Request — payload";
+        readonly description: "The executor asks an enrolled approver device to authorize one pending privileged task, presenting the effects it computed by dry-running the real handler against its own prior state. The executor signs this document; the approver renders only what it verifies under that signature.";
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["challenge", "taskType", "payloadDigest", "sideEffects", "exposure", "effects", "requester", "approverSet", "minApprovals", "excludeRequester", "expiresAt"];
+        readonly properties: {
+            readonly challenge: {
+                readonly type: "string";
+                readonly minLength: 16;
+                readonly description: "Per-request nonce (≥128 bits entropy) echoed and signed by the matching task-consent/decision. It is also the salt in `payloadDigest`, so a party that holds this request can re-derive the digest and a party that does not cannot invert it.";
+            };
+            readonly taskType: {
+                readonly type: "string";
+                readonly format: "uri";
+                readonly description: "Type URI of the task awaiting approval. It is bound into `payloadDigest`: without that binding, two tasks whose payloads canonicalize identically would share a digest, and an approval for a benign task would authorize a destructive one.";
+            };
+            readonly payloadDigest: {
+                readonly $ref: "#/$defs/DigestMultibase";
+                readonly description: "The binding between what the approver sees and what executes. Multibase-encoded multihash over the RFC 8785 (JCS) canonicalization of the payload, the task type, and the `challenge` as salt. The decision echoes it; the executor re-derives it from the payload it is about to run and refuses on mismatch. Salted because an unsalted digest over a low-entropy payload is a confirmation oracle for anyone who observes it in transit.";
+            };
+            readonly sideEffects: {
+                readonly type: "string";
+                readonly enum: readonly ["none", "mutating", "destructive"];
+                readonly description: "Authoritative SPEC §7.3 item 13 side-effect class of the pending task, derived by the executor from the compiled handler it is about to invoke. NEVER taken from the registry: a registry that decided this would be a consent kill-switch, downgradeable by publishing a new version with a weaker class.";
+            };
+            readonly exposure: {
+                readonly $ref: "#/$defs/Exposure";
+            };
+            readonly effects: {
+                readonly type: "array";
+                readonly description: "What executing this task will actually do, computed by dry-running the real handler against the executor's prior state. MAY be empty when the executor has no dry-run for this handler — in which case `consequences` carries the specification's static fallback text. When BOTH are empty the surface MUST tell the approver the consequences could not be determined, and MUST NOT present the task as though it had none.";
+                readonly items: {
+                    readonly $ref: "#/$defs/Effect";
+                };
+            };
+            readonly consequences: {
+                readonly type: "array";
+                readonly description: "Static, human-facing second-order effects declared in the task's specification (SPEC §7.3 item 13). A fallback for handlers with no dry-run — per-task, not per-request, so it can say 'any document change rotates the update keys' but not which keys. Prefer `effects`.";
+                readonly items: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+            };
+            readonly subject: {
+                readonly type: "string";
+                readonly description: "OPTIONAL identifier the task acts on — the value at the specification's `subjectPath`, usually a DID. Absent for subjectless tasks.";
+            };
+            readonly requester: {
+                readonly type: "string";
+                readonly description: "DID that submitted the pending task. Shown to the approver, and compared against the approver when `excludeRequester` is set.";
+            };
+            readonly requesterDeviceId: {
+                readonly type: "string";
+                readonly description: "OPTIONAL enrolled device the task was submitted from.";
+            };
+            readonly origin: {
+                readonly type: "string";
+                readonly description: "OPTIONAL web origin that proposed the task, when it arrived via a relying party. This MUST be the origin the consumer's own runtime attested (e.g. the browser-supplied sender origin) — never a value the proposing page supplied, and never one the relying party could author.";
+            };
+            readonly note: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 500;
+                readonly description: "OPTIONAL requester-authored display text — the one member of this payload whose prose the executor did NOT author, carried verbatim for context ('why I am asking'). EXPLICITLY UNTRUSTED: it is written by the least trusted party in the system and MUST NOT be treated as a statement of the task's effects. A surface that renders it MUST attribute it to `requester`, MUST present it visually distinct from `effects`, and MUST NOT let it substitute for, reorder, or obscure them. The executor's signature on this document attests only that the requester supplied this text, never that it is true.";
+            };
+            readonly statePin: {
+                readonly $ref: "#/$defs/StatePin";
+            };
+            readonly approverSet: {
+                readonly type: "string";
+                readonly description: "Name of the approver set the policy's `requireConsent` named.";
+            };
+            readonly minApprovals: {
+                readonly type: "integer";
+                readonly minimum: 1;
+                readonly description: "Distinct approvals from the set required before the task may execute.";
+            };
+            readonly excludeRequester: {
+                readonly type: "boolean";
+                readonly description: "When true, `requester` may not count toward the threshold — so a single compromised device cannot both propose and approve. A surface MUST NOT offer to approve a request whose `requester` is its own subject when this is set.";
+            };
+            readonly expiresAt: {
+                readonly type: "string";
+                readonly format: "date-time";
+                readonly description: "After this instant the pending request lapses and no decision is accepted for it.";
+            };
+            readonly ext: {
+                readonly $ref: "#/$defs/Ext";
+            };
+        };
+        readonly $defs: {
+            readonly Response: {
+                readonly $anchor: "response";
+                readonly title: "Task Consent Request — response payload";
+                readonly description: "Synchronous acknowledgement from the approver device that a prompt was raised. The decision itself arrives separately as a task-consent/decision — a human is in the loop, so it cannot be a synchronous reply.";
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["status"];
+                readonly properties: {
+                    readonly status: {
+                        readonly type: "string";
+                        readonly enum: readonly ["prompted", "refused"];
+                        readonly description: "`prompted` = the request was verified and an approval prompt raised. `refused` = the device will not prompt; `reason` MUST be set.";
+                    };
+                    readonly reason: {
+                        readonly type: "string";
+                        readonly description: "REQUIRED when status is `refused`.";
+                    };
+                    readonly ext: {
+                        readonly $ref: "#/$defs/Ext";
+                    };
+                };
+            };
+            readonly Ext: {
+                readonly title: "Ext";
+                readonly description: "Vendor-namespaced extension object per SPEC.md §4.5.1. Each immediate key MUST be a reverse-DNS namespace; structure under each namespace is opaque to the framework.";
+                readonly type: "object";
+                readonly minProperties: 1;
+                readonly additionalProperties: true;
+                readonly propertyNames: {
+                    readonly pattern: "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$";
+                };
+            };
+            readonly StatePin: {
+                readonly title: "StatePin";
+                readonly description: "The prior state the effects were computed against. A human in the loop makes the approval window minutes wide, so the state can move underneath a pending approval. The executor asserts this pin still holds at execution and refuses otherwise — without it, a lost update silently executes against state the approver never saw.";
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["resource", "version"];
+                readonly properties: {
+                    readonly resource: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly description: "Identifier of the pinned resource (usually the subject DID).";
+                    };
+                    readonly version: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly description: "Opaque version identifier of the prior state (e.g. a did:webvh `versionId`). Compared for equality at execution; the executor MUST NOT attempt to order or interpret it.";
+                    };
+                };
+            };
+            readonly Effect: {
+                readonly title: "Effect";
+                readonly description: "One consequence of executing the pending task, authored by the executor that is about to run it. An effect is produced by dry-running the real handler against the executor's own prior state — never by the requester, and never by re-implementing the handler's semantics elsewhere. A consent surface renders ONLY effects it received under the executor's signature.";
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["kind", "summary"];
+                readonly properties: {
+                    readonly kind: {
+                        readonly type: "string";
+                        readonly pattern: "^[a-z][a-zA-Z0-9]*$";
+                        readonly description: "Machine discriminator for rich rendering. Well-known kinds are registered in the prose (`documentChange`, `keyRotation`, `preRotationRefresh`, `resourceDelete`, `disclosure`), but the set is OPEN: handlers evolve faster than this schema, and an executor MUST be able to describe a consequence this version does not name. A surface that does not recognise a `kind` MUST still render `summary`.";
+                    };
+                    readonly summary: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly description: "REQUIRED human-facing sentence describing this consequence, authored by the executor. This is the ONLY member a consent surface is guaranteed to be able to render, and it is what makes an unrecognised `kind` degrade to something truthful rather than something invisible. A surface MUST render it verbatim; it MUST NOT substitute its own prose.";
+                    };
+                    readonly path: {
+                        readonly type: "string";
+                        readonly description: "OPTIONAL RFC 6901 JSON Pointer locating the change within the subject resource (e.g. `/service/0`).";
+                    };
+                    readonly before: {
+                        readonly description: "OPTIONAL prior value at `path`, from the executor's authoritative state. ABSENT means there was no prior value (a creation); an explicit `null` is treated identically, so an executor MUST NOT rely on the two being distinguishable. Structured members are for rich rendering only — `summary` is what a surface is obliged to show, and it is where an executor states a distinction this shape cannot carry.";
+                    };
+                    readonly after: {
+                        readonly description: "OPTIONAL resulting value at `path` once the task executes. ABSENT means the value is removed (a deletion), under the same rule as `before`.";
+                    };
+                    readonly detail: {
+                        readonly type: "object";
+                        readonly description: "OPTIONAL kind-specific structured extras (e.g. `{ \"commitments\": 2 }` for `preRotationRefresh`).";
+                        readonly additionalProperties: true;
+                    };
+                };
+            };
+            readonly Exposure: {
+                readonly title: "Exposure";
+                readonly description: "The authoritative SPEC §7.3 item 14 exposure class of the pending task, derived by the executor from the compiled handler it is about to invoke — never from the registry's declared value.";
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["discloses", "actsAsSubject"];
+                readonly properties: {
+                    readonly discloses: {
+                        readonly type: "string";
+                        readonly enum: readonly ["none", "metadata", "secret"];
+                        readonly description: "Sensitivity of data the task returns to its caller.";
+                    };
+                    readonly actsAsSubject: {
+                        readonly type: "boolean";
+                        readonly description: "Whether execution exercises the subject's own authority to produce an attributable effect in the subject's name.";
+                    };
+                };
+            };
+            readonly DigestMultibase: {
+                readonly title: "DigestMultibase";
+                readonly description: "A cryptographic digest as a multibase-encoded multihash — the encoding the W3C Verifiable Credentials Data Model 2.0 defines for `digestMultibase`, and the one `did:webvh` uses for its SCID and entry hashes.\n\nMultihash carries the hash algorithm in-band, so the value is self-describing and the wire format survives an algorithm change without a schema revision; multibase does the same for the base encoding, so a verifier never infers base58 from base64url by context. A bare hex string or a `sha-256:`-style prefix hard-codes one algorithm into the wire contract and is non-conforming here.\n\nThis definition constrains the *encoding only*. What the digest is computed over is stated by each referencing field, because it differs legitimately: a digest over a JSON document is taken over its RFC 8785 (JCS) canonicalization, while a digest over an opaque artifact is taken over its bytes. A field whose input is a JSON document and which does not name a canonicalization is not reproducible.\n\nRestricted to the two multibase headers W3C Controlled Identifiers 1.0 §2.4 normatively requires — `z` (base58btc) and `u` (base64url-no-pad). CID permits others but states that \"interoperability is not guaranteed between implementations using such values\", and a registry whose purpose is interoperability should not mint digests a conforming verifier may be unable to read. The alphabets are enforced rather than assumed: base58btc excludes 0, O, I and l, and an earlier permissive pattern let three published examples carry digests that were not valid base58 at all. base58btc is RECOMMENDED, for consistency with `did:key` and `did:webvh`.";
+                readonly type: "string";
+                readonly minLength: 16;
+                readonly pattern: "^(z[1-9A-HJ-NP-Za-km-z]+|u[A-Za-z0-9_-]+)$";
+                readonly examples: readonly ["zQmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR"];
+            };
+        };
+    };
 };
 /**
  * SPEC.md §7.2 policy for the success-response variant. `isRecipientRequired`
@@ -181,5 +723,122 @@ export declare const RESPONSE_SPEC: {
     readonly isBearer: false;
     readonly isProofRequired: true;
     readonly isRecipientRequired: true;
+    readonly payloadSchema: {
+        readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+        readonly $ref: "#/$defs/Response";
+        readonly $defs: {
+            readonly Response: {
+                readonly $anchor: "response";
+                readonly title: "Task Consent Request — response payload";
+                readonly description: "Synchronous acknowledgement from the approver device that a prompt was raised. The decision itself arrives separately as a task-consent/decision — a human is in the loop, so it cannot be a synchronous reply.";
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["status"];
+                readonly properties: {
+                    readonly status: {
+                        readonly type: "string";
+                        readonly enum: readonly ["prompted", "refused"];
+                        readonly description: "`prompted` = the request was verified and an approval prompt raised. `refused` = the device will not prompt; `reason` MUST be set.";
+                    };
+                    readonly reason: {
+                        readonly type: "string";
+                        readonly description: "REQUIRED when status is `refused`.";
+                    };
+                    readonly ext: {
+                        readonly $ref: "#/$defs/Ext";
+                    };
+                };
+            };
+            readonly Ext: {
+                readonly title: "Ext";
+                readonly description: "Vendor-namespaced extension object per SPEC.md §4.5.1. Each immediate key MUST be a reverse-DNS namespace; structure under each namespace is opaque to the framework.";
+                readonly type: "object";
+                readonly minProperties: 1;
+                readonly additionalProperties: true;
+                readonly propertyNames: {
+                    readonly pattern: "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$";
+                };
+            };
+            readonly StatePin: {
+                readonly title: "StatePin";
+                readonly description: "The prior state the effects were computed against. A human in the loop makes the approval window minutes wide, so the state can move underneath a pending approval. The executor asserts this pin still holds at execution and refuses otherwise — without it, a lost update silently executes against state the approver never saw.";
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["resource", "version"];
+                readonly properties: {
+                    readonly resource: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly description: "Identifier of the pinned resource (usually the subject DID).";
+                    };
+                    readonly version: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly description: "Opaque version identifier of the prior state (e.g. a did:webvh `versionId`). Compared for equality at execution; the executor MUST NOT attempt to order or interpret it.";
+                    };
+                };
+            };
+            readonly Effect: {
+                readonly title: "Effect";
+                readonly description: "One consequence of executing the pending task, authored by the executor that is about to run it. An effect is produced by dry-running the real handler against the executor's own prior state — never by the requester, and never by re-implementing the handler's semantics elsewhere. A consent surface renders ONLY effects it received under the executor's signature.";
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["kind", "summary"];
+                readonly properties: {
+                    readonly kind: {
+                        readonly type: "string";
+                        readonly pattern: "^[a-z][a-zA-Z0-9]*$";
+                        readonly description: "Machine discriminator for rich rendering. Well-known kinds are registered in the prose (`documentChange`, `keyRotation`, `preRotationRefresh`, `resourceDelete`, `disclosure`), but the set is OPEN: handlers evolve faster than this schema, and an executor MUST be able to describe a consequence this version does not name. A surface that does not recognise a `kind` MUST still render `summary`.";
+                    };
+                    readonly summary: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly description: "REQUIRED human-facing sentence describing this consequence, authored by the executor. This is the ONLY member a consent surface is guaranteed to be able to render, and it is what makes an unrecognised `kind` degrade to something truthful rather than something invisible. A surface MUST render it verbatim; it MUST NOT substitute its own prose.";
+                    };
+                    readonly path: {
+                        readonly type: "string";
+                        readonly description: "OPTIONAL RFC 6901 JSON Pointer locating the change within the subject resource (e.g. `/service/0`).";
+                    };
+                    readonly before: {
+                        readonly description: "OPTIONAL prior value at `path`, from the executor's authoritative state. ABSENT means there was no prior value (a creation); an explicit `null` is treated identically, so an executor MUST NOT rely on the two being distinguishable. Structured members are for rich rendering only — `summary` is what a surface is obliged to show, and it is where an executor states a distinction this shape cannot carry.";
+                    };
+                    readonly after: {
+                        readonly description: "OPTIONAL resulting value at `path` once the task executes. ABSENT means the value is removed (a deletion), under the same rule as `before`.";
+                    };
+                    readonly detail: {
+                        readonly type: "object";
+                        readonly description: "OPTIONAL kind-specific structured extras (e.g. `{ \"commitments\": 2 }` for `preRotationRefresh`).";
+                        readonly additionalProperties: true;
+                    };
+                };
+            };
+            readonly Exposure: {
+                readonly title: "Exposure";
+                readonly description: "The authoritative SPEC §7.3 item 14 exposure class of the pending task, derived by the executor from the compiled handler it is about to invoke — never from the registry's declared value.";
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["discloses", "actsAsSubject"];
+                readonly properties: {
+                    readonly discloses: {
+                        readonly type: "string";
+                        readonly enum: readonly ["none", "metadata", "secret"];
+                        readonly description: "Sensitivity of data the task returns to its caller.";
+                    };
+                    readonly actsAsSubject: {
+                        readonly type: "boolean";
+                        readonly description: "Whether execution exercises the subject's own authority to produce an attributable effect in the subject's name.";
+                    };
+                };
+            };
+            readonly DigestMultibase: {
+                readonly title: "DigestMultibase";
+                readonly description: "A cryptographic digest as a multibase-encoded multihash — the encoding the W3C Verifiable Credentials Data Model 2.0 defines for `digestMultibase`, and the one `did:webvh` uses for its SCID and entry hashes.\n\nMultihash carries the hash algorithm in-band, so the value is self-describing and the wire format survives an algorithm change without a schema revision; multibase does the same for the base encoding, so a verifier never infers base58 from base64url by context. A bare hex string or a `sha-256:`-style prefix hard-codes one algorithm into the wire contract and is non-conforming here.\n\nThis definition constrains the *encoding only*. What the digest is computed over is stated by each referencing field, because it differs legitimately: a digest over a JSON document is taken over its RFC 8785 (JCS) canonicalization, while a digest over an opaque artifact is taken over its bytes. A field whose input is a JSON document and which does not name a canonicalization is not reproducible.\n\nRestricted to the two multibase headers W3C Controlled Identifiers 1.0 §2.4 normatively requires — `z` (base58btc) and `u` (base64url-no-pad). CID permits others but states that \"interoperability is not guaranteed between implementations using such values\", and a registry whose purpose is interoperability should not mint digests a conforming verifier may be unable to read. The alphabets are enforced rather than assumed: base58btc excludes 0, O, I and l, and an earlier permissive pattern let three published examples carry digests that were not valid base58 at all. base58btc is RECOMMENDED, for consistency with `did:key` and `did:webvh`.";
+                readonly type: "string";
+                readonly minLength: 16;
+                readonly pattern: "^(z[1-9A-HJ-NP-Za-km-z]+|u[A-Za-z0-9_-]+)$";
+                readonly examples: readonly ["zQmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR"];
+            };
+        };
+    };
 };
 //# sourceMappingURL=payload.d.ts.map