@openvtc/trust-tasks 0.8.2 → 0.9.0

package/dist/acl/swap-key/0.1/payload.d.ts

@@ -131,16 +131,481 @@ export type Payload = ACLSwapKey;
 export declare const RESPONSE_TYPE_URI: "https://trusttasks.org/spec/acl/swap-key/0.1#response";
 /** Stable alias for this specification's success-response payload shape. */
 export type Response = ACLSwapKeyResponsePayload;
+/**
+ * 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/acl/swap-key/0.1";
+    readonly title: "ACL — Swap Key";
+    readonly description: "An ACL holder atomically replaces the VID bound to one of their own AclEntries with a new VID — typically a different DID under their control. The maintainer applies the swap as a single transaction: there is no window where both VIDs have access or neither does.";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["currentSubject", "newSubject"];
+    readonly properties: {
+        readonly currentSubject: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly description: "The VID currently bound in the ACL. MUST equal the document's `issuer` (per the conformance section: the holder swaps THEIR OWN entry).";
+        };
+        readonly newSubject: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly description: "The VID to bind in place of `currentSubject`. The maintainer's policy decides admissibility (e.g. acceptable DID method, required attestations); the wire spec only requires `newSubject !== currentSubject`.";
+        };
+        readonly linkProof: {
+            readonly description: "Cryptographic evidence — required by some maintainers — that the new VID consents to taking over. Format is consumer-defined; a typical shape is a Trust Task or VP/VC signed by `newSubject` carrying a fresh nonce from the maintainer or the holder. Producers omit this when the consumer's policy doesn't require it. Format described in the spec body.";
+            readonly type: readonly ["object", "string"];
+        };
+        readonly reason: {
+            readonly type: "string";
+            readonly description: "Optional human-readable rationale (e.g. \"key-rotation\", \"hardware-token-replacement\", \"account-recovery\").";
+        };
+        readonly ext: {
+            readonly $ref: "#/$defs/Ext";
+            readonly description: "Ecosystem-defined extension members per SPEC.md §4.5.1.";
+        };
+    };
+    readonly $defs: {
+        readonly Response: {
+            readonly $anchor: "response";
+            readonly title: "ACL Swap Key — response payload";
+            readonly description: "The post-swap AclEntry. Carried in a Trust Task document whose type is https://trusttasks.org/spec/acl/swap-key/0.1#response.";
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["entry", "previousSubject"];
+            readonly properties: {
+                readonly entry: {
+                    readonly $ref: "#/$defs/AclEntry";
+                    readonly description: "The AclEntry the maintainer now holds. `subject` equals the request's `newSubject`.";
+                };
+                readonly previousSubject: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly description: "Echo of the swapped-out VID. The maintainer has removed every artifact bound to this subject (refresh tokens, persistent sessions); the holder MUST NOT attempt to reuse it.";
+                };
+                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 AclEntry: {
+            readonly title: "AclEntry";
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["subject", "role"];
+            readonly properties: {
+                readonly subject: {
+                    readonly type: "string";
+                    readonly description: "VID of the party in the ACL. Compared by exact string equality (SPEC.md §4.8); producers SHOULD emit canonical form.";
+                };
+                readonly role: {
+                    readonly type: "string";
+                    readonly description: "Opaque role identifier interpreted by the ACL maintainer.";
+                };
+                readonly scopes: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "Opaque scope identifiers (e.g. contexts, domains, resource prefixes).";
+                };
+                readonly allowedKeys: {
+                    readonly type: readonly ["array", "null"];
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "Key identifiers this subject may invoke the maintainer's signing oracle on. INTERSECTS WITH `scopes` — it can only narrow, never widen: a key named here that lies outside the entry's scopes remains unreachable, exactly as if it were not named. ABSENT means every key within the entry's scopes (the behaviour of entries that pre-date this member); explicit `null` is equivalent to absent, and producers SHOULD omit the member instead. PRESENT-BUT-EMPTY means authorized on NO keys — the opposite of absent, and deliberately so: emptiness is never a wildcard (CONVENTIONS.md §5). A consumer MUST preserve and enforce the absent-vs-empty distinction end to end; collapsing the two (e.g. by testing emptiness alone) re-creates the empty-means-unrestricted class of privilege-escalation defect this family's conventions exist to prevent.";
+                };
+                readonly label: {
+                    readonly type: "string";
+                    readonly description: "Optional human-readable label.";
+                };
+                readonly createdAt: {
+                    readonly type: "string";
+                    readonly format: "date-time";
+                };
+                readonly createdBy: {
+                    readonly type: "string";
+                    readonly description: "VID of the party that originally added this entry.";
+                };
+                readonly updatedAt: {
+                    readonly type: "string";
+                    readonly format: "date-time";
+                };
+                readonly updatedBy: {
+                    readonly type: "string";
+                    readonly description: "VID of the party that last modified this entry.";
+                };
+                readonly expiresAt: {
+                    readonly type: "string";
+                    readonly format: "date-time";
+                    readonly description: "Optional time after which the entry is no longer effective.";
+                };
+                readonly stepUp: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly description: "Per-entry authentication step-up configuration, consumed by the ACL maintainer when it gates an operation behind a step-up (see auth/step-up/policy/0.1). ADDITIVE-ONLY: a per-entry setting MAY raise the assurance required of this subject above the maintainer's system-wide floor, but MUST NOT lower it. The maintainer resolves the effective requirement as the strictest of (system floor, this entry).";
+                    readonly properties: {
+                        readonly approver: {
+                            readonly type: "string";
+                            readonly description: "VID authorized to ratify step-up for this subject — the `recipient` the maintainer addresses an auth/step-up/approve-request to (e.g. the holder's mobile authenticator or browser companion). Absent → the subject is its own approver (mode `self`) when it holds a usable authenticator; if neither an `approver` nor a self authenticator exists, no step-up method is available for this subject and the maintainer's fail-closed rule applies.";
+                        };
+                        readonly require: {
+                            readonly type: "string";
+                            readonly enum: readonly ["self", "delegated"];
+                            readonly description: "Minimum step-up mode this subject MUST satisfy for gated operations, raising the system floor. `self` = the subject re-authenticates its own session; `delegated` = a separate `approver` MUST ratify. Omitted → the system floor applies unchanged. A value weaker than the resolved floor is ignored (additive-only).";
+                        };
+                    };
+                };
+                readonly approve: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly description: "Approve-authority: what this subject may **confer on others** by ratifying an approval, as distinct from `scopes`, which is what it may **exercise itself**. The two axes are independent, and that independence is the point — it is what lets a maintainer configure a least-privilege approver who can authorize an operation in a scope it has no authority to perform.\n\nOMISSION MEANS NOTHING IS CONFERRED. An absent `approve`, an absent `all`, and an empty `scopes` are all equivalent to \"this subject may ratify nothing\". A consumer that does not implement this member therefore confers less than the producer intended rather than more, which is the direction a missed member has to fail in.\n\nA subject with approve-authority is NOT thereby authorized to act. Consumers MUST resolve the two axes separately: reading `approve` to answer \"may this party ratify X\" and `scopes` to answer \"may this party do X\". Collapsing them grants an approver the ability to perform what it was only meant to sign off on.";
+                    readonly properties: {
+                        readonly all: {
+                            readonly type: "boolean";
+                            readonly default: false;
+                            readonly description: "The subject may confer ANY scope. Takes precedence over `scopes`, which a consumer MUST ignore when this is true. Absent or false → only the scopes listed below, if any.";
+                        };
+                        readonly scopes: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                            readonly description: "Opaque scope identifiers this subject may confer, drawn from the same vocabulary as the entry's own `scopes`. Where a maintainer's scopes are hierarchical, conferring a scope confers its descendants — the same containment rule the maintainer already applies to `scopes`, so the two axes cannot disagree about what a scope means. An empty array confers nothing; it is not a wildcard.";
+                        };
+                    };
+                };
+                readonly ext: {
+                    readonly $ref: "#/$defs/Ext";
+                    readonly description: "Ecosystem-defined extension members per SPEC.md §4.5.1. Reverse-DNS-namespaced; consumers MUST ignore unrecognized namespaces.";
+                };
+            };
+        };
+    };
+};
+/** 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: "ACL Swap Key — response payload";
+            readonly description: "The post-swap AclEntry. Carried in a Trust Task document whose type is https://trusttasks.org/spec/acl/swap-key/0.1#response.";
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["entry", "previousSubject"];
+            readonly properties: {
+                readonly entry: {
+                    readonly $ref: "#/$defs/AclEntry";
+                    readonly description: "The AclEntry the maintainer now holds. `subject` equals the request's `newSubject`.";
+                };
+                readonly previousSubject: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly description: "Echo of the swapped-out VID. The maintainer has removed every artifact bound to this subject (refresh tokens, persistent sessions); the holder MUST NOT attempt to reuse it.";
+                };
+                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 AclEntry: {
+            readonly title: "AclEntry";
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["subject", "role"];
+            readonly properties: {
+                readonly subject: {
+                    readonly type: "string";
+                    readonly description: "VID of the party in the ACL. Compared by exact string equality (SPEC.md §4.8); producers SHOULD emit canonical form.";
+                };
+                readonly role: {
+                    readonly type: "string";
+                    readonly description: "Opaque role identifier interpreted by the ACL maintainer.";
+                };
+                readonly scopes: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "Opaque scope identifiers (e.g. contexts, domains, resource prefixes).";
+                };
+                readonly allowedKeys: {
+                    readonly type: readonly ["array", "null"];
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "Key identifiers this subject may invoke the maintainer's signing oracle on. INTERSECTS WITH `scopes` — it can only narrow, never widen: a key named here that lies outside the entry's scopes remains unreachable, exactly as if it were not named. ABSENT means every key within the entry's scopes (the behaviour of entries that pre-date this member); explicit `null` is equivalent to absent, and producers SHOULD omit the member instead. PRESENT-BUT-EMPTY means authorized on NO keys — the opposite of absent, and deliberately so: emptiness is never a wildcard (CONVENTIONS.md §5). A consumer MUST preserve and enforce the absent-vs-empty distinction end to end; collapsing the two (e.g. by testing emptiness alone) re-creates the empty-means-unrestricted class of privilege-escalation defect this family's conventions exist to prevent.";
+                };
+                readonly label: {
+                    readonly type: "string";
+                    readonly description: "Optional human-readable label.";
+                };
+                readonly createdAt: {
+                    readonly type: "string";
+                    readonly format: "date-time";
+                };
+                readonly createdBy: {
+                    readonly type: "string";
+                    readonly description: "VID of the party that originally added this entry.";
+                };
+                readonly updatedAt: {
+                    readonly type: "string";
+                    readonly format: "date-time";
+                };
+                readonly updatedBy: {
+                    readonly type: "string";
+                    readonly description: "VID of the party that last modified this entry.";
+                };
+                readonly expiresAt: {
+                    readonly type: "string";
+                    readonly format: "date-time";
+                    readonly description: "Optional time after which the entry is no longer effective.";
+                };
+                readonly stepUp: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly description: "Per-entry authentication step-up configuration, consumed by the ACL maintainer when it gates an operation behind a step-up (see auth/step-up/policy/0.1). ADDITIVE-ONLY: a per-entry setting MAY raise the assurance required of this subject above the maintainer's system-wide floor, but MUST NOT lower it. The maintainer resolves the effective requirement as the strictest of (system floor, this entry).";
+                    readonly properties: {
+                        readonly approver: {
+                            readonly type: "string";
+                            readonly description: "VID authorized to ratify step-up for this subject — the `recipient` the maintainer addresses an auth/step-up/approve-request to (e.g. the holder's mobile authenticator or browser companion). Absent → the subject is its own approver (mode `self`) when it holds a usable authenticator; if neither an `approver` nor a self authenticator exists, no step-up method is available for this subject and the maintainer's fail-closed rule applies.";
+                        };
+                        readonly require: {
+                            readonly type: "string";
+                            readonly enum: readonly ["self", "delegated"];
+                            readonly description: "Minimum step-up mode this subject MUST satisfy for gated operations, raising the system floor. `self` = the subject re-authenticates its own session; `delegated` = a separate `approver` MUST ratify. Omitted → the system floor applies unchanged. A value weaker than the resolved floor is ignored (additive-only).";
+                        };
+                    };
+                };
+                readonly approve: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly description: "Approve-authority: what this subject may **confer on others** by ratifying an approval, as distinct from `scopes`, which is what it may **exercise itself**. The two axes are independent, and that independence is the point — it is what lets a maintainer configure a least-privilege approver who can authorize an operation in a scope it has no authority to perform.\n\nOMISSION MEANS NOTHING IS CONFERRED. An absent `approve`, an absent `all`, and an empty `scopes` are all equivalent to \"this subject may ratify nothing\". A consumer that does not implement this member therefore confers less than the producer intended rather than more, which is the direction a missed member has to fail in.\n\nA subject with approve-authority is NOT thereby authorized to act. Consumers MUST resolve the two axes separately: reading `approve` to answer \"may this party ratify X\" and `scopes` to answer \"may this party do X\". Collapsing them grants an approver the ability to perform what it was only meant to sign off on.";
+                    readonly properties: {
+                        readonly all: {
+                            readonly type: "boolean";
+                            readonly default: false;
+                            readonly description: "The subject may confer ANY scope. Takes precedence over `scopes`, which a consumer MUST ignore when this is true. Absent or false → only the scopes listed below, if any.";
+                        };
+                        readonly scopes: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                            readonly description: "Opaque scope identifiers this subject may confer, drawn from the same vocabulary as the entry's own `scopes`. Where a maintainer's scopes are hierarchical, conferring a scope confers its descendants — the same containment rule the maintainer already applies to `scopes`, so the two axes cannot disagree about what a scope means. An empty array confers nothing; it is not a wildcard.";
+                        };
+                    };
+                };
+                readonly ext: {
+                    readonly $ref: "#/$defs/Ext";
+                    readonly description: "Ecosystem-defined extension members per SPEC.md §4.5.1. Reverse-DNS-namespaced; consumers MUST ignore unrecognized namespaces.";
+                };
+            };
+        };
+    };
+};
 /**
  * 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/acl/swap-key/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/acl/swap-key/0.1";
+        readonly title: "ACL — Swap Key";
+        readonly description: "An ACL holder atomically replaces the VID bound to one of their own AclEntries with a new VID — typically a different DID under their control. The maintainer applies the swap as a single transaction: there is no window where both VIDs have access or neither does.";
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["currentSubject", "newSubject"];
+        readonly properties: {
+            readonly currentSubject: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly description: "The VID currently bound in the ACL. MUST equal the document's `issuer` (per the conformance section: the holder swaps THEIR OWN entry).";
+            };
+            readonly newSubject: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly description: "The VID to bind in place of `currentSubject`. The maintainer's policy decides admissibility (e.g. acceptable DID method, required attestations); the wire spec only requires `newSubject !== currentSubject`.";
+            };
+            readonly linkProof: {
+                readonly description: "Cryptographic evidence — required by some maintainers — that the new VID consents to taking over. Format is consumer-defined; a typical shape is a Trust Task or VP/VC signed by `newSubject` carrying a fresh nonce from the maintainer or the holder. Producers omit this when the consumer's policy doesn't require it. Format described in the spec body.";
+                readonly type: readonly ["object", "string"];
+            };
+            readonly reason: {
+                readonly type: "string";
+                readonly description: "Optional human-readable rationale (e.g. \"key-rotation\", \"hardware-token-replacement\", \"account-recovery\").";
+            };
+            readonly ext: {
+                readonly $ref: "#/$defs/Ext";
+                readonly description: "Ecosystem-defined extension members per SPEC.md §4.5.1.";
+            };
+        };
+        readonly $defs: {
+            readonly Response: {
+                readonly $anchor: "response";
+                readonly title: "ACL Swap Key — response payload";
+                readonly description: "The post-swap AclEntry. Carried in a Trust Task document whose type is https://trusttasks.org/spec/acl/swap-key/0.1#response.";
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["entry", "previousSubject"];
+                readonly properties: {
+                    readonly entry: {
+                        readonly $ref: "#/$defs/AclEntry";
+                        readonly description: "The AclEntry the maintainer now holds. `subject` equals the request's `newSubject`.";
+                    };
+                    readonly previousSubject: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly description: "Echo of the swapped-out VID. The maintainer has removed every artifact bound to this subject (refresh tokens, persistent sessions); the holder MUST NOT attempt to reuse it.";
+                    };
+                    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 AclEntry: {
+                readonly title: "AclEntry";
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["subject", "role"];
+                readonly properties: {
+                    readonly subject: {
+                        readonly type: "string";
+                        readonly description: "VID of the party in the ACL. Compared by exact string equality (SPEC.md §4.8); producers SHOULD emit canonical form.";
+                    };
+                    readonly role: {
+                        readonly type: "string";
+                        readonly description: "Opaque role identifier interpreted by the ACL maintainer.";
+                    };
+                    readonly scopes: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                        readonly description: "Opaque scope identifiers (e.g. contexts, domains, resource prefixes).";
+                    };
+                    readonly allowedKeys: {
+                        readonly type: readonly ["array", "null"];
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                        readonly description: "Key identifiers this subject may invoke the maintainer's signing oracle on. INTERSECTS WITH `scopes` — it can only narrow, never widen: a key named here that lies outside the entry's scopes remains unreachable, exactly as if it were not named. ABSENT means every key within the entry's scopes (the behaviour of entries that pre-date this member); explicit `null` is equivalent to absent, and producers SHOULD omit the member instead. PRESENT-BUT-EMPTY means authorized on NO keys — the opposite of absent, and deliberately so: emptiness is never a wildcard (CONVENTIONS.md §5). A consumer MUST preserve and enforce the absent-vs-empty distinction end to end; collapsing the two (e.g. by testing emptiness alone) re-creates the empty-means-unrestricted class of privilege-escalation defect this family's conventions exist to prevent.";
+                    };
+                    readonly label: {
+                        readonly type: "string";
+                        readonly description: "Optional human-readable label.";
+                    };
+                    readonly createdAt: {
+                        readonly type: "string";
+                        readonly format: "date-time";
+                    };
+                    readonly createdBy: {
+                        readonly type: "string";
+                        readonly description: "VID of the party that originally added this entry.";
+                    };
+                    readonly updatedAt: {
+                        readonly type: "string";
+                        readonly format: "date-time";
+                    };
+                    readonly updatedBy: {
+                        readonly type: "string";
+                        readonly description: "VID of the party that last modified this entry.";
+                    };
+                    readonly expiresAt: {
+                        readonly type: "string";
+                        readonly format: "date-time";
+                        readonly description: "Optional time after which the entry is no longer effective.";
+                    };
+                    readonly stepUp: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly description: "Per-entry authentication step-up configuration, consumed by the ACL maintainer when it gates an operation behind a step-up (see auth/step-up/policy/0.1). ADDITIVE-ONLY: a per-entry setting MAY raise the assurance required of this subject above the maintainer's system-wide floor, but MUST NOT lower it. The maintainer resolves the effective requirement as the strictest of (system floor, this entry).";
+                        readonly properties: {
+                            readonly approver: {
+                                readonly type: "string";
+                                readonly description: "VID authorized to ratify step-up for this subject — the `recipient` the maintainer addresses an auth/step-up/approve-request to (e.g. the holder's mobile authenticator or browser companion). Absent → the subject is its own approver (mode `self`) when it holds a usable authenticator; if neither an `approver` nor a self authenticator exists, no step-up method is available for this subject and the maintainer's fail-closed rule applies.";
+                            };
+                            readonly require: {
+                                readonly type: "string";
+                                readonly enum: readonly ["self", "delegated"];
+                                readonly description: "Minimum step-up mode this subject MUST satisfy for gated operations, raising the system floor. `self` = the subject re-authenticates its own session; `delegated` = a separate `approver` MUST ratify. Omitted → the system floor applies unchanged. A value weaker than the resolved floor is ignored (additive-only).";
+                            };
+                        };
+                    };
+                    readonly approve: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly description: "Approve-authority: what this subject may **confer on others** by ratifying an approval, as distinct from `scopes`, which is what it may **exercise itself**. The two axes are independent, and that independence is the point — it is what lets a maintainer configure a least-privilege approver who can authorize an operation in a scope it has no authority to perform.\n\nOMISSION MEANS NOTHING IS CONFERRED. An absent `approve`, an absent `all`, and an empty `scopes` are all equivalent to \"this subject may ratify nothing\". A consumer that does not implement this member therefore confers less than the producer intended rather than more, which is the direction a missed member has to fail in.\n\nA subject with approve-authority is NOT thereby authorized to act. Consumers MUST resolve the two axes separately: reading `approve` to answer \"may this party ratify X\" and `scopes` to answer \"may this party do X\". Collapsing them grants an approver the ability to perform what it was only meant to sign off on.";
+                        readonly properties: {
+                            readonly all: {
+                                readonly type: "boolean";
+                                readonly default: false;
+                                readonly description: "The subject may confer ANY scope. Takes precedence over `scopes`, which a consumer MUST ignore when this is true. Absent or false → only the scopes listed below, if any.";
+                            };
+                            readonly scopes: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "string";
+                                };
+                                readonly description: "Opaque scope identifiers this subject may confer, drawn from the same vocabulary as the entry's own `scopes`. Where a maintainer's scopes are hierarchical, conferring a scope confers its descendants — the same containment rule the maintainer already applies to `scopes`, so the two axes cannot disagree about what a scope means. An empty array confers nothing; it is not a wildcard.";
+                            };
+                        };
+                    };
+                    readonly ext: {
+                        readonly $ref: "#/$defs/Ext";
+                        readonly description: "Ecosystem-defined extension members per SPEC.md §4.5.1. Reverse-DNS-namespaced; consumers MUST ignore unrecognized namespaces.";
+                    };
+                };
+            };
+        };
+    };
 };
 /**
  * SPEC.md §7.2 policy for the success-response variant. `isRecipientRequired`
@@ -152,5 +617,137 @@ 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: "ACL Swap Key — response payload";
+                readonly description: "The post-swap AclEntry. Carried in a Trust Task document whose type is https://trusttasks.org/spec/acl/swap-key/0.1#response.";
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["entry", "previousSubject"];
+                readonly properties: {
+                    readonly entry: {
+                        readonly $ref: "#/$defs/AclEntry";
+                        readonly description: "The AclEntry the maintainer now holds. `subject` equals the request's `newSubject`.";
+                    };
+                    readonly previousSubject: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly description: "Echo of the swapped-out VID. The maintainer has removed every artifact bound to this subject (refresh tokens, persistent sessions); the holder MUST NOT attempt to reuse it.";
+                    };
+                    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 AclEntry: {
+                readonly title: "AclEntry";
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["subject", "role"];
+                readonly properties: {
+                    readonly subject: {
+                        readonly type: "string";
+                        readonly description: "VID of the party in the ACL. Compared by exact string equality (SPEC.md §4.8); producers SHOULD emit canonical form.";
+                    };
+                    readonly role: {
+                        readonly type: "string";
+                        readonly description: "Opaque role identifier interpreted by the ACL maintainer.";
+                    };
+                    readonly scopes: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                        readonly description: "Opaque scope identifiers (e.g. contexts, domains, resource prefixes).";
+                    };
+                    readonly allowedKeys: {
+                        readonly type: readonly ["array", "null"];
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                        readonly description: "Key identifiers this subject may invoke the maintainer's signing oracle on. INTERSECTS WITH `scopes` — it can only narrow, never widen: a key named here that lies outside the entry's scopes remains unreachable, exactly as if it were not named. ABSENT means every key within the entry's scopes (the behaviour of entries that pre-date this member); explicit `null` is equivalent to absent, and producers SHOULD omit the member instead. PRESENT-BUT-EMPTY means authorized on NO keys — the opposite of absent, and deliberately so: emptiness is never a wildcard (CONVENTIONS.md §5). A consumer MUST preserve and enforce the absent-vs-empty distinction end to end; collapsing the two (e.g. by testing emptiness alone) re-creates the empty-means-unrestricted class of privilege-escalation defect this family's conventions exist to prevent.";
+                    };
+                    readonly label: {
+                        readonly type: "string";
+                        readonly description: "Optional human-readable label.";
+                    };
+                    readonly createdAt: {
+                        readonly type: "string";
+                        readonly format: "date-time";
+                    };
+                    readonly createdBy: {
+                        readonly type: "string";
+                        readonly description: "VID of the party that originally added this entry.";
+                    };
+                    readonly updatedAt: {
+                        readonly type: "string";
+                        readonly format: "date-time";
+                    };
+                    readonly updatedBy: {
+                        readonly type: "string";
+                        readonly description: "VID of the party that last modified this entry.";
+                    };
+                    readonly expiresAt: {
+                        readonly type: "string";
+                        readonly format: "date-time";
+                        readonly description: "Optional time after which the entry is no longer effective.";
+                    };
+                    readonly stepUp: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly description: "Per-entry authentication step-up configuration, consumed by the ACL maintainer when it gates an operation behind a step-up (see auth/step-up/policy/0.1). ADDITIVE-ONLY: a per-entry setting MAY raise the assurance required of this subject above the maintainer's system-wide floor, but MUST NOT lower it. The maintainer resolves the effective requirement as the strictest of (system floor, this entry).";
+                        readonly properties: {
+                            readonly approver: {
+                                readonly type: "string";
+                                readonly description: "VID authorized to ratify step-up for this subject — the `recipient` the maintainer addresses an auth/step-up/approve-request to (e.g. the holder's mobile authenticator or browser companion). Absent → the subject is its own approver (mode `self`) when it holds a usable authenticator; if neither an `approver` nor a self authenticator exists, no step-up method is available for this subject and the maintainer's fail-closed rule applies.";
+                            };
+                            readonly require: {
+                                readonly type: "string";
+                                readonly enum: readonly ["self", "delegated"];
+                                readonly description: "Minimum step-up mode this subject MUST satisfy for gated operations, raising the system floor. `self` = the subject re-authenticates its own session; `delegated` = a separate `approver` MUST ratify. Omitted → the system floor applies unchanged. A value weaker than the resolved floor is ignored (additive-only).";
+                            };
+                        };
+                    };
+                    readonly approve: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly description: "Approve-authority: what this subject may **confer on others** by ratifying an approval, as distinct from `scopes`, which is what it may **exercise itself**. The two axes are independent, and that independence is the point — it is what lets a maintainer configure a least-privilege approver who can authorize an operation in a scope it has no authority to perform.\n\nOMISSION MEANS NOTHING IS CONFERRED. An absent `approve`, an absent `all`, and an empty `scopes` are all equivalent to \"this subject may ratify nothing\". A consumer that does not implement this member therefore confers less than the producer intended rather than more, which is the direction a missed member has to fail in.\n\nA subject with approve-authority is NOT thereby authorized to act. Consumers MUST resolve the two axes separately: reading `approve` to answer \"may this party ratify X\" and `scopes` to answer \"may this party do X\". Collapsing them grants an approver the ability to perform what it was only meant to sign off on.";
+                        readonly properties: {
+                            readonly all: {
+                                readonly type: "boolean";
+                                readonly default: false;
+                                readonly description: "The subject may confer ANY scope. Takes precedence over `scopes`, which a consumer MUST ignore when this is true. Absent or false → only the scopes listed below, if any.";
+                            };
+                            readonly scopes: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "string";
+                                };
+                                readonly description: "Opaque scope identifiers this subject may confer, drawn from the same vocabulary as the entry's own `scopes`. Where a maintainer's scopes are hierarchical, conferring a scope confers its descendants — the same containment rule the maintainer already applies to `scopes`, so the two axes cannot disagree about what a scope means. An empty array confers nothing; it is not a wildcard.";
+                            };
+                        };
+                    };
+                    readonly ext: {
+                        readonly $ref: "#/$defs/Ext";
+                        readonly description: "Ecosystem-defined extension members per SPEC.md §4.5.1. Reverse-DNS-namespaced; consumers MUST ignore unrecognized namespaces.";
+                    };
+                };
+            };
+        };
+    };
 };
 //# sourceMappingURL=payload.d.ts.map

package/dist/acl/swap-key/0.1/payload.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"payload.d.ts","sourceRoot":"","sources":["../../../../src/acl/swap-key/0.1/payload.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,SAAS,CAAC,EAAE,EAAE,GAAG,MAAM,CAAC;IACxB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,GAAG,CAAC;CACX;AACD;;GAEG;AACH,MAAM,WAAW,GAAG;IAClB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CAClC;AACD;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,QAAQ,CAAC;IAChB;;OAEG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AACD;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC9B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,MAAM,CAAC,EAAE;QACP;;WAEG;QACH,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB;;WAEG;QACH,OAAO,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;KAChC,CAAC;IACF;;;;;;OAMG;IACH,OAAO,CAAC,EAAE;QACR;;WAEG;QACH,GAAG,CAAC,EAAE,OAAO,CAAC;QACd;;WAEG;QACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;KACnB,CAAC;IACF,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AACD;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CAClC;AACD;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CAClC;AAED,2BAA2B;AAC3B,eAAO,MAAM,QAAQ,EAAG,8CAAuD,CAAC;AAEhF,mEAAmE;AACnE,MAAM,MAAM,OAAO,GAAG,UAAU,CAAC;AAEjC,qEAAqE;AACrE,eAAO,MAAM,iBAAiB,EAAG,uDAAgE,CAAC;AAElG,4EAA4E;AAC5E,MAAM,MAAM,QAAQ,GAAG,yBAAyB,CAAC;AAEjD;;;;GAIG;AACH,eAAO,MAAM,IAAI;;;;;CAKP,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,aAAa;;;;;CAKhB,CAAC"}
+{"version":3,"file":"payload.d.ts","sourceRoot":"","sources":["../../../../src/acl/swap-key/0.1/payload.ts"],"names":[],"mappings":"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"}