@ciphera-net/tessera 0.1.3

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+export declare class UnsupportedVersionError extends Error {
+    constructor();
+}
+export declare class MalformedEnvelopeError extends Error {
+    constructor();
+}
+export declare class EmptyVaultKeyError extends Error {
+    constructor();
+}
+export declare class EmptyContextError extends Error {
+    constructor();
+}

package/dist/errors.js

@@ -0,0 +1,27 @@
+// Error taxonomy mirroring tessera-go/vault.go. One GENERIC error for wrong-key / wrong-context /
+// tamper / too-short (no decryption oracle — these MUST be indistinguishable), and a DISTINCT error
+// for an unrecognized version byte (forward-compat; the version is not secret).
+export class UnsupportedVersionError extends Error {
+    constructor() {
+        super('tessera: unsupported vault envelope version');
+        this.name = 'UnsupportedVersionError';
+    }
+}
+export class MalformedEnvelopeError extends Error {
+    constructor() {
+        super('tessera: malformed or unauthentic vault envelope');
+        this.name = 'MalformedEnvelopeError';
+    }
+}
+export class EmptyVaultKeyError extends Error {
+    constructor() {
+        super('tessera: empty vault key');
+        this.name = 'EmptyVaultKeyError';
+    }
+}
+export class EmptyContextError extends Error {
+    constructor() {
+        super('tessera: empty record context');
+        this.name = 'EmptyContextError';
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { Tessera, type Session, type RecoverySession } from './tessera.js';
+export { init } from './wasm.js';
+export { blindIndexString } from './blindIndex.js';
+export { newRecoveryPhrase } from './recovery.js';
+export { isPasskeySupported, evaluatePrf, type PrfProvider, type PrfOptions, type PrfCreateOptions, type PrfGetOptions, } from './passkey.js';
+export type { Transport } from './transport.js';
+export type { UnlockMethod } from './vmk.js';
+export { UnsupportedVersionError, MalformedEnvelopeError, EmptyVaultKeyError, EmptyContextError, } from './errors.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+// Public API of @ciphera-net/tessera.
+export { Tessera } from './tessera.js';
+export { init } from './wasm.js';
+export { blindIndexString } from './blindIndex.js';
+export { newRecoveryPhrase } from './recovery.js';
+export { isPasskeySupported, evaluatePrf, } from './passkey.js';
+export { UnsupportedVersionError, MalformedEnvelopeError, EmptyVaultKeyError, EmptyContextError, } from './errors.js';

package/dist/opaque.d.ts

@@ -0,0 +1,16 @@
+import type { Transport } from './transport.js';
+/** Drive OPAQUE registration. Returns the 64-byte export_key (CLIENT-ONLY). The server stores the
+ *  password file (void). */
+export declare function registerOpaque(t: Transport, credentialId: string, password: Uint8Array): Promise<{
+    exportKey: Uint8Array;
+}>;
+/** Drive OPAQUE login. Returns the export_key (CLIENT-ONLY) and the server's session key (base64). */
+export declare function loginOpaque(t: Transport, credentialId: string, password: Uint8Array): Promise<{
+    exportKey: Uint8Array;
+    sessionKeyB64: string;
+}>;
+/** Re-run registration under an EXISTING credentialId to replace the password file (post-recovery
+ *  reset). Returns the new export_key so the caller can re-wrap the (preserved) VMK under it. */
+export declare function resetPasswordOpaque(t: Transport, credentialId: string, newPassword: Uint8Array): Promise<{
+    exportKey: Uint8Array;
+}>;

package/dist/opaque.js

@@ -0,0 +1,69 @@
+// OPAQUE register/login orchestration over a Transport. Pure relay logic: the crypto is in the WASM
+// handles, the wire encoding is base64-STANDARD (NOT the blind-index base64url) end-to-end, and the
+// transport carries blobs to the app's backend (→ tessera-go → sidecar). The 64-byte export_key is
+// CLIENT-ONLY — the caller (tessera.ts) wraps the VMK under it immediately and then zeroes it. The
+// WASM Finish handles are freed once their bytes are consumed (zeroizes the in-WASM key copies).
+import { fromBase64Std, toBase64Std } from './encoding.js';
+import { createRegistrationHandle, createLoginHandle } from './wasm.js';
+/** Drive OPAQUE registration. Returns the 64-byte export_key (CLIENT-ONLY). The server stores the
+ *  password file (void). */
+export async function registerOpaque(t, credentialId, password) {
+    const reg = createRegistrationHandle(password);
+    try {
+        const { responseB64 } = await t.registerStart({ requestB64: toBase64Std(reg.request), credentialId });
+        const fin = reg.finish(password, fromBase64Std(responseB64));
+        try {
+            const uploadB64 = toBase64Std(fin.upload);
+            const exportKey = fin.exportKey; // getter returns a fresh JS copy; caller owns/zeroes it
+            await t.registerFinish({ credentialId, uploadB64 });
+            return { exportKey };
+        }
+        finally {
+            fin.free(); // zeroize the in-WASM export_key copy
+        }
+    }
+    finally {
+        reg.free();
+    }
+}
+/** Drive OPAQUE login. Returns the export_key (CLIENT-ONLY) and the server's session key (base64). */
+export async function loginOpaque(t, credentialId, password) {
+    const lh = createLoginHandle(password);
+    try {
+        const { loginId, responseB64 } = await t.loginStart({ requestB64: toBase64Std(lh.request), credentialId });
+        const lf = lh.finish(password, fromBase64Std(responseB64));
+        try {
+            const finalizationB64 = toBase64Std(lf.finalization);
+            const exportKey = lf.exportKey;
+            const { sessionKeyB64 } = await t.loginFinish({ loginId, finalizationB64 });
+            return { exportKey, sessionKeyB64 };
+        }
+        finally {
+            lf.free(); // zeroize the in-WASM export_key + session_key copies
+        }
+    }
+    finally {
+        lh.free();
+    }
+}
+/** Re-run registration under an EXISTING credentialId to replace the password file (post-recovery
+ *  reset). Returns the new export_key so the caller can re-wrap the (preserved) VMK under it. */
+export async function resetPasswordOpaque(t, credentialId, newPassword) {
+    const reg = createRegistrationHandle(newPassword);
+    try {
+        const { responseB64 } = await t.registerStart({ requestB64: toBase64Std(reg.request), credentialId });
+        const fin = reg.finish(newPassword, fromBase64Std(responseB64));
+        try {
+            const uploadB64 = toBase64Std(fin.upload);
+            const exportKey = fin.exportKey;
+            await t.replacePasswordFile({ credentialId, uploadB64 });
+            return { exportKey };
+        }
+        finally {
+            fin.free();
+        }
+    }
+    finally {
+        reg.free();
+    }
+}

package/dist/passkey.d.ts

@@ -0,0 +1,30 @@
+/** Supplies the 32-byte WebAuthn-PRF output. The caller runs the ceremony (e.g. via `evaluatePrf`)
+ *  with its own RP/challenge/credential context. Returns exactly the bytes used to wrap the VMK.
+ *  CONTRACT: the SDK ZEROES the returned buffer after use — return a fresh buffer per call; do not
+ *  reuse or share it. */
+export type PrfProvider = () => Promise<Uint8Array>;
+export interface PrfCreateOptions {
+    create: true;
+    rpId: string;
+    rpName: string;
+    userId: Uint8Array;
+    userName: string;
+    userDisplayName?: string;
+    challenge: Uint8Array;
+}
+export interface PrfGetOptions {
+    create: false;
+    rpId: string;
+    challenge: Uint8Array;
+    allowCredentialIds?: Uint8Array[];
+}
+export type PrfOptions = PrfCreateOptions | PrfGetOptions;
+/** Best-effort, NO-user-gesture support probe. Definitive PRF support is only known after a real
+ *  get()/create() returns prf results; this is a conservative gate so the UI can OFFER the option.
+ *  Never throws (returns false on any failure / when WebAuthn is absent). */
+export declare function isPasskeySupported(): Promise<boolean>;
+/** Run a WebAuthn ceremony with the PRF extension and return the 32-byte first output. `create`
+ *  registers a new credential (enable); otherwise asserts an existing one (unlock). Throws if the
+ *  chosen authenticator does not return a PRF result (additive feature — caller surfaces it).
+ *  Browser-only; exercised in the Playwright (virtual-authenticator) matrix, not the Node unit tests. */
+export declare function evaluatePrf(opts: PrfOptions): Promise<Uint8Array>;

package/dist/passkey.js

@@ -0,0 +1,75 @@
+// WebAuthn-PRF passwordless unlock (ADDITIVE — password (OPAQUE) and the recovery phrase are the
+// always-available paths; an authenticator without PRF simply cannot enable this, surfaced via
+// isPasskeySupported(), never a silent failure).
+//
+// SEPARATION OF CONCERNS: a WebAuthn ceremony needs app/server context (rpId, challenge, the user's
+// credential ids) that this SDK does not own. So the SDK's enable/unlock take a `PrfProvider` — the
+// CALLER runs the ceremony (typically via `evaluatePrf` below) and hands back the 32-byte PRF output;
+// the SDK wraps/unwraps the VMK under it. The PRF eval salt is the ONE ceremony input the SDK pins
+// (it must match between enable and unlock or the derived secret differs).
+import { wcView } from './encoding.js';
+/** Fixed PRF eval input — pinned so the PRF output is stable across enable/unlock. */
+const PRF_SALT = new TextEncoder().encode('tessera/prf/v1');
+/** Best-effort, NO-user-gesture support probe. Definitive PRF support is only known after a real
+ *  get()/create() returns prf results; this is a conservative gate so the UI can OFFER the option.
+ *  Never throws (returns false on any failure / when WebAuthn is absent). */
+export async function isPasskeySupported() {
+    if (!('PublicKeyCredential' in globalThis))
+        return false;
+    try {
+        return await PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable();
+    }
+    catch {
+        return false;
+    }
+}
+/** Run a WebAuthn ceremony with the PRF extension and return the 32-byte first output. `create`
+ *  registers a new credential (enable); otherwise asserts an existing one (unlock). Throws if the
+ *  chosen authenticator does not return a PRF result (additive feature — caller surfaces it).
+ *  Browser-only; exercised in the Playwright (virtual-authenticator) matrix, not the Node unit tests. */
+export async function evaluatePrf(opts) {
+    // The PRF extension types are not in every TS lib.dom; cast the extensions object at the boundary.
+    // PRF_SALT is already a Uint8Array (a valid BufferSource), so no wcView wrap is needed here.
+    const extensions = { prf: { eval: { first: PRF_SALT } } };
+    let cred;
+    if (opts.create) {
+        cred = (await navigator.credentials.create({
+            publicKey: {
+                challenge: wcView(opts.challenge),
+                rp: { id: opts.rpId, name: opts.rpName },
+                user: {
+                    id: wcView(opts.userId),
+                    name: opts.userName,
+                    displayName: opts.userDisplayName ?? opts.userName,
+                },
+                pubKeyCredParams: [
+                    { type: 'public-key', alg: -7 }, // ES256
+                    { type: 'public-key', alg: -257 }, // RS256
+                ],
+                authenticatorSelection: { userVerification: 'required', residentKey: 'required' },
+                extensions,
+            },
+        }));
+    }
+    else {
+        cred = (await navigator.credentials.get({
+            publicKey: {
+                challenge: wcView(opts.challenge),
+                rpId: opts.rpId,
+                allowCredentials: (opts.allowCredentialIds ?? []).map((id) => ({
+                    type: 'public-key',
+                    id: wcView(id),
+                })),
+                userVerification: 'required',
+                extensions,
+            },
+        }));
+    }
+    if (!cred)
+        throw new Error('tessera: WebAuthn ceremony returned no credential');
+    const first = cred.getClientExtensionResults().prf?.results?.first;
+    if (!first) {
+        throw new Error('tessera: authenticator did not return a PRF result (PRF unsupported by this authenticator)');
+    }
+    return first instanceof ArrayBuffer ? new Uint8Array(first) : new Uint8Array(first.buffer, first.byteOffset, first.byteLength);
+}

package/dist/recovery.d.ts

@@ -0,0 +1,7 @@
+/** A fresh 24-word (256-bit) recovery phrase. Show to the user ONCE; never persist it. NOTE: the
+ *  returned string is immutable (JS strings cannot be zeroed) — minimise its lifetime; the SDK
+ *  derives the entropy from it and zeroes THAT, but the phrase string itself cannot be wiped. */
+export declare function newRecoveryPhrase(): string;
+/** The 'recovery' VMK-wrap secret = the 32-byte BIP-39 entropy. Throws on an invalid-checksum phrase.
+ *  CALLER must zero the returned buffer after wrapping/unwrapping. */
+export declare function recoverySecret(phrase: string): Uint8Array;

package/dist/recovery.js

@@ -0,0 +1,19 @@
+// BIP-39 (24-word / 256-bit) recovery. The recovery WRAP secret is the mnemonic ENTROPY (already
+// 256 bits of high entropy) — NOT the PBKDF2 seed: there is no passphrase, the entropy is the secret,
+// and using it directly avoids a redundant 2048-round PBKDF2. The phrase is shown to the user ONCE at
+// registration; losing it means losing the recovery path (the password path remains).
+import { generateMnemonic, mnemonicToEntropy, validateMnemonic } from '@scure/bip39';
+import { wordlist } from '@scure/bip39/wordlists/english';
+/** A fresh 24-word (256-bit) recovery phrase. Show to the user ONCE; never persist it. NOTE: the
+ *  returned string is immutable (JS strings cannot be zeroed) — minimise its lifetime; the SDK
+ *  derives the entropy from it and zeroes THAT, but the phrase string itself cannot be wiped. */
+export function newRecoveryPhrase() {
+    return generateMnemonic(wordlist, 256);
+}
+/** The 'recovery' VMK-wrap secret = the 32-byte BIP-39 entropy. Throws on an invalid-checksum phrase.
+ *  CALLER must zero the returned buffer after wrapping/unwrapping. */
+export function recoverySecret(phrase) {
+    if (!validateMnemonic(phrase, wordlist))
+        throw new Error('tessera: invalid recovery phrase');
+    return mnemonicToEntropy(phrase, wordlist); // 32 bytes
+}

package/dist/tessera.d.ts

@@ -0,0 +1,109 @@
+import type { PrfProvider } from './passkey.js';
+import { type VaultKey } from './vault.js';
+import type { Transport } from './transport.js';
+export interface Session {
+    sessionKeyB64: string | null;
+    vault: {
+        seal(context: string, plaintext: Uint8Array): Promise<Uint8Array>;
+        open(context: string, envelope: Uint8Array): Promise<Uint8Array>;
+    };
+}
+export interface RecoverySession extends Session {
+    /** Re-key auth to a new password. Preserves the vault (the SAME VMK is re-wrapped under the new
+     *  export_key — the vault content is never re-encrypted). Single-use: the recovery secret is zeroed
+     *  after, so a second call will fail. */
+    resetPassword(newPassword: Uint8Array): Promise<void>;
+    /** Zero the in-memory recovery secret when finished WITHOUT calling resetPassword. The recovery
+     *  secret is retained in this session because the non-extractable VMK cannot itself be re-wrapped, so
+     *  resetPassword needs it; if you do not call resetPassword, call dispose() to wipe it. After dispose()
+     *  (or resetPassword) the secret is zeroed, and a subsequent resetPassword would fail. */
+    dispose(): void;
+}
+declare function sessionFor(vmk: VaultKey, sessionKeyB64: string | null): Session;
+export declare class Tessera {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** Register: enroll OPAQUE, mint a VMK, wrap it under the password (export_key) and a fresh recovery
+     *  phrase, store both wraps. Returns the recovery phrase to show the user ONCE. */
+    register({ email, password, }: {
+        email: string;
+        password: Uint8Array;
+    }): Promise<{
+        recoveryPhrase: string;
+        session: Session;
+    }>;
+    /** Migration-only enrolment for an existing SRP account. Same crypto as register(), with two
+     *  deliberate differences that make a forced SRP→OPAQUE upgrade safe:
+     *   (1) VERIFY-BEFORE-ZERO — it PROVES both the opaque and recovery wraps round-trip while export_key
+     *       and the recovery entropy are STILL LIVE. register() zeroes those secrets in its finally before
+     *       returning, which makes any post-hoc wrap verification impossible; here the openVaultKey checks
+     *       run inside the try, so a bad wrap throws (AES-GCM tag failure) and NOTHING is returned.
+     *   (2) NO putWraps — the caller submits the wraps itself, atomically, to /auth/migrate/opaque (so the
+     *       auth_version flip and the wrap writes commit in one DB transaction). The wraps are returned as
+     *       base64 for that POST. */
+    registerForMigration({ email, password, }: {
+        email: string;
+        password: Uint8Array;
+    }): Promise<{
+        recoveryPhrase: string;
+        session: Session;
+        wraps: {
+            opaque: string;
+            recovery: string;
+        };
+    }>;
+    /** Login: OPAQUE → export_key → unwrap the VMK (non-extractable) → Session with vault ops. */
+    login({ email, password }: {
+        email: string;
+        password: Uint8Array;
+    }): Promise<Session>;
+    /** Recover via the BIP-39 phrase: unwrap the VMK from the 'recovery' wrap → a Session (no OPAQUE
+     *  session key) plus a single-use `resetPassword`. The recovery secret + wrap blob are held in the
+     *  returned closure ONLY because the session VMK is non-extractable and cannot itself be re-wrapped;
+     *  resetPassword re-derives the raw VMK from the recovery wrap and re-wraps it under the new password,
+     *  so the vault is never re-encrypted. The recovery secret is zeroed once resetPassword runs — or, if
+     *  the caller never calls resetPassword, once dispose() is called. If NEITHER is called, the 32-byte
+     *  recovery secret persists in this session for its lifetime; discard the session promptly. */
+    recoverWithPhrase({ email, phrase, }: {
+        email: string;
+        phrase: string;
+    }): Promise<RecoverySession>;
+    /** Enable passwordless unlock (ADDITIVE). RE-AUTHENTICATES with the password (a non-extractable
+     *  session VMK cannot be re-wrapped), then re-wraps the VMK from the 'opaque' wrap into a 'webauthn'
+     *  wrap keyed by the PRF output. `prf` runs the WebAuthn create() ceremony (see passkey.evaluatePrf).
+     *  Both the export_key and the PRF output are zeroed after use. */
+    enablePasskey({ email, password, prf, }: {
+        email: string;
+        password: Uint8Array;
+        prf: PrfProvider;
+    }): Promise<void>;
+    /** Passwordless unlock via the 'webauthn' wrap. `prf` runs the WebAuthn get() ceremony. No OPAQUE
+     *  handshake on this path, so the Session's sessionKeyB64 is null. The PRF output is zeroed after. */
+    unlockWithPasskey({ email, prf }: {
+        email: string;
+        prf: PrfProvider;
+    }): Promise<Session>;
+    /** Change the password from a logged-in context. Re-authenticates with the OLD
+     *  password, runs a fresh OPAQUE registration under the NEW password, and re-wraps
+     *  the SAME VMK from the 'opaque' wrap into a new 'opaque' wrap under the new
+     *  export_key. The vault is NEVER re-encrypted, and the recovery + passkey wraps
+     *  (which wrap the same VMK) stay valid. Both export_keys are zeroed after use. */
+    changePassword({ email, oldPassword, newPassword, }: {
+        email: string;
+        oldPassword: Uint8Array;
+        newPassword: Uint8Array;
+    }): Promise<void>;
+    /** Rotate the recovery phrase from a logged-in context. Re-authenticates with the
+     *  password, mints a fresh 24-word phrase, and re-wraps the SAME VMK from the
+     *  'opaque' wrap into a new 'recovery' wrap under the new phrase's secret. The vault
+     *  is never re-encrypted, and the OLD phrase's wrap is overwritten. Returns the new
+     *  phrase to show ONCE. export_key and recovery entropy are zeroed after use. */
+    regenerateRecovery({ email, password, }: {
+        email: string;
+        password: Uint8Array;
+    }): Promise<{
+        recoveryPhrase: string;
+    }>;
+}
+/** @internal Exposed for the recovery/passkey methods added in later tasks (not re-exported from index). */
+export { sessionFor };

package/dist/tessera.js

@@ -0,0 +1,228 @@
+// High-level Tessera SDK. Orchestrates blind index → OPAQUE → VMK → vault, transport-agnostic. The
+// 64-byte OPAQUE export_key and the 32-byte recovery entropy are used ONLY to wrap the VMK, then zeroed
+// — they never persist and never cross the wire. The VMK is held as a non-extractable CryptoKey inside
+// the returned Session; the raw VMK never leaves WASM/JS linear memory at rest.
+import { blindIndexString } from './blindIndex.js';
+import { loginOpaque, registerOpaque, resetPasswordOpaque } from './opaque.js';
+import { generateAndWrap, openVaultKey, rewrapForMethod } from './vmk.js';
+import { newRecoveryPhrase, recoverySecret } from './recovery.js';
+import { open as vaultOpen, seal as vaultSeal } from './vault.js';
+import { fromBase64Std, toBase64Std } from './encoding.js';
+// VMK-wrap blobs are stored as standard base64 (they are opaque server storage, not OPAQUE wire blobs).
+const b64 = toBase64Std;
+const fromB64 = fromBase64Std;
+function sessionFor(vmk, sessionKeyB64) {
+    return {
+        sessionKeyB64,
+        vault: {
+            seal: (context, plaintext) => vaultSeal(vmk, context, plaintext),
+            open: (context, envelope) => vaultOpen(vmk, context, envelope),
+        },
+    };
+}
+export class Tessera {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /** Register: enroll OPAQUE, mint a VMK, wrap it under the password (export_key) and a fresh recovery
+     *  phrase, store both wraps. Returns the recovery phrase to show the user ONCE. */
+    async register({ email, password, }) {
+        const credentialId = blindIndexString(email);
+        const { exportKey } = await registerOpaque(this.transport, credentialId, password);
+        // Open the try IMMEDIATELY so exportKey is zeroed on ANY subsequent throw. recovEntropy is
+        // nullable (derived inside) and zeroed only if it was created — no sentinel.
+        let recovEntropy;
+        try {
+            const recoveryPhrase = newRecoveryPhrase();
+            recovEntropy = recoverySecret(recoveryPhrase);
+            // The WHOLE 64-byte export_key is the 'opaque' wrap secret — do NOT slice it.
+            const { vmk, wraps } = await generateAndWrap({ opaque: exportKey, recovery: recovEntropy });
+            await this.transport.putWraps({
+                credentialId,
+                wraps: { opaque: b64(wraps.opaque), recovery: b64(wraps.recovery) },
+            });
+            return { recoveryPhrase, session: sessionFor(vmk, null) };
+        }
+        finally {
+            exportKey.fill(0);
+            recovEntropy?.fill(0);
+        }
+    }
+    /** Migration-only enrolment for an existing SRP account. Same crypto as register(), with two
+     *  deliberate differences that make a forced SRP→OPAQUE upgrade safe:
+     *   (1) VERIFY-BEFORE-ZERO — it PROVES both the opaque and recovery wraps round-trip while export_key
+     *       and the recovery entropy are STILL LIVE. register() zeroes those secrets in its finally before
+     *       returning, which makes any post-hoc wrap verification impossible; here the openVaultKey checks
+     *       run inside the try, so a bad wrap throws (AES-GCM tag failure) and NOTHING is returned.
+     *   (2) NO putWraps — the caller submits the wraps itself, atomically, to /auth/migrate/opaque (so the
+     *       auth_version flip and the wrap writes commit in one DB transaction). The wraps are returned as
+     *       base64 for that POST. */
+    async registerForMigration({ email, password, }) {
+        const credentialId = blindIndexString(email);
+        const { exportKey } = await registerOpaque(this.transport, credentialId, password);
+        let recovEntropy;
+        try {
+            const recoveryPhrase = newRecoveryPhrase();
+            recovEntropy = recoverySecret(recoveryPhrase);
+            // The WHOLE 64-byte export_key is the 'opaque' wrap secret — do NOT slice it.
+            const { vmk, wraps } = await generateAndWrap({ opaque: exportKey, recovery: recovEntropy });
+            // RECOVERABILITY PROOF — both wraps must decrypt to the real VMK BEFORE the finally zeroes the
+            // secrets. A garbled/empty wrap makes openVaultKey throw, aborting the migration with no writes.
+            await openVaultKey(wraps.opaque, exportKey, 'opaque');
+            await openVaultKey(wraps.recovery, recovEntropy, 'recovery');
+            return {
+                recoveryPhrase,
+                session: sessionFor(vmk, null),
+                wraps: { opaque: b64(wraps.opaque), recovery: b64(wraps.recovery) },
+            };
+        }
+        finally {
+            exportKey.fill(0);
+            recovEntropy?.fill(0);
+        }
+    }
+    /** Login: OPAQUE → export_key → unwrap the VMK (non-extractable) → Session with vault ops. */
+    async login({ email, password }) {
+        const credentialId = blindIndexString(email);
+        const { exportKey, sessionKeyB64 } = await loginOpaque(this.transport, credentialId, password);
+        try {
+            const wrap = await this.transport.getWrap({ credentialId, method: 'opaque' });
+            if (!wrap)
+                throw new Error('tessera: no opaque VMK wrap for this account');
+            const vmk = await openVaultKey(fromB64(wrap.blobB64), exportKey, 'opaque');
+            return sessionFor(vmk, sessionKeyB64);
+        }
+        finally {
+            exportKey.fill(0);
+        }
+    }
+    /** Recover via the BIP-39 phrase: unwrap the VMK from the 'recovery' wrap → a Session (no OPAQUE
+     *  session key) plus a single-use `resetPassword`. The recovery secret + wrap blob are held in the
+     *  returned closure ONLY because the session VMK is non-extractable and cannot itself be re-wrapped;
+     *  resetPassword re-derives the raw VMK from the recovery wrap and re-wraps it under the new password,
+     *  so the vault is never re-encrypted. The recovery secret is zeroed once resetPassword runs — or, if
+     *  the caller never calls resetPassword, once dispose() is called. If NEITHER is called, the 32-byte
+     *  recovery secret persists in this session for its lifetime; discard the session promptly. */
+    async recoverWithPhrase({ email, phrase, }) {
+        const credentialId = blindIndexString(email);
+        const recovSecret = recoverySecret(phrase); // throws on bad checksum
+        const recoveryWrap = await this.transport.getWrap({ credentialId, method: 'recovery' });
+        if (!recoveryWrap)
+            throw new Error('tessera: no recovery wrap for this account');
+        const recoveryBlob = fromB64(recoveryWrap.blobB64);
+        const vmk = await openVaultKey(recoveryBlob, recovSecret, 'recovery'); // throws if phrase is wrong
+        const transport = this.transport;
+        return {
+            ...sessionFor(vmk, /* no OPAQUE session on the recovery path */ null),
+            async resetPassword(newPassword) {
+                const { exportKey } = await resetPasswordOpaque(transport, credentialId, newPassword);
+                try {
+                    // Re-wrap the SAME VMK (re-derived from the recovery wrap) under the new export_key.
+                    const newOpaqueWrap = await rewrapForMethod({ blob: recoveryBlob, secret: recovSecret, method: 'recovery' }, { secret: exportKey, method: 'opaque' });
+                    await transport.putWraps({ credentialId, wraps: { opaque: b64(newOpaqueWrap) } });
+                }
+                finally {
+                    exportKey.fill(0);
+                    recovSecret.fill(0);
+                }
+            },
+            dispose() {
+                // Zero the recovery secret when finished WITHOUT re-keying. Idempotent with the resetPassword
+                // wipe; after this, resetPassword would fail (a zeroed secret cannot unwrap the recovery blob).
+                recovSecret.fill(0);
+            },
+        };
+    }
+    /** Enable passwordless unlock (ADDITIVE). RE-AUTHENTICATES with the password (a non-extractable
+     *  session VMK cannot be re-wrapped), then re-wraps the VMK from the 'opaque' wrap into a 'webauthn'
+     *  wrap keyed by the PRF output. `prf` runs the WebAuthn create() ceremony (see passkey.evaluatePrf).
+     *  Both the export_key and the PRF output are zeroed after use. */
+    async enablePasskey({ email, password, prf, }) {
+        const credentialId = blindIndexString(email);
+        const { exportKey } = await loginOpaque(this.transport, credentialId, password); // re-auth
+        try {
+            const prfOutput = await prf();
+            try {
+                const opaqueWrap = await this.transport.getWrap({ credentialId, method: 'opaque' });
+                if (!opaqueWrap)
+                    throw new Error('tessera: no opaque wrap for this account');
+                const webauthnWrap = await rewrapForMethod({ blob: fromB64(opaqueWrap.blobB64), secret: exportKey, method: 'opaque' }, { secret: prfOutput, method: 'webauthn' });
+                await this.transport.putWraps({ credentialId, wraps: { webauthn: b64(webauthnWrap) } });
+            }
+            finally {
+                prfOutput.fill(0);
+            }
+        }
+        finally {
+            exportKey.fill(0);
+        }
+    }
+    /** Passwordless unlock via the 'webauthn' wrap. `prf` runs the WebAuthn get() ceremony. No OPAQUE
+     *  handshake on this path, so the Session's sessionKeyB64 is null. The PRF output is zeroed after. */
+    async unlockWithPasskey({ email, prf }) {
+        const credentialId = blindIndexString(email);
+        const prfOutput = await prf();
+        try {
+            const wrap = await this.transport.getWrap({ credentialId, method: 'webauthn' });
+            if (!wrap)
+                throw new Error('tessera: no passkey wrap for this account');
+            const vmk = await openVaultKey(fromB64(wrap.blobB64), prfOutput, 'webauthn');
+            return sessionFor(vmk, null); // no OPAQUE session on the passkey path
+        }
+        finally {
+            prfOutput.fill(0);
+        }
+    }
+    /** Change the password from a logged-in context. Re-authenticates with the OLD
+     *  password, runs a fresh OPAQUE registration under the NEW password, and re-wraps
+     *  the SAME VMK from the 'opaque' wrap into a new 'opaque' wrap under the new
+     *  export_key. The vault is NEVER re-encrypted, and the recovery + passkey wraps
+     *  (which wrap the same VMK) stay valid. Both export_keys are zeroed after use. */
+    async changePassword({ email, oldPassword, newPassword, }) {
+        const credentialId = blindIndexString(email);
+        const { exportKey: oldExport } = await loginOpaque(this.transport, credentialId, oldPassword); // re-auth
+        try {
+            const opaqueWrap = await this.transport.getWrap({ credentialId, method: 'opaque' });
+            if (!opaqueWrap)
+                throw new Error('tessera: no opaque wrap for this account');
+            const { exportKey: newExport } = await resetPasswordOpaque(this.transport, credentialId, newPassword);
+            try {
+                const newOpaqueWrap = await rewrapForMethod({ blob: fromB64(opaqueWrap.blobB64), secret: oldExport, method: 'opaque' }, { secret: newExport, method: 'opaque' });
+                await this.transport.putWraps({ credentialId, wraps: { opaque: b64(newOpaqueWrap) } });
+            }
+            finally {
+                newExport.fill(0);
+            }
+        }
+        finally {
+            oldExport.fill(0);
+        }
+    }
+    /** Rotate the recovery phrase from a logged-in context. Re-authenticates with the
+     *  password, mints a fresh 24-word phrase, and re-wraps the SAME VMK from the
+     *  'opaque' wrap into a new 'recovery' wrap under the new phrase's secret. The vault
+     *  is never re-encrypted, and the OLD phrase's wrap is overwritten. Returns the new
+     *  phrase to show ONCE. export_key and recovery entropy are zeroed after use. */
+    async regenerateRecovery({ email, password, }) {
+        const credentialId = blindIndexString(email);
+        const { exportKey } = await loginOpaque(this.transport, credentialId, password);
+        let recovEntropy;
+        try {
+            const opaqueWrap = await this.transport.getWrap({ credentialId, method: 'opaque' });
+            if (!opaqueWrap)
+                throw new Error('tessera: no opaque wrap for this account');
+            const recoveryPhrase = newRecoveryPhrase();
+            recovEntropy = recoverySecret(recoveryPhrase);
+            const newRecoveryWrap = await rewrapForMethod({ blob: fromB64(opaqueWrap.blobB64), secret: exportKey, method: 'opaque' }, { secret: recovEntropy, method: 'recovery' });
+            await this.transport.putWraps({ credentialId, wraps: { recovery: b64(newRecoveryWrap) } });
+            return { recoveryPhrase };
+        }
+        finally {
+            exportKey.fill(0);
+            recovEntropy?.fill(0);
+        }
+    }
+}
+/** @internal Exposed for the recovery/passkey methods added in later tasks (not re-exported from index). */
+export { sessionFor };

package/dist/transport.d.ts

@@ -0,0 +1,39 @@
+export interface Transport {
+    registerStart(req: {
+        requestB64: string;
+        credentialId: string;
+    }): Promise<{
+        responseB64: string;
+    }>;
+    registerFinish(req: {
+        credentialId: string;
+        uploadB64: string;
+    }): Promise<void>;
+    loginStart(req: {
+        requestB64: string;
+        credentialId: string;
+    }): Promise<{
+        loginId: string;
+        responseB64: string;
+    }>;
+    loginFinish(req: {
+        loginId: string;
+        finalizationB64: string;
+    }): Promise<{
+        sessionKeyB64: string;
+    }>;
+    replacePasswordFile(req: {
+        credentialId: string;
+        uploadB64: string;
+    }): Promise<void>;
+    putWraps(req: {
+        credentialId: string;
+        wraps: Record<string, string>;
+    }): Promise<void>;
+    getWrap(req: {
+        credentialId: string;
+        method: string;
+    }): Promise<{
+        blobB64: string;
+    } | null>;
+}