@openvtc/trust-tasks 0.23.0 → 0.23.2

package/src/vtc/operator/offline-write/0.1/payload.ts

@@ -0,0 +1,133 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vtc/operator/offline-write/0.1/payload.schema.json
+ */
+
+import type { Ext } from "../../../../_shared/components.js";
+
+
+/**
+ * A RECORD TYPE, not a request. It describes one change to a Verifiable Trust Community's access control made by an operator with access to the community's host, through an offline command run against the community's store (`vtc admin emergency-bootstrap` and its siblings) rather than through any Trust Task. No party sends a document of this type to another and no consumer executes one: its Type URI exists so that an `acknowledge` action (vtc/admin/actions/_shared/0.2) can name what happened in `typeUri`, and so that the community's audit trail can reference it. When an action names it, the action's `payload` is this record. The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, proof) are owned by the framework — SPEC §6.3.
+ */
+export interface VTCOperatorOfflineWriteRecord {
+  /**
+   * Which offline command made the change. `aclAdd` — an access control entry was written. `aclRemove` — an access control entry was removed. `adminInvite` — an administrator invitation was minted. `createDidKeyAdmin` — a new `did:key` was minted on the host and made an administrator. `enrolApprover` — an approver was enrolled for a subject. `emergencyBootstrap` — the break-glass recovery that installs an administrator when none can act. A closed set: a new offline command is a new version, so that a renderer never shows an administrator a change it cannot name.
+   */
+  command: "aclAdd" | "aclRemove" | "adminInvite" | "createDidKeyAdmin" | "enrolApprover" | "emergencyBootstrap";
+  /**
+   * The DIDs whose access the command changed — the subject of an entry added or removed, the administrator installed or invited, the subject an approver was enrolled for and the approver — in the order the command reports them. Never empty: an offline write that changed nobody's access is not one administrators need to acknowledge.
+   *
+   * @minItems 1
+   * @maxItems 64
+   */
+  dids: [string, ...string[]];
+  /**
+   * The host the command ran on, as the community knows it (its hostname, or the deployment's name for the instance). Identifies where an operator held access, not who the operator was; attribution to a person, where the community has one, is the action's `requester`.
+   */
+  host: string;
+  /**
+   * When the command wrote the change to the community's store, as recorded on the host. Not when the community noticed it, which is the action's `createdAt`.
+   */
+  at: string;
+  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/vtc/operator/offline-write/0.1" as const;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = VTCOperatorOfflineWriteRecord;
+
+/**
+ * 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/vtc/operator/offline-write/0.1",
+  "title": "VTC Operator Offline Write — record",
+  "description": "A RECORD TYPE, not a request. It describes one change to a Verifiable Trust Community's access control made by an operator with access to the community's host, through an offline command run against the community's store (`vtc admin emergency-bootstrap` and its siblings) rather than through any Trust Task. No party sends a document of this type to another and no consumer executes one: its Type URI exists so that an `acknowledge` action (vtc/admin/actions/_shared/0.2) can name what happened in `typeUri`, and so that the community's audit trail can reference it. When an action names it, the action's `payload` is this record. The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, proof) are owned by the framework — SPEC §6.3.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "command",
+    "dids",
+    "host",
+    "at"
+  ],
+  "properties": {
+    "command": {
+      "type": "string",
+      "enum": [
+        "aclAdd",
+        "aclRemove",
+        "adminInvite",
+        "createDidKeyAdmin",
+        "enrolApprover",
+        "emergencyBootstrap"
+      ],
+      "description": "Which offline command made the change. `aclAdd` — an access control entry was written. `aclRemove` — an access control entry was removed. `adminInvite` — an administrator invitation was minted. `createDidKeyAdmin` — a new `did:key` was minted on the host and made an administrator. `enrolApprover` — an approver was enrolled for a subject. `emergencyBootstrap` — the break-glass recovery that installs an administrator when none can act. A closed set: a new offline command is a new version, so that a renderer never shows an administrator a change it cannot name."
+    },
+    "dids": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 64,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 2048
+      },
+      "description": "The DIDs whose access the command changed — the subject of an entry added or removed, the administrator installed or invited, the subject an approver was enrolled for and the approver — in the order the command reports them. Never empty: an offline write that changed nobody's access is not one administrators need to acknowledge."
+    },
+    "host": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 253,
+      "description": "The host the command ran on, as the community knows it (its hostname, or the deployment's name for the instance). Identifies where an operator held access, not who the operator was; attribution to a person, where the community has one, is the action's `requester`."
+    },
+    "at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the command wrote the change to the community's store, as recorded on the host. Not when the community noticed it, which is the action's `createdAt`."
+    },
+    "ext": {
+      "$ref": "#/$defs/Ext"
+    }
+  },
+  "$defs": {
+    "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: false,
+  isRecipientRequired: false,
+  isIssuedAtRequired: false,
+  payloadSchema: PAYLOAD_SCHEMA,
+} as const;