@ciphera-net/tessera 0.1.4 → 0.2.1

package/README.md

@@ -93,8 +93,8 @@ const transport: Transport = {
     return res.json(); // { sessionKeyB64: string }
   },
 
-  // Recovery password reset — replaces the server-side password file after the OPAQUE re-enrollment
-  // driven by recoverWithPhrase().resetPassword(). Vault content is untouched.
+  // Password reset outside recovery. The RECOVERY-driven reset goes through
+  // recoveryResetPassword() instead, which is authorised by a reset token and carries both wraps.
   async replacePasswordFile({ credentialId, uploadB64 }) {
     await fetch('/auth/reset-password', {
       method: 'POST',
@@ -159,21 +159,51 @@ const plaintext = await session.vault.open('address', envelope);
 
 ### 5. Recovery
 
+Recovery runs a real OPAQUE ceremony against a **second identity** on the account, authenticated by
+the phrase. The server verifies the phrase, can throttle guessing, and releases the vault and the
+recovery wrap only afterwards.
+
+**Enrol (or rotate) the recovery identity.** Needs the password — the VMK is non-extractable from a
+session and has to be re-derived — and a fresh re-auth proof, because this installs a permanent
+second way into the account.
+
 ```ts
-const rec = await t.recoverWithPhrase({
+const { recoveryPhrase } = await t.enrolRecoveryIdentity({
   email: 'alice@example.com',
-  phrase: 'word1 word2 ... word24', // the 24-word BIP-39 phrase from registration
+  password: new TextEncoder().encode('password'),
+  reauthToken,            // purpose "enr", single-use
 });
+// Show recoveryPhrase ONCE. It cannot be recovered from the server, which is the point.
+```
 
-// rec is a RecoverySession — a Session extended with resetPassword.
-// rec.sessionKeyB64 is null (no OPAQUE handshake on this path).
-// Vault is fully accessible while the session is alive.
+**Recover with the phrase.**
+
+```ts
+const rec = await t.recoverWithRecoveryIdentity({
+  email: 'alice@example.com',
+  phrase: 'word1 word2 ... word24',
+});
+
+// rec.sessionKeyB64 is null — recovery proves the phrase, it is not a login.
+// rec.resetToken is the server's single-use evidence that the ceremony succeeded.
+// The vault is fully accessible while the session is alive.
 
-// Optionally reset the password (re-keys auth; vault content is never re-encrypted).
 await rec.resetPassword(new TextEncoder().encode('new password'));
-// After resetPassword, the recovery secret is zeroed; calling resetPassword again will fail.
+// Re-keys auth only; vault content is never re-encrypted. The recovery identity keeps working.
+// If you do NOT reset, call rec.dispose() to zero the retained recovery secret.
 ```
 
+> #### 🔴 Removed in 0.2.0
+>
+> **`recoverWithPhrase`** derived the recovery secret locally and unwrapped the VMK in the browser.
+> The server never saw the phrase, so it could not verify it, could not rate-limit guessing, and had
+> to hand the recovery wrap to whoever asked. Replaced by `recoverWithRecoveryIdentity`.
+>
+> **`regenerateRecovery`** rotated the phrase by writing the new wrap and nothing else, leaving the
+> recovery record on the OLD phrase — the old phrase then passed the ceremony and could not decrypt,
+> the new phrase failed it, and recovery was dead with no error at rotation time. Rotation now goes
+> through `enrolRecoveryIdentity`, which writes the record and the wrap in one server-side statement.
+
 ### 6. Passkey (WebAuthn-PRF)
 
 ```ts
@@ -267,6 +297,45 @@ An envelope sealed under `"address"` cannot be opened under `"totp"` — wrong-c
 
 For wrong-key, wrong-context, and GCM tag failure, `open` throws a generic `Error` — there is no specific class that reveals which check failed (no decryption oracle).
 
+### OPAQUE ceremony errors
+
+The register/login ceremonies raise two further classes. Both carry a fixed
+`tessera:`-prefixed message, so nothing from inside the WASM core can reach a UI.
+
+| Class | When |
+|---|---|
+| `InvalidCredentialsError` | the password (or recovery phrase) did not open the OPAQUE envelope — i.e. it is wrong |
+| `OpaqueProtocolError` | the ceremony failed for any other reason: malformed or tampered server response, serialization fault, internal library error. `cause` carries the original |
+
+🔑 **The server cannot tell a right password from a wrong one.** In OPAQUE only
+the client can, at `login_finish`, when the envelope fails to open — so
+`InvalidCredentialsError` is the canonical wrong-password signal for the whole
+system, not any HTTP status.
+
+⚠️ **Distinguishing these two is deliberate, and folding them together is a
+bug.** Reporting a broken ceremony as "wrong password" sends a user to reset a
+password that was already correct, and hides a real fault behind the one message
+nobody investigates. Unlike the vault-envelope errors above — which are kept
+indistinguishable because telling them apart would be a decryption oracle — the
+login outcome is safe to report: it describes a password the caller just typed.
+
+```ts
+import { InvalidCredentialsError, OpaqueProtocolError } from '@ciphera-net/tessera'
+
+try {
+  await tessera.login({ email, password })
+} catch (e) {
+  if (e instanceof InvalidCredentialsError) setError('Incorrect email or password.')
+  else if (e instanceof OpaqueProtocolError) setError('Sign-in is temporarily unavailable.')
+  else throw e
+}
+```
+
+Before 0.2.1 these were not wrapped at all: the Rust core raises
+`JsError::new(&format!("{e:?}"))`, so a wrong password surfaced as an `Error`
+whose message was literally `Opaque(InvalidLoginError)` — and consumers rendered
+that string to users.
+
 ---
 
 ## Crypto parameters (pinned)
@@ -337,7 +406,7 @@ AAD = [0x01] ‖ utf8(context)
 ### What the SDK does
 
 - The vault master key (VMK) is held as a **non-extractable `CryptoKey`** inside the `Session` object. `extractable: false` prevents `crypto.subtle.exportKey` from returning the raw bytes.
-- The OPAQUE `export_key` (64 bytes) and the recovery entropy (32 bytes) transit WASM/JS linear memory transiently during unlock. On the register / login / passkey paths they are zeroed in `finally` blocks immediately after the VMK is wrapped or unwrapped. **Exception:** `recoverWithPhrase` retains the 32-byte recovery secret inside the returned `RecoverySession` — the non-extractable VMK cannot itself be re-wrapped, so `resetPassword` needs it. That secret is zeroed by `resetPassword` **or** by `RecoverySession.dispose()`; if you call neither, it persists for the session's lifetime (discard the session promptly). None of these values ever cross the network.
+- The OPAQUE `export_key` (64 bytes) and the recovery entropy (32 bytes) transit WASM/JS linear memory transiently during unlock. On the register / login / passkey paths they are zeroed in `finally` blocks immediately after the VMK is wrapped or unwrapped. **Exception:** `recoverWithRecoveryIdentity` retains the 32-byte recovery entropy inside the returned session — the non-extractable VMK cannot itself be re-wrapped, so `resetPassword` needs it. That secret is zeroed by `resetPassword` **or** by `dispose()`; if you call neither, it persists for the session's lifetime (discard the session promptly). The phrase's aPAKE password and the ceremony's `export_key` are both zeroed before the call returns. None of these values ever cross the network.
 - VMK-wrap blobs stored server-side are opaque byte sequences. The server holds no plaintext passwords and no vault keys.
 
 ### What the SDK cannot guarantee

package/dist/errors.d.ts

@@ -10,3 +10,37 @@ export declare class EmptyVaultKeyError extends Error {
 export declare class EmptyContextError extends Error {
     constructor();
 }
+/**
+ * The password did not open the OPAQUE envelope — i.e. wrong password (or wrong
+ * account for this password file).
+ *
+ * 🔑 In OPAQUE the SERVER cannot tell a right password from a wrong one; only
+ * the client can, at `login_finish`, when the envelope fails to open. So this is
+ * the canonical wrong-password signal for the whole system, and it is raised
+ * here rather than by any HTTP status.
+ *
+ * ⚠️ Unlike the vault-envelope errors above — which are deliberately
+ * indistinguishable because telling them apart would be a decryption oracle —
+ * this one is safe to distinguish. It reports the outcome of a password the
+ * caller just supplied; it tells an attacker nothing they did not already know
+ * by typing it.
+ */
+export declare class InvalidCredentialsError extends Error {
+    constructor();
+}
+/**
+ * The OPAQUE ceremony failed for a reason that is NOT a wrong password —
+ * a malformed or tampered server response, a serialization fault, or an
+ * internal library error.
+ *
+ * 🔴 This is deliberately NOT folded into `InvalidCredentialsError`. Reporting a
+ * broken ceremony as "wrong password" would send a user to reset a password that
+ * was already correct and would hide a real fault behind the one message nobody
+ * investigates. A wrong password is expected; this is not.
+ *
+ * `cause` carries the underlying error for logs. The MESSAGE is fixed and
+ * `tessera:`-prefixed so it can never carry WASM internals into a UI.
+ */
+export declare class OpaqueProtocolError extends Error {
+    constructor(cause?: unknown);
+}

package/dist/errors.js

@@ -25,3 +25,44 @@ export class EmptyContextError extends Error {
         this.name = 'EmptyContextError';
     }
 }
+/**
+ * The password did not open the OPAQUE envelope — i.e. wrong password (or wrong
+ * account for this password file).
+ *
+ * 🔑 In OPAQUE the SERVER cannot tell a right password from a wrong one; only
+ * the client can, at `login_finish`, when the envelope fails to open. So this is
+ * the canonical wrong-password signal for the whole system, and it is raised
+ * here rather than by any HTTP status.
+ *
+ * ⚠️ Unlike the vault-envelope errors above — which are deliberately
+ * indistinguishable because telling them apart would be a decryption oracle —
+ * this one is safe to distinguish. It reports the outcome of a password the
+ * caller just supplied; it tells an attacker nothing they did not already know
+ * by typing it.
+ */
+export class InvalidCredentialsError extends Error {
+    constructor() {
+        super('tessera: invalid credentials');
+        this.name = 'InvalidCredentialsError';
+    }
+}
+/**
+ * The OPAQUE ceremony failed for a reason that is NOT a wrong password —
+ * a malformed or tampered server response, a serialization fault, or an
+ * internal library error.
+ *
+ * 🔴 This is deliberately NOT folded into `InvalidCredentialsError`. Reporting a
+ * broken ceremony as "wrong password" would send a user to reset a password that
+ * was already correct and would hide a real fault behind the one message nobody
+ * investigates. A wrong password is expected; this is not.
+ *
+ * `cause` carries the underlying error for logs. The MESSAGE is fixed and
+ * `tessera:`-prefixed so it can never carry WASM internals into a UI.
+ */
+export class OpaqueProtocolError extends Error {
+    constructor(cause) {
+        super('tessera: OPAQUE ceremony failed');
+        this.name = 'OpaqueProtocolError';
+        this.cause = cause;
+    }
+}

package/dist/index.d.ts

@@ -1,8 +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 { newRecoveryPhrase, recoveryPhrasePassword } 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';
+export { UnsupportedVersionError, MalformedEnvelopeError, EmptyVaultKeyError, EmptyContextError, InvalidCredentialsError, OpaqueProtocolError, } from './errors.js';

package/dist/index.js

@@ -2,6 +2,6 @@
 export { Tessera } from './tessera.js';
 export { init } from './wasm.js';
 export { blindIndexString } from './blindIndex.js';
-export { newRecoveryPhrase } from './recovery.js';
+export { newRecoveryPhrase, recoveryPhrasePassword } from './recovery.js';
 export { isPasskeySupported, evaluatePrf, } from './passkey.js';
-export { UnsupportedVersionError, MalformedEnvelopeError, EmptyVaultKeyError, EmptyContextError, } from './errors.js';
+export { UnsupportedVersionError, MalformedEnvelopeError, EmptyVaultKeyError, EmptyContextError, InvalidCredentialsError, OpaqueProtocolError, } from './errors.js';

package/dist/opaque.d.ts

@@ -14,3 +14,37 @@ export declare function loginOpaque(t: Transport, credentialId: string, password
 export declare function resetPasswordOpaque(t: Transport, credentialId: string, newPassword: Uint8Array): Promise<{
     exportKey: Uint8Array;
 }>;
+/**
+ * Drive OPAQUE login against the account's RECOVERY record.
+ *
+ * Structurally identical to `loginOpaque` — same handles, same wire encoding — but pointed at the
+ * recovery endpoints, because the two records must never be confused by the server. The password
+ * here is `recoveryPhrasePassword(phrase)`, NOT the account password and NOT the phrase entropy.
+ *
+ * Returns the reset token the server minted, plus the encrypted vault and the recovery wrap, which
+ * it releases only now that the ceremony has proved phrase possession.
+ *
+ * 🔑 The export_key is returned too and the caller owns zeroing it. It is NOT what opens the vault
+ * on this path — the `recovery` wrap is sealed under the phrase ENTROPY — but it is real key
+ * material and must not be left lying around.
+ */
+export declare function recoveryLoginOpaque(t: Transport, blindIndex: string, phrasePassword: Uint8Array): Promise<{
+    exportKey: Uint8Array;
+    resetToken: string;
+    encryptedVaultB64: string;
+    recoveryWrappedKeyB64: string;
+}>;
+/**
+ * Drive OPAQUE registration for the account's RECOVERY record.
+ *
+ * Returns the upload the server stores as the recovery password file, and the credential id it is
+ * keyed by. The caller pairs these with the VMK wrap in ONE `enrolRecoveryIdentity` call — see the
+ * Transport docs for why they may never be written separately.
+ *
+ * ⚠️ The export_key from this ceremony is deliberately DISCARDED. The `recovery` wrap is sealed
+ * under the phrase entropy, not under this key, so keeping it would be key material with no
+ * purpose — and a secret with no purpose is a secret waiting to be misused.
+ */
+export declare function registerRecoveryIdentity(t: Transport, credentialIdB64: string, phrasePassword: Uint8Array): Promise<{
+    uploadB64: string;
+}>;

package/dist/opaque.js

@@ -5,13 +5,52 @@
 // 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';
+import { InvalidCredentialsError, OpaqueProtocolError } from './errors.js';
+/**
+ * Translate a failure from inside the WASM core into this package's error
+ * taxonomy.
+ *
+ * 🔴 WHY THIS EXISTS. The Rust binding raises every error as
+ * `JsError::new(&format!("{e:?}"))` — a `Debug` rendering of the Rust enum. So a
+ * wrong password arrives in JavaScript as an `Error` whose message is literally
+ * `Opaque(InvalidLoginError)`. Nothing wrapped it, so it flowed through
+ * consumers' catch blocks and was rendered to users verbatim: id.ciphera.net's
+ * sign-in page showed `Opaque(InvalidLoginError)` in its error banner for the
+ * single most common failure in the product (observed 03-09-2026).
+ *
+ * 🔑 The classification is by Debug string because that is the only signal the
+ * boundary offers today. That is brittle by nature, so the DEFAULT is the safe
+ * one: anything unrecognised becomes `OpaqueProtocolError`, never
+ * `InvalidCredentialsError`. A future core release can emit a stable code (the
+ * Rust `TesseraError::code()` already returns `"invalid_credentials"`) and this
+ * can match on that instead — the exported types would not change.
+ *
+ * Either way, BOTH results carry a fixed `tessera:`-prefixed message, so no
+ * WASM-internal string can reach a UI again regardless of how the match goes.
+ */
+function opaqueFailure(cause) {
+    const raw = cause instanceof Error ? cause.message : String(cause);
+    // `ProtocolError::InvalidLoginError` is the OPAQUE "envelope did not open"
+    // result — the definition of a wrong password.
+    if (/InvalidLoginError/.test(raw))
+        return new InvalidCredentialsError();
+    return new OpaqueProtocolError(cause);
+}
 /** 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));
+        let fin;
+        try {
+            fin = reg.finish(password, fromBase64Std(responseB64));
+        }
+        catch (e) {
+            // Registration has no wrong-password case — the password is being SET —
+            // so any failure here is a protocol fault, never invalid credentials.
+            throw new OpaqueProtocolError(e);
+        }
         try {
             const uploadB64 = toBase64Std(fin.upload);
             const exportKey = fin.exportKey; // getter returns a fresh JS copy; caller owns/zeroes it
@@ -31,7 +70,15 @@ 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));
+        // 🔴 THE wrong-password site. The server cannot detect a bad password; this
+        // call is where it surfaces, as a Rust `Debug` string. Classify it.
+        let lf;
+        try {
+            lf = lh.finish(password, fromBase64Std(responseB64));
+        }
+        catch (e) {
+            throw opaqueFailure(e);
+        }
         try {
             const finalizationB64 = toBase64Std(lf.finalization);
             const exportKey = lf.exportKey;
@@ -52,7 +99,14 @@ 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));
+        let fin;
+        try {
+            fin = reg.finish(newPassword, fromBase64Std(responseB64));
+        }
+        catch (e) {
+            // Setting a password, not proving one — no invalid-credentials case here.
+            throw new OpaqueProtocolError(e);
+        }
         try {
             const uploadB64 = toBase64Std(fin.upload);
             const exportKey = fin.exportKey;
@@ -67,3 +121,88 @@ export async function resetPasswordOpaque(t, credentialId, newPassword) {
         reg.free();
     }
 }
+/**
+ * Drive OPAQUE login against the account's RECOVERY record.
+ *
+ * Structurally identical to `loginOpaque` — same handles, same wire encoding — but pointed at the
+ * recovery endpoints, because the two records must never be confused by the server. The password
+ * here is `recoveryPhrasePassword(phrase)`, NOT the account password and NOT the phrase entropy.
+ *
+ * Returns the reset token the server minted, plus the encrypted vault and the recovery wrap, which
+ * it releases only now that the ceremony has proved phrase possession.
+ *
+ * 🔑 The export_key is returned too and the caller owns zeroing it. It is NOT what opens the vault
+ * on this path — the `recovery` wrap is sealed under the phrase ENTROPY — but it is real key
+ * material and must not be left lying around.
+ */
+export async function recoveryLoginOpaque(t, blindIndex, phrasePassword) {
+    const lh = createLoginHandle(phrasePassword);
+    try {
+        const { loginId, responseB64 } = await t.recoveryLoginStart({
+            requestB64: toBase64Std(lh.request),
+            blindIndex,
+        });
+        // The wrong-PHRASE site. Same mechanism as a wrong password: the server
+        // verified nothing about the phrase's correctness, the envelope did. R6's
+        // /recover depends on telling this apart from a broken ceremony — a user who
+        // mistyped a word must be told to retype it, not that recovery is down.
+        let lf;
+        try {
+            lf = lh.finish(phrasePassword, fromBase64Std(responseB64));
+        }
+        catch (e) {
+            throw opaqueFailure(e);
+        }
+        try {
+            const finalizationB64 = toBase64Std(lf.finalization);
+            const exportKey = lf.exportKey;
+            const res = await t.recoveryLoginFinish({ loginId, finalizationB64 });
+            return { exportKey, ...res };
+        }
+        finally {
+            lf.free();
+        }
+    }
+    finally {
+        lh.free();
+    }
+}
+/**
+ * Drive OPAQUE registration for the account's RECOVERY record.
+ *
+ * Returns the upload the server stores as the recovery password file, and the credential id it is
+ * keyed by. The caller pairs these with the VMK wrap in ONE `enrolRecoveryIdentity` call — see the
+ * Transport docs for why they may never be written separately.
+ *
+ * ⚠️ The export_key from this ceremony is deliberately DISCARDED. The `recovery` wrap is sealed
+ * under the phrase entropy, not under this key, so keeping it would be key material with no
+ * purpose — and a secret with no purpose is a secret waiting to be misused.
+ */
+export async function registerRecoveryIdentity(t, credentialIdB64, phrasePassword) {
+    const reg = createRegistrationHandle(phrasePassword);
+    try {
+        const { responseB64 } = await t.registerStart({
+            requestB64: toBase64Std(reg.request),
+            credentialId: credentialIdB64,
+        });
+        let fin;
+        try {
+            fin = reg.finish(phrasePassword, fromBase64Std(responseB64));
+        }
+        catch (e) {
+            // Registering the recovery record — setting a credential, not proving one.
+            throw new OpaqueProtocolError(e);
+        }
+        try {
+            const uploadB64 = toBase64Std(fin.upload);
+            fin.exportKey.fill(0); // materialised only to be zeroed; see above
+            return { uploadB64 };
+        }
+        finally {
+            fin.free();
+        }
+    }
+    finally {
+        reg.free();
+    }
+}

package/dist/recovery.d.ts

@@ -5,3 +5,32 @@ 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;
+/**
+ * The recovery phrase, encoded as the aPAKE password for the account's SECOND OPAQUE identity.
+ *
+ * 🔴 THIS IS A WIRE CONTRACT. It is what the browser hands to OPAQUE when it registers or logs in
+ * against the recovery identity, and the server stores only the resulting password file. Change a
+ * byte of it after anyone has enrolled and every enrolled recovery identity becomes unopenable —
+ * silently, because a wrong password is indistinguishable from a wrong phrase. It is pinned by a
+ * known-answer vector (`recoveryPhrasePassword` in `test/vectors.test.ts`) for exactly that reason,
+ * in the same spirit as `@ciphera-net/auth`'s blind-index KAT.
+ *
+ * The encoding is: **NFKD-normalise, split on any whitespace, re-join with single U+0020 spaces,
+ * take the UTF-8 bytes.**
+ *
+ *  - **NFKD** because a mnemonic may be typed, pasted or autocorrected on a platform that composes
+ *    accents differently. BIP-39 itself mandates NFKD for exactly this reason, and the English
+ *    wordlist is pure ASCII so this is a no-op for us today — it is here so a future non-English
+ *    wordlist cannot silently break every enrolled identity.
+ *  - **Re-joining on single spaces** normalises the whitespace a human paste introduces: a trailing
+ *    newline, a double space, a non-breaking space from a PDF. Without it, two people typing the
+ *    same 24 words produce different passwords.
+ *
+ * 🔑 IT IS DELIBERATELY THE WORDS, NOT THE ENTROPY. The 32-byte entropy is already the `recovery`
+ * VMK-WRAP secret. Reusing it as the aPAKE password would couple the two secrets for no gain: an
+ * attacker who obtained one would hold the other, and the wrap secret would then transit the OPAQUE
+ * ceremony. They are separate derivations of the same phrase, on purpose.
+ *
+ * Returns a fresh buffer the CALLER should zero after use.
+ */
+export declare function recoveryPhrasePassword(phrase: string): Uint8Array;

package/dist/recovery.js

@@ -17,3 +17,42 @@ export function recoverySecret(phrase) {
         throw new Error('tessera: invalid recovery phrase');
     return mnemonicToEntropy(phrase, wordlist); // 32 bytes
 }
+/**
+ * The recovery phrase, encoded as the aPAKE password for the account's SECOND OPAQUE identity.
+ *
+ * 🔴 THIS IS A WIRE CONTRACT. It is what the browser hands to OPAQUE when it registers or logs in
+ * against the recovery identity, and the server stores only the resulting password file. Change a
+ * byte of it after anyone has enrolled and every enrolled recovery identity becomes unopenable —
+ * silently, because a wrong password is indistinguishable from a wrong phrase. It is pinned by a
+ * known-answer vector (`recoveryPhrasePassword` in `test/vectors.test.ts`) for exactly that reason,
+ * in the same spirit as `@ciphera-net/auth`'s blind-index KAT.
+ *
+ * The encoding is: **NFKD-normalise, split on any whitespace, re-join with single U+0020 spaces,
+ * take the UTF-8 bytes.**
+ *
+ *  - **NFKD** because a mnemonic may be typed, pasted or autocorrected on a platform that composes
+ *    accents differently. BIP-39 itself mandates NFKD for exactly this reason, and the English
+ *    wordlist is pure ASCII so this is a no-op for us today — it is here so a future non-English
+ *    wordlist cannot silently break every enrolled identity.
+ *  - **Re-joining on single spaces** normalises the whitespace a human paste introduces: a trailing
+ *    newline, a double space, a non-breaking space from a PDF. Without it, two people typing the
+ *    same 24 words produce different passwords.
+ *
+ * 🔑 IT IS DELIBERATELY THE WORDS, NOT THE ENTROPY. The 32-byte entropy is already the `recovery`
+ * VMK-WRAP secret. Reusing it as the aPAKE password would couple the two secrets for no gain: an
+ * attacker who obtained one would hold the other, and the wrap secret would then transit the OPAQUE
+ * ceremony. They are separate derivations of the same phrase, on purpose.
+ *
+ * Returns a fresh buffer the CALLER should zero after use.
+ */
+export function recoveryPhrasePassword(phrase) {
+    // 🔴 CANONICALISE FIRST, THEN VALIDATE. Validating the raw string would reject exactly the input
+    // this function exists to accept — a real paste, with a leading space, a tab between two words or
+    // a trailing newline. Validate the bytes that are actually going to be used, never a different
+    // string that merely resembles them.
+    const canonical = phrase.normalize('NFKD').split(/\s+/u).filter(Boolean).join(' ');
+    if (!validateMnemonic(canonical, wordlist)) {
+        throw new Error('tessera: invalid recovery phrase');
+    }
+    return new TextEncoder().encode(canonical);
+}

package/dist/tessera.d.ts

@@ -57,17 +57,17 @@ export declare class Tessera {
         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>;
+    /**
+     * 🔴 `recoverWithPhrase` WAS REMOVED IN 0.2.0. Use `recoverWithRecoveryIdentity`.
+     *
+     * The old method derived the recovery secret from the phrase LOCALLY and unwrapped the VMK in the
+     * browser. The server never saw the phrase and therefore never verified it — which meant it could
+     * not rate-limit guessing, and had to hand the recovery wrap to whoever asked. That is the design
+     * the 08-08-2026 audit condemned, and it does not ship in a public Apache-2.0 package.
+     *
+     * The replacement runs a real OPAQUE ceremony against a SECOND identity on the account. The server
+     * verifies the phrase, throttles attempts, and releases the vault and the wrap only afterwards.
+     */
     /** 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).
@@ -98,9 +98,47 @@ export declare class Tessera {
      *  '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, }: {
+    /**
+     * Recover with the phrase, via the account's RECOVERY OPAQUE identity.
+     *
+     * Replaces `recoverWithPhrase`. The difference is not cosmetic: the server now runs an OPAQUE
+     * ceremony against a second record, so it VERIFIES the phrase, can throttle guesses, and releases
+     * the encrypted vault and the recovery wrap only after that ceremony succeeds. The old method
+     * proved nothing to anyone and required the wrap to be readable by whoever asked.
+     *
+     * 🔑 Two secrets, both from the same phrase, deliberately kept apart:
+     *   - `recoveryPhrasePassword(phrase)` authenticates — it goes into OPAQUE.
+     *   - `recoverySecret(phrase)` (the BIP-39 entropy) decrypts — it opens the `recovery` wrap.
+     * Reusing one for both would put the wrap secret through the ceremony and couple them.
+     *
+     * The returned `resetToken` is what `POST /auth/recovery/opaque/reset` requires; it is the
+     * server's evidence that this caller proved possession, and it is single-use.
+     */
+    recoverWithRecoveryIdentity({ email, phrase, }: {
+        email: string;
+        phrase: string;
+    }): Promise<RecoverySession & {
+        resetToken: string;
+        encryptedVaultB64: string;
+    }>;
+    /**
+     * Enrol (or ROTATE) the account's recovery identity.
+     *
+     * Mints a fresh phrase, registers it as a second OPAQUE identity, and re-wraps the SAME VMK under
+     * its entropy — then sends the record and the wrap in ONE request, because an account holding one
+     * without the other passes recovery login and cannot decrypt.
+     *
+     * Requires the password: the VMK is non-extractable from a session, so it has to be re-derived
+     * from a live ceremony. `reauthToken` is a fresh proof for purpose `enr` — replacing this record
+     * installs a permanent second way into the account, so a stolen session must not be enough.
+     *
+     * Returns the new phrase. Show it ONCE; it cannot be recovered from the server, which is the
+     * point.
+     */
+    enrolRecoveryIdentity({ email, password, reauthToken, }: {
         email: string;
         password: Uint8Array;
+        reauthToken: string;
     }): Promise<{
         recoveryPhrase: string;
     }>;

package/dist/tessera.js

@@ -3,11 +3,12 @@
 // — 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 { loginOpaque, registerOpaque, resetPasswordOpaque, recoveryLoginOpaque, registerRecoveryIdentity, } from './opaque.js';
 import { generateAndWrap, openVaultKey, rewrapForMethod } from './vmk.js';
-import { newRecoveryPhrase, recoverySecret } from './recovery.js';
+import { newRecoveryPhrase, recoverySecret, recoveryPhrasePassword } from './recovery.js';
 import { open as vaultOpen, seal as vaultSeal } from './vault.js';
 import { fromBase64Std, toBase64Std } from './encoding.js';
+import { createRegistrationHandle } from './wasm.js';
 // VMK-wrap blobs are stored as standard base64 (they are opaque server storage, not OPAQUE wire blobs).
 const b64 = toBase64Std;
 const fromB64 = fromBase64Std;
@@ -97,43 +98,17 @@ export class Tessera {
             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);
-            },
-        };
-    }
+    /**
+     * 🔴 `recoverWithPhrase` WAS REMOVED IN 0.2.0. Use `recoverWithRecoveryIdentity`.
+     *
+     * The old method derived the recovery secret from the phrase LOCALLY and unwrapped the VMK in the
+     * browser. The server never saw the phrase and therefore never verified it — which meant it could
+     * not rate-limit guessing, and had to hand the recovery wrap to whoever asked. That is the design
+     * the 08-08-2026 audit condemned, and it does not ship in a public Apache-2.0 package.
+     *
+     * The replacement runs a real OPAQUE ceremony against a SECOND identity on the account. The server
+     * verifies the phrase, throttles attempts, and releases the vault and the wrap only afterwards.
+     */
     /** 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).
@@ -204,23 +179,138 @@ export class Tessera {
      *  '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, }) {
+    /**
+     * Recover with the phrase, via the account's RECOVERY OPAQUE identity.
+     *
+     * Replaces `recoverWithPhrase`. The difference is not cosmetic: the server now runs an OPAQUE
+     * ceremony against a second record, so it VERIFIES the phrase, can throttle guesses, and releases
+     * the encrypted vault and the recovery wrap only after that ceremony succeeds. The old method
+     * proved nothing to anyone and required the wrap to be readable by whoever asked.
+     *
+     * 🔑 Two secrets, both from the same phrase, deliberately kept apart:
+     *   - `recoveryPhrasePassword(phrase)` authenticates — it goes into OPAQUE.
+     *   - `recoverySecret(phrase)` (the BIP-39 entropy) decrypts — it opens the `recovery` wrap.
+     * Reusing one for both would put the wrap secret through the ceremony and couple them.
+     *
+     * The returned `resetToken` is what `POST /auth/recovery/opaque/reset` requires; it is the
+     * server's evidence that this caller proved possession, and it is single-use.
+     */
+    async recoverWithRecoveryIdentity({ email, phrase, }) {
+        const blindIndex = blindIndexString(email);
+        const phrasePassword = recoveryPhrasePassword(phrase); // throws on a bad checksum
+        let entropy;
+        let exportKey;
+        try {
+            const res = await recoveryLoginOpaque(this.transport, blindIndex, phrasePassword);
+            exportKey = res.exportKey;
+            if (!res.recoveryWrappedKeyB64) {
+                // The server proved the phrase but holds no wrap for it. That is the half-written state
+                // ciphera-id#68 made unrepresentable going forward; say so plainly rather than throwing a
+                // decryption error the user would read as "wrong phrase".
+                throw new Error('tessera: this account has a recovery identity but no recovery wrap');
+            }
+            entropy = recoverySecret(phrase);
+            const recoveryBlob = fromB64(res.recoveryWrappedKeyB64);
+            const vmk = await openVaultKey(recoveryBlob, entropy, 'recovery');
+            // Retained for resetPassword ONLY, and zeroed by it or by dispose(). The session VMK is a
+            // non-extractable CryptoKey and cannot be re-wrapped, so the reset has to re-derive the raw
+            // key from this blob — the same reason the old API held it, on a mechanism that now has the
+            // server's verification in front of it.
+            const heldEntropy = entropy;
+            entropy = undefined; // ownership moves into the closures below
+            const transport = this.transport;
+            const { resetToken, encryptedVaultB64 } = res;
+            return {
+                // No OPAQUE session key on this path: recovery proves the phrase, not a login.
+                ...sessionFor(vmk, null),
+                resetToken,
+                encryptedVaultB64,
+                async resetPassword(newPassword) {
+                    const reg = createRegistrationHandle(newPassword);
+                    try {
+                        const { responseB64 } = await transport.registerStart({
+                            requestB64: toBase64Std(reg.request),
+                            credentialId: blindIndex,
+                        });
+                        const fin = reg.finish(newPassword, fromBase64Std(responseB64));
+                        try {
+                            // Re-wrap the SAME VMK under the new export_key. The vault is never re-encrypted.
+                            const newOpaqueWrap = await rewrapForMethod({ blob: recoveryBlob, secret: heldEntropy, method: 'recovery' }, { secret: fin.exportKey, method: 'opaque' });
+                            // 🔴 BOTH wraps travel. Sending only the opaque one would leave the account with a
+                            // recovery record whose wrap the server no longer holds — the exact half-written
+                            // state ciphera-id#68 exists to prevent, arrived at from the other side.
+                            await transport.recoveryResetPassword({
+                                resetToken,
+                                blindIndex,
+                                encryptedVaultB64,
+                                opaqueWrappedKeyB64: b64(newOpaqueWrap),
+                                registrationUploadB64: toBase64Std(fin.upload),
+                                credentialIdB64: blindIndex,
+                                recoveryWrappedKeyB64: b64(recoveryBlob),
+                            });
+                        }
+                        finally {
+                            fin.free();
+                        }
+                    }
+                    finally {
+                        reg.free();
+                        heldEntropy.fill(0);
+                    }
+                },
+                dispose() {
+                    heldEntropy.fill(0);
+                },
+            };
+        }
+        finally {
+            phrasePassword.fill(0);
+            entropy?.fill(0);
+            exportKey?.fill(0);
+        }
+    }
+    /**
+     * Enrol (or ROTATE) the account's recovery identity.
+     *
+     * Mints a fresh phrase, registers it as a second OPAQUE identity, and re-wraps the SAME VMK under
+     * its entropy — then sends the record and the wrap in ONE request, because an account holding one
+     * without the other passes recovery login and cannot decrypt.
+     *
+     * Requires the password: the VMK is non-extractable from a session, so it has to be re-derived
+     * from a live ceremony. `reauthToken` is a fresh proof for purpose `enr` — replacing this record
+     * installs a permanent second way into the account, so a stolen session must not be enough.
+     *
+     * Returns the new phrase. Show it ONCE; it cannot be recovered from the server, which is the
+     * point.
+     */
+    async enrolRecoveryIdentity({ email, password, reauthToken, }) {
         const credentialId = blindIndexString(email);
         const { exportKey } = await loginOpaque(this.transport, credentialId, password);
-        let recovEntropy;
+        let entropy;
+        let phrasePassword;
         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) } });
+            entropy = recoverySecret(recoveryPhrase);
+            phrasePassword = recoveryPhrasePassword(recoveryPhrase);
+            // Re-wrap the SAME VMK. The vault is never re-encrypted.
+            const recoveryWrap = await rewrapForMethod({ blob: fromB64(opaqueWrap.blobB64), secret: exportKey, method: 'opaque' }, { secret: entropy, method: 'recovery' });
+            const { uploadB64 } = await registerRecoveryIdentity(this.transport, credentialId, phrasePassword);
+            // One call: record + wrap, or neither.
+            await this.transport.enrolRecoveryIdentity({
+                uploadB64,
+                credentialIdB64: credentialId,
+                recoveryWrappedKeyB64: b64(recoveryWrap),
+                reauthToken,
+            });
             return { recoveryPhrase };
         }
         finally {
             exportKey.fill(0);
-            recovEntropy?.fill(0);
+            entropy?.fill(0);
+            phrasePassword?.fill(0);
         }
     }
 }

package/dist/transport.d.ts

@@ -36,4 +36,58 @@ export interface Transport {
     }): Promise<{
         blobB64: string;
     } | null>;
+    /** First OPAQUE message against the account's RECOVERY record.
+     *
+     *  Like `loginStart`, this MUST always resolve for a well-formed request — an unknown account
+     *  gets a timing-safe dummy — or it becomes an account-existence oracle for anyone who can guess
+     *  an email. */
+    recoveryLoginStart(req: {
+        blindIndex: string;
+        requestB64: string;
+    }): Promise<{
+        loginId: string;
+        responseB64: string;
+    }>;
+    /** Second OPAQUE message. The vault and the recovery wrap come back ONLY here, AFTER the ceremony
+     *  has proved possession of the phrase — they used to be handed to any unauthenticated caller,
+     *  which is what made the old endpoint a disclosure as well as an oracle. */
+    recoveryLoginFinish(req: {
+        loginId: string;
+        finalizationB64: string;
+    }): Promise<{
+        resetToken: string;
+        encryptedVaultB64: string;
+        recoveryWrappedKeyB64: string;
+    }>;
+    /** Register (or REPLACE) the recovery identity, together with the VMK wrap sealed under the same
+     *  phrase.
+     *
+     *  🔴 BOTH IN ONE CALL, deliberately. The record is what the phrase authenticates against and the
+     *  wrap is the vault key sealed under it; an account holding one without a matching other passes
+     *  recovery login and then cannot decrypt. The server writes them in a single UPDATE for the same
+     *  reason (ciphera-id#68).
+     *
+     *  `reauthToken` is a fresh password proof — replacing this record installs a permanent second
+     *  credential, so a live session alone must not be enough. */
+    enrolRecoveryIdentity(req: {
+        uploadB64: string;
+        credentialIdB64: string;
+        recoveryWrappedKeyB64: string;
+        reauthToken: string;
+    }): Promise<void>;
+    /** Set a new password after a recovery ceremony, in ONE server-side transaction.
+     *
+     *  `resetToken` is the entire authorisation — it is minted only by a completed recovery login and
+     *  is single-use. Everything else is the re-registered account: a new OPAQUE record, the vault
+     *  re-sealed, and BOTH wraps carried forward so the account is not left holding one without the
+     *  other. */
+    recoveryResetPassword(req: {
+        resetToken: string;
+        blindIndex: string;
+        encryptedVaultB64: string;
+        opaqueWrappedKeyB64: string;
+        registrationUploadB64: string;
+        credentialIdB64: string;
+        recoveryWrappedKeyB64: string;
+    }): Promise<void>;
 }

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@ciphera-net/tessera",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
-  "description": "Tessera browser SDK — OPAQUE auth, blind index, vault, BIP-39 recovery, WebAuthn-PRF (WASM + WebCrypto).",
+  "description": "Tessera browser SDK \u2014 OPAQUE auth, blind index, vault, BIP-39 recovery, WebAuthn-PRF (WASM + WebCrypto).",
   "homepage": "https://ciphera.net",
   "repository": {
     "type": "git",