@openvtc/trust-tasks 0.23.0 → 0.23.1

package/src/vtc/members/authority-reduction-pending-notice/0.1/payload.ts

@@ -0,0 +1,176 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vtc/members/authority-reduction-pending-notice/0.1/payload.schema.json
+ */
+
+import type { ActionId, Ext } from "../../../../_shared/components.js";
+
+
+/**
+ * A community tells a subject that a reduction of their administrative authority has been requested and is cooling off: it will land at `landsAt` unless the administrator who requested it cancels it first. Sent when the reduction is parked, never when it lands — vtc/members/authority-reduced-notice reports the landing. The subject cannot block the reduction; the notice exists so that they learn of it before it takes effect. Unsolicited: the subject did not ask.
+ */
+export interface VTCMembersAuthorityReductionPendingNoticePayload {
+  /**
+   * The subject whose authority the pending reduction would reduce — the notice's recipient. Carried in the payload as well as the envelope so that a forwarded notice still names its subject.
+   */
+  did: string;
+  /**
+   * What will happen when the reduction lands. `revoked`: the subject's access control entry will be removed. `demoted`: its role will be changed to one with a lower ceiling. `narrowed`: its role will stay and what it allows will be reduced. The same set, with the same meanings, as vtc/members/authority-reduced-notice/0.1.
+   */
+  code: "revoked" | "demoted" | "narrowed";
+  /**
+   * The role the subject holds now, before the reduction lands.
+   */
+  previousRole: string;
+  /**
+   * The role the subject will hold once the reduction lands. Absent exactly when `code` is `revoked`.
+   */
+  resultingRole?: string;
+  /**
+   * DID of the administrator who requested the reduction — the only party who can cancel it before it lands. The community itself is the document's issuer.
+   */
+  decidedBy: string;
+  /**
+   * When the reduction was requested and parked — not when the notice was sent.
+   */
+  requestedAt: string;
+  /**
+   * When the reduction takes effect unless its requester cancels it first. Equal to the parked action's `landsAt`; fixed when the reduction was parked.
+   */
+  landsAt: string;
+  /**
+   * The cooling-off action holding the reduction. The subject follows it with vtc/admin/actions/show/0.2, where it appears with `callerRole: subject`, to learn whether it was cancelled or landed.
+   */
+  actionId: ActionId;
+  /**
+   * The requesting administrator's stated reason, verbatim. Absent when none was given; absent and empty are different claims.
+   */
+  reason?: string;
+  ext?: Ext;
+}
+
+/** Shared definitions this specification references, re-exported under the names it used to declare them with. */
+export type { ActionId, Ext };
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/vtc/members/authority-reduction-pending-notice/0.1" as const;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = VTCMembersAuthorityReductionPendingNoticePayload;
+
+/**
+ * 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/members/authority-reduction-pending-notice/0.1",
+  "title": "VTC Members Authority-Reduction-Pending Notice — payload",
+  "description": "A community tells a subject that a reduction of their administrative authority has been requested and is cooling off: it will land at `landsAt` unless the administrator who requested it cancels it first. Sent when the reduction is parked, never when it lands — vtc/members/authority-reduced-notice reports the landing. The subject cannot block the reduction; the notice exists so that they learn of it before it takes effect. Unsolicited: the subject did not ask.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "did",
+    "code",
+    "previousRole",
+    "decidedBy",
+    "requestedAt",
+    "landsAt",
+    "actionId"
+  ],
+  "properties": {
+    "did": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The subject whose authority the pending reduction would reduce — the notice's recipient. Carried in the payload as well as the envelope so that a forwarded notice still names its subject."
+    },
+    "code": {
+      "type": "string",
+      "enum": [
+        "revoked",
+        "demoted",
+        "narrowed"
+      ],
+      "description": "What will happen when the reduction lands. `revoked`: the subject's access control entry will be removed. `demoted`: its role will be changed to one with a lower ceiling. `narrowed`: its role will stay and what it allows will be reduced. The same set, with the same meanings, as vtc/members/authority-reduced-notice/0.1."
+    },
+    "previousRole": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "description": "The role the subject holds now, before the reduction lands."
+    },
+    "resultingRole": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "description": "The role the subject will hold once the reduction lands. Absent exactly when `code` is `revoked`."
+    },
+    "decidedBy": {
+      "type": "string",
+      "minLength": 1,
+      "description": "DID of the administrator who requested the reduction — the only party who can cancel it before it lands. The community itself is the document's issuer."
+    },
+    "requestedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the reduction was requested and parked — not when the notice was sent."
+    },
+    "landsAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the reduction takes effect unless its requester cancels it first. Equal to the parked action's `landsAt`; fixed when the reduction was parked."
+    },
+    "actionId": {
+      "$ref": "#/$defs/ActionId",
+      "description": "The cooling-off action holding the reduction. The subject follows it with vtc/admin/actions/show/0.2, where it appears with `callerRole: subject`, to learn whether it was cancelled or landed."
+    },
+    "reason": {
+      "type": "string",
+      "maxLength": 1024,
+      "description": "The requesting administrator's stated reason, verbatim. Absent when none was given; absent and empty are different claims."
+    },
+    "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-]+)+$"
+      }
+    },
+    "ActionId": {
+      "title": "ActionId",
+      "description": "Opaque, community-minted identifier of one action. A consumer MUST NOT parse or order it; it is compared for equality only. Long enough to be unguessable, because a show of an id the caller may not see is answered `notFound` and an enumerable id would turn that answer into an oracle.",
+      "type": "string",
+      "minLength": 16,
+      "maxLength": 128,
+      "pattern": "^[A-Za-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;

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;