@openvtc/trust-tasks 0.23.8 → 0.24.0

package/src/auth/oob/identify/0.1/payload.ts

@@ -0,0 +1,110 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/auth/oob/identify/0.1/payload.schema.json
+ */
+
+import type { MatchNumber, OobKey, RequestId } from "../../../../_shared/components.js";
+
+
+/**
+ * A member's DID states that it holds the lock on one out-of-band request and can see the starter's screen. Issued by the approving DID and signed by its VTA for `authentication`; never sent on its own, only carried inside auth/oob/prove. Closed: additionalProperties false and no `ext`, so a VTA that signs it without user verification signs exactly these three members and nothing else. The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, proof) are owned by the framework — SPEC §6.3.
+ */
+export interface AuthOOBIdentifyPayload {
+  /**
+   * The request being proved for. MUST equal the requestId of the prove that carries this document.
+   */
+  requestId: RequestId;
+  /**
+   * The lock key `K_a`. MUST equal the issuer of the prove that carries this document, so the document cannot be re-wrapped by another device.
+   */
+  approverKey: OobKey;
+  /**
+   * The two digits the member typed from the starter's screen.
+   */
+  enteredNumber: MatchNumber;
+}
+
+/** Shared definitions this specification references, re-exported under the names it used to declare them with. */
+export type { MatchNumber, OobKey, RequestId };
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/auth/oob/identify/0.1" as const;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = AuthOOBIdentifyPayload;
+
+/**
+ * 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/oob/identify/0.1",
+  "title": "Auth — OOB Identify — payload",
+  "description": "A member's DID states that it holds the lock on one out-of-band request and can see the starter's screen. Issued by the approving DID and signed by its VTA for `authentication`; never sent on its own, only carried inside auth/oob/prove. Closed: additionalProperties false and no `ext`, so a VTA that signs it without user verification signs exactly these three members and nothing else. The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, proof) are owned by the framework — SPEC §6.3.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "requestId",
+    "approverKey",
+    "enteredNumber"
+  ],
+  "properties": {
+    "requestId": {
+      "$ref": "#/$defs/RequestId",
+      "description": "The request being proved for. MUST equal the requestId of the prove that carries this document."
+    },
+    "approverKey": {
+      "$ref": "#/$defs/OobKey",
+      "description": "The lock key `K_a`. MUST equal the issuer of the prove that carries this document, so the document cannot be re-wrapped by another device."
+    },
+    "enteredNumber": {
+      "$ref": "#/$defs/MatchNumber",
+      "description": "The two digits the member typed from the starter's screen."
+    }
+  },
+  "$defs": {
+    "MatchNumber": {
+      "title": "MatchNumber",
+      "type": "string",
+      "pattern": "^[0-9]{2}$",
+      "description": "The two-digit number the service chooses at claim, shows only to the starter (through redeem), and the approver types from the starter's screen. A string so that a leading zero survives."
+    },
+    "OobKey": {
+      "title": "OobKey",
+      "type": "string",
+      "minLength": 48,
+      "maxLength": 64,
+      "pattern": "^did:key:z6Mk[1-9A-HJ-NP-Za-km-z]+$",
+      "description": "A starter key (`K_b`) or an approver lock key (`K_a`), as an Ed25519 `did:key` (`z6Mk…`) generated for this one request and used nowhere else. Ed25519 only: a service refuses any other key type with `auth/oob:keyUnsupported` before parsing beyond the multicodec prefix."
+    },
+    "RequestId": {
+      "title": "RequestId",
+      "type": "string",
+      "minLength": 22,
+      "maxLength": 43,
+      "pattern": "^[A-Za-z0-9_-]{22,43}$",
+      "description": "The service-generated handle of one request: 16 to 32 bytes from a cryptographically secure random source, written as unpadded base64url (22 to 43 characters; 16 bytes, 22 characters, is RECOMMENDED). It is also the nonce of the exchange, so the family needs no separate challenge, and it is the `_id` of the trigger link (VTI-LNK-033). Compared as a string. It confers no authority on its holder."
+    }
+  }
+} 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;

package/src/auth/oob/prove/0.1/payload.ts

@@ -0,0 +1,473 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/auth/oob/prove/0.1/payload.schema.json
+ */
+
+import type { Ext, OobKey, Origin, Purpose, Requester, RequestId, SameNetwork, Service } from "../../../../_shared/components.js";
+
+
+/**
+ * The lock holder proves membership and the number on the starter's screen by carrying a signed auth/oob/identify document, and gets back the service-signed step 2. Issued and signed by the lock key `K_a`. The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, parentThreadId, proof) are owned by the framework — SPEC §6.3.
+ */
+export interface AuthOOBProvePayload {
+  /**
+   * A complete, signed auth/oob/identify/0.1 Trust Task document, issued by the approving DID and signed by its VTA for `authentication`. The service verifies it as a document in its own right — envelope, proof and payload against that specification's schema — over the members exactly as received: its proof covers every member, so it is deliberately an open object here rather than a typed one a binding could narrow.
+   */
+  identify: {};
+  ext?: Ext;
+}
+/**
+ * Step 2 of the disclosure ladder, signed by the service's assertionMethod key: the step 1 members unchanged, plus the starter's key, where the request came from, and which DID was identified. The SHA-256 of its JCS canonical form, proof included, is the grant's `contextDigest`.
+ */
+export interface AuthOOBProveResponsePayloadStep2 {
+  requestId: RequestId;
+  service: Service;
+  origin: Origin;
+  purpose: Purpose;
+  /**
+   * Unchanged from step 1 (integer UTC epoch seconds).
+   */
+  decisionDeadline: number;
+  /**
+   * The starter key `K_b`: the key a grant would let act as the identified DID.
+   */
+  sessionKey: OobKey;
+  requester: Requester;
+  /**
+   * The DID that issued the verified identify document. A grant must come from this DID.
+   */
+  identifiedAs: string;
+  ext?: Ext;
+}
+
+/** Shared definitions this specification references, re-exported under the names it used to declare them with. */
+export type { Ext, OobKey, Origin, Purpose, Requester, RequestId, SameNetwork, Service };
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/auth/oob/prove/0.1" as const;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = AuthOOBProvePayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/auth/oob/prove/0.1#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = AuthOOBProveResponsePayloadStep2;
+
+/**
+ * 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/oob/prove/0.1",
+  "title": "Auth — OOB Prove — payload",
+  "description": "The lock holder proves membership and the number on the starter's screen by carrying a signed auth/oob/identify document, and gets back the service-signed step 2. Issued and signed by the lock key `K_a`. The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, parentThreadId, proof) are owned by the framework — SPEC §6.3.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "identify"
+  ],
+  "properties": {
+    "identify": {
+      "type": "object",
+      "description": "A complete, signed auth/oob/identify/0.1 Trust Task document, issued by the approving DID and signed by its VTA for `authentication`. The service verifies it as a document in its own right — envelope, proof and payload against that specification's schema — over the members exactly as received: its proof covers every member, so it is deliberately an open object here rather than a typed one a binding could narrow."
+    },
+    "ext": {
+      "$ref": "#/$defs/Ext"
+    }
+  },
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "Auth — OOB Prove — response payload (step 2)",
+      "description": "Step 2 of the disclosure ladder, signed by the service's assertionMethod key: the step 1 members unchanged, plus the starter's key, where the request came from, and which DID was identified. The SHA-256 of its JCS canonical form, proof included, is the grant's `contextDigest`.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "requestId",
+        "service",
+        "origin",
+        "purpose",
+        "decisionDeadline",
+        "sessionKey",
+        "requester",
+        "identifiedAs"
+      ],
+      "properties": {
+        "requestId": {
+          "$ref": "#/$defs/RequestId"
+        },
+        "service": {
+          "$ref": "#/$defs/Service"
+        },
+        "origin": {
+          "$ref": "#/$defs/Origin"
+        },
+        "purpose": {
+          "$ref": "#/$defs/Purpose"
+        },
+        "decisionDeadline": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Unchanged from step 1 (integer UTC epoch seconds)."
+        },
+        "sessionKey": {
+          "$ref": "#/$defs/OobKey",
+          "description": "The starter key `K_b`: the key a grant would let act as the identified DID."
+        },
+        "requester": {
+          "$ref": "#/$defs/Requester"
+        },
+        "identifiedAs": {
+          "type": "string",
+          "pattern": "^did:",
+          "minLength": 5,
+          "maxLength": 2048,
+          "description": "The DID that issued the verified identify document. A grant must come from this DID."
+        },
+        "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-]+)+$"
+      }
+    },
+    "Requester": {
+      "title": "Requester",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "location",
+        "browser",
+        "os",
+        "createdAt",
+        "sameNetwork"
+      ],
+      "properties": {
+        "location": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "City and country of the starter's connection, from a local lookup with no third-party call, or the literal `unknown`. Never an IP address."
+        },
+        "browser": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "description": "Browser family of the starter (e.g. `Chrome`), never the full User-Agent; `unknown` when it cannot be told."
+        },
+        "os": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "description": "Operating system family of the starter (e.g. `macOS`); `unknown` when it cannot be told."
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the service accepted the starter's auth/oob/request."
+        },
+        "sameNetwork": {
+          "$ref": "#/$defs/SameNetwork"
+        }
+      },
+      "description": "What the service reports about where the request came from. Revealed only in the step 2 response, to the lock holder, after a membership and number proof. Reported by the service, signed by it, and a heuristic: a relaying attacker controls what is observed."
+    },
+    "SameNetwork": {
+      "title": "SameNetwork",
+      "oneOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "string",
+          "const": "unknown"
+        }
+      ],
+      "description": "Whether the starter's request and the approver's prove came from the same egress network, as the service saw them: `true`, `false`, or the string `unknown` when the service cannot tell. The service compares addresses; it never discloses them."
+    },
+    "OobKey": {
+      "title": "OobKey",
+      "type": "string",
+      "minLength": 48,
+      "maxLength": 64,
+      "pattern": "^did:key:z6Mk[1-9A-HJ-NP-Za-km-z]+$",
+      "description": "A starter key (`K_b`) or an approver lock key (`K_a`), as an Ed25519 `did:key` (`z6Mk…`) generated for this one request and used nowhere else. Ed25519 only: a service refuses any other key type with `auth/oob:keyUnsupported` before parsing beyond the multicodec prefix."
+    },
+    "Purpose": {
+      "title": "Purpose",
+      "type": "string",
+      "enum": [
+        "login"
+      ],
+      "description": "What the request is for. A CLOSED list: each purpose has a fixed row in CONVENTIONS.md §3 stating what is revealed at each step, what the grant contains, what redeem returns and the window lengths. Version 0.1 defines `login` only. `stepUp` and `deviceEnrol` are reserved names; adding one is a new version of this component and of every task that references it, never an in-place edit."
+    },
+    "Origin": {
+      "title": "Origin",
+      "type": "string",
+      "minLength": 9,
+      "maxLength": 2048,
+      "pattern": "^https://[^/?#\\s]+$",
+      "description": "A web origin (`https://host[:port]`, no path, no trailing slash) — for `login`, the origin of the portal where the starter runs, which is the origin of the `serviceEndpoint` of the service's `SignInPortal` service in its DID document."
+    },
+    "Service": {
+      "title": "Service",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "did",
+        "name"
+      ],
+      "properties": {
+        "did": {
+          "type": "string",
+          "pattern": "^did:",
+          "minLength": 5,
+          "maxLength": 2048,
+          "description": "The service's DID: the `recipient` of every request in the family, and the `_from` of the trigger link."
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "The name the service calls itself. Supplied by the service: an approver shows the name from its OWN records and flags a difference from this one (VTI-LNK-104); it never shows this value as the community's name on its own authority."
+        }
+      },
+      "description": "Who the service says it is."
+    },
+    "RequestId": {
+      "title": "RequestId",
+      "type": "string",
+      "minLength": 22,
+      "maxLength": 43,
+      "pattern": "^[A-Za-z0-9_-]{22,43}$",
+      "description": "The service-generated handle of one request: 16 to 32 bytes from a cryptographically secure random source, written as unpadded base64url (22 to 43 characters; 16 bytes, 22 characters, is RECOMMENDED). It is also the nonce of the exchange, so the family needs no separate challenge, and it is the `_id` of the trigger link (VTI-LNK-033). Compared as a string. It confers no authority on its holder."
+    }
+  }
+} 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 — OOB Prove — response payload (step 2)",
+      "description": "Step 2 of the disclosure ladder, signed by the service's assertionMethod key: the step 1 members unchanged, plus the starter's key, where the request came from, and which DID was identified. The SHA-256 of its JCS canonical form, proof included, is the grant's `contextDigest`.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "requestId",
+        "service",
+        "origin",
+        "purpose",
+        "decisionDeadline",
+        "sessionKey",
+        "requester",
+        "identifiedAs"
+      ],
+      "properties": {
+        "requestId": {
+          "$ref": "#/$defs/RequestId"
+        },
+        "service": {
+          "$ref": "#/$defs/Service"
+        },
+        "origin": {
+          "$ref": "#/$defs/Origin"
+        },
+        "purpose": {
+          "$ref": "#/$defs/Purpose"
+        },
+        "decisionDeadline": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Unchanged from step 1 (integer UTC epoch seconds)."
+        },
+        "sessionKey": {
+          "$ref": "#/$defs/OobKey",
+          "description": "The starter key `K_b`: the key a grant would let act as the identified DID."
+        },
+        "requester": {
+          "$ref": "#/$defs/Requester"
+        },
+        "identifiedAs": {
+          "type": "string",
+          "pattern": "^did:",
+          "minLength": 5,
+          "maxLength": 2048,
+          "description": "The DID that issued the verified identify document. A grant must come from this DID."
+        },
+        "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-]+)+$"
+      }
+    },
+    "Requester": {
+      "title": "Requester",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "location",
+        "browser",
+        "os",
+        "createdAt",
+        "sameNetwork"
+      ],
+      "properties": {
+        "location": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "City and country of the starter's connection, from a local lookup with no third-party call, or the literal `unknown`. Never an IP address."
+        },
+        "browser": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "description": "Browser family of the starter (e.g. `Chrome`), never the full User-Agent; `unknown` when it cannot be told."
+        },
+        "os": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "description": "Operating system family of the starter (e.g. `macOS`); `unknown` when it cannot be told."
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the service accepted the starter's auth/oob/request."
+        },
+        "sameNetwork": {
+          "$ref": "#/$defs/SameNetwork"
+        }
+      },
+      "description": "What the service reports about where the request came from. Revealed only in the step 2 response, to the lock holder, after a membership and number proof. Reported by the service, signed by it, and a heuristic: a relaying attacker controls what is observed."
+    },
+    "SameNetwork": {
+      "title": "SameNetwork",
+      "oneOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "string",
+          "const": "unknown"
+        }
+      ],
+      "description": "Whether the starter's request and the approver's prove came from the same egress network, as the service saw them: `true`, `false`, or the string `unknown` when the service cannot tell. The service compares addresses; it never discloses them."
+    },
+    "OobKey": {
+      "title": "OobKey",
+      "type": "string",
+      "minLength": 48,
+      "maxLength": 64,
+      "pattern": "^did:key:z6Mk[1-9A-HJ-NP-Za-km-z]+$",
+      "description": "A starter key (`K_b`) or an approver lock key (`K_a`), as an Ed25519 `did:key` (`z6Mk…`) generated for this one request and used nowhere else. Ed25519 only: a service refuses any other key type with `auth/oob:keyUnsupported` before parsing beyond the multicodec prefix."
+    },
+    "Purpose": {
+      "title": "Purpose",
+      "type": "string",
+      "enum": [
+        "login"
+      ],
+      "description": "What the request is for. A CLOSED list: each purpose has a fixed row in CONVENTIONS.md §3 stating what is revealed at each step, what the grant contains, what redeem returns and the window lengths. Version 0.1 defines `login` only. `stepUp` and `deviceEnrol` are reserved names; adding one is a new version of this component and of every task that references it, never an in-place edit."
+    },
+    "Origin": {
+      "title": "Origin",
+      "type": "string",
+      "minLength": 9,
+      "maxLength": 2048,
+      "pattern": "^https://[^/?#\\s]+$",
+      "description": "A web origin (`https://host[:port]`, no path, no trailing slash) — for `login`, the origin of the portal where the starter runs, which is the origin of the `serviceEndpoint` of the service's `SignInPortal` service in its DID document."
+    },
+    "Service": {
+      "title": "Service",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "did",
+        "name"
+      ],
+      "properties": {
+        "did": {
+          "type": "string",
+          "pattern": "^did:",
+          "minLength": 5,
+          "maxLength": 2048,
+          "description": "The service's DID: the `recipient` of every request in the family, and the `_from` of the trigger link."
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "The name the service calls itself. Supplied by the service: an approver shows the name from its OWN records and flags a difference from this one (VTI-LNK-104); it never shows this value as the community's name on its own authority."
+        }
+      },
+      "description": "Who the service says it is."
+    },
+    "RequestId": {
+      "title": "RequestId",
+      "type": "string",
+      "minLength": 22,
+      "maxLength": 43,
+      "pattern": "^[A-Za-z0-9_-]{22,43}$",
+      "description": "The service-generated handle of one request: 16 to 32 bytes from a cryptographically secure random source, written as unpadded base64url (22 to 43 characters; 16 bytes, 22 characters, is RECOMMENDED). It is also the nonce of the exchange, so the family needs no separate challenge, and it is the `_id` of the trigger link (VTI-LNK-033). Compared as a string. It confers no authority on its holder."
+    }
+  }
+} 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;