@openvtc/trust-tasks 0.23.8 → 0.24.0

package/src/rooms/keys/file-key/0.1/payload.ts

@@ -0,0 +1,224 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/rooms/keys/file-key/0.1/payload.schema.json
+ */
+
+import type { Ext } from "../../../../_shared/components.js";
+
+
+/**
+ * A caller asks the party holding its principal's room keys for the key of ONE file in a room: derived from the room's storage key for an epoch, bound to the room, the epoch and the file's identifier, and opening that file and nothing else.
+ */
+export interface RoomsKeysFileKeyPayload {
+  /**
+   * The room the file belongs to. Bound into the derivation, so a key released for one room cannot open a blob relocated from another.
+   */
+  roomId: string;
+  /**
+   * The file's identifier: 32 random bytes, base64url without padding, as in FileManifest.fileId. The salt of the derivation. For `seal` the caller mints it fresh and MUST NOT reuse it; for `open` it is read from the sealed record's file manifest.
+   */
+  fileId: string;
+  /**
+   * `seal`: a key for a file about to be uploaded, derived under the room's CURRENT epoch, which the response names. `open`: a key for a file already in the room, derived under the epoch its manifest names.
+   */
+  purpose: "seal" | "open";
+  /**
+   * The epoch the file key derives from, as FileManifest.epoch states it. REQUIRED for `open` and forbidden for `seal` — a rule over two members this schema does not express; the custodian refuses a violation with `malformedRequest`. A sealing caller never chooses the epoch: sealing under anything but the current one would produce a file members who joined later could not open, or one a removed member still could.
+   */
+  epoch?: number;
+  /**
+   * Ecosystem-defined extension members per SPEC.md §4.5.1.
+   */
+  ext?: Ext;
+}
+/**
+ * Success response to rooms/keys/file-key. Type https://trusttasks.org/spec/rooms/keys/file-key/0.1#response.
+ */
+export interface RoomsKeysFileKeyResponsePayload {
+  /**
+   * The 32-byte file key, base64url without padding. Opens exactly one file. The caller holds it in memory for as long as the file is being sealed or opened and then discards it; it never stores, logs or forwards it.
+   */
+  key: string;
+  /**
+   * The epoch the key was derived under. For `seal`, the room's current epoch, which the caller writes into the file's manifest; for `open`, the epoch requested.
+   */
+  epoch: number;
+  ext?: Ext;
+}
+
+/** Shared definitions this specification references, re-exported under the names it used to declare them with. */
+export type { Ext };
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/rooms/keys/file-key/0.1" as const;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = RoomsKeysFileKeyPayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/rooms/keys/file-key/0.1#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = RoomsKeysFileKeyResponsePayload;
+
+/**
+ * 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/file-key/0.1",
+  "title": "Rooms Keys File Key — payload",
+  "description": "A caller asks the party holding its principal's room keys for the key of ONE file in a room: derived from the room's storage key for an epoch, bound to the room, the epoch and the file's identifier, and opening that file and nothing else.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "roomId",
+    "fileId",
+    "purpose"
+  ],
+  "properties": {
+    "roomId": {
+      "type": "string",
+      "description": "The room the file belongs to. Bound into the derivation, so a key released for one room cannot open a blob relocated from another."
+    },
+    "fileId": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{43}$",
+      "description": "The file's identifier: 32 random bytes, base64url without padding, as in FileManifest.fileId. The salt of the derivation. For `seal` the caller mints it fresh and MUST NOT reuse it; for `open` it is read from the sealed record's file manifest."
+    },
+    "purpose": {
+      "type": "string",
+      "enum": [
+        "seal",
+        "open"
+      ],
+      "description": "`seal`: a key for a file about to be uploaded, derived under the room's CURRENT epoch, which the response names. `open`: a key for a file already in the room, derived under the epoch its manifest names."
+    },
+    "epoch": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "The epoch the file key derives from, as FileManifest.epoch states it. REQUIRED for `open` and forbidden for `seal` — a rule over two members this schema does not express; the custodian refuses a violation with `malformedRequest`. A sealing caller never chooses the epoch: sealing under anything but the current one would produce a file members who joined later could not open, or one a removed member still could."
+    },
+    "ext": {
+      "$ref": "#/$defs/Ext",
+      "description": "Ecosystem-defined extension members per SPEC.md §4.5.1."
+    }
+  },
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "Rooms Keys File Key — response payload",
+      "description": "Success response to rooms/keys/file-key. Type https://trusttasks.org/spec/rooms/keys/file-key/0.1#response.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "key",
+        "epoch"
+      ],
+      "properties": {
+        "key": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_-]{43}$",
+          "description": "The 32-byte file key, base64url without padding. Opens exactly one file. The caller holds it in memory for as long as the file is being sealed or opened and then discards it; it never stores, logs or forwards it."
+        },
+        "epoch": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "The epoch the key was derived under. For `seal`, the room's current epoch, which the caller writes into the file's manifest; for `open`, the epoch requested."
+        },
+        "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-]+)+$"
+      }
+    }
+  }
+} 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 File Key — response payload",
+      "description": "Success response to rooms/keys/file-key. Type https://trusttasks.org/spec/rooms/keys/file-key/0.1#response.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "key",
+        "epoch"
+      ],
+      "properties": {
+        "key": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_-]{43}$",
+          "description": "The 32-byte file key, base64url without padding. Opens exactly one file. The caller holds it in memory for as long as the file is being sealed or opened and then discards it; it never stores, logs or forwards it."
+        },
+        "epoch": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "The epoch the key was derived under. For `seal`, the room's current epoch, which the caller writes into the file's manifest; for `open`, the epoch requested."
+        },
+        "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-]+)+$"
+      }
+    }
+  }
+} 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;