@openvtc/trust-tasks 0.1.0 → 0.2.0

package/src/provision/integration/0.2/payload.ts

@@ -0,0 +1,181 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/provision/integration/0.2/payload.schema.json
+ */
+
+/**
+ * What the holder is asking the maintainer to do. Tagged on `type`; see `TemplateBootstrapAsk` and `AdminRotationAsk`.
+ */
+export type BootstrapAsk = TemplateBootstrapAsk | AdminRotationAsk;
+
+/**
+ * Relayer presents a VP-signed bootstrap request from an integration holder; the maintainer mints the integration's DIDs and admin credential from a registered DID template and ships the material back HPKE-sealed to the holder's ephemeral did:key. Two ask variants are supported: TemplateBootstrap (mint integration DID + optional admin DID) and AdminRotation (mint only the long-term admin DID).
+ */
+export interface ProvisionIntegrationPayload {
+  request: BootstrapRequest;
+  /**
+   * The maintainer's context identifier the integration is to be provisioned into. When present, authoritative — overrides any `contextHint` carried inside `request.ask`. When ABSENT, the maintainer infers the target context using these rules in order: (1) if the relayer's grant scopes to exactly one context, use that context; (2) if the relayer is a super-admin (Admin role with unrestricted scope) and the maintainer has exactly one context registered, use that context; (3) otherwise reject the request with `provision/integration:context_required`. Wallet-class consumers (browser plugins, mobile companions) that don't know the maintainer's context layout SHOULD omit this field; integration-class consumers (mediator, did-hosting) targeting a specific operational context SHOULD send it explicitly.
+   */
+  context?: string;
+  /**
+   * Producer-assertion mode the maintainer should apply to the returned sealed bundle. `didSigned` (default) — Ed25519 signature over the bundle's domain-bound digest, verified by the holder against the maintainer's published key. `pinnedOnly` — holder pins the bundle's SHA-256 digest as the sole integrity anchor; for dev/test only. Maintainers MAY support additional modes (e.g. `attested` for TEE deployments) and respond with `provision/integration:assertion_unsupported` to unsupported requests.
+   */
+  assertion?: "didSigned" | "pinnedOnly";
+  /**
+   * Caller-preferred validity window for the issued VtaAuthorizationCredential, in seconds. The maintainer's policy applies a floor and ceiling; values outside that range MAY be silently clamped. Defaults to the maintainer's policy default (typically 3600s).
+   */
+  vcValiditySeconds?: number;
+  /**
+   * When `true`, the maintainer provisions the target context inline if it does not already exist. Requires super-admin role on the maintainer; context-admin callers MUST receive `provision/integration:forbidden` against a missing context. Idempotent when the context already exists.
+   */
+  createContext?: boolean;
+  ext?: Ext;
+}
+/**
+ * VP-framed bootstrap request signed by the holder's ephemeral did:key. The proof here is independent of, and additional to, the outer Trust Task envelope's proof — it authenticates the holder (the party the sealed bundle is encrypted for), whereas the envelope's proof authenticates the relayer (the party making the call). The two MAY be the same DID in the common case.
+ */
+export interface BootstrapRequest {
+  /**
+   * JSON-LD contexts. MUST contain both `https://www.w3.org/ns/credentials/v2` and `https://openvtc.org/contexts/bootstrap-v1`. Maintainers verifying the proof MAY refuse other shapes.
+   *
+   * @minItems 2
+   */
+  "@context": [string, string, ...string[]];
+  /**
+   * VP types. MUST contain both `VerifiablePresentation` and `BootstrapRequest`. Additional task-specific types MAY be present.
+   *
+   * @minItems 2
+   */
+  type: [string, string, ...string[]];
+  /**
+   * URN-shaped identifier for this presentation. `urn:uuid:<v4>` is RECOMMENDED.
+   */
+  id: string;
+  /**
+   * The integration's ephemeral did:key (Ed25519). Identifies the party the returned bundle is HPKE-sealed for; the VP proof verifies under this DID's verification method.
+   */
+  holder: string;
+  /**
+   * 16 random bytes encoded as base64url-no-pad (22 characters). The maintainer treats this as the sealed bundle's `bundleId` (decoded to hex, exposed in `summary.bundleIdHex`) and SHOULD enforce one-shot semantics — a second provisioning with the same nonce MUST be refused as a replay.
+   */
+  nonce: string;
+  /**
+   * Freshness bound for the VP. RFC 3339 UTC. Maintainers SHOULD allow ±5 minutes of clock skew.
+   */
+  validUntil: string;
+  /**
+   * Optional human-readable label carried into the maintainer's audit log.
+   */
+  label?: string;
+  ask: BootstrapAsk;
+  proof: DataIntegrityProof;
+}
+/**
+ * Mint an integration DID from `template`, and (when `adminTemplate` is present) atomically roll over the holder to a fresh long-term admin DID minted from `adminTemplate`.
+ */
+export interface TemplateBootstrapAsk {
+  type: "templateBootstrap";
+  /**
+   * Hint for the integration's target context. The wire `payload.context` is authoritative; this hint exists for documentation / cross-check only.
+   */
+  contextHint?: string;
+  template: DidTemplateRef;
+  adminTemplate?: DidTemplateRef1;
+  /**
+   * Free-form operator note carried into the maintainer's audit log.
+   */
+  note?: string;
+}
+/**
+ * Integration template. MUST be registered at the maintainer; MUST declare a `kind` other than `"admin"`.
+ */
+export interface DidTemplateRef {
+  /**
+   * Template name as registered at the maintainer (built-in or operator-uploaded). Examples of built-ins shipped with VTA deployments: `didcomm-mediator`, `vta-admin`, `did-hosting-control`, `did-hosting-daemon`, `did-hosting-server`.
+   */
+  name: string;
+  /**
+   * Variable bindings the maintainer feeds to the template renderer. MUST satisfy the template's `requiredVars`; values for `optionalVars` MAY be supplied. Unknown vars are rejected with `provision/integration:template_vars_invalid`.
+   */
+  vars?: {
+    [k: string]: unknown | undefined;
+  };
+}
+/**
+ * Optional admin-DID template. When present, the maintainer mints a fresh long-term admin DID + keys, binds the authorization VC + ACL row to it, and rolls the holder over from the ephemeral did:key in the same transaction. When absent, the authorization VC's subject and ACL row are bound to the ephemeral `holder`, which the operator is expected to swap via `acl/swap-key/0.1` before steady-state operation. MUST declare `kind == "admin"` when present.
+ */
+export interface DidTemplateRef1 {
+  /**
+   * Template name as registered at the maintainer (built-in or operator-uploaded). Examples of built-ins shipped with VTA deployments: `didcomm-mediator`, `vta-admin`, `did-hosting-control`, `did-hosting-daemon`, `did-hosting-server`.
+   */
+  name: string;
+  /**
+   * Variable bindings the maintainer feeds to the template renderer. MUST satisfy the template's `requiredVars`; values for `optionalVars` MAY be supplied. Unknown vars are rejected with `provision/integration:template_vars_invalid`.
+   */
+  vars?: {
+    [k: string]: unknown | undefined;
+  };
+}
+/**
+ * Admin-only mint. No integration DID is produced. Used by holders that bring (or will mint elsewhere) their own integration-side identity and only need an admin credential at this maintainer.
+ */
+export interface AdminRotationAsk {
+  type: "adminRotation";
+  /**
+   * Hint for the admin grant's target context. The wire `payload.context` is authoritative.
+   */
+  contextHint?: string;
+  adminTemplate: DidTemplateRef2;
+  /**
+   * Free-form operator note carried into the maintainer's audit log.
+   */
+  note?: string;
+}
+/**
+ * Admin-DID template. MUST be registered at the maintainer and MUST declare `kind == "admin"`.
+ */
+export interface DidTemplateRef2 {
+  /**
+   * Template name as registered at the maintainer (built-in or operator-uploaded). Examples of built-ins shipped with VTA deployments: `didcomm-mediator`, `vta-admin`, `did-hosting-control`, `did-hosting-daemon`, `did-hosting-server`.
+   */
+  name: string;
+  /**
+   * Variable bindings the maintainer feeds to the template renderer. MUST satisfy the template's `requiredVars`; values for `optionalVars` MAY be supplied. Unknown vars are rejected with `provision/integration:template_vars_invalid`.
+   */
+  vars?: {
+    [k: string]: unknown | undefined;
+  };
+}
+/**
+ * Data Integrity proof signed by the holder's Ed25519 key. Cryptosuite MUST equal `eddsa-jcs-2022`. `proofPurpose` MUST equal `authentication`. `verificationMethod` MUST resolve under `holder`. Signs the JCS canonicalisation of the VP with `proof` removed.
+ */
+export interface DataIntegrityProof {
+  type: "DataIntegrityProof";
+  /**
+   * This version pins `eddsa-jcs-2022`. Maintainers MUST reject other values until a future minor extends the allowlist.
+   */
+  cryptosuite: string;
+  /**
+   * DID URL with fragment. The DID portion (left of `#`) MUST equal `holder`.
+   */
+  verificationMethod: string;
+  created?: string;
+  proofPurpose: "authentication";
+  /**
+   * Multibase-encoded Ed25519 signature.
+   */
+  proofValue: string;
+  [k: string]: unknown | undefined;
+}
+/**
+ * Ecosystem-defined extension members per SPEC.md §4.5.1.
+ */
+export interface Ext {
+  [k: string]: unknown | undefined;
+}
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/provision/integration/0.2" as const;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/provision/integration/0.2#response" as const;

package/src/push/provision/0.1/payload.ts

@@ -0,0 +1,37 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/push/provision/0.1/payload.schema.json
+ */
+
+/**
+ * The controller VTA sets a wake handle's trigger allowlist on the push gateway — the DIDs permitted to wake the device. The gateway accepts it only from the handle's recorded controller VTA and enforces it on every push/wake. See the push wake-up binding (https://trusttasks.org/binding/push/0.1).
+ */
+export interface PushProvisionPayload {
+  /**
+   * The opaque gateway-issued handle (from push/register) whose allowlist is being set.
+   */
+  handle: string;
+  policy: WakeTriggerPolicy;
+  ext?: Ext;
+}
+/**
+ * The trigger allowlist the VTA computed by its own policy — the DIDs permitted to wake this handle (typically the device's mediator and/or the VTA itself). Empty disables waking.
+ */
+export interface WakeTriggerPolicy {
+  /**
+   * DIDs authorized to trigger a wake for this handle. An empty array means no party may wake the device (push effectively disabled while the handle exists). The gateway authenticates the trigger's DID before checking membership.
+   */
+  allowedTriggers: string[];
+}
+/**
+ * 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.
+ */
+export interface Ext {
+  [k: string]: unknown | undefined;
+}
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/push/provision/0.1" as const;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/push/provision/0.1#response" as const;

package/src/push/provision/0.2/payload.ts

@@ -0,0 +1,37 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/push/provision/0.2/payload.schema.json
+ */
+
+/**
+ * The controller VTA sets a wake handle's trigger allowlist on the push gateway — the DIDs permitted to wake the device. The gateway accepts it only from the handle's recorded controller VTA and enforces it on every push/wake. See the push wake-up binding (https://trusttasks.org/binding/push/0.1).
+ */
+export interface PushProvisionPayload {
+  /**
+   * The opaque gateway-issued handle (from push/register) whose allowlist is being set.
+   */
+  handle: string;
+  policy: WakeTriggerPolicy;
+  ext?: Ext;
+}
+/**
+ * The trigger allowlist the VTA computed by its own policy — the DIDs permitted to wake this handle (typically the device's mediator and/or the VTA itself). Empty disables waking.
+ */
+export interface WakeTriggerPolicy {
+  /**
+   * DIDs authorized to trigger a wake for this handle. An empty array means no party may wake the device (push effectively disabled while the handle exists). The gateway authenticates the trigger's DID before checking membership.
+   */
+  allowedTriggers: string[];
+}
+/**
+ * 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.
+ */
+export interface Ext {
+  [k: string]: unknown | undefined;
+}
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/push/provision/0.2" as const;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/push/provision/0.2#response" as const;

package/src/push/register/0.1/payload.ts

@@ -0,0 +1,75 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/push/register/0.1/payload.schema.json
+ */
+
+/**
+ * The platform push channel (token). Held by the gateway only — never disclosed to any other party.
+ */
+export type PushRegistration = Apns | Fcm | WebPush;
+
+/**
+ * A device registers its platform push token (APNs / FCM / Web Push) with a push gateway and names the controller VTA permitted to provision its trigger allowlist. The gateway returns an opaque WakeHandle; the raw token is held by the gateway only. See the push wake-up binding (https://trusttasks.org/binding/push/0.1).
+ */
+export interface PushRegisterPayload {
+  registration: PushRegistration;
+  /**
+   * The DID of the VTA permitted to provision this handle's trigger allowlist (push/provision). The device conveys the resulting handle to this VTA via device/set-wake.
+   */
+  controllerVtaDid: string;
+  ext?: Ext;
+}
+export interface Apns {
+  platform: "apns";
+  /**
+   * APNs device token (hex string issued by Apple Push Notification service).
+   */
+  token: string;
+  /**
+   * APNs topic — typically the app bundle identifier the gateway pushes to.
+   */
+  topic: string;
+  /**
+   * Which APNs environment issued the token. Maintainers route to the matching APNs endpoint.
+   */
+  environment?: "sandbox" | "production";
+}
+export interface Fcm {
+  platform: "fcm";
+  /**
+   * Firebase Cloud Messaging registration token. The gateway sends a data message (not a notification message) so the app controls wake and display.
+   */
+  token: string;
+}
+export interface WebPush {
+  platform: "webpush";
+  /**
+   * RFC 8030 Web Push subscription endpoint.
+   */
+  endpoint: string;
+  /**
+   * Web Push (RFC 8291) encryption keys. Note: per the push binding the payload remains contentless regardless of this encryption.
+   */
+  keys: {
+    /**
+     * base64url-encoded P-256 ECDH public key.
+     */
+    p256dh: string;
+    /**
+     * base64url-encoded auth secret.
+     */
+    auth: string;
+  };
+}
+/**
+ * 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.
+ */
+export interface Ext {
+  [k: string]: unknown | undefined;
+}
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/push/register/0.1" as const;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/push/register/0.1#response" as const;

package/src/push/register/0.2/payload.ts

@@ -0,0 +1,75 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/push/register/0.2/payload.schema.json
+ */
+
+/**
+ * The platform push channel (token). Held by the gateway only — never disclosed to any other party.
+ */
+export type PushRegistration = Apns | Fcm | WebPush;
+
+/**
+ * A device registers its platform push token (APNs / FCM / Web Push) with a push gateway and names the controller VTA permitted to provision its trigger allowlist. The gateway returns an opaque WakeHandle; the raw token is held by the gateway only. See the push wake-up binding (https://trusttasks.org/binding/push/0.1).
+ */
+export interface PushRegisterPayload {
+  registration: PushRegistration;
+  /**
+   * The DID of the VTA permitted to provision this handle's trigger allowlist (push/provision). The device conveys the resulting handle to this VTA via device/set-wake.
+   */
+  controllerVtaDid: string;
+  ext?: Ext;
+}
+export interface Apns {
+  platform: "apns";
+  /**
+   * APNs device token (hex string issued by Apple Push Notification service).
+   */
+  token: string;
+  /**
+   * APNs topic — typically the app bundle identifier the gateway pushes to.
+   */
+  topic: string;
+  /**
+   * Which APNs environment issued the token. Maintainers route to the matching APNs endpoint.
+   */
+  environment?: "sandbox" | "production";
+}
+export interface Fcm {
+  platform: "fcm";
+  /**
+   * Firebase Cloud Messaging registration token. The gateway sends a data message (not a notification message) so the app controls wake and display.
+   */
+  token: string;
+}
+export interface WebPush {
+  platform: "webpush";
+  /**
+   * RFC 8030 Web Push subscription endpoint.
+   */
+  endpoint: string;
+  /**
+   * Web Push (RFC 8291) encryption keys. Note: per the push binding the payload remains contentless regardless of this encryption.
+   */
+  keys: {
+    /**
+     * base64url-encoded P-256 ECDH public key.
+     */
+    p256dh: string;
+    /**
+     * base64url-encoded auth secret.
+     */
+    auth: string;
+  };
+}
+/**
+ * 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.
+ */
+export interface Ext {
+  [k: string]: unknown | undefined;
+}
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/push/register/0.2" as const;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/push/register/0.2#response" as const;

package/src/push/wake/0.1/payload.ts

@@ -0,0 +1,43 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/push/wake/0.1/payload.schema.json
+ */
+
+/**
+ * A trigger (the device's mediator or its VTA) asks the push gateway to deliver a contentless wake to a handle. Carries ONLY the push binding's contentless hint fields — never Trust Task content. The gateway authorizes against the handle's allowlist, then fires the doorbell. See the push wake-up binding (https://trusttasks.org/binding/push/0.1).
+ */
+export interface PushWakePayload {
+  /**
+   * The opaque gateway-issued handle to wake.
+   */
+  handle: string;
+  /**
+   * Push binding wire version.
+   */
+  v: 1;
+  /**
+   * OPTIONAL. The mediator holding the queued messages, so a multi-mediator consumer knows which to drain. A hint — echoed into the contentless push.
+   */
+  mediator?: string;
+  /**
+   * OPTIONAL. Approximate count of queued messages. Advisory only.
+   */
+  count?: number;
+  /**
+   * OPTIONAL. A hint the consumer MAY map to platform priority/alert behavior.
+   */
+  urgency?: "interactive" | "background";
+  ext?: Ext;
+}
+/**
+ * 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.
+ */
+export interface Ext {
+  [k: string]: unknown | undefined;
+}
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/push/wake/0.1" as const;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/push/wake/0.1#response" as const;

package/src/push/wake/0.2/payload.ts

@@ -0,0 +1,43 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/push/wake/0.2/payload.schema.json
+ */
+
+/**
+ * A trigger (the device's mediator or its VTA) asks the push gateway to deliver a contentless wake to a handle. Carries ONLY the push binding's contentless hint fields — never Trust Task content. The gateway authorizes against the handle's allowlist, then fires the doorbell. See the push wake-up binding (https://trusttasks.org/binding/push/0.1).
+ */
+export interface PushWakePayload {
+  /**
+   * The opaque gateway-issued handle to wake.
+   */
+  handle: string;
+  /**
+   * Push binding wire version.
+   */
+  v: 1;
+  /**
+   * OPTIONAL. The mediator holding the queued messages, so a multi-mediator consumer knows which to drain. A hint — echoed into the contentless push.
+   */
+  mediator?: string;
+  /**
+   * OPTIONAL. Approximate count of queued messages. Advisory only.
+   */
+  count?: number;
+  /**
+   * OPTIONAL. A hint the consumer MAY map to platform priority/alert behavior.
+   */
+  urgency?: "interactive" | "background";
+  ext?: Ext;
+}
+/**
+ * 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.
+ */
+export interface Ext {
+  [k: string]: unknown | undefined;
+}
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/push/wake/0.2" as const;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/push/wake/0.2#response" as const;

package/src/sync/_shared/0.2/sync-event.ts

@@ -0,0 +1,11 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/sync/_shared/0.2/sync-event.schema.json
+ */
+
+/**
+ * Canonical event union referenced by sync/event/0.1 (the push-notification task) and by vault/sync/0.1 (the request-response catch-up task). Both deliver the same event shapes; the difference is only the transport (push vs pull).
+ */
+export interface SyncEventSharedDefinitionForServerPushedSyncNotifications {
+  [k: string]: unknown | undefined;
+}