@openvtc/trust-tasks 0.28.13 → 0.28.15

package/src/rooms/watch/0.1/payload.ts

@@ -0,0 +1,340 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/rooms/watch/0.1/payload.schema.json
+ */
+
+import type { AuthorityPresentation, Ext } from "../../../_shared/components.js";
+
+
+/**
+ * A member asks a room's host to send one content-free `rooms/changed` signal to an address the member names, the first time the room moves past a version the member has read to. One signal per arming: a member re-arms the watch after it has caught up. The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, proof) are owned by the framework — SPEC §6.3.
+ */
+export interface RoomsWatchPayload {
+  /**
+   * The room to watch. A host verifies the presentation against credentials issued by this identifier, never against a member list of its own.
+   */
+  roomId: string;
+  /**
+   * Must confer `read` at this room's scope — the grant a listing takes, since a signal says no more than a listing would.
+   */
+  presentation: AuthorityPresentation;
+  /**
+   * The DID the host sends the signal to, over a transport that DID's document advertises and the host speaks. Chosen by the member. It identifies the watch: a request naming the same room and address re-arms or cancels that watch, and one naming another address is another watch. On a `private` room it MUST be a DID the member uses for nothing else (*Security & Privacy*).
+   */
+  address: string;
+  /**
+   * The highest version of the room the member has read to — the watermark it would pass as `sinceVersion` to `rooms/records/list`. The host signals as soon as the room's latest version is above it, at once if it already is, so that a change landing between the member's last listing and this request is not missed. Absent means the room's latest version when the host arms the watch, which a member that has just listed the room may rely on only if it accepts missing a change made in between.
+   */
+  sinceVersion?: number;
+  /**
+   * How long the member asks the watch to last if it does not fire, in seconds, up to 30 days. A host MAY grant less, and says what it granted in `expiresAt`. Absent means the host's default.
+   */
+  leaseSeconds?: number;
+  /**
+   * End the watch on this room and address. Only `true` is meaningful, so only `true` is accepted. A producer sends neither `sinceVersion` nor `leaseSeconds` with it, and a host ignores them on a cancel. A cancel of a watch the host does not hold succeeds and says `armed: false`, so a retry is harmless.
+   */
+  cancel?: true;
+  /**
+   * Ecosystem-defined extension members per SPEC.md §4.5.1.
+   */
+  ext?: Ext;
+}
+/**
+ * Success response to rooms/watch. Type https://trusttasks.org/spec/rooms/watch/0.1#response.
+ */
+export interface RoomsWatchResponsePayload {
+  roomId: string;
+  /**
+   * The address, echoed.
+   */
+  address: string;
+  /**
+   * `true`: the host will send one signal to `address` the first time the room is above `sinceVersion`, or has sent it already because the room was. `false`: the watch was cancelled, or there was none to cancel.
+   */
+  armed: boolean;
+  /**
+   * Present when `armed` is `true`: when the host forgets the watch if it has not fired — the lease granted, never later than the earliest instant at which any credential of the presentation stops being valid.
+   */
+  expiresAt?: string;
+  ext?: Ext;
+}
+
+/** Shared definitions this specification references, re-exported under the names it used to declare them with. */
+export type { AuthorityPresentation, Ext };
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/rooms/watch/0.1" as const;
+
+/**
+ * The earlier version of this specification that this one declares it
+ * extends (front matter `extends`, SPEC §5.2 "Declared extension"), or
+ * `null`. Only the direct declaration — follow the chain with
+ * `extendsChain` / `readForSpec`.
+ */
+export const EXTENDS: string | null = null;
+
+/**
+ * Why this version is deprecated, or `null` while it is current. A
+ * superseded or retired version is still supported, and is withdrawn from
+ * this package in a later scheduled batch (SPEC "Superseded and Withdrawn
+ * Versions").
+ */
+export const DEPRECATION: string | null = null;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = RoomsWatchPayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/rooms/watch/0.1#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = RoomsWatchResponsePayload;
+
+/**
+ * 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/watch/0.1",
+  "title": "Rooms — Watch — payload",
+  "description": "A member asks a room's host to send one content-free `rooms/changed` signal to an address the member names, the first time the room moves past a version the member has read to. One signal per arming: a member re-arms the watch after it has caught up. The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, proof) are owned by the framework — SPEC §6.3.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "roomId",
+    "presentation",
+    "address"
+  ],
+  "properties": {
+    "roomId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The room to watch. A host verifies the presentation against credentials issued by this identifier, never against a member list of its own."
+    },
+    "presentation": {
+      "$ref": "#/$defs/AuthorityPresentation",
+      "description": "Must confer `read` at this room's scope — the grant a listing takes, since a signal says no more than a listing would."
+    },
+    "address": {
+      "type": "string",
+      "pattern": "^did:",
+      "maxLength": 1000,
+      "description": "The DID the host sends the signal to, over a transport that DID's document advertises and the host speaks. Chosen by the member. It identifies the watch: a request naming the same room and address re-arms or cancels that watch, and one naming another address is another watch. On a `private` room it MUST be a DID the member uses for nothing else (*Security & Privacy*)."
+    },
+    "sinceVersion": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "The highest version of the room the member has read to — the watermark it would pass as `sinceVersion` to `rooms/records/list`. The host signals as soon as the room's latest version is above it, at once if it already is, so that a change landing between the member's last listing and this request is not missed. Absent means the room's latest version when the host arms the watch, which a member that has just listed the room may rely on only if it accepts missing a change made in between."
+    },
+    "leaseSeconds": {
+      "type": "integer",
+      "minimum": 60,
+      "maximum": 2592000,
+      "description": "How long the member asks the watch to last if it does not fire, in seconds, up to 30 days. A host MAY grant less, and says what it granted in `expiresAt`. Absent means the host's default."
+    },
+    "cancel": {
+      "type": "boolean",
+      "const": true,
+      "description": "End the watch on this room and address. Only `true` is meaningful, so only `true` is accepted. A producer sends neither `sinceVersion` nor `leaseSeconds` with it, and a host ignores them on a cancel. A cancel of a watch the host does not hold succeeds and says `armed: false`, so a retry is harmless."
+    },
+    "ext": {
+      "$ref": "#/$defs/Ext",
+      "description": "Ecosystem-defined extension members per SPEC.md §4.5.1."
+    }
+  },
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "Rooms — Watch — response payload",
+      "description": "Success response to rooms/watch. Type https://trusttasks.org/spec/rooms/watch/0.1#response.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "roomId",
+        "address",
+        "armed"
+      ],
+      "properties": {
+        "roomId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "address": {
+          "type": "string",
+          "pattern": "^did:",
+          "maxLength": 1000,
+          "description": "The address, echoed."
+        },
+        "armed": {
+          "type": "boolean",
+          "description": "`true`: the host will send one signal to `address` the first time the room is above `sinceVersion`, or has sent it already because the room was. `false`: the watch was cancelled, or there was none to cancel."
+        },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Present when `armed` is `true`: when the host forgets the watch if it has not fired — the lease granted, never later than the earliest instant at which any credential of the presentation stops being valid."
+        },
+        "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-]+)+$"
+      }
+    },
+    "AuthorityPresentation": {
+      "title": "AuthorityPresentation",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "membership",
+        "authority"
+      ],
+      "description": "What a party presents to act on a room. Carries the whole authority chain: a host MUST NOT dereference an authority credential's `parent` to fetch a link it was not given. Resolving over the network would make verification depend on availability, turn every identifier into a request the host can be induced to make against an address the holder chooses, and signal credential use to whoever hosts the identifier. A host MUST bind the presenter to the chain's leaf. A chain that verifies is evidence that authority was conferred on somebody; it is not evidence that the party presenting it is that somebody. The leaf's subject MUST equal the party the host authenticated for this request — an identity the transport established or a document `proof` proved, never one named in a payload. A host that omits this check authorizes every captured presentation, and the omission is silent, because the chain still verifies.\n\n**Every credential is its issuer's attestation, and only its issuer's.** For the membership credential and for every link of `authority`, a host MUST verify the credential's `proof` with a key that the credential's own `issuer` lists for `assertionMethod` in its DID document, and MUST refuse a credential whose proof names a verification method that is not its issuer's. A proof that verifies under some other party's key is that party's statement, not the issuer's, and confers nothing. The same binding holds for every other document a room signs, such as a `RevocationList`.\n\n**A chain that verifies may still be revoked.** A host that has accepted a `RevocationList` for the room (`rooms/revocations/put`) MUST, from the moment it accepted it, refuse every presentation in which the membership credential or any link of `authority` is revoked by that list, under every task and every version of every task it serves for the room. A chain from which any link is revoked is refused whole: a credential delegated from a revoked one confers nothing, however it was attenuated. The refusal is the same `permissionDenied` as any other failed presentation.",
+      "properties": {
+        "membership": {
+          "type": "string",
+          "description": "The presenter's membership credential for this room, or — on a `private` room — a zero-knowledge presentation of it. Serialized per the governing profile."
+        },
+        "authority": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 8,
+          "items": {
+            "type": "string"
+          },
+          "description": "The authority chain, LEAF FIRST: the first element is the credential being relied on and the last MUST be one issued by the room itself. Every link the presenter relies on is present, because the host will not fetch one. Capped at 8: verification is linear in chain length and runs on every operation, so an unbounded chain is a denial-of-service surface against the host. The known uses need 2 to 3 — a person attenuating to an agent, and that agent to a sub-agent."
+        },
+        "subjectBinding": {
+          "type": "string",
+          "description": "REQUIRED on a `private` room, where the subject identifier is withheld: a proof that the membership credential and the authority chain's leaf describe the SAME subject. Without it two parties pool credentials — one contributes membership, the other authority — and the combination verifies as a single party holding both. A host MUST refuse a private-room presentation that omits this."
+        }
+      }
+    }
+  }
+} 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 — Watch — response payload",
+      "description": "Success response to rooms/watch. Type https://trusttasks.org/spec/rooms/watch/0.1#response.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "roomId",
+        "address",
+        "armed"
+      ],
+      "properties": {
+        "roomId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "address": {
+          "type": "string",
+          "pattern": "^did:",
+          "maxLength": 1000,
+          "description": "The address, echoed."
+        },
+        "armed": {
+          "type": "boolean",
+          "description": "`true`: the host will send one signal to `address` the first time the room is above `sinceVersion`, or has sent it already because the room was. `false`: the watch was cancelled, or there was none to cancel."
+        },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Present when `armed` is `true`: when the host forgets the watch if it has not fired — the lease granted, never later than the earliest instant at which any credential of the presentation stops being valid."
+        },
+        "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-]+)+$"
+      }
+    },
+    "AuthorityPresentation": {
+      "title": "AuthorityPresentation",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "membership",
+        "authority"
+      ],
+      "description": "What a party presents to act on a room. Carries the whole authority chain: a host MUST NOT dereference an authority credential's `parent` to fetch a link it was not given. Resolving over the network would make verification depend on availability, turn every identifier into a request the host can be induced to make against an address the holder chooses, and signal credential use to whoever hosts the identifier. A host MUST bind the presenter to the chain's leaf. A chain that verifies is evidence that authority was conferred on somebody; it is not evidence that the party presenting it is that somebody. The leaf's subject MUST equal the party the host authenticated for this request — an identity the transport established or a document `proof` proved, never one named in a payload. A host that omits this check authorizes every captured presentation, and the omission is silent, because the chain still verifies.\n\n**Every credential is its issuer's attestation, and only its issuer's.** For the membership credential and for every link of `authority`, a host MUST verify the credential's `proof` with a key that the credential's own `issuer` lists for `assertionMethod` in its DID document, and MUST refuse a credential whose proof names a verification method that is not its issuer's. A proof that verifies under some other party's key is that party's statement, not the issuer's, and confers nothing. The same binding holds for every other document a room signs, such as a `RevocationList`.\n\n**A chain that verifies may still be revoked.** A host that has accepted a `RevocationList` for the room (`rooms/revocations/put`) MUST, from the moment it accepted it, refuse every presentation in which the membership credential or any link of `authority` is revoked by that list, under every task and every version of every task it serves for the room. A chain from which any link is revoked is refused whole: a credential delegated from a revoked one confers nothing, however it was attenuated. The refusal is the same `permissionDenied` as any other failed presentation.",
+      "properties": {
+        "membership": {
+          "type": "string",
+          "description": "The presenter's membership credential for this room, or — on a `private` room — a zero-knowledge presentation of it. Serialized per the governing profile."
+        },
+        "authority": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 8,
+          "items": {
+            "type": "string"
+          },
+          "description": "The authority chain, LEAF FIRST: the first element is the credential being relied on and the last MUST be one issued by the room itself. Every link the presenter relies on is present, because the host will not fetch one. Capped at 8: verification is linear in chain length and runs on every operation, so an unbounded chain is a denial-of-service surface against the host. The known uses need 2 to 3 — a person attenuating to an agent, and that agent to a sub-agent."
+        },
+        "subjectBinding": {
+          "type": "string",
+          "description": "REQUIRED on a `private` room, where the subject identifier is withheld: a proof that the membership credential and the authority chain's leaf describe the SAME subject. Without it two parties pool credentials — one contributes membership, the other authority — and the combination verifies as a single party holding both. A host MUST refuse a private-room presentation that omits this."
+        }
+      }
+    }
+  }
+} 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/trust-task-discovery/0.1/payload.ts

@@ -6,7 +6,7 @@
 /**
  * Request payload for the framework-defined trust-task-discovery exchange. Carries zero or more slug-glob patterns the discoverer wants the responder to filter against. The response payload schema is reachable via $anchor: 'response'.
  *
- * @deprecated superseded by trust-task-discovery/0.3
+ * @deprecated superseded by trust-task-discovery/0.4
  */
 export interface TrustTaskDiscoveryPayload {
   /**
@@ -69,7 +69,7 @@ export interface TrustTaskDiscoveryPayload {
 /**
  * List of bare Type URIs the responding party supports. Carried in a Trust Task document whose type is https://trusttasks.org/spec/trust-task-discovery/0.1#response.
  *
- * @deprecated superseded by trust-task-discovery/0.3
+ * @deprecated superseded by trust-task-discovery/0.4
  */
 export interface TrustTaskDiscoveryResponsePayload {
   /**
@@ -113,12 +113,12 @@ export const EXTENDS: string | null = null;
  * this package in a later scheduled batch (SPEC "Superseded and Withdrawn
  * Versions").
  */
-export const DEPRECATION: string | null = "superseded by trust-task-discovery/0.3";
+export const DEPRECATION: string | null = "superseded by trust-task-discovery/0.4";
 
 /**
  * Stable alias for this specification's request payload shape.
  *
- * @deprecated superseded by trust-task-discovery/0.3
+ * @deprecated superseded by trust-task-discovery/0.4
  */
 export type Payload = TrustTaskDiscoveryPayload;
 
@@ -128,7 +128,7 @@ export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/trust-task-discove
 /**
  * Stable alias for this specification's success-response payload shape.
  *
- * @deprecated superseded by trust-task-discovery/0.3
+ * @deprecated superseded by trust-task-discovery/0.4
  */
 export type Response = TrustTaskDiscoveryResponsePayload;
 

package/src/trust-task-discovery/0.2/payload.ts

@@ -6,7 +6,7 @@
 /**
  * Request payload for the framework-defined trust-task-discovery exchange. Carries zero or more slug-glob patterns the discoverer wants the responder to filter against. The response payload schema is reachable via $anchor: 'response'.
  *
- * @deprecated superseded by trust-task-discovery/0.3
+ * @deprecated superseded by trust-task-discovery/0.4
  */
 export interface TrustTaskDiscoveryPayload {
   /**
@@ -69,7 +69,7 @@ export interface TrustTaskDiscoveryPayload {
 /**
  * List of bare Type URIs the responding party supports. Carried in a Trust Task document whose type is https://trusttasks.org/spec/trust-task-discovery/0.2#response.
  *
- * @deprecated superseded by trust-task-discovery/0.3
+ * @deprecated superseded by trust-task-discovery/0.4
  */
 export interface TrustTaskDiscoveryResponsePayload {
   /**
@@ -113,12 +113,12 @@ export const EXTENDS: string | null = null;
  * this package in a later scheduled batch (SPEC "Superseded and Withdrawn
  * Versions").
  */
-export const DEPRECATION: string | null = "superseded by trust-task-discovery/0.3";
+export const DEPRECATION: string | null = "superseded by trust-task-discovery/0.4";
 
 /**
  * Stable alias for this specification's request payload shape.
  *
- * @deprecated superseded by trust-task-discovery/0.3
+ * @deprecated superseded by trust-task-discovery/0.4
  */
 export type Payload = TrustTaskDiscoveryPayload;
 
@@ -128,7 +128,7 @@ export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/trust-task-discove
 /**
  * Stable alias for this specification's success-response payload shape.
  *
- * @deprecated superseded by trust-task-discovery/0.3
+ * @deprecated superseded by trust-task-discovery/0.4
  */
 export type Response = TrustTaskDiscoveryResponsePayload;
 

package/src/trust-task-discovery/0.3/payload.ts

@@ -5,6 +5,8 @@
 
 /**
  * Request payload for the framework-defined trust-task-discovery exchange. Carries zero or more slug-glob patterns the discoverer wants the responder to filter against. The response payload schema is reachable via $anchor: 'response'.
+ *
+ * @deprecated superseded by trust-task-discovery/0.4
  */
 export interface TrustTaskDiscoveryPayload {
   /**
@@ -66,6 +68,8 @@ export interface TrustTaskDiscoveryPayload {
 }
 /**
  * List of bare Type URIs the responding party supports. Carried in a Trust Task document whose type is https://trusttasks.org/spec/trust-task-discovery/0.3#response. A response-level `acceptanceWindow` is the window the responder applies to every listed Type URI whose entry carries none of its own. Where neither is present for an entry, the discoverer has learnt nothing about that entry's window and MUST NOT read the absence as the absence of a window.
+ *
+ * @deprecated superseded by trust-task-discovery/0.4
  */
 export interface TrustTaskDiscoveryResponsePayload {
   /**
@@ -124,15 +128,23 @@ export const EXTENDS: string | null = null;
  * this package in a later scheduled batch (SPEC "Superseded and Withdrawn
  * Versions").
  */
-export const DEPRECATION: string | null = null;
+export const DEPRECATION: string | null = "superseded by trust-task-discovery/0.4";
 
-/** Stable alias for this specification's request payload shape. */
+/**
+ * Stable alias for this specification's request payload shape.
+ *
+ * @deprecated superseded by trust-task-discovery/0.4
+ */
 export type Payload = TrustTaskDiscoveryPayload;
 
 /** Trust Task response type URI (request type URI + "#response"). */
 export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/trust-task-discovery/0.3#response" as const;
 
-/** Stable alias for this specification's success-response payload shape. */
+/**
+ * Stable alias for this specification's success-response payload shape.
+ *
+ * @deprecated superseded by trust-task-discovery/0.4
+ */
 export type Response = TrustTaskDiscoveryResponsePayload;
 
 /**