@openvtc/trust-tasks 0.22.5 → 0.22.7

package/src/auth/step-up/approver/invite/0.1/payload.ts

@@ -0,0 +1,258 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/auth/step-up/approver/invite/0.1/payload.schema.json
+ */
+
+import type { ApproverLabel, Ext } from "../../../../../_shared/components.js";
+
+
+/**
+ * An administrator asks the relying party for a single-use invite, redeemed by the invited subject with a separately delivered claim code, to bind a step-up approver to that subject. The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, proof) are owned by the framework — SPEC §6.3.
+ */
+export interface AuthStepUpApproverInvitePayload {
+  /**
+   * The DID invited to bind a step-up approver. MUST be a subject the relying party recognises, and MUST NOT be the administrator issuing the invite.
+   */
+  subject: string;
+  /**
+   * A suggested label for the approver. The subject MAY override it at redeem/finish.
+   */
+  label?: ApproverLabel;
+  /**
+   * Seconds the invite stays redeemable. Default 900 (15 minutes). The relying party refuses more than 86400 (24 hours), or more than its own lower cap, with `ttlTooLong`.
+   */
+  ttl?: number;
+  ext?: Ext;
+}
+/**
+ * The issued invite. The claim code is returned only here.
+ */
+export interface AuthStepUpApproverInviteResponsePayload {
+  /**
+   * The relying party's identifier for the invite, for audit and administration. Not a redemption factor: it is neither the token nor derivable from it.
+   */
+  inviteId: string;
+  /**
+   * Where the invited subject redeems the invite. Carries the single-use token (≥128 bits). MUST NOT carry the claim code.
+   */
+  url: string;
+  /**
+   * A short code (≥40 bits) the invited subject types at redemption, returned exactly once. Delivered by the administrator over a different channel from `url`. The relying party stores only a slow hash of it.
+   */
+  claimCode: string;
+  /**
+   * When the invite stops being redeemable.
+   */
+  expiresAt: string;
+  ext?: Ext;
+}
+
+/** Shared definitions this specification references, re-exported under the names it used to declare them with. */
+export type { ApproverLabel, Ext };
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/auth/step-up/approver/invite/0.1" as const;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = AuthStepUpApproverInvitePayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/auth/step-up/approver/invite/0.1#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = AuthStepUpApproverInviteResponsePayload;
+
+/**
+ * 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 const PAYLOAD_SCHEMA = {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://trusttasks.org/spec/auth/step-up/approver/invite/0.1",
+  "title": "Auth — Step-up Approver Invite — payload",
+  "description": "An administrator asks the relying party for a single-use invite, redeemed by the invited subject with a separately delivered claim code, to bind a step-up approver to that subject. The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, proof) are owned by the framework — SPEC §6.3.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "subject"
+  ],
+  "properties": {
+    "subject": {
+      "type": "string",
+      "pattern": "^did:",
+      "minLength": 5,
+      "maxLength": 2048,
+      "description": "The DID invited to bind a step-up approver. MUST be a subject the relying party recognises, and MUST NOT be the administrator issuing the invite."
+    },
+    "label": {
+      "$ref": "#/$defs/ApproverLabel",
+      "description": "A suggested label for the approver. The subject MAY override it at redeem/finish."
+    },
+    "ttl": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Seconds the invite stays redeemable. Default 900 (15 minutes). The relying party refuses more than 86400 (24 hours), or more than its own lower cap, with `ttlTooLong`."
+    },
+    "ext": {
+      "$ref": "#/$defs/Ext"
+    }
+  },
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "Auth — Step-up Approver Invite — response payload",
+      "description": "The issued invite. The claim code is returned only here.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "inviteId",
+        "url",
+        "claimCode",
+        "expiresAt"
+      ],
+      "properties": {
+        "inviteId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "The relying party's identifier for the invite, for audit and administration. Not a redemption factor: it is neither the token nor derivable from it."
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Where the invited subject redeems the invite. Carries the single-use token (≥128 bits). MUST NOT carry the claim code."
+        },
+        "claimCode": {
+          "type": "string",
+          "minLength": 8,
+          "maxLength": 64,
+          "description": "A short code (≥40 bits) the invited subject types at redemption, returned exactly once. Delivered by the administrator over a different channel from `url`. The relying party stores only a slow hash of it."
+        },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the invite stops being redeemable."
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext"
+        }
+      }
+    },
+    "Ext": {
+      "title": "Ext",
+      "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.",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": true,
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$"
+      }
+    },
+    "ApproverLabel": {
+      "title": "ApproverLabel",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "description": "A human-readable name for where the approver lives — e.g. `Browser plugin — work laptop`. Chosen by the subject (or suggested by an inviter), untrusted, and attributed to its author wherever it is rendered. Absent rather than invented when none was chosen."
+    }
+  }
+} as const;
+
+/** As {@link PAYLOAD_SCHEMA}, for the success-response variant. */
+export const RESPONSE_PAYLOAD_SCHEMA = {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$ref": "#/$defs/Response",
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "Auth — Step-up Approver Invite — response payload",
+      "description": "The issued invite. The claim code is returned only here.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "inviteId",
+        "url",
+        "claimCode",
+        "expiresAt"
+      ],
+      "properties": {
+        "inviteId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "The relying party's identifier for the invite, for audit and administration. Not a redemption factor: it is neither the token nor derivable from it."
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Where the invited subject redeems the invite. Carries the single-use token (≥128 bits). MUST NOT carry the claim code."
+        },
+        "claimCode": {
+          "type": "string",
+          "minLength": 8,
+          "maxLength": 64,
+          "description": "A short code (≥40 bits) the invited subject types at redemption, returned exactly once. Delivered by the administrator over a different channel from `url`. The relying party stores only a slow hash of it."
+        },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the invite stops being redeemable."
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext"
+        }
+      }
+    },
+    "Ext": {
+      "title": "Ext",
+      "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.",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": true,
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$"
+      }
+    },
+    "ApproverLabel": {
+      "title": "ApproverLabel",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "description": "A human-readable name for where the approver lives — e.g. `Browser plugin — work laptop`. Chosen by the subject (or suggested by an inviter), untrusted, and attributed to its author wherever it is rendered. Absent rather than invented when none was chosen."
+    }
+  }
+} as const;
+
+/**
+ * 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, and
+ * item 2 needs the schema this carries.
+ */
+export const SPEC = {
+  typeUri: TYPE_URI,
+  isBearer: false,
+  isProofRequired: true,
+  isRecipientRequired: true,
+  isIssuedAtRequired: true,
+  payloadSchema: PAYLOAD_SCHEMA,
+} as const;
+
+/**
+ * SPEC.md §7.2 policy for the success-response variant. `isRecipientRequired`
+ * tracks the *issuer* party's requirement because a response swaps the
+ * parties (§7.3 item 5).
+ */
+export const RESPONSE_SPEC = {
+  typeUri: RESPONSE_TYPE_URI,
+  isBearer: false,
+  isProofRequired: true,
+  isRecipientRequired: true,
+  isIssuedAtRequired: true,
+  payloadSchema: RESPONSE_PAYLOAD_SCHEMA,
+} as const;

package/src/auth/step-up/approver/list/0.1/payload.ts

@@ -0,0 +1,318 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/auth/step-up/approver/list/0.1/payload.schema.json
+ */
+
+import type { Approver, ApproverDid, ApproverLabel, EnrolledVia, Ext } from "../../../../../_shared/components.js";
+
+
+/**
+ * List the live step-up approvers bound to one subject — the caller by default, or another subject within an administrator's authority. The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, proof) are owned by the framework — SPEC §6.3.
+ */
+export interface AuthStepUpApproverListPayload {
+  /**
+   * Whose approvers to list. Absent means the caller. A subject other than the caller is answered only for an administrator whose standing covers it.
+   */
+  subject?: string;
+  ext?: Ext;
+}
+/**
+ * Every live approver bound to the subject. Empty when the subject holds none.
+ */
+export interface AuthStepUpApproverListResponsePayload {
+  /**
+   * The subject's live approvers — at most five, so the whole set is always returned.
+   *
+   * @maxItems 5
+   */
+  approvers:
+    | []
+    | [Approver]
+    | [Approver, Approver]
+    | [Approver, Approver, Approver]
+    | [Approver, Approver, Approver, Approver]
+    | [Approver, Approver, Approver, Approver, Approver];
+  ext?: Ext;
+}
+
+/** Shared definitions this specification references, re-exported under the names it used to declare them with. */
+export type { Approver, ApproverDid, ApproverLabel, EnrolledVia, Ext };
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/auth/step-up/approver/list/0.1" as const;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = AuthStepUpApproverListPayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/auth/step-up/approver/list/0.1#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = AuthStepUpApproverListResponsePayload;
+
+/**
+ * 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 const PAYLOAD_SCHEMA = {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://trusttasks.org/spec/auth/step-up/approver/list/0.1",
+  "title": "Auth — Step-up Approver List — payload",
+  "description": "List the live step-up approvers bound to one subject — the caller by default, or another subject within an administrator's authority. The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, proof) are owned by the framework — SPEC §6.3.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "subject": {
+      "type": "string",
+      "pattern": "^did:",
+      "minLength": 5,
+      "maxLength": 2048,
+      "description": "Whose approvers to list. Absent means the caller. A subject other than the caller is answered only for an administrator whose standing covers it."
+    },
+    "ext": {
+      "$ref": "#/$defs/Ext"
+    }
+  },
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "Auth — Step-up Approver List — response payload",
+      "description": "Every live approver bound to the subject. Empty when the subject holds none.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "approvers"
+      ],
+      "properties": {
+        "approvers": {
+          "type": "array",
+          "maxItems": 5,
+          "items": {
+            "$ref": "#/$defs/Approver"
+          },
+          "description": "The subject's live approvers — at most five, so the whole set is always returned."
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext"
+        }
+      }
+    },
+    "Ext": {
+      "title": "Ext",
+      "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.",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": true,
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$"
+      }
+    },
+    "Approver": {
+      "title": "Approver",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "approverDid",
+        "subject",
+        "enrolledAt",
+        "enrolledVia"
+      ],
+      "description": "One step-up approver binding, as its subject or an administrator sees it. The binding confers nothing of its own: it is read only when the relying party checks the evidence of a step-up asked of `subject`.",
+      "properties": {
+        "approverDid": {
+          "$ref": "#/$defs/ApproverDid"
+        },
+        "subject": {
+          "type": "string",
+          "pattern": "^did:",
+          "minLength": 5,
+          "maxLength": 2048,
+          "description": "The one subject DID this approver is bound to. An approver DID is bound to at most one subject at a relying party."
+        },
+        "label": {
+          "$ref": "#/$defs/ApproverLabel"
+        },
+        "enrolledAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the binding was written."
+        },
+        "enrolledVia": {
+          "$ref": "#/$defs/EnrolledVia"
+        },
+        "lastUsedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When a statement by this approver last satisfied a step-up. Absent when it never has."
+        }
+      }
+    },
+    "EnrolledVia": {
+      "title": "EnrolledVia",
+      "type": "string",
+      "enum": [
+        "install",
+        "invite",
+        "selfService",
+        "offline"
+      ],
+      "description": "The anchor the binding rested on, recorded so an incident review can see how each factor came to exist. `install`: claimed with the community's install token (vtc/install/claim/finish/0.3). `invite`: redeemed from an administrator's invite (auth/step-up/approver/redeem/finish/0.1). `selfService`: added by the subject behind a factor they already held (auth/step-up/approver/enroll/0.1). `offline`: redeemed from an invite minted by the operator with host access while the service was stopped — an `invite`-shaped redemption whose issuer was the host rather than an administrator."
+    },
+    "ApproverLabel": {
+      "title": "ApproverLabel",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "description": "A human-readable name for where the approver lives — e.g. `Browser plugin — work laptop`. Chosen by the subject (or suggested by an inviter), untrusted, and attributed to its author wherever it is rendered. Absent rather than invented when none was chosen."
+    },
+    "ApproverDid": {
+      "title": "ApproverDid",
+      "type": "string",
+      "minLength": 16,
+      "maxLength": 128,
+      "pattern": "^did:key:z6Mk[1-9A-HJ-NP-Za-km-z]+$",
+      "description": "A step-up approver, as an Ed25519 `did:key` (`z6Mk…`). `did:key` only, because its document is a function of the key and resolves with no network, so verifying an approver's statement never depends on a fetch, and a key whose DID document could be rewritten after enrolment would not be the key that was enrolled. Distinct from the subject's DID, from every verification method in the subject's DID document, and from every key the subject can sign operations with at the relying party."
+    }
+  }
+} as const;
+
+/** As {@link PAYLOAD_SCHEMA}, for the success-response variant. */
+export const RESPONSE_PAYLOAD_SCHEMA = {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$ref": "#/$defs/Response",
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "Auth — Step-up Approver List — response payload",
+      "description": "Every live approver bound to the subject. Empty when the subject holds none.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "approvers"
+      ],
+      "properties": {
+        "approvers": {
+          "type": "array",
+          "maxItems": 5,
+          "items": {
+            "$ref": "#/$defs/Approver"
+          },
+          "description": "The subject's live approvers — at most five, so the whole set is always returned."
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext"
+        }
+      }
+    },
+    "Ext": {
+      "title": "Ext",
+      "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.",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": true,
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$"
+      }
+    },
+    "Approver": {
+      "title": "Approver",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "approverDid",
+        "subject",
+        "enrolledAt",
+        "enrolledVia"
+      ],
+      "description": "One step-up approver binding, as its subject or an administrator sees it. The binding confers nothing of its own: it is read only when the relying party checks the evidence of a step-up asked of `subject`.",
+      "properties": {
+        "approverDid": {
+          "$ref": "#/$defs/ApproverDid"
+        },
+        "subject": {
+          "type": "string",
+          "pattern": "^did:",
+          "minLength": 5,
+          "maxLength": 2048,
+          "description": "The one subject DID this approver is bound to. An approver DID is bound to at most one subject at a relying party."
+        },
+        "label": {
+          "$ref": "#/$defs/ApproverLabel"
+        },
+        "enrolledAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the binding was written."
+        },
+        "enrolledVia": {
+          "$ref": "#/$defs/EnrolledVia"
+        },
+        "lastUsedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When a statement by this approver last satisfied a step-up. Absent when it never has."
+        }
+      }
+    },
+    "EnrolledVia": {
+      "title": "EnrolledVia",
+      "type": "string",
+      "enum": [
+        "install",
+        "invite",
+        "selfService",
+        "offline"
+      ],
+      "description": "The anchor the binding rested on, recorded so an incident review can see how each factor came to exist. `install`: claimed with the community's install token (vtc/install/claim/finish/0.3). `invite`: redeemed from an administrator's invite (auth/step-up/approver/redeem/finish/0.1). `selfService`: added by the subject behind a factor they already held (auth/step-up/approver/enroll/0.1). `offline`: redeemed from an invite minted by the operator with host access while the service was stopped — an `invite`-shaped redemption whose issuer was the host rather than an administrator."
+    },
+    "ApproverLabel": {
+      "title": "ApproverLabel",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "description": "A human-readable name for where the approver lives — e.g. `Browser plugin — work laptop`. Chosen by the subject (or suggested by an inviter), untrusted, and attributed to its author wherever it is rendered. Absent rather than invented when none was chosen."
+    },
+    "ApproverDid": {
+      "title": "ApproverDid",
+      "type": "string",
+      "minLength": 16,
+      "maxLength": 128,
+      "pattern": "^did:key:z6Mk[1-9A-HJ-NP-Za-km-z]+$",
+      "description": "A step-up approver, as an Ed25519 `did:key` (`z6Mk…`). `did:key` only, because its document is a function of the key and resolves with no network, so verifying an approver's statement never depends on a fetch, and a key whose DID document could be rewritten after enrolment would not be the key that was enrolled. Distinct from the subject's DID, from every verification method in the subject's DID document, and from every key the subject can sign operations with at the relying party."
+    }
+  }
+} as const;
+
+/**
+ * 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, and
+ * item 2 needs the schema this carries.
+ */
+export const SPEC = {
+  typeUri: TYPE_URI,
+  isBearer: false,
+  isProofRequired: true,
+  isRecipientRequired: true,
+  isIssuedAtRequired: false,
+  payloadSchema: PAYLOAD_SCHEMA,
+} as const;
+
+/**
+ * SPEC.md §7.2 policy for the success-response variant. `isRecipientRequired`
+ * tracks the *issuer* party's requirement because a response swaps the
+ * parties (§7.3 item 5).
+ */
+export const RESPONSE_SPEC = {
+  typeUri: RESPONSE_TYPE_URI,
+  isBearer: false,
+  isProofRequired: true,
+  isRecipientRequired: true,
+  isIssuedAtRequired: false,
+  payloadSchema: RESPONSE_PAYLOAD_SCHEMA,
+} as const;