@ciphera-net/tessera 0.2.0 → 0.2.1

package/README.md

@@ -297,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)

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

@@ -5,4 +5,4 @@ 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

@@ -4,4 +4,4 @@ export { init } from './wasm.js';
 export { blindIndexString } from './blindIndex.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.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;
@@ -88,7 +142,17 @@ export async function recoveryLoginOpaque(t, blindIndex, phrasePassword) {
             requestB64: toBase64Std(lh.request),
             blindIndex,
         });
-        const lf = lh.finish(phrasePassword, fromBase64Std(responseB64));
+        // 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;
@@ -121,7 +185,14 @@ export async function registerRecoveryIdentity(t, credentialIdB64, phrasePasswor
             requestB64: toBase64Std(reg.request),
             credentialId: credentialIdB64,
         });
-        const fin = reg.finish(phrasePassword, fromBase64Std(responseB64));
+        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

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@ciphera-net/tessera",
-  "version": "0.2.0",
+  "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",