@openvtc/trust-tasks 0.28.1 → 0.28.3

package/dist/_shared/components.d.ts

@@ -341,6 +341,10 @@ export type AnchorCadence = "never" | "renewal" | "manual";
  * How the admission came to execute. `policyAllowed`: the community's policy admitted it at once. `approved`: the policy referred it, the community parked it, and another administrator approved it. `waived`: the policy referred it, and the community's single-administrator mode waived the approval on the requester's own re-authentication bound to the operation.
  */
 export type Approval = "policyAllowed" | "approved" | "waived";
+/**
+ * The evidence an approval was recorded on, as `auth/step-up/approve-response` names it. Only the approver's own evidence is ever recorded: a proof by a key the VTA records as acting for an approver — a console signing key or any other delegation — is never an approval (CONVENTIONS.md §6.3).
+ */
+export type ApprovalEvidenceKind = "didSigned" | "webauthn" | "approverSigned";
 /**
  * An explicit statement of the capabilities a subject may approve. Exactly one of `ceiling` (the role's full approve ceiling), `none`, or `listed` with a NON-EMPTY list of CapabilityRef.
  */
@@ -544,6 +548,10 @@ export type DeviceAttestation_DeviceV0_2 = WebAuthnAttestation_DeviceV0_2 | Appl
  * A human-readable name for where the key lives, chosen by the enrolling identity — e.g. `Work laptop — Chrome`. Read by that identity and by administrators deciding which key to revoke; retained with the delegation. Free text authored by the enrolling identity, untrusted, and attributed to it wherever it is rendered. Absent rather than invented when none was chosen: an invented label is indistinguishable from a chosen one to somebody deciding which key to revoke.
  */
 export type DeviceLabel = string;
+/**
+ * The DID method an identity uses, as the method profile that governs it is named: `webvh` for a did:webvh identity, `scid:vh` for the did:scid:vh:1 form of one, `webs` for did:webs. Deliberately a pattern and not an enumeration: a method is added by publishing its profile under method-profiles/, never by changing this schema. A VTA MUST refuse a method it holds no profile for, or whose profile declares it ineligible, with `vta/dids:methodNotEligible`.
+ */
+export type DidMethodName = string;
 /**
  * A DID Core verification relationship.
  */
@@ -799,6 +807,10 @@ export type Handle = string;
  * **Not a timestamp.** A time is host-asserted, unverifiable and useless for this: two roots a second apart are not evidence of anything, while two roots at one version are.
  */
 export type HeadVersion = number;
+/**
+ * The named key role a key occupies in an identity (CONVENTIONS.md §2; VTI-KEY-070 onward). `attestation` — the only keys in `assertionMethod`; sign the identity's attestation artefacts (credentials, endorsements, status lists) through the VTA's signing service and nowhere else. Generated inside the VTA, never derived, never exportable, never in a backup. `operational` — the only keys the identity's own process uses in `authentication`; sign the node's own traffic (Trust Task requests and responses, DIDComm and TSP signatures, invitations, notices, audit checkpoints). Derived. `messaging` — the only keys in `keyAgreement`; sign nothing. X25519, derived or generated in its own right and never converted from a signing key. `update` — the identifier's change authority as its DID method states it (a did:webvh log's `updateKeys` and `nextKeyHashes`, a KERI key event log's current and next keys); never a role-bound verification method, never in `keyRoles`. Generated inside the VTA, never derived, never exportable, never in a backup, and always accompanied by a committed recovery key held outside the VTA's protection boundary. `authenticator` — a key held on a person's own authenticator (a WebAuthn passkey), listed in `authentication` of that person's identity only; used only to verify the person's WebAuthn assertions (sign-in and step-up evidence) and never to accept a Data Integrity proof. The VTA never holds its private half, so it is enrolled by the passkey ceremony and never generated, added or rotated by these tasks. Never permitted on the durable identity of a VTA, a VTC or a VTN. No role permits `capabilityInvocation` or `capabilityDelegation` (VTI-KEY-075). The set is an extensible registry: a consumer that meets a role it does not implement MUST rely on the key for nothing, and MUST NOT map it onto a role it does know (VTI-KEY-074).
+ */
+export type IdentityKeyRole = "attestation" | "operational" | "messaging" | "update" | "authenticator";
 /**
  * The media types a directory image may have — those a `CardBlobRef` admits.
  */
@@ -807,6 +819,10 @@ export type ImageMediaType = "image/png" | "image/jpeg" | "image/webp" | "image/
  * Who may ask the community to introduce them to this member. `anyone`: any active member who can find the entry. `groups`: only members who share a community group with them. `connections`: only members holding an attributed, in-force verified relationship with them. `off`: nobody. A refused introduction is never reported to its sender.
  */
 export type Introductions = "anyone" | "groups" | "connections" | "off";
+/**
+ * `wallet`: the invitation names a DID, and is claimed by signing as it (vtc/install/claim/start and finish 0.3). `passkey`: it names none, and the administrator's DID is the `did:key` of the passkey registered at its claim (vtc/install/claim/passkey/start and finish 0.1).
+ */
+export type InviteKind = "wallet" | "passkey";
 /**
  * `issued` is outstanding and revocable; `consumed` and `expired` are terminal.
  */
@@ -820,6 +836,26 @@ export type JoinRequestId = string;
  * An optional note from the member to the group's managers. Plain text.
  */
 export type JoinRequestMessage = string;
+/**
+ * `planned` — a successor was staged, activated, and the predecessor retired on the operator's schedule. `compromise` — a key was revoked and, where the role would otherwise be empty, replaced in the same change. `addition` — a key joined a role without anything leaving it. `recovery` — the identifier's update authority moved to the committed recovery key, because the VTA's own update keys were lost or may be in someone else's hands.
+ */
+export type KeyChangeKind = "planned" | "compromise" | "addition" | "recovery";
+/**
+ * `preview` — nothing was written; the response carries the plan. `applied` — the change was made (and published, unless `publication.selfPublish`). `pendingApproval` — the plan is recorded and awaits further approvals. `awaitingRecoveryProof` — the plan is approved and waits for the recovery custodian's proof (`preview.recoverySigning`); nothing is published until it arrives.
+ */
+export type KeyChangeOutcome = "preview" | "applied" | "pendingApproval" | "awaitingRecoveryProof";
+/**
+ * `pendingApproval` — awaiting the approvals the VTA's policy requires; nothing is published. `awaitingRecoveryProof` — approved, and waiting for the recovery custodian's proof over the change; nothing is published. `staged` — successor published, not yet used. `overlapping` — successor active, predecessor `retiring`. `completed` — every predecessor retired, or the change is published and any overlap it began has ended. `aborted` — the successor was retired instead of the predecessor, or a revocation superseded the change. `expired` — the approvals or the recovery proof did not arrive before the preview expired; nothing was published.
+ */
+export type KeyChangeState = "pendingApproval" | "awaitingRecoveryProof" | "staged" | "overlapping" | "completed" | "aborted" | "expired";
+/**
+ * Where a key is in its role's lifecycle (CONVENTIONS.md §8, §10). `pending` — planned by a preview or a change awaiting approval; not published; custody projection only. `staged` — published and bound to its role but not yet used, until the publishing change's cache horizon. `active` — the key the VTA uses for new signatures (for `messaging`, advertises for new sessions; for `update`, the current authority). `retiring` — still published but never used to sign again; a retiring `messaging` key still decrypts until retirement. `retired` — removed by planned rotation; what it signed while published stays valid, judged against the identifier version current at issuance. `revoked` — withdrawn for compromise, recorded with `compromisedSince`; what it signed from then on establishes nothing. `committed` — an `update` key the identifier commits to as a successor but has not revealed (a did:webvh `nextKeyHashes` entry, a KERI next-key digest). `retired` and `revoked` are terminal.
+ */
+export type KeyLifecycleState = "pending" | "staged" | "active" | "retiring" | "retired" | "revoked" | "committed";
+/**
+ * Which view of the identity's key roles the caller was given (CONVENTIONS.md §11). `public` — only what the published identifier document and history already reveal. `custody` — additionally the VTA's custody state: pending keys, the custodian record and protection boundary behind each key, overlap deadlines, who initiated and approved each change, and why.
+ */
+export type KeyListProjection = "public" | "custody";
 /**
  * Where the private key came from. `derived` means the maintainer generated it from a seed it holds and can reproduce it from `derivationPath`; `imported` means it arrived from outside and exists only as stored material; `internal` means the maintainer generated it from a CSPRNG and it is reproducible from nothing at all. The distinction is operationally load-bearing: a `derived` key survives a seed restore, an `imported` one is lost unless it was backed up separately, and an `internal` one cannot be recovered by any means once the maintainer's storage is gone. This member is also the only way a consumer can confirm that a `keys/create` request for an `internal` key was honoured rather than silently downgraded to a derived one — see that specification's `internal` member.
  */
@@ -1136,6 +1172,10 @@ export type Petname = string;
  * A region or city name as the vetter writes it. Compared case-insensitively and otherwise exactly.
  */
 export type PlaceName = string;
+/**
+ * Conditions a human should be shown before approving. `singleKeyRole` — the role will hold one active key. `algorithmNotInAcceptedSet` — a verifier population the VTA knows of does not accept the new key's algorithm. `roleWillHaveNoClassicalKey` — every remaining key is post-quantum. `attestationReissuanceRequired` — revoking this attestation key obliges re-issuance and re-signed status lists (VTI-KEY-133). `selfPublish` — the VTA will not publish the change; the operator must. `noWitnesses` — the identifier has no witnesses, so a party holding the VTA's routine update key can drop the recovery commitment unobserved (CONVENTIONS.md §5.3). `protectionBelowPolicy` — a key will be held at a `ProtectionClass` below what the VTA's policy recommends for its role (a plain VTA holding an attestation key). `recoveryKeyRevealed` — this change uses the recovery key, which must be replaced by a fresh recovery commitment in the same change.
+ */
+export type PreviewWarning = "singleKeyRole" | "algorithmNotInAcceptedSet" | "roleWillHaveNoClassicalKey" | "attestationReissuanceRequired" | "selfPublish" | "noWitnesses" | "protectionBelowPolicy" | "recoveryKeyRevealed";
 /**
  * One line of a profile, in exactly one of four forms. Together they are the whole of a profile's flexibility, and each exists for a case the others handle badly.
  *
@@ -1184,6 +1224,10 @@ export type ProfileEntry = {
  * The distinction between the first two and the last two is of kind, not degree: only `predicate` and `derived` avoid handing two verifiers a join key. A maintainer MUST default to the highest rung the credential's format supports, and MUST NOT silently fall to a lower one — a request that cannot be satisfied at the rung a producer asked for is refused, because a silent privacy downgrade discloses material the holder believed was hidden.
  */
 export type ProofRung = "predicate" | "derived" | "selectiveDisclosure" | "whole";
+/**
+ * How a private half is protected (CONVENTIONS.md §5.2). `software` — stored by the VTA without encryption independent of the host (a plain VTA). `encryptedAtRest` — wrapped under a key the VTA holds outside its store (a hardened VTA). `enclave` — held only inside an attested trusted execution environment, wrapped under a key released only to its measurement (a TEE VTA). `hardwareModule` — held by a hardware security module or cloud key service that performs the operation without releasing the key. `externalCustodian` — not held by this VTA at all: a recovery update key, or an `authenticator` key on a person's device.
+ */
+export type ProtectionClass = "software" | "encryptedAtRest" | "enclave" | "hardwareModule" | "externalCustodian";
 /**
  * Where a value comes from, and the member that makes this family worth building on a trust stack rather than in an address book. It survives to the verifier, so a recipient can tell — per field — what the holder typed from what an issuer attested.
  *
@@ -1756,6 +1800,10 @@ export type TrusteePhase = "enrolling" | "dealing" | "confirming" | "keyed" | "d
  * A ULID in Crockford base32, uppercase. Used for `attributeId` and `profileId`. Chosen over a UUID because the leading 48 bits are a timestamp, so a key-ordered scan of the store is also creation-ordered and a `list` needs no secondary sort. Server-assigned on create; a producer MAY supply one to make a create idempotent, and a maintainer MUST reject a supplied value that already exists rather than silently overwriting.
  */
 export type Ulid = string;
+/**
+ * For an `update` key only (CONVENTIONS.md §5.3). `routine` — generated and held by the VTA, which authorizes the identity's ordinary changes with it. `recovery` — held by a recovery custodian in a protection boundary other than the VTA's; the VTA holds only its commitment, carries that commitment forward in every change it makes, and can use the key only by asking the custodian for a proof (`RecoverySigningRequest`).
+ */
+export type UpdateKeyClass = "routine" | "recovery";
 /**
  * Handle for one upload across begin, chunk, commit and abort, and — for a bundle — deploy. Recipient-generated and unguessable, which is what lets a reference to somebody else's upload be answered as not-found without confirming it exists. Opaque: a producer quotes what it was given.
  */
@@ -6895,6 +6943,73 @@ export interface DidTemplateRecord_VtaV0_7 {
      */
     createdBy: string;
 }
+/**
+ * A persisted template. The DidTemplate fields are flattened at the top level alongside the resolved scope and provenance metadata. Same shape returned by get/create/update and carried per-item by list.
+ */
+export interface DidTemplateRecord_VtaV0_9 {
+    /**
+     * Template schema version. 1 is the historical shape, whose keys are implicitly an Ed25519 signing key and an X25519 key-agreement key. 2 adds the `keys` block, which makes those explicit and allows others.
+     */
+    schemaVersion: 1 | 2 | 3;
+    name: string;
+    kind: string;
+    description?: string | null;
+    methods?: string[];
+    requiredVars?: string[];
+    optionalVars?: {
+        [k: string]: unknown | undefined;
+    };
+    defaults?: {
+        [k: string]: unknown | undefined;
+    };
+    /**
+     * The keys this template needs, by slot name. REQUIRES `schemaVersion` 2.
+     *
+     * A slot's name becomes a document placeholder by an explicit rule — uppercase, `-` to `_`, suffix `_KEY_MB` — so slot `signing` is rendered into `{SIGNING_KEY_MB}` and slot `ka` into `{KA_KEY_MB}`. Those are the two names a `schemaVersion` 1 template already uses, which is deliberate: a v1 template is exactly a v2 template whose `keys` block is `{signing: [ed25519], ka: [x25519]}`, so an implementation can read both through one path and raising the version cannot change how a v1 template renders.
+     *
+     * An implementation MUST refuse a template that declares a slot whose placeholder never appears in `document` — the key would be minted and never published, so verifiers would continue to see only the keys that are, while the operator believes the template migrated. It MUST likewise refuse a slot placeholder in `document` that no slot declares, which would render as an unsubstituted literal.
+     */
+    keys?: {
+        [k: string]: {
+            /**
+             * What the key is for. Deliberately coarser than DID Core's five verification relationships: the template says what the key is, and the `document` body says where it appears. Encoding the relationship here as well would let the two disagree.
+             */
+            purpose: "signing" | "keyAgreement";
+            /**
+             * Acceptable algorithms, MOST PREFERRED FIRST. A list rather than a single value because a fleet does not migrate atomically: `["mldsa44", "ed25519"]` means mint ML-DSA-44 where the implementation can and Ed25519 otherwise, so one template serves a VTA with post-quantum support and one without. An implementation MUST NOT substitute an algorithm absent from this list; running out of candidates is an error, never a silent downgrade — a deployment intended to be post-quantum would otherwise ship classical keys with nothing reporting it. `minItems: 1` for the same reason: an empty list would express no preference and inherit whatever the implementation defaulted to.
+             *
+             * @minItems 1
+             */
+            algorithms: [
+                "ed25519" | "x25519" | "p256" | "mldsa44" | "mldsa65",
+                ...("ed25519" | "x25519" | "p256" | "mldsa44" | "mldsa65")[]
+            ];
+        } | undefined;
+    };
+    /**
+     * The key roles of a key-role identity, one `RoleLayout` per role (vta/dids/_shared/0.1/CONVENTIONS.md §4). REQUIRED for, and only for, `schemaVersion` 3, which then MUST NOT carry `keys`. A v3 template describes only an identity's non-key members: its `document` MUST NOT contain `verificationMethod`, `authentication`, `assertionMethod`, `keyAgreement`, `capabilityInvocation`, `capabilityDelegation` or `keyRoles`, and the VTA renders all of them from this layout and the key-role registry — so a template can never place a key in a relationship its role does not own. Each listed algorithm is minted, one key each; unlike v2's `keys`, the list is not a preference order, and a VTA that cannot mint one refuses rather than substitutes. Used by vta/dids/create; a v1 or v2 template cannot create a key-role identity.
+     *
+     * @minItems 1
+     */
+    keyRoles?: [RoleLayout, ...RoleLayout[]];
+    document: {};
+    /**
+     * Resolved scope of the stored template.
+     */
+    scope: Scope_VtaV0_1;
+    /**
+     * When the template was first stored (RFC 3339).
+     */
+    createdAt: string;
+    /**
+     * When the template was last written (RFC 3339).
+     */
+    updatedAt: string;
+    /**
+     * DID of the admin who last wrote the template.
+     */
+    createdBy: string;
+}
 /**
  * Authored template shape: a DID document with `{TOKEN}` placeholders plus the variable contract the VTA's renderer enforces.
  */
@@ -7009,6 +7124,81 @@ export interface DidTemplate_VtaV0_2 {
      */
     document: {};
 }
+/**
+ * Authored template shape: a DID document with `{TOKEN}` placeholders plus the variable contract the VTA's renderer enforces.
+ */
+export interface DidTemplate_VtaV0_9 {
+    /**
+     * Template schema version. 1 is the historical shape, whose keys are implicitly an Ed25519 signing key and an X25519 key-agreement key. 2 adds the `keys` block, which makes those explicit and allows others. 3 is a key-role template (`keyRoles`), whose document carries no key members.
+     */
+    schemaVersion: 1 | 2 | 3;
+    /**
+     * Template id within its scope. Lowercase alphanumeric and hyphen only.
+     */
+    name: string;
+    /**
+     * Classification hint, e.g. `mediator`, `did-host-http`, `app`. Drives downstream provisioning behaviour.
+     */
+    kind: string;
+    /**
+     * Human-readable description of what the template provisions.
+     */
+    description?: string | null;
+    /**
+     * DID methods this template targets, e.g. ["webvh", "web"] for a hosted DID or ["key"] for a did:key.
+     */
+    methods?: string[];
+    /**
+     * Variables the caller MUST supply at render time. MUST NOT include reserved ambient names (DID, SIGNING_KEY_MB, KA_KEY_MB, VTA_DID, VTA_URL, CONTEXT_ID, CONTEXT_DID, NOW).
+     */
+    requiredVars?: string[];
+    /**
+     * Variables with default values, keyed by variable name.
+     */
+    optionalVars?: {
+        [k: string]: unknown | undefined;
+    };
+    /**
+     * Hints for CLI / setup wizards (e.g. preRotationCount, portable, addMediatorService).
+     */
+    defaults?: {
+        [k: string]: unknown | undefined;
+    };
+    /**
+     * The keys this template needs, by slot name. REQUIRES `schemaVersion` 2.
+     *
+     * A slot's name becomes a document placeholder by an explicit rule — uppercase, `-` to `_`, suffix `_KEY_MB` — so slot `signing` is rendered into `{SIGNING_KEY_MB}` and slot `ka` into `{KA_KEY_MB}`. Those are the two names a `schemaVersion` 1 template already uses, which is deliberate: a v1 template is exactly a v2 template whose `keys` block is `{signing: [ed25519], ka: [x25519]}`, so an implementation can read both through one path and raising the version cannot change how a v1 template renders.
+     *
+     * An implementation MUST refuse a template that declares a slot whose placeholder never appears in `document` — the key would be minted and never published, so verifiers would continue to see only the keys that are, while the operator believes the template migrated. It MUST likewise refuse a slot placeholder in `document` that no slot declares, which would render as an unsubstituted literal.
+     */
+    keys?: {
+        [k: string]: {
+            /**
+             * What the key is for. Deliberately coarser than DID Core's five verification relationships: the template says what the key is, and the `document` body says where it appears. Encoding the relationship here as well would let the two disagree.
+             */
+            purpose: "signing" | "keyAgreement";
+            /**
+             * Acceptable algorithms, MOST PREFERRED FIRST. A list rather than a single value because a fleet does not migrate atomically: `["mldsa44", "ed25519"]` means mint ML-DSA-44 where the implementation can and Ed25519 otherwise, so one template serves a VTA with post-quantum support and one without. An implementation MUST NOT substitute an algorithm absent from this list; running out of candidates is an error, never a silent downgrade — a deployment intended to be post-quantum would otherwise ship classical keys with nothing reporting it. `minItems: 1` for the same reason: an empty list would express no preference and inherit whatever the implementation defaulted to.
+             *
+             * @minItems 1
+             */
+            algorithms: [
+                "ed25519" | "x25519" | "p256" | "mldsa44" | "mldsa65",
+                ...("ed25519" | "x25519" | "p256" | "mldsa44" | "mldsa65")[]
+            ];
+        } | undefined;
+    };
+    /**
+     * The key roles of a key-role identity, one `RoleLayout` per role (vta/dids/_shared/0.1/CONVENTIONS.md §4). REQUIRED for, and only for, `schemaVersion` 3, which then MUST NOT carry `keys`. A v3 template describes only an identity's non-key members: its `document` MUST NOT contain `verificationMethod`, `authentication`, `assertionMethod`, `keyAgreement`, `capabilityInvocation`, `capabilityDelegation` or `keyRoles`, and the VTA renders all of them from this layout and the key-role registry — so a template can never place a key in a relationship its role does not own. Each listed algorithm is minted, one key each; unlike v2's `keys`, the list is not a preference order, and a VTA that cannot mint one refuses rather than substitutes. Used by vta/dids/create; a v1 or v2 template cannot create a key-role identity.
+     *
+     * @minItems 1
+     */
+    keyRoles?: [RoleLayout, ...RoleLayout[]];
+    /**
+     * The DID document body with `{TOKEN}` placeholders. `document.id` MUST contain the `{DID}` placeholder. Every `{TOKEN}` MUST be declared in requiredVars/optionalVars or be a reserved ambient name.
+     */
+    document: {};
+}
 /**
  * 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.
  *
@@ -7924,12 +8114,14 @@ export interface FieldVisibility {
     [k: string]: Audience | undefined;
 }
 /**
- * The `file` member of a sealed record body: everything that describes a file, sealed with the record, signed by the record's author, and never seen by the host. Defined here so that clients interoperate; no host task carries it, because the host receives only ciphertext.
+ * Everything that describes a file. On an `attributed` or `private` room it is the `file` member of the sealed record body: sealed with the record, signed by the record's author, and never seen by the host. On an `open` room it is the `file` member of the record's `cleartext` (rooms/records/put/0.4), carrying its own `fileKey`, and the host reads it like the rest of the record. Defined here so that clients interoperate.
  *
  * **Byte encodings.** In every derivation below, `fileId` is its **32 decoded bytes**, never its base64url text; `roomId` is the **UTF-8 bytes** of the room identifier exactly as it appears on the wire; string constants are their ASCII bytes; `u8`, `u32be` and `u64be` are unsigned integers of that width, big-endian. Epochs are unsigned 64-bit on the wire. An implementation that holds epochs in a narrower type **MUST** refuse a value it cannot represent with `malformedRequest` (or, reading a manifest, refuse the file), and **MUST NOT** truncate it.
  *
  * **The file key.** `file_key = HKDF-SHA256(ikm = storage_key(epoch), salt = fileId, info = "openvtc/room/file/v1" || roomId || u64be(epoch))`, where `storage_key(epoch)` is the room's per-epoch storage key, the one records are sealed under. It is derived per file and never stored. It is bound to the room and the epoch, so a key released for one room cannot open a blob relocated from another, and releasing it exposes one file and nothing else.
  *
+ * **The file key on an `open` room.** An open room has no group and so no storage key to derive from. There the uploader mints the file key itself — 32 bytes from a cryptographically secure random source, for this file only — and carries it in `fileKey`; a reader uses that key and derives nothing. Everything else below (padding, STREAM, the associated data, reading) is the same on every tier, with `epoch` the room's epoch when the file was written. `fileKey` **MUST** be present in an open room's manifest and **MUST** be absent from a sealed record body's, where the key is derived; a reader **MUST** refuse a file whose manifest breaks either rule. The key in the clear withholds nothing from the host or from anyone it serves the record to — the open tier withholds nothing from them — but it keeps the stored blob opaque to whoever holds only the storage, and keeps one blob format, and one reader, for every tier.
+ *
  * **Padding.** With `padding: "padme"`, the plaintext of length `L = size` is extended with zero bytes to `padme(L)`: for `L < 2`, `padme(L) = L`; otherwise `E = floor(log2 L)`, `S = floor(log2 E) + 1`, `z = E − S`, `mask = 2^z − 1`, and `padme(L) = (L + mask) & ~mask`. The padded length is `padme(size)`; without padding it is `size`. Padding bytes **MUST** be zero.
  *
  * **The STREAM construction.** The padded plaintext is cut into `segmentSize`-byte segments, the last holding the remainder; an empty plaintext is one empty final segment. Segment `i` is sealed with ChaCha20-Poly1305 under `file_key`, with nonce `u32be(0) || u64be(i)` and associated data `"openvtc/room/file/v1" || roomId || fileId || u64be(epoch) || u64be(i) || u8(final)`, where `final` is 1 on the last segment and 0 on every other. A host that truncates, reorders or splices ciphertext produces an authentication failure, never a shorter or rearranged file. The nonces are counters, so a `file_key` MUST NOT seal two different files; a fresh random `fileId` is what guarantees it. Each sealed segment is one transfer chunk of the blob (BlobManifest), so `segmentSize + 16` is the blob's `chunks.chunkSize`, and an empty file is one 16-byte chunk.
@@ -7947,7 +8139,7 @@ export interface FileManifest {
      */
     fileId: string;
     /**
-     * The file's name as the uploader gave it. Sealed: the host never sees it. Readers MUST treat it as untrusted text: strip path separators before using it as a local file name, and never interpret it as markup.
+     * The file's name as the uploader gave it. Sealed on `attributed` and `private` rooms, where the host never sees it; in the clear on `open` ones. Readers MUST treat it as untrusted text: strip path separators before using it as a local file name, and never interpret it as markup.
      */
     name: string;
     /**
@@ -7959,7 +8151,7 @@ export interface FileManifest {
      */
     size: number;
     /**
-     * Digest of the plaintext bytes. Signed, with the rest of the record body, by the record's author, so a reader that verifies it knows which member put exactly these bytes there.
+     * Digest of the plaintext bytes. On `attributed` and `private` rooms it is signed, with the rest of the record body, by the record's author, so a reader that verifies it knows which member put exactly these bytes there. On an `open` room it is the writer's claim as the host stores it, like the rest of the record.
      */
     digest: DigestMultibase;
     /**
@@ -7975,6 +8167,10 @@ export interface FileManifest {
      */
     padding?: "none" | "padme";
     blobRef: BlobRef;
+    /**
+     * The file key itself, 32 bytes base64url without padding: present on an `open` room only, where there is no storage key to derive it from. Minted by the uploader from a cryptographically secure random source for this one file and never reused. MUST be absent on `attributed` and `private` rooms, where the key is derived and never stored.
+     */
+    fileKey?: string;
 }
 /**
  * A person's account on one forge. `id` is authoritative; `login` is for display only, because logins can be renamed and re-registered.
@@ -8321,6 +8517,133 @@ export interface HpkeArmoredEnvelope_VaultV0_2 {
      */
     producerAssertion?: "didSigned" | "attested" | "pinnedOnly";
 }
+export interface IdentityChange {
+    /**
+     * `addKey` — a verification method joins its role's relationship and `keyRoles`. `retireKey` — a verification method leaves its relationship, `keyRoles` and the document. `revokeKey` — a verification method leaves its relationship and `keyRoles`, and stays in `verificationMethod` with `revoked` set to the compromise time (CONVENTIONS.md §9.1). `rotateUpdateKey` — the identifier's update authority moves to a committed routine successor. `commitUpdateKey` — a new routine successor is committed. `replaceRecoveryCommitment` — the recovery commitment changes. `useRecoveryKey` — the change is authorized by the recovery key, which the identifier then reveals.
+     */
+    op: "addKey" | "retireKey" | "revokeKey" | "rotateUpdateKey" | "commitUpdateKey" | "replaceRecoveryCommitment" | "useRecoveryKey";
+    role: IdentityKeyRole;
+    verificationMethod?: string;
+    keyType?: KeyType;
+    publicKeyMultibase?: string;
+    commitment?: string;
+    relationships?: DidVerificationRelationship[];
+}
+/**
+ * What a change would publish, computed by the VTA by running the handler it would run to apply it (CONVENTIONS.md §6.1). This is what a consent surface renders and what an approval is bound to.
+ */
+export interface IdentityChangePreview {
+    /**
+     * Opaque, unguessable identifier of this exact plan. Carried back by the apply request; every approval and any recovery proof is bound to it.
+     */
+    previewId: string;
+    method: DidMethodName;
+    /**
+     * The version identifier the plan was computed against. Absent only for a creation. The plan is void once the identifier moves past it.
+     */
+    baseVersionId?: string;
+    expiresAt: string;
+    /**
+     * Every change the plan would make, including the ones the caller did not ask for — in particular any movement of the update authority the method requires.
+     */
+    changes: IdentityChange[];
+    /**
+     * The complete identifier document the change would publish, `keyRoles` included. Public data by construction.
+     */
+    document: {};
+    warnings?: PreviewWarning[];
+    /**
+     * True when applying the plan also moves the identifier's update authority to a committed successor — every change under did:webvh pre-rotation, never a KERI interaction event. Stated as its own member because it is the consequence a reviewer most often misses.
+     */
+    updateKeyRotates: boolean;
+    recoverySigning?: RecoverySigningRequest;
+}
+/**
+ * How a key is held. Present only in the custody projection. Carries no key material, and a conforming VTA MUST NOT place any in `ext`.
+ */
+export interface IdentityKeyCustody {
+    /**
+     * The custodian record identifier (`keys/*`'s `keyId`) behind this key. Absent for a key this VTA does not hold (`protection: externalCustodian`).
+     */
+    keyId?: string;
+    origin?: KeyOrigin;
+    /**
+     * Whether the custodian would release the private half. Always `false` for `attestation` and `update` keys. Stated explicitly, never absent.
+     */
+    exportable: boolean;
+    /**
+     * True when no authority can make the key exportable. `true` implies `exportable: false`.
+     */
+    neverExportable: boolean;
+    /**
+     * Whether the key, or material it can be re-derived or decrypted from, is in the VTA's backups or any state transfer. Always `false` for `attestation` and `update` keys (VTI-KEY-112).
+     */
+    inBackups: boolean;
+    protection: ProtectionClass;
+    /**
+     * Opaque, VTA-assigned label of the protection boundary holding the key (CONVENTIONS.md §5.2). Two keys with the same label are lost or compromised together. A recovery update key MUST carry a label different from every routine update key's. Custody projection only; never published.
+     */
+    boundary?: string;
+    /**
+     * True once the private half has been destroyed — a retired `attestation` or `messaging` key. The record survives so the key's past signatures stay attributable.
+     */
+    destroyed?: boolean;
+}
+/**
+ * One key in one role. A key is in exactly one role for its whole life; a change of role is a retirement from one and an addition to another, with fresh material under a fresh identifier.
+ */
+export interface IdentityRoleKey {
+    /**
+     * The full verification-method identifier (`did#fragment`) the document publishes the key under and lists in `keyRoles`. Absent for `update` keys, which are never role-bound verification methods (VTI-KEY-093). A VTA minting a method SHOULD derive its fragment from the key (VTI-KEY-150).
+     */
+    verificationMethod?: string;
+    role: IdentityKeyRole;
+    updateKeyClass?: UpdateKeyClass;
+    /**
+     * The relationships the key is (or, while `pending`, will be) listed in: always exactly its role's one relationship. Empty for `update`, `retired` and `revoked` keys.
+     */
+    relationships?: DidVerificationRelationship[];
+    keyType: KeyType;
+    /**
+     * The public half, multibase-encoded, exactly as published. Absent for a `committed` update key, whose public half the identifier has not yet revealed.
+     */
+    publicKeyMultibase?: string;
+    /**
+     * For a `committed` update key: the commitment the identifier publishes (a did:webvh `nextKeyHashes` entry, a KERI next-key digest), in the method's own encoding.
+     */
+    commitment?: string;
+    state: KeyLifecycleState;
+    /**
+     * The method's version identifier of the change that first published the key or its commitment (method-profiles/: a did:webvh `versionId`, a KERI event's sequence number and digest). Absent while `pending`.
+     */
+    publishedInVersionId?: string;
+    /**
+     * Version identifier of the change that retired or revoked the key.
+     */
+    removedInVersionId?: string;
+    /**
+     * For a `staged` key: when the VTA will begin using it — no earlier than the publishing change's cache horizon.
+     */
+    activatesAt?: string;
+    /**
+     * For a `retiring` key: the end of its overlap. Custody projection only.
+     */
+    retireAfter?: string;
+    /**
+     * For a `revoked` key: the compromise time (VTI-KEY-121), published as the verification method's `revoked` value. Where it cannot be established, the time the key was first published.
+     */
+    compromisedSince?: string;
+    /**
+     * The rotation this key was introduced or retired by.
+     */
+    rotationId?: string;
+    /**
+     * Operator-facing label. Custody projection only.
+     */
+    label?: string;
+    custody?: IdentityKeyCustody;
+    ext?: Ext;
+}
 /**
  * Whether the edge is in force now, and if not, why not — the edge's resolved state, which is not the same thing as the event just recorded: restoring an edge whose `validUntil` passed while it was suspended records the restoration and still resolves `expired`. Exactly the members its `state` names are present.
  */
@@ -8466,6 +8789,29 @@ export interface InviteSummary_VtcV0_1 {
      */
     consumedAt?: string;
 }
+/**
+ * One outstanding or historical admin invite. Consumed rows are retained as audit history.
+ */
+export interface InviteSummary_VtcV0_2 {
+    /**
+     * Unique invite identifier; the revoke target.
+     */
+    jti: string;
+    kind: InviteKind;
+    status: InviteStatus;
+    /**
+     * The administrator's DID: for a wallet invitation the DID it names; for a passkey invitation the DID derived from the passkey that claimed it, so absent until it is consumed.
+     */
+    targetDid?: string;
+    /**
+     * When an `issued` invite lapses.
+     */
+    expiresAt?: string;
+    /**
+     * When the invite was redeemed, if it was.
+     */
+    consumedAt?: string;
+}
 /**
  * The members of an issuance receipt, deliberately left **open** so a consuming specification can `$ref` it under `allOf` and add its own, then close the result with `unevaluatedProperties: false`.
  *
@@ -8595,6 +8941,74 @@ export interface KdfParams {
      */
     pCost: number;
 }
+/**
+ * Approval progress of a change the VTA's policy gates on approvals (CONVENTIONS.md §6).
+ */
+export interface KeyChangeApprovalState {
+    /**
+     * Distinct approvals the VTA's policy requires.
+     */
+    required: number;
+    /**
+     * Distinct approvals recorded so far, the initiator's own included.
+     */
+    received: number;
+    /**
+     * The approvals recorded. Custody projection only; omitted from a response to anyone who is not themselves an eligible approver of this change.
+     */
+    approvals?: RecordedApproval[];
+    /**
+     * When the preview, and every approval bound to it, stops being usable.
+     */
+    expiresAt: string;
+}
+/**
+ * One change to a role's key set, from preview to completion. The identifier's history is the authority for what was published; this record adds which change was which and, in the custody projection, who asked, who approved, and why.
+ */
+export interface KeyChangeRecord {
+    rotationId: string;
+    role: IdentityKeyRole;
+    kind: KeyChangeKind;
+    state: KeyChangeState;
+    /**
+     * Verification-method identifiers (for `update`, public keys or commitments) leaving the role.
+     */
+    predecessors?: string[];
+    /**
+     * Verification-method identifiers (for `update`, public keys or commitments) entering the role.
+     */
+    successors?: string[];
+    startedInVersionId?: string;
+    endedInVersionId?: string;
+    startedAt?: string;
+    /**
+     * Planned rotations: the publishing change's cache horizon (CONVENTIONS.md §10.1). The switch and any retirement happen no earlier.
+     */
+    cacheHorizonAt?: string;
+    /**
+     * When the successor becomes `active` and the predecessor `retiring`; never before `cacheHorizonAt`.
+     */
+    activatesAt?: string;
+    /**
+     * Custody projection only. End of the overlap.
+     */
+    overlapUntil?: string;
+    /**
+     * Custody projection only. Whether the VTA retires the predecessor itself at `overlapUntil`.
+     */
+    autoRetire?: boolean;
+    endedAt?: string;
+    /**
+     * Custody projection only. VID of the administrator whose signed request started the change.
+     */
+    initiatedBy?: string;
+    approvals?: KeyChangeApprovalState;
+    /**
+     * Custody projection only. The operator's stated reason. Never published.
+     */
+    reason?: string;
+    ext?: Ext;
+}
 /**
  * How a device custodies its private key material — maintainer policy input, mirroring `attestation`. See docs/design-notes/mobile-key-custody-profile.md.
  */
@@ -8675,6 +9089,25 @@ export interface KeyRoleApprovalState {
      */
     expiresAt: string;
 }
+export interface KeyRoleSummary {
+    role: IdentityKeyRole;
+    /**
+     * The relationship this role owns. Empty for `update`.
+     */
+    relationships: DidVerificationRelationship[];
+    /**
+     * The role's keys, in the order the document publishes them. Terminal-state keys are included only when the request asked for them, except a `revoked` key the document still lists, which is always included.
+     */
+    keys: IdentityRoleKey[];
+    /**
+     * `update` only: whether the identifier's latest version commits to a recovery key in a boundary other than the VTA's (CONVENTIONS.md §5.3). `false` is a defect the VTA reports rather than hides.
+     */
+    recoveryCommitted?: boolean;
+    /**
+     * `update` only, where the method has one: the signing threshold over the current update keys, in the method's own notation (a KERI `kt`).
+     */
+    threshold?: string;
+}
 /**
  * Every key the entry's act scope reaches.
  */
@@ -9838,6 +10271,30 @@ export interface PublicKeyCredentialRequestOptions {
     allowCredentials?: PublicKeyCredentialDescriptor[];
     userVerification?: "discouraged" | "preferred" | "required";
 }
+/**
+ * How the change reaches resolvers.
+ */
+export interface Publication {
+    /**
+     * True when no hosting service holds the identifier for the VTA: the caller must publish `artifacts`, and until it does resolvers see the previous version.
+     */
+    selfPublish: boolean;
+    /**
+     * Present when `selfPublish` is true.
+     */
+    artifacts?: PublishedArtifact[];
+}
+/**
+ * A file the identifier's method publishes, as the method profile names it (`did.jsonl` for did:webvh, `did.json` and `keri.cesr` for did:webs).
+ */
+export interface PublishedArtifact {
+    name: string;
+    mediaType: string;
+    /**
+     * The artefact's content, or for an append-only artefact the appended part, as text.
+     */
+    content: string;
+}
 /**
  * A member's external card: a JSContact `Card` (RFC 9553) holding exactly their values whose visibility is `public`, mapped as `JSContactCard` maps them, with the member's W3C Data Integrity `proof`. The community serves it as received and never signs, composes or edits it (VTI-REG-004 item 4).
  *
@@ -10301,6 +10758,51 @@ export interface RecordRetention {
      */
     ext?: Ext;
 }
+export interface RecordedApproval {
+    /**
+     * VID of the approver.
+     */
+    approver: string;
+    evidence: ApprovalEvidenceKind;
+    recordedAt?: string;
+}
+/**
+ * A recovery key offered for commitment (CONVENTIONS.md §5.3). The VTA computes the method's commitment from it, verifies `proofOfPossession`, and then keeps only the commitment. The key MUST be held by a custodian in a protection boundary other than the VTA's; a VTA MUST refuse one it generated or can derive (`vta/dids:recoveryCommitmentRequired`).
+ */
+export interface RecoveryCommitment {
+    keyType: KeyType;
+    /**
+     * The recovery key's public half. Not published by the VTA where the method commits by hash.
+     */
+    publicKeyMultibase: string;
+    /**
+     * Multibase signature by the recovery key over the UTF-8 bytes of `vta-dids-recovery-commitment/v1`, a zero byte, and the request's `previewId`. Absent on a dry run, which is how the `previewId` is obtained; REQUIRED on the apply request, and the only member besides `previewId`, `dryRun` and `recoveryProof` that may differ between the two.
+     */
+    proofOfPossession?: string;
+    /**
+     * Operator-facing name of the custodian. Custody projection only; never published.
+     */
+    label?: string;
+}
+/**
+ * What a recovery custodian must sign for a change that only the recovery key may authorize (CONVENTIONS.md §5.4, §9.4). The custodian MUST check `unsignedChange` itself — render it to its human, confirm that it reveals the recovery key it holds and commits to a fresh recovery key it also holds — and MUST NOT sign on the strength of this request's description alone.
+ */
+export interface RecoverySigningRequest {
+    /**
+     * The recovery commitment the identifier publishes; the custodian's key MUST be the one it commits to.
+     */
+    commitment: string;
+    keyType: KeyType;
+    /**
+     * The change exactly as it will be published, without the recovery proof, as JSON text in the method's own form (a did:webvh log entry, a KERI rotation event).
+     */
+    unsignedChange: string;
+    /**
+     * The proof the method requires over `unsignedChange`, without its signature value, as the method profile defines it (for did:webvh, a Data Integrity proof configuration with `proofPurpose: assertionMethod` and the recovery key's `did:key` as `verificationMethod`).
+     */
+    proofOptions: {};
+    expiresAt?: string;
+}
 /**
  * A passkey already bound to a subject, as listed by `auth/passkey/list` and targeted by `auth/passkey/revoke/*`. This is the auth service's own management view of a credential — not a WebAuthn dictionary — so its members are camelCase per SPEC.md §4.10. The exception is `transports`, whose values are the externally-owned WebAuthn transport tokens and are carried verbatim.
  */
@@ -10347,6 +10849,19 @@ export interface RegisteredInstance {
     lastSeenAt?: string;
     ext?: Ext;
 }
+/**
+ * What the node must now do that the change cannot (VTI-KEY-133, CONVENTIONS.md §9.6). Custody data, present when an `attestation` key is revoked or lost.
+ */
+export interface ReissuanceFollowUp {
+    /**
+     * Status lists signed by the revoked or lost key, which the node MUST re-sign at once under a sound attestation key.
+     */
+    statusListsToResign?: number;
+    /**
+     * Attestation artefacts still in force that the VTA's signing record shows the key signed, which the node MUST re-issue with identical claims and expiry.
+     */
+    artefactsToReissue?: number;
+}
 /**
  * A key a patch declined to apply, with the reason.
  */
@@ -10890,6 +11405,18 @@ export interface RoleKeyCustody {
      */
     destroyed?: boolean;
 }
+/**
+ * The keys an identity is created with in one role (CONVENTIONS.md §4). A key-role DID template carries one per role; a creation request may narrow it but never widen it.
+ */
+export interface RoleLayout {
+    role: IdentityKeyRole;
+    /**
+     * The algorithms to mint, one key each, in publication order — `["ed25519", "mldsa44"]` mints a classical and a post-quantum attestation key that sign as a proof set. Every entry MUST suit the role (CONVENTIONS.md §2.2). A VTA that cannot mint one of them MUST refuse the creation with `vta/dids:unsupportedKeyType`; it never substitutes an algorithm or omits a key.
+     *
+     * @minItems 1
+     */
+    algorithms: [KeyType, ...KeyType[]];
+}
 export interface RoleSummary {
     role: KeyRole;
     /**