@openvtc/trust-tasks 0.16.7 → 0.16.9

package/src/vta/backup/complete-export/1.0/payload.ts

@@ -0,0 +1,191 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vta/backup/complete-export/1.0/payload.schema.json
+ */
+
+import type { Ext } from "../../../../_shared/components.js";
+
+
+/**
+ * Acknowledges that an export bundle was downloaded, so the recipient can release the staged bytes and retire the transport token. The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, proof) are owned by the framework — SPEC §6.3.
+ */
+export interface VTABackupCompleteExportPayload {
+  /**
+   * Handle from the initiate-export descriptor. Opaque: a producer quotes what it was given and must not derive, guess or enumerate one.
+   */
+  bundleId: string;
+  /**
+   * Ecosystem-defined extension members per SPEC.md §4.5.1.
+   */
+  ext?: Ext;
+}
+export interface VTABackupCompleteExportResponsePayload {
+  /**
+   * Echoed so the response stands alone as a record.
+   */
+  bundleId: string;
+  /**
+   * Whether the byte stream was actually fetched before this acknowledgement. Required, not optional: false is the honest answer when the operator skipped the download or the slot expired first, and an absent member would let that be read as success.
+   */
+  downloaded: boolean;
+  /**
+   * Ecosystem-defined extension members per SPEC.md §4.5.1.
+   */
+  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/vta/backup/complete-export/1.0" as const;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = VTABackupCompleteExportPayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/vta/backup/complete-export/1.0#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = VTABackupCompleteExportResponsePayload;
+
+/**
+ * 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/vta/backup/complete-export/1.0",
+  "title": "VTA Backup — Complete Export — payload",
+  "description": "Acknowledges that an export bundle was downloaded, so the recipient can release the staged bytes and retire the transport token. The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, proof) are owned by the framework — SPEC §6.3.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "bundleId"
+  ],
+  "properties": {
+    "bundleId": {
+      "type": "string",
+      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
+      "description": "Handle from the initiate-export descriptor. Opaque: a producer quotes what it was given and must not derive, guess or enumerate one."
+    },
+    "ext": {
+      "$ref": "#/$defs/Ext",
+      "description": "Ecosystem-defined extension members per SPEC.md §4.5.1."
+    }
+  },
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "VTA Backup Complete Export — response payload",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "bundleId",
+        "downloaded"
+      ],
+      "properties": {
+        "bundleId": {
+          "type": "string",
+          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
+          "description": "Echoed so the response stands alone as a record."
+        },
+        "downloaded": {
+          "type": "boolean",
+          "description": "Whether the byte stream was actually fetched before this acknowledgement. Required, not optional: false is the honest answer when the operator skipped the download or the slot expired first, and an absent member would let that be read as success."
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext",
+          "description": "Ecosystem-defined extension members per SPEC.md §4.5.1."
+        }
+      }
+    },
+    "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": "VTA Backup Complete Export — response payload",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "bundleId",
+        "downloaded"
+      ],
+      "properties": {
+        "bundleId": {
+          "type": "string",
+          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
+          "description": "Echoed so the response stands alone as a record."
+        },
+        "downloaded": {
+          "type": "boolean",
+          "description": "Whether the byte stream was actually fetched before this acknowledgement. Required, not optional: false is the honest answer when the operator skipped the download or the slot expired first, and an absent member would let that be read as success."
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext",
+          "description": "Ecosystem-defined extension members per SPEC.md §4.5.1."
+        }
+      }
+    },
+    "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;

package/src/vta/backup/finalize-import/1.0/payload.ts

@@ -0,0 +1,333 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vta/backup/finalize-import/1.0/payload.schema.json
+ */
+
+import type { Ext } from "../../../../_shared/components.js";
+
+
+/**
+ * Supplies the password for an uploaded bundle and asks the recipient to decrypt it and adopt what is inside, or to rehearse that without committing. The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, proof) are owned by the framework — SPEC §6.3.
+ */
+export interface VTABackupFinalizeImportPayload {
+  /**
+   * Handle from the initiate-import descriptor. Opaque: a producer quotes what it was given and must not derive, guess or enumerate one.
+   */
+  bundleId: string;
+  /**
+   * Key-derivation input that unlocks the bundle. Supplied here rather than at initiate-import so the key never travels alongside the slot holding the ciphertext. `writeOnly` is the machine-readable form of the rule in Data carried: this member goes in and never comes back, so a generated client must not surface it in a response type, and a recipient must never log, echo or persist it.
+   */
+  password: string;
+  /**
+   * True commits and replaces the agent's state; false rehearses and mutates nothing. Absent means true — stated in prose rather than as a schema `default` on purpose, because a materialised default makes an omitted member indistinguishable from a deliberate one, and this is the member separating a rehearsal from an irreversible replacement. See Defaulting.
+   */
+  confirm?: boolean;
+  /**
+   * Ecosystem-defined extension members per SPEC.md §4.5.1.
+   */
+  ext?: Ext;
+}
+/**
+ * Counts and a status, never contents. This document is the operator-held record of a replacement the agent's own trail no longer describes.
+ */
+export interface VTABackupFinalizeImportResponsePayload {
+  /**
+   * Echoed so the response stands alone as a record.
+   */
+  bundleId: string;
+  /**
+   * Which the recipient did. Reported rather than left to be inferred from the request, so that a response is complete evidence on its own: `committed` says the agent was replaced, `preview` says it was not.
+   */
+  status: "preview" | "committed";
+  /**
+   * Identifier of the agent the bundle was exported from. The one identifier a preview returns, because the common import error is a valid bundle from the wrong agent and this is what shows it. Absent where the bundle does not record one.
+   */
+  sourceDid?: string;
+  /**
+   * How many keys the bundle holds. A count, not an inventory — enough to recognise a bundle as plausibly the right one, and not enough to learn what is in it.
+   */
+  keyCount: number;
+  /**
+   * How many access-control entries the bundle holds. A count, not an inventory — enough to recognise a bundle as plausibly the right one, and not enough to learn what is in it.
+   */
+  aclCount: number;
+  /**
+   * How many trust contexts the bundle holds. A count, not an inventory — enough to recognise a bundle as plausibly the right one, and not enough to learn what is in it.
+   */
+  contextCount: number;
+  /**
+   * How many audit entries the bundle holds. Zero for a bundle exported without its trail, which is a legitimate outcome and not a sign of a truncated bundle.
+   */
+  auditCount: number;
+  /**
+   * How many secrets the bundle holds. A count, not an inventory — enough to recognise a bundle as plausibly the right one, and not enough to learn what is in it.
+   */
+  importedSecretCount?: number;
+  /**
+   * Operator-facing text elaborating on the outcome. Advisory: a producer must not parse it or derive behaviour from it, and a recipient must not put bundle contents or a secret in it.
+   */
+  message?: string;
+  /**
+   * Ecosystem-defined extension members per SPEC.md §4.5.1.
+   */
+  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/vta/backup/finalize-import/1.0" as const;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = VTABackupFinalizeImportPayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/vta/backup/finalize-import/1.0#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = VTABackupFinalizeImportResponsePayload;
+
+/**
+ * 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/vta/backup/finalize-import/1.0",
+  "title": "VTA Backup — Finalize Import — payload",
+  "description": "Supplies the password for an uploaded bundle and asks the recipient to decrypt it and adopt what is inside, or to rehearse that without committing. The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, proof) are owned by the framework — SPEC §6.3.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "bundleId",
+    "password"
+  ],
+  "properties": {
+    "bundleId": {
+      "type": "string",
+      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
+      "description": "Handle from the initiate-import descriptor. Opaque: a producer quotes what it was given and must not derive, guess or enumerate one."
+    },
+    "password": {
+      "type": "string",
+      "minLength": 15,
+      "maxLength": 1024,
+      "writeOnly": true,
+      "description": "Key-derivation input that unlocks the bundle. Supplied here rather than at initiate-import so the key never travels alongside the slot holding the ciphertext. `writeOnly` is the machine-readable form of the rule in Data carried: this member goes in and never comes back, so a generated client must not surface it in a response type, and a recipient must never log, echo or persist it.",
+      "$comment": "No example value anywhere in this directory: a specimen password is the one thing implementers copy. minLength mirrors the export floor so a bundle that could be created can be read back."
+    },
+    "confirm": {
+      "type": "boolean",
+      "description": "True commits and replaces the agent's state; false rehearses and mutates nothing. Absent means true — stated in prose rather than as a schema `default` on purpose, because a materialised default makes an omitted member indistinguishable from a deliberate one, and this is the member separating a rehearsal from an irreversible replacement. See Defaulting."
+    },
+    "ext": {
+      "$ref": "#/$defs/Ext",
+      "description": "Ecosystem-defined extension members per SPEC.md §4.5.1."
+    }
+  },
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "VTA Backup Finalize Import — response payload",
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Counts and a status, never contents. This document is the operator-held record of a replacement the agent's own trail no longer describes.",
+      "required": [
+        "bundleId",
+        "status",
+        "keyCount",
+        "aclCount",
+        "contextCount",
+        "auditCount"
+      ],
+      "properties": {
+        "bundleId": {
+          "type": "string",
+          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
+          "description": "Echoed so the response stands alone as a record."
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "preview",
+            "committed"
+          ],
+          "description": "Which the recipient did. Reported rather than left to be inferred from the request, so that a response is complete evidence on its own: `committed` says the agent was replaced, `preview` says it was not."
+        },
+        "sourceDid": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 2048,
+          "description": "Identifier of the agent the bundle was exported from. The one identifier a preview returns, because the common import error is a valid bundle from the wrong agent and this is what shows it. Absent where the bundle does not record one."
+        },
+        "keyCount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "How many keys the bundle holds. A count, not an inventory — enough to recognise a bundle as plausibly the right one, and not enough to learn what is in it."
+        },
+        "aclCount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "How many access-control entries the bundle holds. A count, not an inventory — enough to recognise a bundle as plausibly the right one, and not enough to learn what is in it."
+        },
+        "contextCount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "How many trust contexts the bundle holds. A count, not an inventory — enough to recognise a bundle as plausibly the right one, and not enough to learn what is in it."
+        },
+        "auditCount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "How many audit entries the bundle holds. Zero for a bundle exported without its trail, which is a legitimate outcome and not a sign of a truncated bundle."
+        },
+        "importedSecretCount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "How many secrets the bundle holds. A count, not an inventory — enough to recognise a bundle as plausibly the right one, and not enough to learn what is in it."
+        },
+        "message": {
+          "type": "string",
+          "maxLength": 1024,
+          "description": "Operator-facing text elaborating on the outcome. Advisory: a producer must not parse it or derive behaviour from it, and a recipient must not put bundle contents or a secret in it."
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext",
+          "description": "Ecosystem-defined extension members per SPEC.md §4.5.1."
+        }
+      }
+    },
+    "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": "VTA Backup Finalize Import — response payload",
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Counts and a status, never contents. This document is the operator-held record of a replacement the agent's own trail no longer describes.",
+      "required": [
+        "bundleId",
+        "status",
+        "keyCount",
+        "aclCount",
+        "contextCount",
+        "auditCount"
+      ],
+      "properties": {
+        "bundleId": {
+          "type": "string",
+          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
+          "description": "Echoed so the response stands alone as a record."
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "preview",
+            "committed"
+          ],
+          "description": "Which the recipient did. Reported rather than left to be inferred from the request, so that a response is complete evidence on its own: `committed` says the agent was replaced, `preview` says it was not."
+        },
+        "sourceDid": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 2048,
+          "description": "Identifier of the agent the bundle was exported from. The one identifier a preview returns, because the common import error is a valid bundle from the wrong agent and this is what shows it. Absent where the bundle does not record one."
+        },
+        "keyCount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "How many keys the bundle holds. A count, not an inventory — enough to recognise a bundle as plausibly the right one, and not enough to learn what is in it."
+        },
+        "aclCount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "How many access-control entries the bundle holds. A count, not an inventory — enough to recognise a bundle as plausibly the right one, and not enough to learn what is in it."
+        },
+        "contextCount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "How many trust contexts the bundle holds. A count, not an inventory — enough to recognise a bundle as plausibly the right one, and not enough to learn what is in it."
+        },
+        "auditCount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "How many audit entries the bundle holds. Zero for a bundle exported without its trail, which is a legitimate outcome and not a sign of a truncated bundle."
+        },
+        "importedSecretCount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "How many secrets the bundle holds. A count, not an inventory — enough to recognise a bundle as plausibly the right one, and not enough to learn what is in it."
+        },
+        "message": {
+          "type": "string",
+          "maxLength": 1024,
+          "description": "Operator-facing text elaborating on the outcome. Advisory: a producer must not parse it or derive behaviour from it, and a recipient must not put bundle contents or a secret in it."
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext",
+          "description": "Ecosystem-defined extension members per SPEC.md §4.5.1."
+        }
+      }
+    },
+    "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;