@openvtc/trust-tasks 0.26.14 → 0.26.16

package/src/rooms/keys/list/0.2/payload.ts

@@ -0,0 +1,412 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/rooms/keys/list/0.2/payload.schema.json
+ */
+
+import type { Ext, PersonalLabel, PersonalLabelDescription, PersonalLabelName, PersonalLabelNotes, PersonalLabelTag, PersonalLabelTags } from "../../../../_shared/components.js";
+
+
+/**
+ * List the rooms the key holder can open for members the caller may act as. `includePersonal` asks for each entry's personal label as well; absent, none is returned. Carries no filter: the recipient answers for the members its caller acts as, and there is nothing to ask it about. The outer document members are owned by the framework — SPEC §6.3.
+ */
+export interface RoomsKeysListPayload {
+  /**
+   * `true` asks for each entry's personal label (rooms/keys/label) in `personal`. Absent or `false`: no entry carries one. A request option, not a filter — it changes which members of an entry are returned, never which entries — and off by default so that a caller that has no use for the member's own names, or will pass the list on, never receives them.
+   */
+  includePersonal?: boolean;
+  /**
+   * Ecosystem-defined extension members per SPEC.md §4.5.1.
+   */
+  ext?: Ext;
+}
+/**
+ * Success response to rooms/keys/list. Type https://trusttasks.org/spec/rooms/keys/list/0.2#response. The rooms this key holder can open, one entry per room and member, for the members the caller may act as. This is key custody, not membership: a room whose group state was never delivered is absent here and the member may still hold a perfectly good VMC for it.
+ */
+export interface RoomsKeysListResponsePayload {
+  /**
+   * One entry per room and member, in no guaranteed order. A room held as two members the caller may act as appears twice, once per member.
+   */
+  rooms: {
+    /**
+     * The room's identifier.
+     */
+    roomId: string;
+    /**
+     * The member this entry's group state is held for: the DID the room admitted. What a client names as `member` to rooms/keys/label, and as `issuer` to rooms/keys/act, to act on this entry rather than on the same room held as another member.
+     */
+    member: string;
+    /**
+     * The epoch this key holder is at for this member. Behind the room's own epoch means a commit has not been delivered, and records sealed since will not open.
+     */
+    epoch: number;
+    /**
+     * The earliest epoch this key holder can derive a key for, for this member, walking the epoch key chain it holds. Equal to `epoch` means it reads only from where it joined; `1` means the room's whole retained history. Anything between is a chain that has been delivered in part, or one deliberately severed below that point.
+     */
+    earliestReadableEpoch: number;
+    /**
+     * The member's own label for the room (rooms/keys/label). Present only when the request set `includePersonal: true` and the member has one. Private to the member: a caller MUST NOT pass it to the room's host, its owner, a community or a website the member has not chosen to show it to.
+     */
+    personal?: PersonalLabel;
+  }[];
+  ext?: Ext;
+}
+
+/** Shared definitions this specification references, re-exported under the names it used to declare them with. */
+export type { Ext, PersonalLabel, PersonalLabelDescription, PersonalLabelName, PersonalLabelNotes, PersonalLabelTag, PersonalLabelTags };
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/rooms/keys/list/0.2" as const;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = RoomsKeysListPayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/rooms/keys/list/0.2#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = RoomsKeysListResponsePayload;
+
+/**
+ * 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/rooms/keys/list/0.2",
+  "title": "Rooms Keys List — payload",
+  "description": "List the rooms the key holder can open for members the caller may act as. `includePersonal` asks for each entry's personal label as well; absent, none is returned. Carries no filter: the recipient answers for the members its caller acts as, and there is nothing to ask it about. The outer document members are owned by the framework — SPEC §6.3.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "includePersonal": {
+      "type": "boolean",
+      "description": "`true` asks for each entry's personal label (rooms/keys/label) in `personal`. Absent or `false`: no entry carries one. A request option, not a filter — it changes which members of an entry are returned, never which entries — and off by default so that a caller that has no use for the member's own names, or will pass the list on, never receives them."
+    },
+    "ext": {
+      "$ref": "#/$defs/Ext",
+      "description": "Ecosystem-defined extension members per SPEC.md §4.5.1."
+    }
+  },
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "Rooms Keys List — response payload",
+      "description": "Success response to rooms/keys/list. Type https://trusttasks.org/spec/rooms/keys/list/0.2#response. The rooms this key holder can open, one entry per room and member, for the members the caller may act as. This is key custody, not membership: a room whose group state was never delivered is absent here and the member may still hold a perfectly good VMC for it.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "rooms"
+      ],
+      "properties": {
+        "rooms": {
+          "type": "array",
+          "description": "One entry per room and member, in no guaranteed order. A room held as two members the caller may act as appears twice, once per member.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "roomId",
+              "member",
+              "epoch",
+              "earliestReadableEpoch"
+            ],
+            "properties": {
+              "roomId": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 512,
+                "description": "The room's identifier."
+              },
+              "member": {
+                "type": "string",
+                "pattern": "^did:",
+                "maxLength": 2048,
+                "description": "The member this entry's group state is held for: the DID the room admitted. What a client names as `member` to rooms/keys/label, and as `issuer` to rooms/keys/act, to act on this entry rather than on the same room held as another member."
+              },
+              "epoch": {
+                "type": "integer",
+                "minimum": 1,
+                "description": "The epoch this key holder is at for this member. Behind the room's own epoch means a commit has not been delivered, and records sealed since will not open."
+              },
+              "earliestReadableEpoch": {
+                "type": "integer",
+                "minimum": 1,
+                "description": "The earliest epoch this key holder can derive a key for, for this member, walking the epoch key chain it holds. Equal to `epoch` means it reads only from where it joined; `1` means the room's whole retained history. Anything between is a chain that has been delivered in part, or one deliberately severed below that point."
+              },
+              "personal": {
+                "$ref": "#/$defs/PersonalLabel",
+                "description": "The member's own label for the room (rooms/keys/label). Present only when the request set `includePersonal: true` and the member has one. Private to the member: a caller MUST NOT pass it to the room's host, its owner, a community or a website the member has not chosen to show it to."
+              }
+            }
+          }
+        },
+        "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-]+)+$"
+      }
+    },
+    "PersonalLabel": {
+      "title": "PersonalLabel",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "updatedAt"
+      ],
+      "minProperties": 2,
+      "description": "A member's personal label for one room, as their key holder keeps it: at least one detail (`minProperties` counts `updatedAt`), and when it last changed. A key holder that holds no detail for the room holds no label, and returns none — there is no empty label.",
+      "properties": {
+        "label": {
+          "$ref": "#/$defs/PersonalLabelName"
+        },
+        "description": {
+          "$ref": "#/$defs/PersonalLabelDescription"
+        },
+        "notes": {
+          "$ref": "#/$defs/PersonalLabelNotes"
+        },
+        "tags": {
+          "$ref": "#/$defs/PersonalLabelTags"
+        },
+        "updatedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the label last changed, as the key holder recorded it. A request that changed nothing does not move it."
+        }
+      }
+    },
+    "PersonalLabelTags": {
+      "title": "PersonalLabelTags",
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 16,
+      "uniqueItems": true,
+      "items": {
+        "$ref": "#/$defs/PersonalLabelTag"
+      },
+      "description": "The member's tags for the room, one to sixteen, as a set: order carries no meaning. A room with no tags has no `tags` member, never an empty list, so there is one way to say \"none\"."
+    },
+    "PersonalLabelTag": {
+      "title": "PersonalLabelTag",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 32,
+      "pattern": "^[^\\u0000-\\u001F\\u007F]+$",
+      "description": "A word or short phrase the member files the room under, in any script, so their own surfaces can group and filter their rooms. Compared exactly, as a string: a key holder does not case-fold or normalise it."
+    },
+    "PersonalLabelNotes": {
+      "title": "PersonalLabelNotes",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 4000,
+      "pattern": "^[^\\u0000-\\u0008\\u000B\\u000C\\u000E-\\u001F\\u007F]+$",
+      "description": "Longer free-form notes the member keeps about the room: who introduced them, what to look for in it, what they agreed there. Line breaks and tabs are allowed; other control characters are not."
+    },
+    "PersonalLabelDescription": {
+      "title": "PersonalLabelDescription",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1000,
+      "pattern": "^[^\\u0000-\\u0008\\u000B\\u000C\\u000E-\\u001F\\u007F]+$",
+      "description": "What the room is to the member, in a sentence or a short paragraph. Line breaks and tabs are allowed; other control characters are not."
+    },
+    "PersonalLabelName": {
+      "title": "PersonalLabelName",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[^\\u0000-\\u001F\\u007F]+$",
+      "description": "The member's own name for the room, on one line: no control characters, line breaks included. Shown before every name a third party gave the room, because it is the only one nobody else wrote."
+    }
+  }
+} 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": "Rooms Keys List — response payload",
+      "description": "Success response to rooms/keys/list. Type https://trusttasks.org/spec/rooms/keys/list/0.2#response. The rooms this key holder can open, one entry per room and member, for the members the caller may act as. This is key custody, not membership: a room whose group state was never delivered is absent here and the member may still hold a perfectly good VMC for it.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "rooms"
+      ],
+      "properties": {
+        "rooms": {
+          "type": "array",
+          "description": "One entry per room and member, in no guaranteed order. A room held as two members the caller may act as appears twice, once per member.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "roomId",
+              "member",
+              "epoch",
+              "earliestReadableEpoch"
+            ],
+            "properties": {
+              "roomId": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 512,
+                "description": "The room's identifier."
+              },
+              "member": {
+                "type": "string",
+                "pattern": "^did:",
+                "maxLength": 2048,
+                "description": "The member this entry's group state is held for: the DID the room admitted. What a client names as `member` to rooms/keys/label, and as `issuer` to rooms/keys/act, to act on this entry rather than on the same room held as another member."
+              },
+              "epoch": {
+                "type": "integer",
+                "minimum": 1,
+                "description": "The epoch this key holder is at for this member. Behind the room's own epoch means a commit has not been delivered, and records sealed since will not open."
+              },
+              "earliestReadableEpoch": {
+                "type": "integer",
+                "minimum": 1,
+                "description": "The earliest epoch this key holder can derive a key for, for this member, walking the epoch key chain it holds. Equal to `epoch` means it reads only from where it joined; `1` means the room's whole retained history. Anything between is a chain that has been delivered in part, or one deliberately severed below that point."
+              },
+              "personal": {
+                "$ref": "#/$defs/PersonalLabel",
+                "description": "The member's own label for the room (rooms/keys/label). Present only when the request set `includePersonal: true` and the member has one. Private to the member: a caller MUST NOT pass it to the room's host, its owner, a community or a website the member has not chosen to show it to."
+              }
+            }
+          }
+        },
+        "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-]+)+$"
+      }
+    },
+    "PersonalLabel": {
+      "title": "PersonalLabel",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "updatedAt"
+      ],
+      "minProperties": 2,
+      "description": "A member's personal label for one room, as their key holder keeps it: at least one detail (`minProperties` counts `updatedAt`), and when it last changed. A key holder that holds no detail for the room holds no label, and returns none — there is no empty label.",
+      "properties": {
+        "label": {
+          "$ref": "#/$defs/PersonalLabelName"
+        },
+        "description": {
+          "$ref": "#/$defs/PersonalLabelDescription"
+        },
+        "notes": {
+          "$ref": "#/$defs/PersonalLabelNotes"
+        },
+        "tags": {
+          "$ref": "#/$defs/PersonalLabelTags"
+        },
+        "updatedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the label last changed, as the key holder recorded it. A request that changed nothing does not move it."
+        }
+      }
+    },
+    "PersonalLabelTags": {
+      "title": "PersonalLabelTags",
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 16,
+      "uniqueItems": true,
+      "items": {
+        "$ref": "#/$defs/PersonalLabelTag"
+      },
+      "description": "The member's tags for the room, one to sixteen, as a set: order carries no meaning. A room with no tags has no `tags` member, never an empty list, so there is one way to say \"none\"."
+    },
+    "PersonalLabelTag": {
+      "title": "PersonalLabelTag",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 32,
+      "pattern": "^[^\\u0000-\\u001F\\u007F]+$",
+      "description": "A word or short phrase the member files the room under, in any script, so their own surfaces can group and filter their rooms. Compared exactly, as a string: a key holder does not case-fold or normalise it."
+    },
+    "PersonalLabelNotes": {
+      "title": "PersonalLabelNotes",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 4000,
+      "pattern": "^[^\\u0000-\\u0008\\u000B\\u000C\\u000E-\\u001F\\u007F]+$",
+      "description": "Longer free-form notes the member keeps about the room: who introduced them, what to look for in it, what they agreed there. Line breaks and tabs are allowed; other control characters are not."
+    },
+    "PersonalLabelDescription": {
+      "title": "PersonalLabelDescription",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1000,
+      "pattern": "^[^\\u0000-\\u0008\\u000B\\u000C\\u000E-\\u001F\\u007F]+$",
+      "description": "What the room is to the member, in a sentence or a short paragraph. Line breaks and tabs are allowed; other control characters are not."
+    },
+    "PersonalLabelName": {
+      "title": "PersonalLabelName",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[^\\u0000-\\u001F\\u007F]+$",
+      "description": "The member's own name for the room, on one line: no control characters, line breaks included. Shown before every name a third party gave the room, because it is the only one nobody else wrote."
+    }
+  }
+} 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/rooms/keys/present/0.2/payload.ts

@@ -136,7 +136,7 @@ export const PAYLOAD_SCHEMA = {
         "membership",
         "authority"
       ],
-      "description": "What a party presents to act on a room. Carries the whole authority chain: a host MUST NOT dereference an authority credential's `parent` to fetch a link it was not given. Resolving over the network would make verification depend on availability, turn every identifier into a request the host can be induced to make against an address the holder chooses, and signal credential use to whoever hosts the identifier. A host MUST bind the presenter to the chain's leaf. A chain that verifies is evidence that authority was conferred on somebody; it is not evidence that the party presenting it is that somebody. The leaf's subject MUST equal the party the host authenticated for this request — an identity the transport established or a document `proof` proved, never one named in a payload. A host that omits this check authorizes every captured presentation, and the omission is silent, because the chain still verifies.",
+      "description": "What a party presents to act on a room. Carries the whole authority chain: a host MUST NOT dereference an authority credential's `parent` to fetch a link it was not given. Resolving over the network would make verification depend on availability, turn every identifier into a request the host can be induced to make against an address the holder chooses, and signal credential use to whoever hosts the identifier. A host MUST bind the presenter to the chain's leaf. A chain that verifies is evidence that authority was conferred on somebody; it is not evidence that the party presenting it is that somebody. The leaf's subject MUST equal the party the host authenticated for this request — an identity the transport established or a document `proof` proved, never one named in a payload. A host that omits this check authorizes every captured presentation, and the omission is silent, because the chain still verifies.\n\n**Every credential is its issuer's attestation, and only its issuer's.** For the membership credential and for every link of `authority`, a host MUST verify the credential's `proof` with a key that the credential's own `issuer` lists for `assertionMethod` in its DID document, and MUST refuse a credential whose proof names a verification method that is not its issuer's. A proof that verifies under some other party's key is that party's statement, not the issuer's, and confers nothing. The same binding holds for every other document a room signs, such as a `RevocationList`.\n\n**A chain that verifies may still be revoked.** A host that has accepted a `RevocationList` for the room (`rooms/revocations/put`) MUST, from the moment it accepted it, refuse every presentation in which the membership credential or any link of `authority` is revoked by that list, under every task and every version of every task it serves for the room. A chain from which any link is revoked is refused whole: a credential delegated from a revoked one confers nothing, however it was attenuated. The refusal is the same `permissionDenied` as any other failed presentation.",
       "properties": {
         "membership": {
           "type": "string",
@@ -207,7 +207,7 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
         "membership",
         "authority"
       ],
-      "description": "What a party presents to act on a room. Carries the whole authority chain: a host MUST NOT dereference an authority credential's `parent` to fetch a link it was not given. Resolving over the network would make verification depend on availability, turn every identifier into a request the host can be induced to make against an address the holder chooses, and signal credential use to whoever hosts the identifier. A host MUST bind the presenter to the chain's leaf. A chain that verifies is evidence that authority was conferred on somebody; it is not evidence that the party presenting it is that somebody. The leaf's subject MUST equal the party the host authenticated for this request — an identity the transport established or a document `proof` proved, never one named in a payload. A host that omits this check authorizes every captured presentation, and the omission is silent, because the chain still verifies.",
+      "description": "What a party presents to act on a room. Carries the whole authority chain: a host MUST NOT dereference an authority credential's `parent` to fetch a link it was not given. Resolving over the network would make verification depend on availability, turn every identifier into a request the host can be induced to make against an address the holder chooses, and signal credential use to whoever hosts the identifier. A host MUST bind the presenter to the chain's leaf. A chain that verifies is evidence that authority was conferred on somebody; it is not evidence that the party presenting it is that somebody. The leaf's subject MUST equal the party the host authenticated for this request — an identity the transport established or a document `proof` proved, never one named in a payload. A host that omits this check authorizes every captured presentation, and the omission is silent, because the chain still verifies.\n\n**Every credential is its issuer's attestation, and only its issuer's.** For the membership credential and for every link of `authority`, a host MUST verify the credential's `proof` with a key that the credential's own `issuer` lists for `assertionMethod` in its DID document, and MUST refuse a credential whose proof names a verification method that is not its issuer's. A proof that verifies under some other party's key is that party's statement, not the issuer's, and confers nothing. The same binding holds for every other document a room signs, such as a `RevocationList`.\n\n**A chain that verifies may still be revoked.** A host that has accepted a `RevocationList` for the room (`rooms/revocations/put`) MUST, from the moment it accepted it, refuse every presentation in which the membership credential or any link of `authority` is revoked by that list, under every task and every version of every task it serves for the room. A chain from which any link is revoked is refused whole: a credential delegated from a revoked one confers nothing, however it was attenuated. The refusal is the same `permissionDenied` as any other failed presentation.",
       "properties": {
         "membership": {
           "type": "string",