@openvtc/trust-tasks 0.16.7 → 0.16.8

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

@@ -0,0 +1,349 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vta/backup/initiate-import/1.0/payload.schema.json
+ */
+
+import type { Ext } from "../../../../_shared/components.js";
+
+
+/**
+ * Asks the recipient to open a slot for an encrypted bundle the producer is about to upload, pre-committing the digest and size so the transfer is verifiable. The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, proof) are owned by the framework — SPEC §6.3.
+ */
+export interface VTABackupInitiateImportPayload {
+  /**
+   * Lowercase hex SHA-256 of the bytes about to be uploaded, committed before the upload begins. The recipient refuses a stream that hashes differently, which is what bounds the damage from a leaked write token. A wire-integrity check only: it says the bytes that arrived are the bytes that were sent, and nothing about whether they are worth applying.
+   */
+  expectedSha256: string;
+  /**
+   * Byte count of the upload. Lets the recipient size the slot and refuse a truncated or oversized transfer without hashing it first. A zero-length bundle is not a degenerate case — there is nothing to import — so the floor is 1.
+   */
+  expectedSizeBytes: number;
+  /**
+   * Requested transport mechanism — how the bytes move, not how they are encrypted. `stream` is the only value this version defines and is what an absent member means. Deliberately not an enum, so a recipient offering more can be asked for it without a specification revision; one that does not implement the request refuses with unsupportedAlgorithm.
+   */
+  algorithm?: string;
+  /**
+   * Ecosystem-defined extension members per SPEC.md §4.5.1.
+   */
+  ext?: Ext;
+}
+export interface VTABackupInitiateImportResponsePayload {
+  descriptor: BundleDescriptor;
+  /**
+   * Operator-facing text describing how to complete the upload. Advisory: a producer must not parse it or derive behaviour from it, and a recipient must not put a secret in it.
+   */
+  completionHint?: string;
+  /**
+   * Ecosystem-defined extension members per SPEC.md §4.5.1.
+   */
+  ext?: Ext;
+}
+/**
+ * Where to write the bytes, on what terms, and until when.
+ */
+export interface BundleDescriptor {
+  /**
+   * Handle for this bundle across its whole lifecycle. Quoted back by finalize-import and abort. Recipient-generated and unguessable, which is what lets an unauthorized reference be answered as not-found without confirming existence.
+   */
+  bundleId: string;
+  /**
+   * The mechanism actually used, which is authoritative over what was requested.
+   */
+  algorithm: string;
+  /**
+   * Where to write the bytes. Write-only: a recipient must not serve staged bytes back from this address, or a leaked token becomes a read of the operator's bundle. A recipient with no address at which it is reachable cannot produce this and refuses with transportUnavailable.
+   */
+  transportUrl: string;
+  /**
+   * Bearer credential for transportUrl, presented in the X-Backup-Token header. Minted per bundle and never reused. A recipient should store only a hash of it. Leaking it lets a third party fill the slot; expectedSha256 is what bounds that to a failed transfer rather than a staged substitution.
+   */
+  transportToken: string;
+  /**
+   * Echoed from the request, so the descriptor stands alone as the terms of the transfer.
+   */
+  expectedSha256: string;
+  /**
+   * Echoed from the request, so the descriptor stands alone as the terms of the transfer.
+   */
+  expectedSizeBytes: number;
+  /**
+   * After which the slot closes, the token is refused, and any staged bytes are discarded unread. Short by design: the window is how long a writable endpoint into the agent exists.
+   */
+  expiresAt: string;
+}
+
+/** 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/initiate-import/1.0" as const;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = VTABackupInitiateImportPayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/vta/backup/initiate-import/1.0#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = VTABackupInitiateImportResponsePayload;
+
+/**
+ * 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/initiate-import/1.0",
+  "title": "VTA Backup — Initiate Import — payload",
+  "description": "Asks the recipient to open a slot for an encrypted bundle the producer is about to upload, pre-committing the digest and size so the transfer is verifiable. The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, proof) are owned by the framework — SPEC §6.3.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "expectedSha256",
+    "expectedSizeBytes"
+  ],
+  "properties": {
+    "expectedSha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$",
+      "description": "Lowercase hex SHA-256 of the bytes about to be uploaded, committed before the upload begins. The recipient refuses a stream that hashes differently, which is what bounds the damage from a leaked write token. A wire-integrity check only: it says the bytes that arrived are the bytes that were sent, and nothing about whether they are worth applying."
+    },
+    "expectedSizeBytes": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Byte count of the upload. Lets the recipient size the slot and refuse a truncated or oversized transfer without hashing it first. A zero-length bundle is not a degenerate case — there is nothing to import — so the floor is 1."
+    },
+    "algorithm": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "description": "Requested transport mechanism — how the bytes move, not how they are encrypted. `stream` is the only value this version defines and is what an absent member means. Deliberately not an enum, so a recipient offering more can be asked for it without a specification revision; one that does not implement the request refuses with unsupportedAlgorithm."
+    },
+    "ext": {
+      "$ref": "#/$defs/Ext",
+      "description": "Ecosystem-defined extension members per SPEC.md §4.5.1."
+    }
+  },
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "VTA Backup Initiate Import — response payload",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "descriptor"
+      ],
+      "properties": {
+        "descriptor": {
+          "$ref": "#/$defs/BundleDescriptor",
+          "description": "Where to write the bytes, on what terms, and until when."
+        },
+        "completionHint": {
+          "type": "string",
+          "maxLength": 1024,
+          "description": "Operator-facing text describing how to complete the upload. Advisory: a producer must not parse it or derive behaviour from it, and a recipient must not put a secret in it."
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext",
+          "description": "Ecosystem-defined extension members per SPEC.md §4.5.1."
+        }
+      }
+    },
+    "BundleDescriptor": {
+      "title": "Bundle descriptor",
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The control-plane account of an out-of-band byte transfer. Shared in shape with initiate-export, where it describes a download rather than an upload.",
+      "required": [
+        "bundleId",
+        "algorithm",
+        "transportUrl",
+        "transportToken",
+        "expectedSha256",
+        "expectedSizeBytes",
+        "expiresAt"
+      ],
+      "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 for this bundle across its whole lifecycle. Quoted back by finalize-import and abort. Recipient-generated and unguessable, which is what lets an unauthorized reference be answered as not-found without confirming existence."
+        },
+        "algorithm": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "description": "The mechanism actually used, which is authoritative over what was requested."
+        },
+        "transportUrl": {
+          "type": "string",
+          "format": "uri",
+          "maxLength": 2048,
+          "description": "Where to write the bytes. Write-only: a recipient must not serve staged bytes back from this address, or a leaked token becomes a read of the operator's bundle. A recipient with no address at which it is reachable cannot produce this and refuses with transportUnavailable."
+        },
+        "transportToken": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024,
+          "description": "Bearer credential for transportUrl, presented in the X-Backup-Token header. Minted per bundle and never reused. A recipient should store only a hash of it. Leaking it lets a third party fill the slot; expectedSha256 is what bounds that to a failed transfer rather than a staged substitution."
+        },
+        "expectedSha256": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$",
+          "description": "Echoed from the request, so the descriptor stands alone as the terms of the transfer."
+        },
+        "expectedSizeBytes": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Echoed from the request, so the descriptor stands alone as the terms of the transfer."
+        },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "After which the slot closes, the token is refused, and any staged bytes are discarded unread. Short by design: the window is how long a writable endpoint into the agent exists."
+        }
+      }
+    },
+    "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 Initiate Import — response payload",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "descriptor"
+      ],
+      "properties": {
+        "descriptor": {
+          "$ref": "#/$defs/BundleDescriptor",
+          "description": "Where to write the bytes, on what terms, and until when."
+        },
+        "completionHint": {
+          "type": "string",
+          "maxLength": 1024,
+          "description": "Operator-facing text describing how to complete the upload. Advisory: a producer must not parse it or derive behaviour from it, and a recipient must not put a secret in it."
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext",
+          "description": "Ecosystem-defined extension members per SPEC.md §4.5.1."
+        }
+      }
+    },
+    "BundleDescriptor": {
+      "title": "Bundle descriptor",
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The control-plane account of an out-of-band byte transfer. Shared in shape with initiate-export, where it describes a download rather than an upload.",
+      "required": [
+        "bundleId",
+        "algorithm",
+        "transportUrl",
+        "transportToken",
+        "expectedSha256",
+        "expectedSizeBytes",
+        "expiresAt"
+      ],
+      "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 for this bundle across its whole lifecycle. Quoted back by finalize-import and abort. Recipient-generated and unguessable, which is what lets an unauthorized reference be answered as not-found without confirming existence."
+        },
+        "algorithm": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "description": "The mechanism actually used, which is authoritative over what was requested."
+        },
+        "transportUrl": {
+          "type": "string",
+          "format": "uri",
+          "maxLength": 2048,
+          "description": "Where to write the bytes. Write-only: a recipient must not serve staged bytes back from this address, or a leaked token becomes a read of the operator's bundle. A recipient with no address at which it is reachable cannot produce this and refuses with transportUnavailable."
+        },
+        "transportToken": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024,
+          "description": "Bearer credential for transportUrl, presented in the X-Backup-Token header. Minted per bundle and never reused. A recipient should store only a hash of it. Leaking it lets a third party fill the slot; expectedSha256 is what bounds that to a failed transfer rather than a staged substitution."
+        },
+        "expectedSha256": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$",
+          "description": "Echoed from the request, so the descriptor stands alone as the terms of the transfer."
+        },
+        "expectedSizeBytes": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Echoed from the request, so the descriptor stands alone as the terms of the transfer."
+        },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "After which the slot closes, the token is refused, and any staged bytes are discarded unread. Short by design: the window is how long a writable endpoint into the agent exists."
+        }
+      }
+    },
+    "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/management/reload-services/1.0/payload.ts

@@ -0,0 +1,167 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vta/management/reload-services/1.0/payload.schema.json
+ */
+
+import type { Ext } from "../../../../_shared/components.js";
+
+
+/**
+ * Asks the recipient to re-read its service configuration and restart its transports. Defines no members: every parameter this task might carry would be a way of asking the agent to run on something other than its configuration — see Why the payload is empty. The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, proof) are owned by the framework — SPEC §6.3.
+ */
+export interface VTAManagementReloadServicesPayload {
+  /**
+   * Ecosystem-defined extension members per SPEC.md §4.5.1. Note the limit stated in the specification: an ecosystem must not use this slot to add selective reload, inline configuration, or a skip-validation flag, which are the members the empty payload exists to exclude.
+   */
+  ext?: Ext;
+}
+export interface VTAManagementReloadServicesResponsePayload {
+  /**
+   * The recipient's account of what it is doing. Advisory free text, deliberately not an enum: a producer must not parse it or branch on its value, because the reliable signal is whether the agent answers afterwards, not what it said before restarting. Bounded per §7.3 item 19 — the value lands in transcripts and audit entries.
+   */
+  status: 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/management/reload-services/1.0" as const;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = VTAManagementReloadServicesPayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/vta/management/reload-services/1.0#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = VTAManagementReloadServicesResponsePayload;
+
+/**
+ * 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/management/reload-services/1.0",
+  "title": "VTA Management — Reload Services — payload",
+  "description": "Asks the recipient to re-read its service configuration and restart its transports. Defines no members: every parameter this task might carry would be a way of asking the agent to run on something other than its configuration — see Why the payload is empty. The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, proof) are owned by the framework — SPEC §6.3.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "ext": {
+      "$ref": "#/$defs/Ext",
+      "description": "Ecosystem-defined extension members per SPEC.md §4.5.1. Note the limit stated in the specification: an ecosystem must not use this slot to add selective reload, inline configuration, or a skip-validation flag, which are the members the empty payload exists to exclude."
+    }
+  },
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "VTA Management Reload Services — response payload",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status"
+      ],
+      "properties": {
+        "status": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "description": "The recipient's account of what it is doing. Advisory free text, deliberately not an enum: a producer must not parse it or branch on its value, because the reliable signal is whether the agent answers afterwards, not what it said before restarting. Bounded per §7.3 item 19 — the value lands in transcripts and audit entries."
+        },
+        "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 Management Reload Services — response payload",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status"
+      ],
+      "properties": {
+        "status": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "description": "The recipient's account of what it is doing. Advisory free text, deliberately not an enum: a producer must not parse it or branch on its value, because the reliable signal is whether the agent answers afterwards, not what it said before restarting. Bounded per §7.3 item 19 — the value lands in transcripts and audit entries."
+        },
+        "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;