@openvtc/trust-tasks 0.23.6 → 0.23.8

package/src/keys/sign-sshsig/0.1/payload.ts

@@ -0,0 +1,261 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/keys/sign-sshsig/0.1/payload.schema.json
+ */
+
+import type { Ext } from "../../../_shared/components.js";
+
+
+/**
+ * A request for an SSHSIG signature (the OpenSSH `PROTOCOL.sshsig` format git uses for SSH commit signing) over a message digest, made with a key the custodian holds. The producer supplies the digest and the namespace; the custodian builds the signed-data structure itself. The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, proof) are owned by the framework — SPEC §6.3.
+ */
+export interface KeysSignSSHSIGPayload {
+  /**
+   * Identifier of the key to sign with. The key MUST be `active`.
+   */
+  keyId: string;
+  /**
+   * Signature algorithm, as a JOSE identifier: `EdDSA` with an `ed25519` key (SSH key type `ssh-ed25519`), `ES256` with a `p256` key (`ecdsa-sha2-nistp256`). These are the custodian-held key types SSHSIG defines a signature for. MUST be compatible with the named key's `keyType`. Closed: an unrecognised algorithm is refused, never substituted.
+   */
+  algorithm: "EdDSA" | "ES256";
+  /**
+   * The SSHSIG namespace the signature is bound to — `git` for a git commit or tag, `file` for `ssh-keygen -Y sign` over a file. Printable ASCII without spaces. A signature made under one namespace does not verify under another, so the custodian MAY restrict which namespaces a producer may name.
+   */
+  namespace: string;
+  /**
+   * The digest algorithm the producer applied to the message, in the SSHSIG spelling (externally owned, carried verbatim). It is written into the signed data, so the verifier recomputes the digest with the same algorithm.
+   */
+  hashAlgorithm: "sha256" | "sha512";
+  /**
+   * The digest of the message, `H(message)` in `PROTOCOL.sshsig`, base64url-encoded without padding: 32 bytes (43 characters) for `sha256`, 64 bytes (86 characters) for `sha512`. The custodian never sees the message itself.
+   */
+  messageHash: string;
+  /**
+   * Ecosystem-defined extension members per SPEC.md §4.5.1.
+   */
+  ext?: Ext;
+}
+/**
+ * The success response to a keys/sign-sshsig request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/keys/sign-sshsig/0.1#response. Failures use trust-task-error, not this shape.
+ */
+export interface KeysSignSSHSIGResponsePayload {
+  /**
+   * The key that produced the signature. Echoed so a response separated from its request is still attributable.
+   */
+  keyId: string;
+  /**
+   * The algorithm the signature was made with — the one the request named.
+   */
+  algorithm: "EdDSA" | "ES256";
+  /**
+   * The raw signature over the SSHSIG signed data, base64url-encoded without padding: 64 bytes for `EdDSA`; for `ES256`, the 64-byte JOSE `r || s` form, which the producer re-encodes as the two SSH `mpint`s when it assembles the SSHSIG blob.
+   */
+  signature: 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/keys/sign-sshsig/0.1" as const;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = KeysSignSSHSIGPayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/keys/sign-sshsig/0.1#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = KeysSignSSHSIGResponsePayload;
+
+/**
+ * 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/keys/sign-sshsig/0.1",
+  "title": "Keys — Sign SSHSIG — payload",
+  "description": "A request for an SSHSIG signature (the OpenSSH `PROTOCOL.sshsig` format git uses for SSH commit signing) over a message digest, made with a key the custodian holds. The producer supplies the digest and the namespace; the custodian builds the signed-data structure itself. The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, proof) are owned by the framework — SPEC §6.3.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "keyId",
+    "algorithm",
+    "namespace",
+    "hashAlgorithm",
+    "messageHash"
+  ],
+  "properties": {
+    "keyId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Identifier of the key to sign with. The key MUST be `active`."
+    },
+    "algorithm": {
+      "type": "string",
+      "enum": [
+        "EdDSA",
+        "ES256"
+      ],
+      "description": "Signature algorithm, as a JOSE identifier: `EdDSA` with an `ed25519` key (SSH key type `ssh-ed25519`), `ES256` with a `p256` key (`ecdsa-sha2-nistp256`). These are the custodian-held key types SSHSIG defines a signature for. MUST be compatible with the named key's `keyType`. Closed: an unrecognised algorithm is refused, never substituted."
+    },
+    "namespace": {
+      "type": "string",
+      "pattern": "^[!-~]{1,128}$",
+      "description": "The SSHSIG namespace the signature is bound to — `git` for a git commit or tag, `file` for `ssh-keygen -Y sign` over a file. Printable ASCII without spaces. A signature made under one namespace does not verify under another, so the custodian MAY restrict which namespaces a producer may name."
+    },
+    "hashAlgorithm": {
+      "type": "string",
+      "enum": [
+        "sha256",
+        "sha512"
+      ],
+      "description": "The digest algorithm the producer applied to the message, in the SSHSIG spelling (externally owned, carried verbatim). It is written into the signed data, so the verifier recomputes the digest with the same algorithm."
+    },
+    "messageHash": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]+$",
+      "minLength": 43,
+      "maxLength": 86,
+      "description": "The digest of the message, `H(message)` in `PROTOCOL.sshsig`, base64url-encoded without padding: 32 bytes (43 characters) for `sha256`, 64 bytes (86 characters) for `sha512`. The custodian never sees the message itself."
+    },
+    "ext": {
+      "$ref": "#/$defs/Ext",
+      "description": "Ecosystem-defined extension members per SPEC.md §4.5.1."
+    }
+  },
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "Keys — Sign SSHSIG — response payload",
+      "description": "The success response to a keys/sign-sshsig request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/keys/sign-sshsig/0.1#response. Failures use trust-task-error, not this shape.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "keyId",
+        "algorithm",
+        "signature"
+      ],
+      "properties": {
+        "keyId": {
+          "type": "string",
+          "description": "The key that produced the signature. Echoed so a response separated from its request is still attributable."
+        },
+        "algorithm": {
+          "type": "string",
+          "enum": [
+            "EdDSA",
+            "ES256"
+          ],
+          "description": "The algorithm the signature was made with — the one the request named."
+        },
+        "signature": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_-]+$",
+          "description": "The raw signature over the SSHSIG signed data, base64url-encoded without padding: 64 bytes for `EdDSA`; for `ES256`, the 64-byte JOSE `r || s` form, which the producer re-encodes as the two SSH `mpint`s when it assembles the SSHSIG blob."
+        },
+        "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-]+)+$"
+      }
+    }
+  }
+} 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": "Keys — Sign SSHSIG — response payload",
+      "description": "The success response to a keys/sign-sshsig request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/keys/sign-sshsig/0.1#response. Failures use trust-task-error, not this shape.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "keyId",
+        "algorithm",
+        "signature"
+      ],
+      "properties": {
+        "keyId": {
+          "type": "string",
+          "description": "The key that produced the signature. Echoed so a response separated from its request is still attributable."
+        },
+        "algorithm": {
+          "type": "string",
+          "enum": [
+            "EdDSA",
+            "ES256"
+          ],
+          "description": "The algorithm the signature was made with — the one the request named."
+        },
+        "signature": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_-]+$",
+          "description": "The raw signature over the SSHSIG signed data, base64url-encoded without padding: 64 bytes for `EdDSA`; for `ES256`, the 64-byte JOSE `r || s` form, which the producer re-encodes as the two SSH `mpint`s when it assembles the SSHSIG blob."
+        },
+        "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-]+)+$"
+      }
+    }
+  }
+} 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: false,
+  isRecipientRequired: true,
+  isIssuedAtRequired: true,
+  payloadSchema: RESPONSE_PAYLOAD_SCHEMA,
+} as const;

package/src/vtc/vetting/hidden/publish/0.1/payload.ts

@@ -6,6 +6,11 @@
 import type { Ext } from "../../../../../_shared/components.js";
 
 
+/**
+ * The length of one tick of the drip, as an ISO 8601 duration in days and/or hours — at least `PT1H`; a request that omits it gets `P3D`. A label's tick `t` is the window starting `t` tick lengths after the label's start (`vtc/vetting/vetters/pcs-tokens`).
+ */
+export type TickLength = string;
+
 /**
  * Turn on (or rotate the parameters of) hidden-vetter admission for one criterion. Every member but criterionId has a default. The outer document members are owned by the framework — SPEC §6.3.
  */
@@ -30,6 +35,7 @@ export interface VTCVettingHiddenPublishPayload {
    * How many attestation tokens a vetter draws per tick. Defaults to three.
    */
   dripPerTick?: number;
+  tickLength?: TickLength;
   /**
    * Events this community is running, replacing whatever was there. Absent or empty removes every event.
    */
@@ -113,6 +119,7 @@ export interface StoredConfig {
   livePeriods: string[];
   liveTokenLabels: string[];
   dripPerTick: number;
+  tickLength: TickLength;
   events: StoredEvent[];
 }
 export interface StoredEvent {
@@ -146,6 +153,7 @@ export interface PublishedConfig {
   vetterLabels: string[];
   tokenLabels: string[];
   dripPerTick: number;
+  tickLength: TickLength;
   events: PublishedEvent[];
 }
 /**
@@ -222,6 +230,9 @@ export const PAYLOAD_SCHEMA = {
       "minimum": 1,
       "description": "How many attestation tokens a vetter draws per tick. Defaults to three."
     },
+    "tickLength": {
+      "$ref": "#/$defs/TickLength"
+    },
     "events": {
       "type": "array",
       "items": {
@@ -234,6 +245,12 @@ export const PAYLOAD_SCHEMA = {
     }
   },
   "$defs": {
+    "TickLength": {
+      "title": "TickLength",
+      "type": "string",
+      "pattern": "^P(?:\\d+D(?:T\\d+H)?|T\\d+H)$",
+      "description": "The length of one tick of the drip, as an ISO 8601 duration in days and/or hours — at least `PT1H`; a request that omits it gets `P3D`. A label's tick `t` is the window starting `t` tick lengths after the label's start (`vtc/vetting/vetters/pcs-tokens`)."
+    },
     "RequestEvent": {
       "title": "RequestEvent",
       "type": "object",
@@ -403,6 +420,7 @@ export const PAYLOAD_SCHEMA = {
         "livePeriods",
         "liveTokenLabels",
         "dripPerTick",
+        "tickLength",
         "events"
       ],
       "properties": {
@@ -440,6 +458,9 @@ export const PAYLOAD_SCHEMA = {
           "type": "integer",
           "minimum": 1
         },
+        "tickLength": {
+          "$ref": "#/$defs/TickLength"
+        },
         "events": {
           "type": "array",
           "items": {
@@ -460,6 +481,7 @@ export const PAYLOAD_SCHEMA = {
         "vetterLabels",
         "tokenLabels",
         "dripPerTick",
+        "tickLength",
         "events"
       ],
       "properties": {
@@ -496,6 +518,9 @@ export const PAYLOAD_SCHEMA = {
           "type": "integer",
           "minimum": 1
         },
+        "tickLength": {
+          "$ref": "#/$defs/TickLength"
+        },
         "events": {
           "type": "array",
           "items": {
@@ -557,6 +582,12 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$ref": "#/$defs/Response",
   "$defs": {
+    "TickLength": {
+      "title": "TickLength",
+      "type": "string",
+      "pattern": "^P(?:\\d+D(?:T\\d+H)?|T\\d+H)$",
+      "description": "The length of one tick of the drip, as an ISO 8601 duration in days and/or hours — at least `PT1H`; a request that omits it gets `P3D`. A label's tick `t` is the window starting `t` tick lengths after the label's start (`vtc/vetting/vetters/pcs-tokens`)."
+    },
     "RequestEvent": {
       "title": "RequestEvent",
       "type": "object",
@@ -726,6 +757,7 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
         "livePeriods",
         "liveTokenLabels",
         "dripPerTick",
+        "tickLength",
         "events"
       ],
       "properties": {
@@ -763,6 +795,9 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
           "type": "integer",
           "minimum": 1
         },
+        "tickLength": {
+          "$ref": "#/$defs/TickLength"
+        },
         "events": {
           "type": "array",
           "items": {
@@ -783,6 +818,7 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
         "vetterLabels",
         "tokenLabels",
         "dripPerTick",
+        "tickLength",
         "events"
       ],
       "properties": {
@@ -819,6 +855,9 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
           "type": "integer",
           "minimum": 1
         },
+        "tickLength": {
+          "$ref": "#/$defs/TickLength"
+        },
         "events": {
           "type": "array",
           "items": {

package/src/vtc/vetting/hidden/show/0.1/payload.ts

@@ -6,6 +6,11 @@
 import type { Ext } from "../../../../../_shared/components.js";
 
 
+/**
+ * The length of one tick of the drip, as an ISO 8601 duration in days and/or hours — at least `PT1H`. A label's tick `t` is the window starting `t` tick lengths after the label's start (`vtc/vetting/vetters/pcs-tokens`).
+ */
+export type TickLength = string;
+
 /**
  * Read one criterion's stored hidden-vetting configuration, what it publishes, and the aggregate counts an administrator needs to run it. The outer document members are owned by the framework — SPEC §6.3.
  */
@@ -65,6 +70,7 @@ export interface StoredConfig {
   livePeriods: string[];
   liveTokenLabels: string[];
   dripPerTick: number;
+  tickLength: TickLength;
   events: StoredEvent[];
 }
 export interface StoredEvent {
@@ -108,6 +114,7 @@ export interface PublishedConfig {
   vetterLabels: string[];
   tokenLabels: string[];
   dripPerTick: number;
+  tickLength: TickLength;
   events: PublishedEvent[];
 }
 /**
@@ -306,6 +313,7 @@ export const PAYLOAD_SCHEMA = {
         "livePeriods",
         "liveTokenLabels",
         "dripPerTick",
+        "tickLength",
         "events"
       ],
       "properties": {
@@ -343,6 +351,9 @@ export const PAYLOAD_SCHEMA = {
           "type": "integer",
           "minimum": 1
         },
+        "tickLength": {
+          "$ref": "#/$defs/TickLength"
+        },
         "events": {
           "type": "array",
           "items": {
@@ -363,6 +374,7 @@ export const PAYLOAD_SCHEMA = {
         "vetterLabels",
         "tokenLabels",
         "dripPerTick",
+        "tickLength",
         "events"
       ],
       "properties": {
@@ -399,6 +411,9 @@ export const PAYLOAD_SCHEMA = {
           "type": "integer",
           "minimum": 1
         },
+        "tickLength": {
+          "$ref": "#/$defs/TickLength"
+        },
         "events": {
           "type": "array",
           "items": {
@@ -516,6 +531,12 @@ export const PAYLOAD_SCHEMA = {
         }
       }
     },
+    "TickLength": {
+      "title": "TickLength",
+      "type": "string",
+      "pattern": "^P(?:\\d+D(?:T\\d+H)?|T\\d+H)$",
+      "description": "The length of one tick of the drip, as an ISO 8601 duration in days and/or hours — at least `PT1H`. A label's tick `t` is the window starting `t` tick lengths after the label's start (`vtc/vetting/vetters/pcs-tokens`)."
+    },
     "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.",
@@ -652,6 +673,7 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
         "livePeriods",
         "liveTokenLabels",
         "dripPerTick",
+        "tickLength",
         "events"
       ],
       "properties": {
@@ -689,6 +711,9 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
           "type": "integer",
           "minimum": 1
         },
+        "tickLength": {
+          "$ref": "#/$defs/TickLength"
+        },
         "events": {
           "type": "array",
           "items": {
@@ -709,6 +734,7 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
         "vetterLabels",
         "tokenLabels",
         "dripPerTick",
+        "tickLength",
         "events"
       ],
       "properties": {
@@ -745,6 +771,9 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
           "type": "integer",
           "minimum": 1
         },
+        "tickLength": {
+          "$ref": "#/$defs/TickLength"
+        },
         "events": {
           "type": "array",
           "items": {
@@ -862,6 +891,12 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
         }
       }
     },
+    "TickLength": {
+      "title": "TickLength",
+      "type": "string",
+      "pattern": "^P(?:\\d+D(?:T\\d+H)?|T\\d+H)$",
+      "description": "The length of one tick of the drip, as an ISO 8601 duration in days and/or hours — at least `PT1H`. A label's tick `t` is the window starting `t` tick lengths after the label's start (`vtc/vetting/vetters/pcs-tokens`)."
+    },
     "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.",

package/src/vtc/vetting/vetters/pcs-tokens/0.1/payload.ts

@@ -15,7 +15,7 @@ export interface VTCVettingPCSTokensPayload {
    */
   label: string;
   /**
-   * The vetter's own schedule counter for this label. It makes `once per tick` a rule the community can enforce without learning whether the vetter has been busy.
+   * Which tick of this label is being drawn: tick `t` is the window starting `t` tick lengths after the label's start instant (see the specification's Definitions). The community refuses a tick that has not begun (`tickNotYet`) and one already served (`alreadyServed`), so the total drawn under a label is bounded by the drip rate times the ticks elapsed.
    */
   tick: number;
   /**
@@ -116,7 +116,7 @@ export const PAYLOAD_SCHEMA = {
     "tick": {
       "type": "integer",
       "minimum": 0,
-      "description": "The vetter's own schedule counter for this label. It makes `once per tick` a rule the community can enforce without learning whether the vetter has been busy."
+      "description": "Which tick of this label is being drawn: tick `t` is the window starting `t` tick lengths after the label's start instant (see the specification's Definitions). The community refuses a tick that has not begun (`tickNotYet`) and one already served (`alreadyServed`), so the total drawn under a label is bounded by the drip rate times the ticks elapsed."
     },
     "requests": {
       "type": "array",