@openvtc/trust-tasks 0.1.0 → 0.2.0

package/src/vault/release/0.2/payload.ts

@@ -0,0 +1,105 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vault/release/0.2/payload.schema.json
+ */
+
+/**
+ * Optional — for entries with multiple targets, indicates which one the consumer is acting against. The maintainer's policy may decide release based on the target (e.g. release for web origin allowed, release for iOS app denied).
+ */
+export type SiteTarget = WebOrigin | Did | IosApp | AndroidApp;
+
+/**
+ * Consumer requests that the maintainer release the cleartext secret material of a vault entry. The response carries the secret in a pluggable cipher envelope (see vault/_shared/0.1/sealed-envelope); the cleartext shape is `vault/_shared/0.1/vault-secret#/$defs/VaultSecret`. This is the fallback when proxy-login is not viable (`vault/proxy-login:not_proxyable`) or when the consumer needs the raw secret for a flow the maintainer cannot perform (e.g. autofill into a desktop app, copy-to-clipboard for offline use).
+ */
+export interface VaultReleasePayload {
+  entryId: string;
+  target?: SiteTarget;
+  consumerContext?: ConsumerContext;
+  stepUpProof?: StepUpProof;
+  /**
+   * Consumer's requested cache TTL for the released secret. The maintainer MAY cap this; the consumer MUST honour the maintainer's decision.
+   */
+  ttlSecondsHint?: number;
+  ext?: Ext;
+}
+export interface WebOrigin {
+  kind: "webOrigin";
+  /**
+   * Web origin per RFC 6454 (scheme + host + optional port), e.g. "https://github.com". Compared by exact string equality after canonicalisation (lowercase host, default port elided). Consumers wanting subdomain coverage SHOULD add multiple targets, not encode a wildcard.
+   */
+  origin: string;
+}
+export interface Did {
+  kind: "did";
+  /**
+   * DID identifying the relying party (e.g. did:web:rp.example). The vault maintainer is responsible for any DID resolution required to act on this entry.
+   */
+  did: string;
+}
+export interface IosApp {
+  kind: "iosApp";
+  /**
+   * iOS bundle identifier in reverse-DNS form (e.g. "com.github.stwalkerster.codehub"). Compared by exact string equality. Matches when an iOS Companion identifies the requesting app via its bundle id (typically via the OS Credential Manager integration).
+   */
+  bundleId: string;
+  /**
+   * Optional Apple Developer Team identifier (10-character alphanumeric). When supplied, the maintainer SHOULD also verify the team id of the requesting app before matching — defense in depth against bundle-id squatting on jailbroken devices.
+   */
+  teamId?: string;
+}
+export interface AndroidApp {
+  kind: "androidApp";
+  /**
+   * Android package name in reverse-DNS form (e.g. "com.github.android").
+   */
+  packageName: string;
+  /**
+   * SHA-256 fingerprints of the app's signing certificates, in colon-separated hex (the format `apksigner` and the Play Console emit). At least one fingerprint MUST be present. The maintainer matches when ANY of the provided fingerprints matches the requesting app's signature — this supports apps signed by multiple keys (e.g. during certificate rotation via Play App Signing).
+   *
+   * @minItems 1
+   */
+  sha256CertFingerprints: [string, ...string[]];
+}
+/**
+ * Caller's situational context — fed to the policy engine.
+ */
+export interface ConsumerContext {
+  /**
+   * Device-binding id assigned at registration. The maintainer cross-checks this against the authenticated transport identity.
+   */
+  deviceId?: string;
+  /**
+   * Most recent local user-verification on the consumer device (WebAuthn UV, biometric unlock). The maintainer's policy may require this to be within N seconds.
+   */
+  lastUserVerificationAt?: string;
+  /**
+   * Producer-supplied network classification. Advisory.
+   */
+  networkClass?: "unknown" | "home" | "corp" | "public" | "vpn";
+}
+/**
+ * Step-up proof on retry after step_up_required.
+ */
+export interface StepUpProof {
+  kind: "webauthnUv" | "pushApproval" | "totp";
+  /**
+   * Format depends on kind: WebAuthn assertion (base64url), DIDComm approval-response message id, or 6–8-digit TOTP code.
+   */
+  proof: string;
+  /**
+   * Maintainer-issued challenge id the proof responds to.
+   */
+  challengeId: 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/vault/release/0.2" as const;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/vault/release/0.2#response" as const;

package/src/vault/sign-trust-task/0.2/payload.ts

@@ -0,0 +1,101 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vault/sign-trust-task/0.2/payload.schema.json
+ */
+
+/**
+ * Consumer asks the maintainer to attach a Data Integrity proof (eddsa-jcs-2022) to a Trust Task envelope, signing as the principal DID of a `didSelfIssued` or `didcommPeer` vault entry. The long-term signing key never leaves the maintainer. This is the per-envelope signing complement to `vault/proxy-login/0.1`'s session-credential minting: proxy-login mints a session at session-start; sign-trust-task signs individual follow-up tasks during the session.
+ */
+export interface VaultSignTrustTaskPayload {
+  /**
+   * Identifier of the vault entry whose principal will sign. The maintainer rejects with `not_signable` when `entry.secretKind` is not `didSelfIssued` or `didcommPeer` (other kinds have no DID-based signing identity).
+   */
+  entryId: string;
+  unsignedEnvelope: UnsignedTrustTaskEnvelope;
+  consumerContext?: ConsumerContext;
+  stepUpProof?: StepUpProof;
+  ext?: Ext;
+}
+/**
+ * The Trust Task document to sign. MUST satisfy the framework's structural requirements (id/type/issuer/recipient/issuedAt/payload). MUST NOT carry a `proof`. `issuer` MUST equal the referenced entry's principalDid — the maintainer refuses to silently rewrite `issuer` (see `envelope_issuer_mismatch`).
+ */
+export interface UnsignedTrustTaskEnvelope {
+  /**
+   * Envelope identifier. Set by the producer of the inner task.
+   */
+  id: string;
+  /**
+   * Optional thread/correlation id, per framework §4.x.
+   */
+  threadId?: string;
+  /**
+   * Type URI of the inner Trust Task (e.g. `https://trusttasks.org/spec/acl/grant/0.1`).
+   */
+  type: string;
+  /**
+   * Issuer DID of the inner task. MUST equal the vault entry's principalDid — the maintainer rejects mismatches with `envelope_issuer_mismatch` rather than overwriting.
+   */
+  issuer: string;
+  /**
+   * Recipient DID — the relying party / audience the signed envelope will be delivered to.
+   */
+  recipient: string;
+  /**
+   * Producer's wall-clock when the inner task was constructed. Maintainer copies through; the proof's `created` is the maintainer's wall-clock at signing.
+   */
+  issuedAt: string;
+  /**
+   * Optional inner-task expiry. The maintainer rejects with `envelope_expired` when this is in the past at sign time.
+   */
+  expiresAt?: string;
+  /**
+   * Inner task's payload object. Opaque to the maintainer — passed through unchanged into the signed envelope.
+   */
+  payload: {
+    [k: string]: unknown | undefined;
+  };
+  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;
+}
+/**
+ * Caller's situational context — fed to the policy engine.
+ */
+export interface ConsumerContext {
+  /**
+   * Device-binding id assigned at registration. The maintainer cross-checks this against the authenticated transport identity.
+   */
+  deviceId?: string;
+  /**
+   * Most recent local user-verification on the consumer device (WebAuthn UV, biometric unlock). The maintainer's policy may require this to be within N seconds.
+   */
+  lastUserVerificationAt?: string;
+  /**
+   * Producer-supplied network classification. Advisory.
+   */
+  networkClass?: "unknown" | "home" | "corp" | "public" | "vpn";
+}
+/**
+ * Step-up proof on retry after `stepUpRequired`.
+ */
+export interface StepUpProof {
+  kind: "webauthnUv" | "pushApproval" | "totp";
+  /**
+   * Format depends on kind: WebAuthn assertion (base64url), DIDComm approval-response message id, or 6–8-digit TOTP code.
+   */
+  proof: string;
+  /**
+   * Maintainer-issued challenge id the proof responds to.
+   */
+  challengeId: string;
+}
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/vault/sign-trust-task/0.2" as const;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/vault/sign-trust-task/0.2#response" as const;

package/src/vault/sync/0.2/payload.ts

@@ -0,0 +1,35 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vault/sync/0.2/payload.schema.json
+ */
+
+/**
+ * Consumer requests an incremental delta of vault changes since a given seq baseline. The maintainer returns an ordered list of upsert/delete/acl/policy events, followed by a new seq baseline the consumer SHOULD persist for the next sync. Pairs with sync/event/0.1 server-push notifications: a live consumer subscribes to push events; on reconnect after offline, it calls vault/sync to catch up.
+ */
+export interface VaultSyncPayload {
+  /**
+   * Optional — narrow the delta to a single context. Omit for all contexts the consumer has VaultRead on.
+   */
+  contextId?: string;
+  /**
+   * The seq value the consumer last received. Omit on first sync (= full snapshot). When supplied, the maintainer returns events with seq > sinceSeq.
+   */
+  sinceSeq?: number;
+  /**
+   * Maximum number of events to include in this response. Maintainer-defined default and ceiling.
+   */
+  pageSize?: number;
+  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/vault/sync/0.2" as const;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/vault/sync/0.2#response" as const;

package/src/vault/upsert/0.2/payload.ts

@@ -0,0 +1,161 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vault/upsert/0.2/payload.schema.json
+ */
+
+/**
+ * A single binding target for a vault entry. Tagged union over the discriminator `kind`. A VaultEntry's `targets` array MAY mix any number of these.
+ */
+export type SiteTarget = WebOrigin | Did | IosApp | AndroidApp;
+/**
+ * Discriminator for the secret type stored in the entry. Definitions:
+ * - `password` — username + password (+ optional TOTP seed).
+ * - `passkey` — WebAuthn discoverable credential (private key + rpId + userHandle).
+ * - `oauthTokens` — OAuth 2.0 refresh + access token bundle for a specific provider.
+ * - `didSelfIssued` — Self-Issued OpenID Provider v2 (SIOP) credential: the entry points at a DID + signing key already managed by the VTA.
+ * - `didcommPeer` — DIDComm peer identity used to authenticate against a DIDComm-speaking relying party.
+ * - `bearerToken` — opaque bearer token carried in a maintainer-named header (covers API tokens, long-lived JWTs, personal-access tokens).
+ * - `sshKey` — SSH private key + comment.
+ * - `custom` — arbitrary structured fields; release-time consumer responsible for interpretation.
+ */
+export type SecretKind =
+  | "password"
+  | "passkey"
+  | "oauthTokens"
+  | "didSelfIssued"
+  | "didcommPeer"
+  | "bearerToken"
+  | "sshKey"
+  | "custom";
+/**
+ * Pluggable cipher envelope (discriminated by `envelope`) whose cleartext is a JCS-canonical JSON conforming to `vault/_shared/0.1/vault-secret#/$defs/VaultSecret`. The supported envelope kinds are listed in the SealedEnvelope shared schema; M2A consumers reject any kind they don't implement with `vault/upsert:envelope_unsupported`. REQUIRED on create unless `secretKind` is `didSelfIssued` or `didcommPeer` (those carry only references to maintainer-internal key ids and have no extra secret bytes). On update, omit if the secret material is unchanged; populate if the secret is being rotated.
+ */
+export type SealedEnvelope = DidcommAuthcryptEnvelope | HpkeArmoredEnvelope | TspMessageEnvelope;
+
+/**
+ * Create a new vault entry or update an existing one. The secret material — if present — rides inside a pluggable cipher envelope (see `vault/_shared/0.1/sealed-envelope`), so the Trust Task carries ciphertext and an authenticator, not plaintext. Updates may be partial: any populated metadata field replaces the current value; omitted fields are left untouched; explicit null clears the field (per `clearFields`). Optimistic-concurrency check via `expectedVersion`.
+ */
+export interface VaultUpsertPayload {
+  /**
+   * Entry id. Omit to create; supply to update. Maintainers MAY accept consumer-supplied ids on create (recommended: ULID) or MAY assign their own and return the assigned id in the response.
+   */
+  id?: string;
+  /**
+   * When updating, the consumer's last-observed `version` for the entry. The maintainer rejects with `vault/upsert:version_conflict` if the current version differs. Omit on create.
+   */
+  expectedVersion?: number;
+  /**
+   * Trust context the entry belongs to. Cannot be changed by upsert; to move an entry between contexts the consumer MUST delete and recreate.
+   */
+  contextId: string;
+  /**
+   * @minItems 1
+   */
+  targets: [SiteTarget, ...SiteTarget[]];
+  label: string;
+  secretKind: SecretKind;
+  tags?: string[];
+  notes?: string;
+  favicon?: string;
+  selectors?: string[];
+  customFieldNames?: string[];
+  expiresAt?: string;
+  sealedSecret?: SealedEnvelope;
+  /**
+   * List of metadata fields to explicitly clear on this upsert. Distinguishes "don't touch" (field omitted from payload) from "clear" (field listed here).
+   */
+  clearFields?: ("notes" | "favicon" | "expiresAt" | "tags" | "selectors" | "customFieldNames")[];
+  ext?: Ext;
+}
+export interface WebOrigin {
+  kind: "webOrigin";
+  /**
+   * Web origin per RFC 6454 (scheme + host + optional port), e.g. "https://github.com". Compared by exact string equality after canonicalisation (lowercase host, default port elided). Consumers wanting subdomain coverage SHOULD add multiple targets, not encode a wildcard.
+   */
+  origin: string;
+}
+export interface Did {
+  kind: "did";
+  /**
+   * DID identifying the relying party (e.g. did:web:rp.example). The vault maintainer is responsible for any DID resolution required to act on this entry.
+   */
+  did: string;
+}
+export interface IosApp {
+  kind: "iosApp";
+  /**
+   * iOS bundle identifier in reverse-DNS form (e.g. "com.github.stwalkerster.codehub"). Compared by exact string equality. Matches when an iOS Companion identifies the requesting app via its bundle id (typically via the OS Credential Manager integration).
+   */
+  bundleId: string;
+  /**
+   * Optional Apple Developer Team identifier (10-character alphanumeric). When supplied, the maintainer SHOULD also verify the team id of the requesting app before matching — defense in depth against bundle-id squatting on jailbroken devices.
+   */
+  teamId?: string;
+}
+export interface AndroidApp {
+  kind: "androidApp";
+  /**
+   * Android package name in reverse-DNS form (e.g. "com.github.android").
+   */
+  packageName: string;
+  /**
+   * SHA-256 fingerprints of the app's signing certificates, in colon-separated hex (the format `apksigner` and the Play Console emit). At least one fingerprint MUST be present. The maintainer matches when ANY of the provided fingerprints matches the requesting app's signature — this supports apps signed by multiple keys (e.g. during certificate rotation via Play App Signing).
+   *
+   * @minItems 1
+   */
+  sha256CertFingerprints: [string, ...string[]];
+}
+/**
+ * DIDComm v2 authcrypt JWE (ECDH-1PU + A256CBC-HS512, X25519/P-256 key agreement). Sender authentication is the JWE's `skid` — the producer's DID#keyAgreement. The maintainer's keyAgreement key is the recipient. Cleartext is JCS-canonical JSON of the variant's payload type.
+ *
+ * M2A is the only implementation today; this is also the canonical default for new code.
+ */
+export interface DidcommAuthcryptEnvelope {
+  envelope: "didcommAuthcrypt";
+  /**
+   * Compact DIDComm v2 JWE (base64url-encoded, dot-separated). Unpacks via the framework's standard DIDComm machinery; cleartext is the payload-specific JSON.
+   */
+  jwe: string;
+}
+/**
+ * OpenPGP-style ASCII-armored HPKE bundle — the existing OpenVTC sealed-transfer wire form (X25519-HKDF-SHA256 KEM + ChaCha20-Poly1305 AEAD, framed in armor with Bundle-Id / Digest-Algo headers and a CRC24 checksum). Producer assertion (`didSigned` / `attested` / `pinnedOnly`) is the integrity / authenticity anchor.
+ *
+ * No open-source implementation reads this yet outside vta-sdk's `sealed_transfer` crate; new code SHOULD prefer the DIDComm variant. Defined here for parity with the existing offline-bundle / cross-VTA workflows that the design plan reserves for M5+.
+ */
+export interface HpkeArmoredEnvelope {
+  envelope: "hpkeArmored";
+  /**
+   * ASCII-armored bundle text. Multi-line base64 with framing headers + CRC24.
+   */
+  armored: string;
+  /**
+   * did:key identifier of the X25519 public key the envelope was sealed to. The recipient uses this to select the matching private key.
+   */
+  recipientKeyId: string;
+  /**
+   * Producer-assertion mode per the sealed-transfer framework. `didSigned` = Ed25519 signature by issuer; `attested` = TEE attestation quote (e.g. Nitro); `pinnedOnly` = OOB SHA-256 digest only (dev/test, NOT for production).
+   */
+  producerAssertion?: "didSigned" | "attested" | "pinnedOnly";
+}
+/**
+ * Trust Spanning Protocol message (https://trustoverip.github.io/tswg-tsp-specification/). Reserved variant; no OpenVTC component reads or emits this today. Listed in the union so implementations can declare intent to use TSP in discovery and so consumers reject `tspMessage` envelopes explicitly (`envelope_unsupported`) until they're wired up — rather than silently failing in DIDComm parsing.
+ */
+export interface TspMessageEnvelope {
+  envelope: "tspMessage";
+  /**
+   * Base64url-encoded TSP message bytes. Format reference: https://trustoverip.github.io/tswg-tsp-specification/#message-format
+   */
+  message: 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/vault/upsert/0.2" as const;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/vault/upsert/0.2#response" as const;

package/src/vault/usage/0.2/payload.ts

@@ -0,0 +1,40 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vault/usage/0.2/payload.schema.json
+ */
+
+/**
+ * Consumer queries the maintainer's audit log of recent vault uses (proxy-logins, releases). Drives UIs like "recent activity" and "which AI agent has been using my GitHub credential". Read-only.
+ */
+export interface VaultUsagePayload {
+  /**
+   * Optional filter — usage for this entry only.
+   */
+  entryId?: string;
+  /**
+   * Optional filter — usage within this trust context only.
+   */
+  contextId?: string;
+  /**
+   * Optional filter — usage by this consumer DID only. Useful for "what has AI agent X been doing on my behalf".
+   */
+  byConsumer?: string;
+  since?: string;
+  until?: string;
+  kindFilter?: ("proxyLogin" | "release")[];
+  pageSize?: number;
+  cursor?: string;
+  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/vault/usage/0.2" as const;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/vault/usage/0.2#response" as const;