@ciphera-net/tessera 0.1.3

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Ciphera
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,380 @@
+# @ciphera-net/tessera
+
+Browser SDK for the Tessera authentication and vault system.
+
+> **Self-reviewed, not independently audited.** Apache-2.0. Read the
+> [security model](https://github.com/ciphera-net/tessera/blob/main/docs/THREAT-MODEL.md) and
+> [self-audit](https://github.com/ciphera-net/tessera/blob/main/docs/SELF-AUDIT.md) before relying on it.
+
+---
+
+## What it is
+
+`@ciphera-net/tessera` is a browser-first TypeScript SDK that implements:
+
+- **OPAQUE (RFC 9807) password authentication** — the password never reaches the server in any form; the server stores only an opaque OPAQUE registration record (password file) that cannot be reversed into the password. The `export_key` produced by the OPAQUE handshake is used exclusively to wrap the vault master key (VMK), then zeroed.
+- **Argon2id blind index** — a deterministic, pseudonymous lookup key derived from the email address (Argon2id/v0x13/m=64 MiB/t=3/p=1, domain-separated salt). Used as the server-side `credentialId`; the plaintext email never hits the database.
+- **AES-256-GCM vault** — a two-layer envelope (wrapped DEK under a per-context KEK). Context is required on every seal/open call and is bound into the key derivation and AAD; it is never stored in the envelope.
+- **BIP-39 (24-word / 256-bit) recovery phrase** — the mnemonic entropy is used directly as the VMK-wrap secret (no PBKDF2 indirection). Shown to the user once at registration.
+- **WebAuthn-PRF passwordless unlock** — additive. The password and recovery phrase remain valid at all times; an authenticator without PRF support simply cannot enroll the passkey path.
+
+The SDK is byte-for-byte interoperable with **tessera-go** (the Go server SDK) and the **Rust sidecar**. All three implementations share the pinned algorithm constants in the canonical conformance kit at `ciphera-net/tessera` (`conformance/schema.md` + `conformance/CONFORMANCE.md`) and are validated by cross-language parity vectors in `conformance/vectors/`.
+
+---
+
+## Install
+
+```
+npm i @ciphera-net/tessera
+```
+
+> Published to npm as [`@ciphera-net/tessera`](https://www.npmjs.com/package/@ciphera-net/tessera) (public, no auth required).
+
+**Peer requirement:** the SDK is transport-agnostic. Your application must supply a `Transport` implementation that relays OPAQUE blobs and VMK-wrap storage to your backend (which fronts tessera-go → the Rust sidecar). See [Transport](#transport) below.
+
+---
+
+## Quick start
+
+### 1. Initialize the WASM module
+
+```ts
+import { init, Tessera } from '@ciphera-net/tessera';
+
+// Must resolve before any WASM-backed API (blind index, OPAQUE handles).
+// Safe to call multiple times — idempotent.
+await init();
+```
+
+**Browser:** loads the `web` wasm-pack target (ESM + async fetch of the `.wasm` binary).  
+**Node (tests/SSR):** loads the `nodejs` wasm-pack target (CommonJS, auto-initialized on require — no separate async init needed, but calling `init()` is still safe and recommended for uniform code paths).
+
+### 2. Implement Transport
+
+```ts
+import type { Transport } from '@ciphera-net/tessera';
+
+const transport: Transport = {
+  // OPAQUE registration — phase 1: send the client request, receive the server response.
+  async registerStart({ requestB64, credentialId }) {
+    const res = await fetch('/auth/register/start', {
+      method: 'POST',
+      body: JSON.stringify({ requestB64, credentialId }),
+    });
+    return res.json(); // { responseB64: string }
+  },
+
+  // OPAQUE registration — phase 2: send the finalization upload. The server stores the password
+  // file; it is never returned to the browser.
+  async registerFinish({ credentialId, uploadB64 }) {
+    await fetch('/auth/register/finish', {
+      method: 'POST',
+      body: JSON.stringify({ credentialId, uploadB64 }),
+    });
+  },
+
+  // OPAQUE login — phase 1. passwordFile is nullable: an unknown account passes null to the
+  // sidecar for a timing-safe dummy response. The browser cannot distinguish existing from
+  // non-existing accounts.
+  async loginStart({ requestB64, credentialId }) {
+    const res = await fetch('/auth/login/start', {
+      method: 'POST',
+      body: JSON.stringify({ requestB64, credentialId }),
+    });
+    return res.json(); // { loginId: string; responseB64: string }
+  },
+
+  // OPAQUE login — phase 2. Returns the OPAQUE session key (opaque to the server).
+  async loginFinish({ loginId, finalizationB64 }) {
+    const res = await fetch('/auth/login/finish', {
+      method: 'POST',
+      body: JSON.stringify({ loginId, finalizationB64 }),
+    });
+    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.
+  async replacePasswordFile({ credentialId, uploadB64 }) {
+    await fetch('/auth/reset-password', {
+      method: 'POST',
+      body: JSON.stringify({ credentialId, uploadB64 }),
+    });
+  },
+
+  // Store one or more VMK-wrap blobs (opaque bytes to the server), keyed by method name.
+  // method names used by the SDK: "opaque", "recovery", "webauthn".
+  async putWraps({ credentialId, wraps }) {
+    await fetch('/auth/wraps', {
+      method: 'PUT',
+      body: JSON.stringify({ credentialId, wraps }),
+    });
+  },
+
+  // Fetch a single VMK-wrap blob by method. Returns null if the method has no stored wrap.
+  async getWrap({ credentialId, method }) {
+    const res = await fetch(`/auth/wraps/${credentialId}/${method}`);
+    if (res.status === 404) return null;
+    return res.json(); // { blobB64: string } | null
+  },
+};
+```
+
+All OPAQUE blobs exchanged with the server (`requestB64`, `responseB64`, `uploadB64`, `finalizationB64`, `sessionKeyB64`) are **base64-STANDARD** strings. VMK-wrap blobs (`blobB64`) are also base64-STANDARD (opaque byte sequences; not OPAQUE wire format).
+
+### 3. Register
+
+```ts
+const t = new Tessera(transport);
+
+// password must be a Uint8Array — the WASM OPAQUE layer operates on bytes.
+const password = new TextEncoder().encode('correct horse battery staple');
+
+const { recoveryPhrase } = await t.register({ email: 'alice@example.com', password });
+
+// Show recoveryPhrase to the user EXACTLY ONCE and prompt them to write it down.
+// The SDK does not store it. The string is immutable (JS strings cannot be zeroed —
+// see Security model below).
+console.log(recoveryPhrase); // 24 BIP-39 words
+```
+
+`register` performs: blind-index → OPAQUE enrollment → VMK generation → wrap under `export_key` (method `"opaque"`) + fresh recovery entropy (method `"recovery"`) → `putWraps`. The `export_key` and recovery entropy are zeroed in a `finally` block before the call resolves.
+
+### 4. Login
+
+```ts
+const session = await t.login({ email: 'alice@example.com', password });
+
+// session.sessionKeyB64 — the OPAQUE session key (string | null).
+// null on recovery and passkey paths (no OPAQUE handshake ran).
+console.log(session.sessionKeyB64);
+
+// Seal a record.
+const envelope = await session.vault.seal('address', new TextEncoder().encode('123 Main St'));
+
+// Open it later. Wrong key, wrong context, or tampered bytes all throw the same error
+// (no decryption oracle — see Security model).
+const plaintext = await session.vault.open('address', envelope);
+```
+
+### 5. Recovery
+
+```ts
+const rec = await t.recoverWithPhrase({
+  email: 'alice@example.com',
+  phrase: 'word1 word2 ... word24', // the 24-word BIP-39 phrase from registration
+});
+
+// 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.
+
+// 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.
+```
+
+### 6. Passkey (WebAuthn-PRF)
+
+```ts
+import { isPasskeySupported, evaluatePrf } from '@ciphera-net/tessera';
+
+// Conservative support probe (no user gesture needed, no credential created).
+// Definitive PRF availability is only known after a real ceremony returns results.
+if (await isPasskeySupported()) {
+  // Enable: creates a new WebAuthn credential and wraps the VMK under the PRF output.
+  // The app owns rpId, challenge, and userId — the SDK does not.
+  await t.enablePasskey({
+    email: 'alice@example.com',
+    password, // re-authenticates via OPAQUE (required — non-extractable VMK cannot be re-wrapped)
+    prf: () =>
+      evaluatePrf({
+        create: true,
+        rpId: 'example.com',
+        rpName: 'Example',
+        userId: crypto.getRandomValues(new Uint8Array(16)),
+        userName: 'alice@example.com',
+        challenge: crypto.getRandomValues(new Uint8Array(32)),
+      }),
+  });
+
+  // Unlock on a later visit — no password needed.
+  const session = await t.unlockWithPasskey({
+    email: 'alice@example.com',
+    prf: () =>
+      evaluatePrf({
+        create: false,
+        rpId: 'example.com',
+        challenge: crypto.getRandomValues(new Uint8Array(32)),
+        allowCredentialIds: [storedCredentialId], // optional; omit for discoverable credentials
+      }),
+  });
+  // session.sessionKeyB64 is null — no OPAQUE handshake on the passkey path.
+}
+```
+
+`PrfProvider` is `() => Promise<Uint8Array>` — a zero-argument async function that runs the WebAuthn ceremony and returns exactly 32 bytes. The SDK zeroes the returned buffer after use. Return a fresh buffer on each call; do not share or reuse it.
+
+`evaluatePrf` uses a pinned PRF eval input (`"tessera/prf/v1"` UTF-8) so the PRF output is stable across `enablePasskey` and `unlockWithPasskey`. This input is an SDK internal — the app does not need to supply it.
+
+---
+
+## Transport
+
+The full `Transport` interface (7 methods):
+
+| Method | Direction | Description |
+|---|---|---|
+| `registerStart({ requestB64, credentialId })` | client → server | OPAQUE reg phase 1 |
+| `registerFinish({ credentialId, uploadB64 })` | client → server | OPAQUE reg phase 2; returns `void` |
+| `loginStart({ requestB64, credentialId })` | client → server | OPAQUE login phase 1; returns `{ loginId, responseB64 }` |
+| `loginFinish({ loginId, finalizationB64 })` | client → server | OPAQUE login phase 2; returns `{ sessionKeyB64 }` |
+| `replacePasswordFile({ credentialId, uploadB64 })` | client → server | password reset after recovery; returns `void` |
+| `putWraps({ credentialId, wraps })` | client → server | store VMK-wrap blobs by method name; returns `void` |
+| `getWrap({ credentialId, method })` | client ← server | fetch one VMK-wrap blob; returns `{ blobB64: string } \| null` |
+
+`passwordFile` on the server side is `string | null` — `null` for an unknown account. The server passes it to the sidecar for a timing-safe dummy OPAQUE response. The browser cannot distinguish an existing from a non-existing account.
+
+---
+
+## The vault
+
+```ts
+// seal — encrypts plaintext and returns an opaque envelope (Uint8Array).
+const envelope: Uint8Array = await session.vault.seal(context, plaintext);
+
+// open — decrypts and authenticates. Returns the original plaintext.
+const plaintext: Uint8Array = await session.vault.open(context, envelope);
+```
+
+**`context`** (a non-empty string) is mandatory on every call. It:
+
+- Names the record type, e.g. `"address"`, `"totp"`, `"note"`.
+- Is fed into the HKDF info string (`"tessera/vault/v1/record/" + context`), deriving an independent KEK per record type.
+- Is bound as AAD into both GCM operations (wrap and content), preventing context substitution.
+- Is **not stored** in the envelope — the caller must supply the same context to `open` that was used in `seal`.
+
+An envelope sealed under `"address"` cannot be opened under `"totp"` — wrong-context is indistinguishable from wrong-key or tampered bytes, and will throw.
+
+**Thrown errors** (all from the same error module):
+
+| Class | When |
+|---|---|
+| `UnsupportedVersionError` | envelope version byte ≠ `0x01` |
+| `MalformedEnvelopeError` | envelope too short to parse |
+| `EmptyVaultKeyError` | zero-length key material passed |
+| `EmptyContextError` | context is an empty string |
+
+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).
+
+---
+
+## Crypto parameters (pinned)
+
+These constants are fixed across all SDK implementations (TS, Go, Rust). Any change requires a new version label and a migration.
+
+### Blind index
+
+| Parameter | Value |
+|---|---|
+| KDF | Argon2id |
+| Version | `0x13` (19) — must be specified explicitly |
+| Memory (m) | `65536 KiB` (64 MiB) |
+| Time (t) | `3` |
+| Parallelism (p) | `1` |
+| Output length | 32 bytes |
+| Salt | `"tessera/blind-index/v1"` (UTF-8, no NUL) |
+| Encoding | base64url **unpadded** (`+→-`, `/→_`, no `=`) |
+
+Email normalization (applied in order before hashing): trim whitespace → lowercase.
+
+`p=1` is pinned because common browser/WASM Argon2 builds run single-threaded and may silently clamp `p>1` to `p=1`, yielding a different output from a native multi-lane build.
+
+### OPAQUE KSF
+
+The OPAQUE password-hardening KSF uses the same Argon2id suite, applied at `register_finish` and `login_finish` on the client:
+
+| Parameter | Value |
+|---|---|
+| KDF | Argon2id `0x13` |
+| Memory (m) | `65536 KiB` (64 MiB) |
+| Time (t) | `3` |
+| Parallelism (p) | `1` |
+
+OPAQUE blobs are encoded as **base64-STANDARD** (not base64url) on the wire.
+
+### Vault envelope v1
+
+```
+[0x01][nonceW 12B][AES-256-GCM(KEK, DEK) = 48B][nonceC 12B][AES-256-GCM(DEK, msg)]
+```
+
+Minimum size (empty plaintext): 89 bytes.
+
+KEK derivation:
+
+```
+KEK = HKDF-SHA-256(
+  IKM  = vaultKey (VMK),
+  salt = 32 zero bytes,   // RFC 5869 §2.2 nil-salt → HashLen zeros; SHA-256 HashLen = 32
+  info = "tessera/vault/v1/record/" ‖ utf8(context),
+  L    = 32
+)
+```
+
+The 32-zero salt is intentional and matches Go's `hkdf.Key(sha256.New, vaultKey, nil, ...)`. Using a genuinely zero-length salt derives a different KEK and breaks interoperability.
+
+AAD (bound into both GCM operations):
+
+```
+AAD = [0x01] ‖ utf8(context)
+```
+
+---
+
+## Security model and honest limits
+
+### 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.
+- 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
+
+**Non-extractable is an API-layer guard, not process isolation.** A compromised page (XSS, malicious dependency, compromised browser extension) can still *use* the non-extractable key to seal/open arbitrary records. It cannot export the raw VMK bytes via `exportKey`, but it can call `session.vault.seal` and `session.vault.open` freely. Non-extractable does not defend against a compromised execution context.
+
+**Memory zeroing is best-effort.** The `export_key` and raw VMK transit WASM/JS linear memory and are zeroed after use, but the JavaScript runtime and the JIT compiler may copy values to internal buffers (AES round-key schedules, GC copying collectors) that are not reachable for zeroing. These copies are transient and never written to persistent storage or the network, but they cannot be guaranteed erased.
+
+**The recovery phrase string cannot be zeroed.** JavaScript strings are immutable. `newRecoveryPhrase()` returns a `string`; the SDK derives the 32-byte entropy from it and zeroes that buffer, but the phrase string itself lives until it is garbage-collected. Minimize its lifetime: store it only long enough to display it to the user, then discard all references.
+
+**Constant-time is not fully achievable in TS/WASM.** JavaScript engines make no constant-time guarantees for arithmetic or memory access. The SDK relies on the underlying OPAQUE and AES-GCM primitives (Rust sidecar, WebCrypto) for timing safety; the TS orchestration layer is not constant-time.
+
+**WebAuthn-PRF is additive.** Enrolling a passkey does not remove the password or recovery paths. An attacker who compromises the password can still log in even if the user has a passkey. This is intentional — the passkey path is a convenience unlock, not a security upgrade of the authentication factor.
+
+**`open` collapses all failure modes into one error.** Wrong key, wrong context, and GCM tag failure all result in a generic decryption error. This is intentional — a caller cannot tell which check failed, so there is no decryption oracle.
+
+---
+
+## Testing and status
+
+```bash
+cd packages/tessera-ts
+
+# Run unit and parity tests (Node, no browser needed).
+npm test
+```
+
+Tests run with **vitest**. The parity test suite (`test/vectors.test.ts`) validates byte-exact blind-index vectors and vault open-parity vectors against the Go-generated snapshots in the canonical kit (`ciphera-net/tessera` → `conformance/vectors/`).
+
+Tests that require the **tessera-go sidecar** (OPAQUE handshake, recovery flow, passkey flow) read the sidecar binary path from `TESSERA_SIDECAR_BIN`. They are skipped automatically when the variable is unset.
+
+```bash
+TESSERA_SIDECAR_BIN=/path/to/tessera-sidecar npm test
+```
+
+Cross-language parity vectors are the canonical conformance kit in `ciphera-net/tessera` (`conformance/vectors/blind-index.json`, `conformance/vectors/vault.json`) alongside `conformance/schema.md` + `conformance/CONFORMANCE.md`, the authoritative contract for all pinned constants. The Go generator at `tessera-go/harness/vectors/gen_go.go` regenerates the files and performs an in-process round-trip assertion before writing output.
+
+A Playwright browser matrix (real WebAuthn virtual-authenticator, full in-browser WASM path) is a planned follow-up and is not yet part of the CI suite.
+
+Current test suite: **44 tests across 10 files**, all passing.

package/dist/blindIndex.d.ts

@@ -0,0 +1,2 @@
+/** base64url-unpadded blind index for `email`. Requires `init()` (WASM) to have resolved. */
+export declare function blindIndexString(email: string): string;

package/dist/blindIndex.js

@@ -0,0 +1,10 @@
+// Deterministic, privacy-preserving account lookup key. The normalization (trim → lowercase) and the
+// Argon2id derivation live in the WASM core (single source of truth, byte-parity with tessera-go); this
+// module only encodes the 32-byte result as base64url-UNPADDED — the form used as the OPAQUE
+// credential_id and the server lookup key (matches Go's base64.RawURLEncoding).
+import { toBase64UrlUnpadded } from './encoding.js';
+import { blindIndexBytes } from './wasm.js';
+/** base64url-unpadded blind index for `email`. Requires `init()` (WASM) to have resolved. */
+export function blindIndexString(email) {
+    return toBase64UrlUnpadded(blindIndexBytes(email));
+}

package/dist/encoding.d.ts

@@ -0,0 +1,19 @@
+/** Standard padded base64 (`BASE64_STANDARD`) — for OPAQUE wire blobs. */
+export declare function toBase64Std(bytes: Uint8Array): string;
+export declare function fromBase64Std(b64: string): Uint8Array;
+/** base64url UNPADDED — for the blind index (matches Go's `base64.RawURLEncoding`).
+ *  No decode direction is provided on purpose: blind-index / credential_id values are write-only in
+ *  this SDK (sent to the server, never received and decoded here). */
+export declare function toBase64UrlUnpadded(bytes: Uint8Array): string;
+export declare function utf8(s: string): Uint8Array;
+/**
+ * Bridge the TS 5.7+ typed-array generic split at the WebCrypto boundary.
+ *
+ * TS 5.7 split `Uint8Array` into `Uint8Array<ArrayBufferLike>`, but lib.dom's WebCrypto signatures
+ * (`BufferSource`) require the `ArrayBuffer`-backed form (`SharedArrayBuffer` is rejected). Every byte
+ * value this SDK feeds to WebCrypto is ArrayBuffer-backed at runtime — fresh `new Uint8Array(n)`,
+ * `crypto.getRandomValues`, `TextEncoder`, copies out of WASM, and `@scure/bip39` output — and a
+ * `Uint8Array` is always a valid `BufferSource` at runtime regardless. This is therefore a sound,
+ * zero-copy re-view that closes a TYPE-ONLY gap; use it only when handing bytes to `crypto.subtle`.
+ */
+export declare function wcView(b: Uint8Array): Uint8Array<ArrayBuffer>;

package/dist/encoding.js

@@ -0,0 +1,44 @@
+// Base64 + UTF-8 helpers. Browser-safe by design: uses `btoa`/`atob` and `TextEncoder`, never Node's
+// `Buffer`, so the same source runs in the browser and (via Node's global btoa/atob) in tests/SSR.
+//
+// TWO base64 variants, deliberately distinct — mixing them silently breaks the wire:
+//   - toBase64Std / fromBase64Std  = standard padded base64 (Rust `BASE64_STANDARD`) for OPAQUE blobs
+//     relayed browser ↔ relay ↔ sidecar.
+//   - toBase64UrlUnpadded          = base64url WITHOUT padding (Go `base64.RawURLEncoding`) for the
+//     blind index / credential_id.
+/** Standard padded base64 (`BASE64_STANDARD`) — for OPAQUE wire blobs. */
+export function toBase64Std(bytes) {
+    let s = '';
+    for (const b of bytes)
+        s += String.fromCharCode(b);
+    return btoa(s);
+}
+export function fromBase64Std(b64) {
+    const s = atob(b64);
+    const out = new Uint8Array(s.length);
+    for (let i = 0; i < s.length; i++)
+        out[i] = s.charCodeAt(i);
+    return out;
+}
+/** base64url UNPADDED — for the blind index (matches Go's `base64.RawURLEncoding`).
+ *  No decode direction is provided on purpose: blind-index / credential_id values are write-only in
+ *  this SDK (sent to the server, never received and decoded here). */
+export function toBase64UrlUnpadded(bytes) {
+    return toBase64Std(bytes).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+export function utf8(s) {
+    return new TextEncoder().encode(s);
+}
+/**
+ * Bridge the TS 5.7+ typed-array generic split at the WebCrypto boundary.
+ *
+ * TS 5.7 split `Uint8Array` into `Uint8Array<ArrayBufferLike>`, but lib.dom's WebCrypto signatures
+ * (`BufferSource`) require the `ArrayBuffer`-backed form (`SharedArrayBuffer` is rejected). Every byte
+ * value this SDK feeds to WebCrypto is ArrayBuffer-backed at runtime — fresh `new Uint8Array(n)`,
+ * `crypto.getRandomValues`, `TextEncoder`, copies out of WASM, and `@scure/bip39` output — and a
+ * `Uint8Array` is always a valid `BufferSource` at runtime regardless. This is therefore a sound,
+ * zero-copy re-view that closes a TYPE-ONLY gap; use it only when handing bytes to `crypto.subtle`.
+ */
+export function wcView(b) {
+    return b;
+}