@openvtc/trust-tasks 0.2.54 → 0.2.56

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

@@ -7,6 +7,22 @@
  * 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;
+/**
+ * Pluggable cipher envelope. Cleartext is a `vault/_shared/0.1/vault-secret#/$defs/VaultSecret`. Consumers reject envelope kinds they don't implement with `vault/release:envelope_unsupported`.
+ */
+export type SealedEnvelope = DidcommAuthcryptEnvelope | HpkeArmoredEnvelope | TspMessageEnvelope;
+/**
+ * Discriminator so the consumer can pre-allocate the right type before unsealing.
+ */
+export type SecretKind =
+  | "password"
+  | "passkey"
+  | "oauthTokens"
+  | "didSelfIssued"
+  | "didcommPeer"
+  | "bearerToken"
+  | "sshKey"
+  | "custom";
 
 /**
  * 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).
@@ -97,9 +113,66 @@ export interface StepUpProof {
 export interface Ext {
   [k: string]: unknown | undefined;
 }
+export interface VaultReleaseResponsePayload {
+  sealedSecret: SealedEnvelope;
+  secretKind: SecretKind;
+  /**
+   * Cache TTL the consumer MUST enforce — wipe the cleartext after this many seconds, even if the user has not finished interacting with it.
+   */
+  ttlSeconds: number;
+  ext?: Ext;
+}
+/**
+ * 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;
+}
 
 /** Trust Task type URI. */
 export const TYPE_URI = "https://trusttasks.org/spec/vault/release/0.2" as const;
 
+/** Stable alias for this specification's request payload shape. */
+export type Payload = SiteTarget;
+
 /** 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;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = VaultReleaseResponsePayload;

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

@@ -93,9 +93,22 @@ export interface StepUpProof {
    */
   challengeId: string;
 }
+export interface VaultSignTrustTaskResponsePayload {
+  /**
+   * The supplied `unsignedEnvelope` with a Data Integrity `proof` attached. `proof.verificationMethod` is `<principalDid>#<signingKeyId>`; `proof.proofPurpose` is `assertionMethod`; `proof.cryptosuite` is `eddsa-jcs-2022`. All other members of the envelope (`id`, `type`, `issuer`, `recipient`, `issuedAt`, `expiresAt`, `payload`, `ext`) are unchanged from the request.
+   */
+  signedEnvelope: {};
+  ext?: Ext;
+}
 
 /** Trust Task type URI. */
 export const TYPE_URI = "https://trusttasks.org/spec/vault/sign-trust-task/0.1" as const;
 
+/** Stable alias for this specification's request payload shape. */
+export type Payload = VaultSignTrustTaskPayload;
+
 /** Trust Task response type URI (request type URI + "#response"). */
 export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/vault/sign-trust-task/0.1#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = VaultSignTrustTaskResponsePayload;

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

@@ -93,9 +93,22 @@ export interface StepUpProof {
    */
   challengeId: string;
 }
+export interface VaultSignTrustTaskResponsePayload {
+  /**
+   * The supplied `unsignedEnvelope` with a Data Integrity `proof` attached. `proof.verificationMethod` is `<principalDid>#<signingKeyId>`; `proof.proofPurpose` is `assertionMethod`; `proof.cryptosuite` is `eddsa-jcs-2022`. All other members of the envelope (`id`, `type`, `issuer`, `recipient`, `issuedAt`, `expiresAt`, `payload`, `ext`) are unchanged from the request.
+   */
+  signedEnvelope: {};
+  ext?: Ext;
+}
 
 /** Trust Task type URI. */
 export const TYPE_URI = "https://trusttasks.org/spec/vault/sign-trust-task/0.2" as const;
 
+/** Stable alias for this specification's request payload shape. */
+export type Payload = VaultSignTrustTaskPayload;
+
 /** 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;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = VaultSignTrustTaskResponsePayload;

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

@@ -3,6 +3,24 @@
  * Source: specs/vault/sync/0.1/payload.schema.json
  */
 
+export type SyncEvent = VaultUpsertedEvent | VaultDeletedEvent | AclChangedEvent | PolicyChangedEvent;
+/**
+ * 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"
+  | "oauth-tokens"
+  | "did-self-issued"
+  | "didcomm-peer"
+  | "bearer-token"
+  | "ssh-key"
+  | "custom";
+
 /**
  * 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.
  */
@@ -27,9 +45,207 @@ export interface VaultSyncPayload {
 export interface Ext {
   [k: string]: unknown | undefined;
 }
+export interface VaultSyncResponsePayload {
+  /**
+   * Ordered events; consumer applies in order. Each event carries its own `seq` (strictly monotonic, no gaps within a context). Shape is the same as sync/event/0.1's push form.
+   */
+  events: SyncEvent[];
+  /**
+   * The seq value the consumer should persist for its next vault/sync call. Equal to the highest event seq in this response, or the consumer's prior `sinceSeq` if the response was empty.
+   */
+  newSinceSeq: number;
+  /**
+   * true if more events exist beyond this page. Consumer SHOULD immediately call vault/sync again with `sinceSeq = newSinceSeq`.
+   */
+  truncated: boolean;
+  ext?: Ext;
+}
+export interface VaultUpsertedEvent {
+  kind: "vault.upserted";
+  seq: number;
+  occurredAt: string;
+  entry: VaultEntry;
+}
+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 (`did-self-issued`, `didcomm-peer`). Absent for kinds that have no DID concept (`password`, `passkey`, `oauth-tokens`, `bearer-token`, `ssh-key`, `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: "web-origin";
+  /**
+   * 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: "ios-app";
+  /**
+   * 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: "android-app";
+  /**
+   * 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;
+  /**
+   * Hex-encoded SHA-256 of the encrypted blob bytes (post-encryption). Lets the consumer verify integrity after fetch.
+   */
+  sha256: string;
+  /**
+   * 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;
+}
+export interface VaultDeletedEvent {
+  kind: "vault.deleted";
+  seq: number;
+  occurredAt: string;
+  id: string;
+  contextId: string;
+  graceUntil: string;
+}
+export interface AclChangedEvent {
+  kind: "acl.changed";
+  seq: number;
+  occurredAt: string;
+  /**
+   * DID of the consumer whose ACL entry changed.
+   */
+  subject: string;
+  change: "granted" | "revoked" | "role_changed" | "swapped" | "device_disabled" | "device_wiped";
+}
+export interface PolicyChangedEvent {
+  kind: "policy.changed";
+  seq: number;
+  occurredAt: string;
+  policyId: string;
+  change: "created" | "updated" | "deleted";
+}
 
 /** Trust Task type URI. */
 export const TYPE_URI = "https://trusttasks.org/spec/vault/sync/0.1" as const;
 
+/** Stable alias for this specification's request payload shape. */
+export type Payload = SyncEvent;
+
 /** Trust Task response type URI (request type URI + "#response"). */
 export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/vault/sync/0.1#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = VaultSyncResponsePayload;

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

@@ -3,6 +3,24 @@
  * Source: specs/vault/sync/0.2/payload.schema.json
  */
 
+export type SyncEvent = VaultUpsertedEvent | VaultDeletedEvent | AclChangedEvent | PolicyChangedEvent;
+/**
+ * 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";
+
 /**
  * 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.
  */
@@ -27,9 +45,207 @@ export interface VaultSyncPayload {
 export interface Ext {
   [k: string]: unknown | undefined;
 }
+export interface VaultSyncResponsePayload {
+  /**
+   * Ordered events; consumer applies in order. Each event carries its own `seq` (strictly monotonic, no gaps within a context). Shape is the same as sync/event/0.1's push form.
+   */
+  events: SyncEvent[];
+  /**
+   * The seq value the consumer should persist for its next vault/sync call. Equal to the highest event seq in this response, or the consumer's prior `sinceSeq` if the response was empty.
+   */
+  newSinceSeq: number;
+  /**
+   * true if more events exist beyond this page. Consumer SHOULD immediately call vault/sync again with `sinceSeq = newSinceSeq`.
+   */
+  truncated: boolean;
+  ext?: Ext;
+}
+export interface VaultUpsertedEvent {
+  kind: "vaultUpserted";
+  seq: number;
+  occurredAt: string;
+  entry: VaultEntry;
+}
+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;
+  /**
+   * Hex-encoded SHA-256 of the encrypted blob bytes (post-encryption). Lets the consumer verify integrity after fetch.
+   */
+  sha256: string;
+  /**
+   * 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;
+}
+export interface VaultDeletedEvent {
+  kind: "vaultDeleted";
+  seq: number;
+  occurredAt: string;
+  id: string;
+  contextId: string;
+  graceUntil: string;
+}
+export interface AclChangedEvent {
+  kind: "aclChanged";
+  seq: number;
+  occurredAt: string;
+  /**
+   * DID of the consumer whose ACL entry changed.
+   */
+  subject: string;
+  change: "granted" | "revoked" | "roleChanged" | "swapped" | "deviceDisabled" | "deviceWiped";
+}
+export interface PolicyChangedEvent {
+  kind: "policyChanged";
+  seq: number;
+  occurredAt: string;
+  policyId: string;
+  change: "created" | "updated" | "deleted";
+}
 
 /** Trust Task type URI. */
 export const TYPE_URI = "https://trusttasks.org/spec/vault/sync/0.2" as const;
 
+/** Stable alias for this specification's request payload shape. */
+export type Payload = SyncEvent;
+
 /** 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;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = VaultSyncResponsePayload;