@openvtc/trust-tasks 0.6.4 → 0.6.5

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

@@ -0,0 +1,286 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/provision/integration/0.3/payload.schema.json
+ */
+
+/**
+ * What the holder is asking the maintainer to do. Tagged on `type`; see `TemplateBootstrapAsk` and `AdminRotationAsk`.
+ */
+export type BootstrapAsk = TemplateBootstrapAsk | AdminRotationAsk;
+/**
+ * Digest over the armored ciphertext, for holders that pin the bundle out-of-band. Taken over the armored bytes exactly as carried in `bundle`, not over a canonicalization: the armor is the artifact, and re-armoring the same ciphertext does not have to reproduce the same bytes.
+ */
+export type DigestMultibase = string;
+
+/**
+ * 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;
+}
+/**
+ * Carried in a Trust Task document whose type is https://trusttasks.org/spec/provision/integration/0.1#response. The sealed `bundle` is the secret-bearing artefact; `summary` is non-secret audit metadata.
+ */
+export interface ProvisionIntegrationResponsePayload {
+  /**
+   * OpenPGP-style ASCII-armored ciphertext of `SealedPayloadV1`. HPKE base mode, X25519-HKDF-SHA256 KEM, ChaCha20-Poly1305 AEAD, info string `vta-sealed-transfer/v1`. Recipient is the X25519 derivation of `request.holder`'s Ed25519 pubkey.
+   */
+  bundle: string;
+  digestMultibase?: DigestMultibase;
+  summary: ProvisionSummary;
+  ext?: Ext1;
+}
+/**
+ * Non-secret audit metadata. MUST NOT include any private key material; the bundle is the only secret-bearing field.
+ */
+export interface ProvisionSummary {
+  /**
+   * Ephemeral did:key the holder signed the VP with and opens the sealed bundle with. Echo of `request.holder`.
+   */
+  clientDid: string;
+  /**
+   * Long-term admin DID after this provisioning. Equals `clientDid` when no admin rollover occurred (TemplateBootstrap with no `adminTemplate`); equals the freshly-minted admin DID when `adminTemplate` was used or when the ask was `adminRotation`. Maintainers that pre-date admin rollover MAY omit this; consumers SHOULD default it to `clientDid` for backward compatibility.
+   */
+  adminDid?: string;
+  /**
+   * True when the maintainer minted a fresh long-term admin DID and bound the authorization VC + ACL row to it (i.e. `adminDid != clientDid`).
+   */
+  adminRolledOver?: boolean;
+  /**
+   * DID rendered from the integration template. Absent for `adminRotation` (no integration was rendered).
+   */
+  integrationDid?: string;
+  /**
+   * Name of the integration template that was rendered. Absent for `adminRotation`.
+   */
+  templateName?: string;
+  /**
+   * `kind` of the integration template (e.g. `mediator`, `did-hosting-control`, `app`). Absent for `adminRotation`.
+   */
+  templateKind?: string;
+  /**
+   * Name of the admin template that was rendered. Present when an admin DID was minted (either via `TemplateBootstrap.adminTemplate` or `adminRotation`).
+   */
+  adminTemplateName?: string;
+  /**
+   * VP nonce as lowercase hex (32 characters = 16 bytes). MUST equal the `Bundle-Id` armor header of `bundle`. Cross-check anchor: a holder that decodes the VP nonce can verify the bundle they opened matches the one the maintainer minted for them.
+   */
+  bundleIdHex: string;
+  /**
+   * Number of DIDs the sealed bundle carries private key material for. `templateBootstrap` with no adminTemplate typically yields 1 (the integration DID's keys). `adminRotation` yields 0 (the `admin` field is top-level, not under `secrets`).
+   */
+  secretCount: number;
+  /**
+   * Number of template-declared side outputs the sealed bundle carries (`did.jsonl` logs, DIDComm service advertisements, etc.). Always 0 for `adminRotation`.
+   */
+  outputCount: number;
+  /**
+   * Identifier of the registered webvh hosting server the maintainer published the integration's `did.jsonl` to, if any. Absent when the integration is self-hosted or when the template did not declare a webvh server var.
+   */
+  webvhServerId?: string;
+  /**
+   * True when `payload.createContext` was honoured and the maintainer provisioned the target context inline. False when the context already existed (or when `createContext` was omitted / false).
+   */
+  contextCreated?: boolean;
+}
+/**
+ * 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 Ext1 {
+  [k: string]: unknown | undefined;
+}
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/provision/integration/0.3" as const;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = ProvisionIntegrationPayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/provision/integration/0.3#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = ProvisionIntegrationResponsePayload;
+
+/**
+ * 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.
+ */
+export const SPEC = {
+  typeUri: TYPE_URI,
+  isBearer: false,
+  isProofRequired: true,
+  isRecipientRequired: true,
+} 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: false,
+} as const;

package/src/vault/_shared/0.3/consumer-context.ts

@@ -0,0 +1,11 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vault/_shared/0.3/consumer-context.schema.json
+ */
+
+/**
+ * Reused by vault/proxy-login, vault/release, and any future vault task that needs to feed situational context to the maintainer's policy engine or carry the response to a step-up demand. Producer-supplied fields are advisory — the maintainer cross-checks anything security-relevant against its own state.
+ */
+export interface ConsumerContextStepUpProofSharedDefinitionsUsedByVaultTasksThatHitThePolicyEngine {
+  [k: string]: unknown | undefined;
+}

package/src/vault/_shared/0.3/sealed-envelope.ts

@@ -0,0 +1,15 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vault/_shared/0.3/sealed-envelope.schema.json
+ */
+
+/**
+ * Discriminated union over `envelope` kind, used by every vault task that ships secret material across the wire (vault/upsert/0.1 → SealedSecret, vault/release/0.1 → SealedSecret in the response, vault/proxy-login/0.1 → SealedSessionBlob in the response). The cleartext shape sitting INSIDE the envelope is task-specific — VaultSecret for the secret variants, SessionBlob for the proxy-login variant — and is referenced from each task's spec.
+ *
+ * Consumers dispatch on `envelope`. An unknown envelope kind MUST be rejected (`<task>:envelope_unsupported` error code) rather than silently accepted — there is no fallback to "try parsing as DIDComm". Producers SHOULD advertise the envelope kinds they emit via `trust-task-discovery/0.1`.
+ *
+ * Forward compatibility: this union starts with three variants for the OpenVTC stack today. New variants (KERI/ACDC envelopes, a future TSP successor, hardware-attested envelopes for TEE-to-TEE transfer, etc.) land as additional `oneOf` entries — never as silent schema relaxations on an existing variant.
+ */
+export interface SealedEnvelopePluggableCipherBearingEnvelopeForVaultPayloads {
+  [k: string]: unknown | undefined;
+}

package/src/vault/_shared/0.3/session-blob.ts

@@ -0,0 +1,13 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vault/_shared/0.3/session-blob.schema.json
+ */
+
+/**
+ * Cleartext shape of the session material returned by vault/proxy-login/0.1. Like VaultSecret, this is documented for both sides to code-generate against; the wire-form is carried inside an HPKE-sealed envelope.
+ *
+ * A SessionBlob represents an active session at the third-party service the VTA logged in to on the holder's behalf. The Companion uses it to operate the session (e.g. inject cookies into the browser, set an Authorization header) without ever seeing the long-term credential. The session has a finite TTL; the Companion MUST discard the blob when `expiresAt` passes.
+ */
+export interface SessionBlobSharedDefinitionForTheResultOfAProxyLogin {
+  [k: string]: unknown | undefined;
+}

package/src/vault/_shared/0.3/vault-entry.ts

@@ -0,0 +1,13 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vault/_shared/0.3/vault-entry.schema.json
+ */
+
+/**
+ * Canonical metadata view of a single vault entry — a credential the holder has stored for use against a third-party site, mobile app, or DID-identified relying party. Referenced by every vault/* specification that returns entry metadata (vault/list, vault/get, vault/upsert response, vault/sync, vault/usage). This definition is the metadata-only view: it deliberately does NOT include secret material. Secrets are released only via vault/release/0.1, and even then are carried inside HPKE-sealed envelopes that the vault Trust Task itself does not parse. The `_shared` folder is skipped by the registry build and by the codegen.
+ *
+ * Timestamp invariants (SHOULD-level, prose — not expressible in JSON Schema): when both `createdAt` and `updatedAt` are present, `updatedAt >= createdAt`; when `lastUsedAt` is present, `lastUsedAt >= createdAt`; when `expiresAt` is present, `expiresAt > createdAt`. Consumers SHOULD reject documents that violate any of these.
+ */
+export interface VaultEntrySharedDefinitionForTheVaultSpecFamily {
+  [k: string]: unknown | undefined;
+}

package/src/vault/_shared/0.3/vault-secret.ts

@@ -0,0 +1,15 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vault/_shared/0.3/vault-secret.schema.json
+ */
+
+/**
+ * Schema for the cleartext secret payload of a vault entry. Documents the shape both sides of a vault/release/0.1 transfer code-generate against. The secret payload is NEVER transmitted as plaintext JSON on the wire: vault/release/0.1 returns it inside an HPKE-sealed envelope (see SealedSecret in the vault/release payload schema). This shared schema is the authoritative description of the bytes inside that envelope.
+ *
+ * Sensitive fields (`password`, `privateKey`, `refreshToken`, `secureNotes`, etc.) MUST be zeroised by consumers as soon as their use is complete. Consumers MUST NOT log, persist beyond cache lifetime, or transmit the cleartext outside the release-time scope.
+ *
+ * Discriminated by `kind`, which mirrors VaultEntry.secretKind on the metadata side. The `kind` value MUST equal the metadata view's `secretKind` for the same entry.
+ */
+export interface VaultSecretSharedDefinitionForVaultSecretMaterial {
+  [k: string]: unknown | undefined;
+}

package/src/vault/get/0.3/payload.ts

@@ -0,0 +1,226 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vault/get/0.3/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 kind of secret this entry holds. The secret material itself is NEVER returned in metadata views; the kind is exposed so consumers can render an appropriate UI affordance and so policy decisions can route by kind.
+ */
+export type SecretKind =
+  | "password"
+  | "passkey"
+  | "oauthTokens"
+  | "didSelfIssued"
+  | "didcommPeer"
+  | "bearerToken"
+  | "sshKey"
+  | "custom";
+/**
+ * Digest over the encrypted blob bytes (post-encryption), so the consumer can verify integrity after fetch. Taken over the bytes as stored, not over a canonicalization: the blob is an opaque artifact, not a JSON document.
+ */
+export type DigestMultibase = string;
+
+/**
+ * Fetch the metadata view of a single vault entry by id. Returns the same VaultEntry shape vault/list does, but for one specific entry. Secret material is NEVER returned by this task; use vault/release/0.1 to obtain secret bytes.
+ */
+export interface VaultGetPayload {
+  /**
+   * Vault entry id (as returned in a prior vault/list or vault/sync response).
+   */
+  id: 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;
+}
+export interface VaultGetResponsePayload {
+  entry: VaultEntry;
+  redactedFields?: string[];
+  ext?: Ext;
+}
+export interface VaultEntry {
+  /**
+   * Opaque vault-maintainer-assigned identifier for the entry. ULID/UUID/base32 are common; the wire spec only requires non-empty string equality.
+   */
+  id: string;
+  /**
+   * Identifier of the trust context (persona) the entry belongs to. Opaque string interpreted by the vault maintainer; corresponds to a single ContextRecord on the VTA side.
+   */
+  contextId: string;
+  /**
+   * One or more binding targets — web origins, mobile app identifiers, and/or DIDs — that this credential applies to. A request from any matching target uses this entry. A typical entry for a service that exists as both a website and mobile apps will list a web origin, an iOS bundle id, and an Android package id; passkeys for that service typically list only the origin (because iOS Associated Domains and Android Asset Links bind apps to the domain at the OS level).
+   *
+   * @minItems 1
+   */
+  targets: [SiteTarget, ...SiteTarget[]];
+  /**
+   * Human-readable display name (e.g. "Work GitHub", "Personal bank — checking"). Maintainers MAY enforce a maximum length; the wire spec does not.
+   */
+  label: string;
+  secretKind: SecretKind;
+  /**
+   * User-defined tags for organisation and filtering (e.g. ["family", "finance"]). Maintainers MAY enforce a maximum count; the wire spec does not.
+   */
+  tags?: string[];
+  /**
+   * Non-sensitive notes the user attached to the entry. Visible in metadata view (suitable for support contact, account number, expiry policy memos). SENSITIVE notes belong in the secret payload as a `secureNotes` field — those are only released by vault/release/0.1.
+   */
+  notes?: string;
+  /**
+   * Optional URI of an icon to display in the consumer UI. Maintainers MAY fetch and cache; consumers SHOULD treat as untrusted content and fetch via a sandboxed pipeline.
+   */
+  favicon?: string;
+  /**
+   * Opaque maintainer-defined selector strings fed to the policy engine when this entry is requested (e.g. "recent_uv_required", "network_class=corp", "step_up_push"). Consumers MUST treat selectors as opaque; they exist for policy authoring on the maintainer side.
+   */
+  selectors?: string[];
+  /**
+   * Names of additional fields the user has attached (e.g. ["security-question-1", "account-number"]). The VALUES live in the secret payload and are only delivered by vault/release/0.1. Exposing names in metadata lets the consumer render the right form layout before requesting release.
+   */
+  customFieldNames?: string[];
+  /**
+   * References to encrypted blobs associated with the entry (recovery codes, PEM files, screenshots of authenticator setup). The blobs themselves are fetched via a separate mechanism the maintainer documents; metadata view exposes only the descriptor.
+   */
+  attachments?: AttachmentRef[];
+  /**
+   * Optional time after which the credential is no longer expected to be valid (e.g. an OAuth refresh token's known expiry, a time-limited API token, an enterprise password rotation policy). Maintainers MAY surface this in the consumer UI as a warning.
+   */
+  expiresAt?: string;
+  /**
+   * Set by the maintainer (via HIBP integration or equivalent) when the password material associated with this entry is known to appear in a public breach. Consumers SHOULD surface this prominently. Cleared when the user rotates the password and the new password is not in any known breach.
+   */
+  breachedAt?: string;
+  /**
+   * Set whenever the password component of the secret payload is rotated. Maintainers MUST update this on every secret-material change for entries of kind `password` (or any kind that carries a password component). Used by consumers to surface rotation-overdue warnings.
+   */
+  passwordChangedAt?: string;
+  createdAt: string;
+  /**
+   * VID of the consumer that originally created the entry.
+   */
+  createdBy?: string;
+  updatedAt: string;
+  /**
+   * VID of the consumer that last modified the entry.
+   */
+  updatedBy?: string;
+  /**
+   * Most recent time the entry was used (either released or proxy-login performed). Maintainers MAY return this with reduced precision (e.g. hour-floored) when releasing to a less-trusted consumer.
+   */
+  lastUsedAt?: string;
+  /**
+   * Monotonic version counter incremented on every mutation. Used by consumers for optimistic-concurrency checks on vault/upsert and as the seq baseline for vault/sync.
+   */
+  version: number;
+  /**
+   * Optional cached DID the entry will act AS for DID-shaped flows — mirrors the `did` field of the entry's secret payload when `secretKind` carries one (`didSelfIssued`, `didcommPeer`). Absent for kinds that have no DID concept (`password`, `passkey`, `oauthTokens`, `bearerToken`, `sshKey`, `custom`). MAINTAINER-DERIVED, NOT CONSUMER-SUPPLIED: the maintainer MUST recompute this from the canonical secret at every upsert / secret rotation; a producer-supplied value on `vault/upsert/0.1` MUST be ignored (no error, but no honour). Read-only on the wire, present in metadata views so consumers can drive RP-side flows (e.g. fetch `/auth/challenge` keyed on the principal DID before requesting a proxy-login) without releasing the secret.
+   */
+  principalDid?: string;
+  ext?: Ext1;
+}
+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[]];
+}
+export interface AttachmentRef {
+  /**
+   * Opaque maintainer-assigned id for this attachment; used to fetch the blob via a separate mechanism.
+   */
+  id: string;
+  /**
+   * User-supplied filename (e.g. "recovery-codes.txt").
+   */
+  name: string;
+  /**
+   * Size of the encrypted blob in bytes. Maintainers MAY enforce a maximum per attachment and per entry.
+   */
+  sizeBytes: number;
+  digestMultibase: DigestMultibase;
+  /**
+   * Optional MIME type hint for the consumer UI (e.g. "text/plain", "application/x-pem-file").
+   */
+  contentType?: 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 Ext1 {
+  [k: string]: unknown | undefined;
+}
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/vault/get/0.3" as const;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = VaultGetPayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/vault/get/0.3#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = VaultGetResponsePayload;
+
+/**
+ * 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.
+ */
+export const SPEC = {
+  typeUri: TYPE_URI,
+  isBearer: false,
+  isProofRequired: false,
+  isRecipientRequired: true,
+} 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,
+} as const;