p2party 0.14.2 → 0.14.7

package/lib/cryptography/hpkeSuite.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Constants-only SSOT for the fixed pair-bootstrap HPKE suite.
+ *
+ * Keeping this separate from the executable HPKE adapter lets schemas and the
+ * blind-rendezvous suite registry consume the exact wire geometry without
+ * importing WASM-backed cryptographic code.
+ */
+export declare const HPKE_MLKEM768_X25519_KEM_ID = 25722;
+export declare const HPKE_HKDF_SHA256_KDF_ID = 1;
+export declare const HPKE_CHACHA20POLY1305_AEAD_ID = 3;
+export declare const HPKE_MODE_BASE = 0;
+export declare const HPKE_MODE_PSK = 1;
+export declare const HPKE_HASH_BYTES = 32;
+export declare const HPKE_KEY_BYTES = 32;
+export declare const HPKE_NONCE_BYTES = 12;
+export declare const HPKE_TAG_BYTES = 16;
+export declare const HPKE_PAIR_PSK_BYTES = 32;
+export declare const HPKE_PAIR_PSK_ID_BYTES = 32;
+export declare const HPKE_MAX_EXPORT_BYTES: number;
+export declare const HPKE_MAX_APPLICATION_CONTEXT_BYTES = 65535;
+export declare const HPKE_MLKEM768_X25519_SUITE: Readonly<{
+    readonly specification: Readonly<{
+        kem: "draft-ietf-hpke-pq-05";
+        kemKeyDerivation: "draft-ietf-hpke-hpke-03";
+        keySchedule: "RFC 9180";
+    }>;
+    readonly kemId: 25722;
+    readonly kdfId: 1;
+    readonly aeadId: 3;
+    readonly publicKeyBytes: 1216;
+    readonly secretKeyBytes: 32;
+    readonly encapsulatedKeyBytes: 1120;
+    readonly sharedSecretBytes: 32;
+    readonly keyBytes: 32;
+    readonly nonceBytes: 12;
+    readonly tagBytes: 16;
+    readonly pskBytes: 32;
+    readonly pskIdBytes: 32;
+}>;

package/lib/cryptography/hybridKem.d.ts

@@ -0,0 +1,42 @@
+import { MLKEM768_X25519_SUITE } from "./hybridKemSuite";
+import type { LibCrypto } from "./libcrypto";
+import type { MlKemDecapsulation, MlKemEncapsulation, MlKemKeyPair } from "./mlkem";
+export { MLKEM768_X25519_CIPHERTEXT_BYTES, MLKEM768_X25519_PUBLIC_KEY_BYTES, MLKEM768_X25519_RANDOM_BYTES, MLKEM768_X25519_SEED_BYTES, MLKEM768_X25519_SECRET_KEY_BYTES, MLKEM768_X25519_SHARED_SECRET_BYTES, MLKEM768_X25519_SUITE, } from "./hybridKemSuite";
+export type MlKem768X25519KeyPair = MlKemKeyPair;
+export type MlKem768X25519Encapsulation = MlKemEncapsulation;
+export type MlKem768X25519Decapsulation = MlKemDecapsulation;
+/**
+ * A correctly framed peer ciphertext is not a valid ciphertext for this
+ * hybrid KEM. Infrastructure and local-key failures use their original errors.
+ */
+export declare class HybridKemInvalidCiphertextError extends Error {
+    readonly name = "HybridKemInvalidCiphertextError";
+    constructor();
+}
+/**
+ * A correctly framed hybrid encapsulation key failed FIPS 203's ML-KEM
+ * modulus check or X25519 low-order-point validation.
+ */
+export declare class HybridKemInvalidPublicKeyError extends Error {
+    readonly name = "HybridKemInvalidPublicKeyError";
+    constructor();
+}
+/**
+ * Validate one suite-1 hybrid encapsulation key without performing a second
+ * ML-KEM encapsulation.
+ *
+ * FIPS 203 encodes two 12-bit ML-KEM coefficients in each three-byte group;
+ * every coefficient must be below q=3329. The final 32 ML-KEM bytes are rho
+ * and are unrestricted. X25519 validity is the library's ordinary
+ * all-zero-shared-secret rejection. Public inputs need no constant-time scan.
+ */
+export declare const validateMlKem768X25519PublicKey: (publicKey: Uint8Array, module: LibCrypto) => void;
+export interface MlKem768X25519Backend {
+    readonly suite: typeof MLKEM768_X25519_SUITE;
+    generateKeyPair(): Promise<MlKem768X25519KeyPair>;
+    deriveKeyPair(seed: Uint8Array): Promise<MlKem768X25519KeyPair>;
+    encapsulate(publicKey: Uint8Array): Promise<MlKem768X25519Encapsulation>;
+    encapsulateDeterministically(publicKey: Uint8Array, randomness: Uint8Array): Promise<MlKem768X25519Encapsulation>;
+    decapsulate(ciphertext: Uint8Array, secretKey: Uint8Array): Promise<MlKem768X25519Decapsulation>;
+}
+export declare const createMlKem768X25519Backend: (module: LibCrypto) => MlKem768X25519Backend;

package/lib/cryptography/hybridKemSuite.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Frozen wire geometry for the pair-bootstrap KEM.
+ *
+ * This constants-only module is the SSOT shared by the crypto implementation
+ * and blind-rendezvous schemas. Changing any value requires a new suite ID.
+ */
+export declare const MLKEM768_X25519_SEED_BYTES = 32;
+export declare const MLKEM768_X25519_PUBLIC_KEY_BYTES = 1216;
+export declare const MLKEM768_X25519_SECRET_KEY_BYTES = 32;
+export declare const MLKEM768_X25519_CIPHERTEXT_BYTES = 1120;
+export declare const MLKEM768_X25519_SHARED_SECRET_BYTES = 32;
+export declare const MLKEM768_X25519_RANDOM_BYTES = 64;
+export declare const MLKEM768_X25519_SUITE: Readonly<{
+    readonly standardName: "MLKEM768-X25519";
+    readonly specification: "draft-irtf-cfrg-concrete-hybrid-kems-04";
+    readonly seedBytes: 32;
+    readonly publicKeyBytes: 1216;
+    readonly secretKeyBytes: 32;
+    readonly ciphertextBytes: 1120;
+    readonly sharedSecretBytes: 32;
+    readonly randomnessBytes: 64;
+}>;

package/lib/cryptography/interfaces.d.ts

@@ -11,6 +11,9 @@ export declare const crypto_secretbox_NONCEBYTES: number;
 export declare const crypto_aead_chacha20poly1305_ietf_KEYBYTES: number;
 export declare const crypto_aead_chacha20poly1305_ietf_NPUBBYTES: number;
 export declare const crypto_aead_chacha20poly1305_ietf_ABYTES: number;
+export declare const crypto_aead_xchacha20poly1305_ietf_KEYBYTES: number;
+export declare const crypto_aead_xchacha20poly1305_ietf_NPUBBYTES: number;
+export declare const crypto_aead_xchacha20poly1305_ietf_ABYTES: number;
 export declare const crypto_pwhash_argon2id_SALTBYTES: number;
 export declare const crypto_core_ristretto255_BYTES: number;
 export declare const crypto_core_ristretto255_HASHBYTES: number;

package/lib/cryptography/mlkem.d.ts

@@ -45,6 +45,15 @@ export declare const ML_KEM_SUITES: Readonly<{
     1024: Readonly<MlKemSuiteDescriptor<1024>>;
 }>;
 export declare const getMlKemSuite: <P extends MlKemParameterSet>(parameterSet: P) => Readonly<MlKemSuiteDescriptor<P>>;
+/**
+ * FIPS 203 Section 7.2 modulus check for one encoded encapsulation key.
+ *
+ * Each three-byte group in the encoded polynomial vector contains two
+ * little-endian 12-bit coefficients, both of which must be below q=3329.
+ * The final 32-byte public seed is unrestricted. This pure check is shared by
+ * every composed KEM so canonical ML-KEM public-key encoding has one SSOT.
+ */
+export declare const mlKemPublicKeyHasCanonicalEncoding: (publicKey: unknown, parameterSet: MlKemParameterSet) => boolean;
 type MlKemKeyPairFunction = (publicKey: number, secretKey: number, coins64: number) => number;
 type MlKemEncapsFunction = (ciphertext: number, sharedSecret: number, publicKey: number, coins32: number) => number;
 type MlKemDecapsFunction = (sharedSecret: number, ciphertext: number, secretKey: number) => number;
@@ -104,12 +113,29 @@ export interface MlKemBackend<P extends MlKemParameterSet = MlKemParameterSet> {
     encapsulate(publicKey: Uint8Array): Promise<MlKemEncapsulation>;
     decapsulate(ciphertext: Uint8Array, secretKey: Uint8Array): Promise<MlKemDecapsulation>;
 }
+/**
+ * Real-WASM ML-KEM backend with the explicit deterministic inputs required by
+ * composed, version-pinned KEMs. The ordinary backend remains the narrower
+ * seam used by protocol state machines and test doubles.
+ */
+export interface DeterministicMlKemBackend<P extends MlKemParameterSet = MlKemParameterSet> extends MlKemBackend<P> {
+    /**
+     * FIPS 203 KeyGen_internal with the caller-supplied 64-byte d || z seed.
+     * The seed is borrowed; this method snapshots but never wipes caller bytes.
+     */
+    deriveKeyPair(seed: Uint8Array): Promise<MlKemKeyPair>;
+    /**
+     * FIPS 203 Encaps_internal with caller-supplied 32-byte randomness.
+     * Inputs are borrowed; this method snapshots but never wipes caller bytes.
+     */
+    encapsulateDeterministically(publicKey: Uint8Array, randomness: Uint8Array): Promise<MlKemEncapsulation>;
+}
 /** Compatibility aliases for the currently shipped ML-KEM-768 handshake. */
 export type MlKem768KeyPair = MlKemKeyPair;
 export type MlKem768Encapsulation = MlKemEncapsulation;
 export type MlKem768Decapsulation = MlKemDecapsulation;
 export type MlKem768Backend = MlKemBackend<768>;
-export declare const createMlKemBackend: <P extends MlKemParameterSet>(module: LibCrypto, suite: Readonly<MlKemSuiteDescriptor<P>>) => MlKemBackend<P>;
+export declare const createMlKemBackend: <P extends MlKemParameterSet>(module: LibCrypto, suite: Readonly<MlKemSuiteDescriptor<P>>) => DeterministicMlKemBackend<P>;
 /**
  * Temporary compatibility factory for the protocol-v3 ML-KEM-768 wire suite.
  */

package/lib/cryptography/mnemonic.d.ts

@@ -1,4 +1,41 @@
 import type { LibCrypto } from "./libcrypto";
+/**
+ * The result of a mnemonic check, shaped for a form field: `reason` is a
+ * displayable sentence naming the first problem found, and is absent when the
+ * phrase is usable.
+ */
+export interface MnemonicValidation {
+    ok: boolean;
+    reason?: string;
+}
+/**
+ * The canonical form of a recovery phrase, and part of the derivation
+ * contract: NFKD, then any run of whitespace collapsed to a single space,
+ * trimmed, lowercased.
+ *
+ * A phrase is transcribed by a human from paper, a password manager or a
+ * screenshot, so it arrives with a trailing newline, a double space, a soft
+ * wrap, or a capital first letter from a keyboard's autocapitalisation. All of
+ * those used to be rejected outright by the wordlist lookup. Normalising them
+ * away here means `"  Adapt  patrol "` and `"adapt patrol"` are the same
+ * phrase everywhere: for validation, and for the argon2id input that produces
+ * the seed. Every phrase that derived a key before this normalisation existed
+ * was already in canonical form, so no backup changes what it restores.
+ */
+export declare const normalizeMnemonic: (mnemonic: string) => string;
+/**
+ * Derive an argon2id seed from a passphrase.
+ *
+ * This is the low-level KDF: it applies NFKD only, because an arbitrary
+ * passphrase is not a mnemonic and must not be lowercased. Callers that hash a
+ * recovery phrase pass it through `normalizeMnemonic` first, as
+ * `keyPairFromMnemonic` does.
+ *
+ * @param mnemonic - Passphrase to stretch
+ * @param salt - Optional salt; a random one is generated when omitted
+ * @param module - Optional preloaded WASM module, otherwise one is loaded
+ * @returns The argon2id seed. The caller owns it and should wipe it.
+ */
 export declare const argon2: (mnemonic: string, salt?: Uint8Array, module?: LibCrypto) => Promise<Uint8Array>;
 /**
  * Generates a sequence of words chosen from a prespecified wordlist
@@ -15,6 +52,27 @@ export declare const argon2: (mnemonic: string, salt?: Uint8Array, module?: LibC
 export declare const generateMnemonic: (strength?: 128 | 160 | 192 | 224 | 256 | 288 | 320 | 352 | 384 | 416 | 448 | 480 | 512) => Promise<string>;
 export declare const mnemonicToEntropy: (mnemonic: string) => Promise<boolean>;
 export declare const validateMnemonic: (mnemonic: string) => Promise<boolean>;
+/**
+ * Everything about a recovery phrase that can be checked without hashing:
+ * word count and membership of the wordlist. Synchronous, so a form can call
+ * it on every keystroke and tell the user which word they mistyped.
+ *
+ * The checksum is deliberately not checked here — SHA-512 is only available
+ * asynchronously through Web Crypto. Use `validateMnemonicPhrase` (or
+ * `validateMnemonic`) once the phrase is structurally complete.
+ *
+ * @param words - The phrase as typed; normalisation is applied for you
+ * @returns `{ ok }`, plus a displayable `reason` for the first problem found
+ */
+export declare const validateMnemonicWords: (words: string) => MnemonicValidation;
+/**
+ * The full check: `validateMnemonicWords` plus the checksum, reported in the
+ * same shape so a form can show one message wherever the phrase went wrong.
+ *
+ * @param words - The phrase as typed; normalisation is applied for you
+ * @returns `{ ok }`, plus a displayable `reason` when the phrase is unusable
+ */
+export declare const validateMnemonicPhrase: (words: string) => Promise<MnemonicValidation>;
 /**
  * Generates an Ed25519 key pair from the provided mnemonic.
  * Optionally, you can strenthen the generation with a password.
@@ -22,8 +80,14 @@ export declare const validateMnemonic: (mnemonic: string) => Promise<boolean>;
  * The password is used as a salt for argon2id.
  * From the generated seed we extract the key pair.
  *
+ * The phrase is normalised first (see `normalizeMnemonic`), so how it was
+ * typed does not change the identity it restores. Nothing here is persisted:
+ * the seed, the salt and the encoded password are wiped before returning, and
+ * the phrase itself stays the caller's to forget.
+ *
  * @param mnemonic - Sequence of words from the predefined wordlist
  * @param password - Optional salt for the seed derivation
+ * @param module - Optional preloaded WASM module, otherwise one is loaded
  * @returns An Ed25519 key pair
  */
-export declare const keyPairFromMnemonic: (mnemonic: string, password?: string) => Promise<import("./interfaces").SignKeyPair>;
+export declare const keyPairFromMnemonic: (mnemonic: string, password?: string, module?: LibCrypto) => Promise<import("./interfaces").SignKeyPair>;

package/lib/cryptography/ownedEd25519KeyMaterial.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Internal, owned Ed25519 secret-key capture shared by trusted local
+ * persistence and custody boundaries.
+ *
+ * This module deliberately exposes no process-local capability and no signing
+ * operation. Callers must keep the returned material behind their own trusted
+ * boundary and wipe it when that ownership ends.
+ */
+import type { LibCrypto } from "./libcrypto";
+export interface OwnedEd25519KeyMaterial {
+    readonly secretKey: Uint8Array;
+    readonly publicKey: Uint8Array;
+}
+export interface CaptureConsistentEd25519KeyMaterialOptions {
+    readonly module?: LibCrypto;
+    readonly secretKey: Uint8Array;
+    readonly inputLabel: string;
+    /** Optional synchronous validation after secret capture and before await. */
+    readonly validateBeforeDerivation?: () => void;
+    readonly rejectInconsistentSecretKey: () => never;
+}
+/**
+ * Own a 64-byte Ed25519 secret before the first await and verify its public
+ * suffix by deriving the key pair from its seed.
+ */
+export declare const captureConsistentEd25519KeyMaterial: (options: CaptureConsistentEd25519KeyMaterialOptions) => Promise<OwnedEd25519KeyMaterial>;
+export declare const wipeOwnedEd25519KeyMaterial: (material: OwnedEd25519KeyMaterial) => void;

package/lib/cryptography/webCryptoSha256.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared WebCrypto SHA-256, HMAC-SHA-256, and RFC 5869 HKDF-SHA-256.
+ *
+ * Every public function snapshots caller-owned bytes synchronously. Callers may
+ * therefore mutate or transfer their buffers as soon as the function returns
+ * its promise without changing the in-flight operation.
+ */
+/** SHA-256 over a synchronous snapshot of `input`. */
+export declare const sha256: (input: Uint8Array) => Promise<Uint8Array>;
+/** HMAC-SHA-256 over synchronous snapshots of `key` and `message`. */
+export declare const hmacSha256: (key: Uint8Array, message: Uint8Array) => Promise<Uint8Array>;
+/** RFC 5869 HKDF-Extract with SHA-256. */
+export declare const hkdfSha256Extract: (salt: Uint8Array, ikm: Uint8Array) => Promise<Uint8Array>;
+/**
+ * RFC 5869 HKDF-Expand with SHA-256.
+ *
+ * This API requires a standards-conforming PRK of at least 32 bytes and a
+ * nonempty output no longer than RFC 5869's 255-block upper bound.
+ */
+export declare const hkdfSha256Expand: (prk: Uint8Array, info: Uint8Array, length: number) => Promise<Uint8Array>;

package/lib/cryptography/x25519.d.ts

@@ -3,6 +3,18 @@ export interface X25519KeyPair {
     publicKey: Uint8Array;
     secretKey: Uint8Array;
 }
+/**
+ * The peer-supplied u-coordinate produced the prohibited all-zero X25519
+ * shared secret (for example, a low-order point).
+ *
+ * This is distinct from allocation/module failures so protocol receivers can
+ * classify attacker-controlled invalid KEM input as a closed no-match without
+ * hiding cryptographic infrastructure faults.
+ */
+export declare class X25519RejectedPublicPointError extends Error {
+    readonly name = "X25519RejectedPublicPointError";
+    constructor();
+}
 export declare const x25519Keypair: (module: LibCrypto) => X25519KeyPair;
 /**
  * Async, optional-module wrapper over `x25519Keypair`, mirroring `ed25519.newKeyPair`:
@@ -13,3 +25,9 @@ export declare const x25519Keypair: (module: LibCrypto) => X25519KeyPair;
  */
 export declare const newX25519KeyPair: (module?: LibCrypto) => Promise<X25519KeyPair>;
 export declare const x25519Dh: (secretKey: Uint8Array, publicKey: Uint8Array, module: LibCrypto) => Uint8Array;
+/**
+ * Derive an X25519 public key by scalar-multiplying the RFC 7748 u=9 base
+ * point. The canonical base point stays module-owned so callers cannot mutate
+ * protocol input shared by later derivations.
+ */
+export declare const x25519PublicFromSecret: (secretKey: Uint8Array, module: LibCrypto) => Uint8Array;

package/lib/cryptography/xchacha20poly1305.d.ts

@@ -0,0 +1,7 @@
+import type { LibCrypto } from "./libcrypto";
+export declare const XCHACHA20POLY1305_MAX_WASM_BYTES = 2147483647;
+export declare const XCHACHA20POLY1305_MAX_PLAINTEXT_BYTES: number;
+/** Seal to XChaCha20-Poly1305 `ciphertext || 16-byte tag`. */
+export declare const xchacha20Poly1305Seal: (module: LibCrypto, key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, associatedData: Uint8Array) => Uint8Array;
+/** Open `ciphertext || tag`, returning null on authentication failure. */
+export declare const xchacha20Poly1305Open: (module: LibCrypto, key: Uint8Array, nonce: Uint8Array, ciphertextAndTag: Uint8Array, associatedData: Uint8Array) => Uint8Array | null;

package/lib/db/api.d.ts

@@ -1,4 +1,4 @@
-import type { Chunk, ReceiveChunk, NewChunk, NewChunkSelector, SendQueue, RatchetSession, IdentityEd25519, IdentityX25519 } from "./types";
+import type { Chunk, ReceiveChunk, NewChunk, NewChunkSelector, SendQueue, RatchetSession, IdentityDerivation, IdentityEd25519KeyMaterial, IdentityX25519 } from "./types";
 export declare const getDBAddressBookEntry: (peerId?: string, peerPublicKey?: string) => Promise<import("./types").UsernamedPeer | undefined>;
 export declare const getAllDBAddressBookEntries: () => Promise<import("./types").UsernamedPeer[]>;
 export declare const setDBAddressBookEntry: (username: string, peerId: string, peerPublicKey: string) => Promise<undefined>;
@@ -62,6 +62,9 @@ export declare const deletePinAttemptState: (roomId: string, peerIdentityEd25519
 export declare const getIdentityX25519: () => Promise<IdentityX25519 | undefined>;
 export declare const setIdentityX25519: (identity: IdentityX25519) => Promise<undefined>;
 export declare const deleteIdentityX25519: () => Promise<undefined>;
-export declare const getIdentityEd25519: () => Promise<IdentityEd25519 | undefined>;
-export declare const setIdentityEd25519: (identity: IdentityEd25519) => Promise<undefined>;
+export declare const getIdentityEd25519: () => Promise<import("./types").IdentityEd25519 | undefined>;
+export declare const setIdentityEd25519: (identity: IdentityEd25519KeyMaterial) => Promise<bigint>;
 export declare const deleteIdentityEd25519: () => Promise<undefined>;
+export declare const getIdentityDerivation: () => Promise<IdentityDerivation | null>;
+export declare const setIdentityDerivation: (derivation: IdentityDerivation) => Promise<undefined>;
+export declare const deleteIdentityDerivation: () => Promise<undefined>;

package/lib/db/identityEd25519ClientBoundary.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Main-realm ownership boundary for the persisted Ed25519 identity.
+ *
+ * The database worker only wraps bytes and allocates revisions. Seed
+ * derivation stays here so it uses the application's one configured
+ * cryptography/WASM source.
+ */
+import type { IdentityEd25519, IdentityEd25519KeyMaterial } from "./types";
+type IdentityWriter = (identity: IdentityEd25519KeyMaterial, transfer: Transferable[]) => Promise<unknown> | unknown;
+export declare const wipeUnclaimedWorkerSecret: (value: unknown) => void;
+export declare const readIdentityEd25519AtClientBoundary: (read: () => Promise<unknown>) => Promise<IdentityEd25519 | undefined>;
+export declare const writeIdentityEd25519AtClientBoundary: (identity: IdentityEd25519KeyMaterial, write: IdentityWriter) => Promise<bigint>;
+export {};

package/lib/db/src/getDB.d.ts

@@ -1,5 +1,5 @@
 import type { DBSchema, IDBPDatabase } from "idb";
-import type { MessageData, Chunk, SendQueue, AddressBook, BlacklistedPeer, UniqueRoom, NewChunk, RatchetSession, StoredIdentityX25519, StoredIdentityEd25519, PinAttemptState } from "../types";
+import type { MessageData, Chunk, SendQueue, AddressBook, BlacklistedPeer, UniqueRoom, NewChunk, RatchetSession, StoredIdentityX25519, StoredIdentityEd25519, StoredIdentityEd25519Revision, StoredIdentityDerivation, PinAttemptState } from "../types";
 export declare const dbName = "p2party";
 export declare const dbVersion = 19;
 export interface RepoSchema extends DBSchema {
@@ -74,7 +74,7 @@ export interface RepoSchema extends DBSchema {
         };
     };
     meta: {
-        value: CryptoKey | StoredIdentityX25519 | StoredIdentityEd25519 | PinAttemptState;
+        value: CryptoKey | StoredIdentityX25519 | StoredIdentityEd25519 | StoredIdentityEd25519Revision | StoredIdentityDerivation | PinAttemptState;
         key: string;
     };
 }

package/lib/db/types.d.ts

@@ -167,15 +167,48 @@ export interface StoredIdentityX25519 {
     wrappedSecret: ArrayBuffer;
     crossSig: ArrayBuffer;
 }
-/** Ed25519 account identity at the worker API boundary. */
-export interface IdentityEd25519 {
+/** Ed25519 account key material accepted by the worker write boundary. */
+export interface IdentityEd25519KeyMaterial {
     pub: ArrayBuffer;
     secret: ArrayBuffer;
 }
+/** Ed25519 account identity returned by the worker read boundary. */
+export interface IdentityEd25519 extends IdentityEd25519KeyMaterial {
+    /** Persistent, non-reused uint64 revision allocated by IndexedDB. */
+    recordRevision: bigint;
+}
 /** At-rest Ed25519 record (meta key "identityEd25519"). */
 export interface StoredIdentityEd25519 {
+    version: 1;
     pub: ArrayBuffer;
     wrappedSecret: ArrayBuffer;
+    recordRevision: bigint;
+}
+/** Persistent Ed25519 revision high-water/tombstone record in the meta store. */
+export interface StoredIdentityEd25519Revision {
+    version: 1;
+    lastRevision: bigint;
+}
+/**
+ * How the current Ed25519 account identity came into being. "mnemonic" means it
+ * was derived from a recovery phrase and can therefore be reproduced from one;
+ * "random" means it was generated from a random seed and is unrecoverable.
+ * Non-secret: it says nothing about the phrase or the key, only about whether a
+ * backup is possible at all.
+ */
+export type IdentityDerivation = "random" | "mnemonic";
+/** At-rest derivation record (meta key "identityDerivation"). */
+export interface StoredIdentityDerivation {
+    version: 1;
+    derivation: IdentityDerivation;
+    /**
+     * The Ed25519 public key this claim describes, when one was stored at the
+     * time it was recorded. A flag whose binding no longer matches the stored
+     * account key is reported as unknown rather than carried over: claiming
+     * recoverability for a key that was never derived from a phrase would hand
+     * the user a backup that restores someone else's identity.
+     */
+    boundPub: ArrayBuffer | null;
 }
 /** Non-secret online PIN-guess throttle state for one room/peer-identity edge. */
 export interface PinAttemptState {
@@ -410,11 +443,23 @@ export type WorkerMessages = {
 } | {
     id: number;
     method: "setIdentityEd25519";
-    args: [identity: IdentityEd25519];
+    args: [identity: IdentityEd25519KeyMaterial];
 } | {
     id: number;
     method: "deleteIdentityEd25519";
     args: [];
+} | {
+    id: number;
+    method: "getIdentityDerivation";
+    args: [];
+} | {
+    id: number;
+    method: "setIdentityDerivation";
+    args: [derivation: IdentityDerivation];
+} | {
+    id: number;
+    method: "deleteIdentityDerivation";
+    args: [];
 } | {
     id: number;
     method: "deleteDB";
@@ -470,7 +515,10 @@ export interface WorkerMethodReturnTypes {
     setIdentityX25519: undefined;
     deleteIdentityX25519: undefined;
     getIdentityEd25519: IdentityEd25519 | undefined;
-    setIdentityEd25519: undefined;
+    setIdentityEd25519: bigint;
     deleteIdentityEd25519: undefined;
+    getIdentityDerivation: IdentityDerivation | null;
+    setIdentityDerivation: undefined;
+    deleteIdentityDerivation: undefined;
     deleteDB: undefined;
 }