@ciphera-net/tessera 0.1.3

package/dist/transport.js

@@ -0,0 +1 @@
+export {};

package/dist/vault.d.ts

@@ -0,0 +1,9 @@
+export type VaultKey = CryptoKey & {
+    readonly __tesseraVaultKey: unique symbol;
+};
+/** Import raw vault-key material (e.g. the VMK) as a non-extractable HKDF base key. */
+export declare function importVaultKey(raw: Uint8Array): Promise<VaultKey>;
+/** Seal plaintext under a fresh DEK wrapped by a per-context KEK. context is REQUIRED and not stored. */
+export declare function seal(vaultKey: VaultKey, context: string, plaintext: Uint8Array): Promise<Uint8Array>;
+/** Open reverses seal. Same generic error for wrong-key/tamper/short; distinct UnsupportedVersion. */
+export declare function open(vaultKey: VaultKey, context: string, envelope: Uint8Array): Promise<Uint8Array>;

package/dist/vault.js

@@ -0,0 +1,108 @@
+// WebCrypto vault: seal/open a record under a per-context key, BYTE-IDENTICAL to tessera-go/vault.go.
+// Envelope v1: [0x01][nonceW 12][AES-256-GCM(KEK, DEK)=48][nonceC 12][AES-256-GCM(DEK, msg)].
+//   KEK = HKDF-SHA256(IKM=vaultKey, salt=32 zero bytes, info="tessera/vault/v1/record/"+context, L=32)
+//   DEK = random 32 bytes;  AAD = [0x01] ‖ utf8(context) on BOTH GCM ops;  context REQUIRED, NOT stored.
+import { utf8, wcView } from './encoding.js';
+import { EmptyContextError, EmptyVaultKeyError, MalformedEnvelopeError, UnsupportedVersionError, } from './errors.js';
+const VERSION = 0x01;
+const NONCE_LEN = 12;
+const TAG_LEN = 16;
+const DEK_LEN = 32;
+const WRAPPED_DEK_LEN = DEK_LEN + TAG_LEN; // 48
+const MIN_ENVELOPE = 1 + NONCE_LEN + WRAPPED_DEK_LEN + NONCE_LEN + TAG_LEN; // 89
+const KEK_INFO_BASE = 'tessera/vault/v1/record/';
+// SHA-256 HashLen. Go's hkdf.Key(nil salt) expands to a HashLen-zero salt (RFC 5869 §2.2); we mirror
+// that EXACTLY with an explicit 32-zero salt. If the HKDF hash ever changes, this MUST change with it
+// or KEK derivation silently diverges from Go.
+const HKDF_SALT_LEN = 32;
+const subtle = globalThis.crypto.subtle;
+// AAD = versionByte ‖ utf8(context), bound into BOTH GCM ops (downgrade/substitution resistance).
+function aad(context) {
+    const c = utf8(context);
+    const out = new Uint8Array(1 + c.length);
+    out[0] = VERSION;
+    out.set(c, 1);
+    return out;
+}
+// KEK = HKDF-SHA256(vaultKey, salt=32 zero bytes, info=KEK_INFO_BASE+context, 32B), non-extractable.
+// 32 zero bytes explicitly matches Go's nil-salt → RFC 5869 HashLen-zeros expansion.
+async function deriveKEK(vaultKey, context) {
+    return subtle.deriveKey({
+        name: 'HKDF',
+        hash: 'SHA-256',
+        salt: wcView(new Uint8Array(HKDF_SALT_LEN)),
+        info: wcView(utf8(KEK_INFO_BASE + context)),
+    }, vaultKey, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
+}
+/** Import raw vault-key material (e.g. the VMK) as a non-extractable HKDF base key. */
+export async function importVaultKey(raw) {
+    if (raw.length === 0)
+        throw new EmptyVaultKeyError();
+    return (await subtle.importKey('raw', wcView(raw), 'HKDF', false, ['deriveKey']));
+}
+/** Seal plaintext under a fresh DEK wrapped by a per-context KEK. context is REQUIRED and not stored. */
+export async function seal(vaultKey, context, plaintext) {
+    if (!context)
+        throw new EmptyContextError();
+    const a = aad(context);
+    const kek = await deriveKEK(vaultKey, context);
+    const dekRaw = crypto.getRandomValues(new Uint8Array(DEK_LEN));
+    try {
+        const dek = await subtle.importKey('raw', wcView(dekRaw), 'AES-GCM', false, ['encrypt']);
+        const nonceW = crypto.getRandomValues(new Uint8Array(NONCE_LEN));
+        const wrappedDEK = new Uint8Array(await subtle.encrypt({ name: 'AES-GCM', iv: wcView(nonceW), additionalData: wcView(a) }, kek, wcView(dekRaw)));
+        const nonceC = crypto.getRandomValues(new Uint8Array(NONCE_LEN));
+        const ct = new Uint8Array(await subtle.encrypt({ name: 'AES-GCM', iv: wcView(nonceC), additionalData: wcView(a) }, dek, wcView(plaintext)));
+        const out = new Uint8Array(1 + NONCE_LEN + wrappedDEK.length + NONCE_LEN + ct.length);
+        let o = 0;
+        out[o++] = VERSION;
+        out.set(nonceW, o);
+        o += NONCE_LEN;
+        out.set(wrappedDEK, o);
+        o += wrappedDEK.length;
+        out.set(nonceC, o);
+        o += NONCE_LEN;
+        out.set(ct, o);
+        return out;
+    }
+    finally {
+        dekRaw.fill(0); // wipe the raw DEK unconditionally (mirrors Go's `defer wipe(dek)`), even on error
+    }
+}
+/** Open reverses seal. Same generic error for wrong-key/tamper/short; distinct UnsupportedVersion. */
+export async function open(vaultKey, context, envelope) {
+    if (!context)
+        throw new EmptyContextError();
+    if (envelope.length < 1)
+        throw new MalformedEnvelopeError();
+    if (envelope[0] !== VERSION)
+        throw new UnsupportedVersionError();
+    if (envelope.length < MIN_ENVELOPE)
+        throw new MalformedEnvelopeError();
+    let o = 1;
+    const nonceW = envelope.subarray(o, (o += NONCE_LEN));
+    const wrappedDEK = envelope.subarray(o, (o += WRAPPED_DEK_LEN));
+    const nonceC = envelope.subarray(o, (o += NONCE_LEN));
+    const ct = envelope.subarray(o);
+    const a = aad(context);
+    const kek = await deriveKEK(vaultKey, context);
+    // Nullable (not a sentinel): stays null if the wrap-decrypt throws before the DEK exists, so the
+    // finally wipe is a safe no-op in that case.
+    let dekRaw = null;
+    try {
+        dekRaw = new Uint8Array(await subtle.decrypt({ name: 'AES-GCM', iv: wcView(nonceW), additionalData: wcView(a) }, kek, wcView(wrappedDEK)));
+        const dek = await subtle.importKey('raw', wcView(dekRaw), 'AES-GCM', false, ['decrypt']);
+        // pt is a FRESH allocation (a copy out of WebCrypto), not a view into `envelope`; callers handling
+        // sensitive plaintext own this buffer and may zero it after use.
+        return new Uint8Array(await subtle.decrypt({ name: 'AES-GCM', iv: wcView(nonceC), additionalData: wcView(a) }, dek, wcView(ct)));
+    }
+    catch {
+        // One generic error for wrong-key / wrong-context / tamper (oracle resistance — matches Go, which
+        // returns ErrMalformedEnvelope for ANY Open failure). UnsupportedVersion is handled above, before
+        // this block, so it is never collapsed here.
+        throw new MalformedEnvelopeError();
+    }
+    finally {
+        dekRaw?.fill(0); // wipe the raw DEK unconditionally (mirrors Go's `defer wipe(dek)`)
+    }
+}

package/dist/vmk.d.ts

@@ -0,0 +1,29 @@
+import { type VaultKey } from './vault.js';
+export type UnlockMethod = 'opaque' | 'recovery' | 'webauthn';
+/** Encrypt raw VMK bytes under a method secret → versioned envelope. The CALLER owns and must zero
+ *  both `vmkRaw` and `methodSecret` after use (this fn does not zero its inputs). */
+export declare function wrapVmk(vmkRaw: Uint8Array, methodSecret: Uint8Array, method: UnlockMethod): Promise<Uint8Array>;
+/** Decrypt a VMK envelope → raw VMK bytes. CALLER MUST zero BOTH the returned buffer AND `methodSecret`
+ *  after use. */
+export declare function unwrapVmkRaw(blob: Uint8Array, methodSecret: Uint8Array, method: UnlockMethod): Promise<Uint8Array>;
+/** Unlock: decrypt the envelope and import the VMK as a NON-extractable VaultKey (raw is zeroed).
+ *  CALLER must zero `methodSecret` after this returns. */
+export declare function openVaultKey(blob: Uint8Array, methodSecret: Uint8Array, method: UnlockMethod): Promise<VaultKey>;
+/** Generate a fresh VMK. Returns the non-extractable VaultKey (for vault ops) + the wrapped blobs.
+ *  Raw VMK exists only transiently during setup, then is zeroed. */
+export declare function generateAndWrap(secrets: Partial<Record<UnlockMethod, Uint8Array>>): Promise<{
+    vmk: VaultKey;
+    wraps: Partial<Record<UnlockMethod, Uint8Array>>;
+}>;
+/** Add/replace an unlock method WITHOUT re-encrypting the vault: re-decrypt the VMK from an existing
+ *  wrap (using a JUST-RE-AUTHENTICATED secret) and re-wrap it under the new method. Used by
+ *  enablePasskey and resetPassword. The raw VMK is zeroed before returning. CALLER must zero
+ *  `existing.secret` and `next.secret` after this returns. */
+export declare function rewrapForMethod(existing: {
+    blob: Uint8Array;
+    secret: Uint8Array;
+    method: UnlockMethod;
+}, next: {
+    secret: Uint8Array;
+    method: UnlockMethod;
+}): Promise<Uint8Array>;

package/dist/vmk.js

@@ -0,0 +1,117 @@
+// VMK (Vault Master Key) hierarchy. The long-lived vault key is a random 32-byte VMK held only as a
+// non-extractable WebCrypto CryptoKey; it is WRAPPED once per unlock method (opaque / recovery /
+// webauthn) so adding or resetting a method only re-wraps the VMK — the vault itself is never
+// re-encrypted. Each wrap is a dedicated single-layer envelope (the payload is exactly the 32-byte
+// VMK; no DEK indirection):
+//   [0x01][nonce 12][AES-256-GCM(wrapKEK, VMK)=48]  = 61 bytes
+//   wrapKEK = HKDF-SHA256(IKM=methodSecret, salt=32 zero bytes, info="tessera/vmk-wrap/v1/"+method, 32)
+//   AAD     = [0x01] ‖ utf8("tessera/vmk-wrap/v1/"+method)  (binds version + method into the GCM tag)
+// Wrap/unwrap is plain AES-GCM encrypt/decrypt (NOT WebCrypto wrapKey/unwrapKey): one universally
+// supported path, and the same KEK works both directions.
+import { utf8, wcView } from './encoding.js';
+import { importVaultKey } from './vault.js';
+import { MalformedEnvelopeError, UnsupportedVersionError } from './errors.js';
+const subtle = globalThis.crypto.subtle;
+const VERSION = 0x01;
+const NONCE_LEN = 12;
+const TAG_LEN = 16;
+const VMK_LEN = 32;
+const WRAPPED_VMK_LEN = VMK_LEN + TAG_LEN; // 48 (AES-GCM ct ‖ tag)
+const ENVELOPE_LEN = 1 + NONCE_LEN + WRAPPED_VMK_LEN; // 61
+function wrapInfo(method) {
+    return utf8('tessera/vmk-wrap/v1/' + method);
+}
+function wrapAad(method) {
+    const m = wrapInfo(method);
+    const out = new Uint8Array(1 + m.length);
+    out[0] = VERSION;
+    out.set(m, 1);
+    return out;
+}
+// wrapKEK = HKDF-SHA256(methodSecret, salt=32 zeros, info, 32) as a non-extractable AES-GCM key with
+// encrypt+decrypt usage (one KEK, both directions).
+async function deriveWrapKEK(methodSecret, method) {
+    const base = await subtle.importKey('raw', wcView(methodSecret), 'HKDF', false, ['deriveKey']);
+    return subtle.deriveKey({ name: 'HKDF', hash: 'SHA-256', salt: wcView(new Uint8Array(32)), info: wcView(wrapInfo(method)) }, base, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
+}
+/** Encrypt raw VMK bytes under a method secret → versioned envelope. The CALLER owns and must zero
+ *  both `vmkRaw` and `methodSecret` after use (this fn does not zero its inputs). */
+export async function wrapVmk(vmkRaw, methodSecret, method) {
+    // Derived OUTSIDE a catch on purpose: a bad secret at wrap (setup) time is a programming error that
+    // should surface loudly, not an attacker-observable oracle (contrast unwrapVmkRaw below).
+    const kek = await deriveWrapKEK(methodSecret, method);
+    const nonce = globalThis.crypto.getRandomValues(new Uint8Array(NONCE_LEN));
+    const ct = new Uint8Array(await subtle.encrypt({ name: 'AES-GCM', iv: wcView(nonce), additionalData: wcView(wrapAad(method)) }, kek, wcView(vmkRaw)));
+    const out = new Uint8Array(ENVELOPE_LEN);
+    out[0] = VERSION;
+    out.set(nonce, 1);
+    out.set(ct, 1 + NONCE_LEN);
+    return out;
+}
+/** Decrypt a VMK envelope → raw VMK bytes. CALLER MUST zero BOTH the returned buffer AND `methodSecret`
+ *  after use. */
+export async function unwrapVmkRaw(blob, methodSecret, method) {
+    if (blob.length !== ENVELOPE_LEN)
+        throw new MalformedEnvelopeError();
+    // Unknown version is a DISTINCT, non-secret rejection (forward-compat) — matches vault.open rather
+    // than collapsing into MalformedEnvelopeError. The version byte carries no secret, so this is no oracle.
+    if (blob[0] !== VERSION)
+        throw new UnsupportedVersionError();
+    const nonce = blob.subarray(1, 1 + NONCE_LEN);
+    const ct = blob.subarray(1 + NONCE_LEN);
+    try {
+        // Derive INSIDE the try so a bad methodSecret (e.g. zero-length → HKDF importKey DataError) also
+        // collapses to MalformedEnvelope rather than leaking a raw DOMException (oracle resistance — any
+        // unlock failure is indistinguishable, matching vault.open).
+        const kek = await deriveWrapKEK(methodSecret, method);
+        return new Uint8Array(await subtle.decrypt({ name: 'AES-GCM', iv: wcView(nonce), additionalData: wcView(wrapAad(method)) }, kek, wcView(ct)));
+    }
+    catch {
+        throw new MalformedEnvelopeError(); // wrong secret / wrong method / tamper — never distinguished
+    }
+}
+/** Unlock: decrypt the envelope and import the VMK as a NON-extractable VaultKey (raw is zeroed).
+ *  CALLER must zero `methodSecret` after this returns. */
+export async function openVaultKey(blob, methodSecret, method) {
+    const raw = await unwrapVmkRaw(blob, methodSecret, method);
+    try {
+        return await importVaultKey(raw);
+    }
+    finally {
+        raw.fill(0);
+    }
+}
+/** Generate a fresh VMK. Returns the non-extractable VaultKey (for vault ops) + the wrapped blobs.
+ *  Raw VMK exists only transiently during setup, then is zeroed. */
+export async function generateAndWrap(secrets) {
+    // No silent footgun: an empty map would mint an IRRECOVERABLE VMK (no wrap can ever unlock it).
+    if (Object.keys(secrets).length === 0) {
+        throw new Error('tessera: generateAndWrap requires at least one unlock method');
+    }
+    const raw = globalThis.crypto.getRandomValues(new Uint8Array(VMK_LEN));
+    try {
+        const wraps = {};
+        for (const method of Object.keys(secrets)) {
+            // `method` came from Object.keys(secrets), so secrets[method] is defined (the `!` is sound).
+            wraps[method] = await wrapVmk(raw, secrets[method], method);
+        }
+        const vmk = await importVaultKey(raw);
+        return { vmk, wraps };
+    }
+    finally {
+        raw.fill(0);
+    }
+}
+/** Add/replace an unlock method WITHOUT re-encrypting the vault: re-decrypt the VMK from an existing
+ *  wrap (using a JUST-RE-AUTHENTICATED secret) and re-wrap it under the new method. Used by
+ *  enablePasskey and resetPassword. The raw VMK is zeroed before returning. CALLER must zero
+ *  `existing.secret` and `next.secret` after this returns. */
+export async function rewrapForMethod(existing, next) {
+    const raw = await unwrapVmkRaw(existing.blob, existing.secret, existing.method);
+    try {
+        return await wrapVmk(raw, next.secret, next.method);
+    }
+    finally {
+        raw.fill(0);
+    }
+}

package/dist/wasm.d.ts

@@ -0,0 +1,10 @@
+import type { RegistrationHandle, LoginHandle } from '../wasm/web/tessera.js';
+export type { RegistrationHandle, LoginHandle };
+/** Idempotent: load + initialize the WASM module. Await once before any WASM-backed API. */
+export declare function init(): Promise<void>;
+/** Raw 32-byte blind index from an email (normalization + Argon2id happen inside the WASM core). */
+export declare function blindIndexBytes(email: string): Uint8Array;
+/** Construct an OPAQUE registration handle (single-use; see the WASM binding). */
+export declare function createRegistrationHandle(password: Uint8Array): RegistrationHandle;
+/** Construct an OPAQUE login handle (single-use). */
+export declare function createLoginHandle(password: Uint8Array): LoginHandle;

package/dist/wasm.js

@@ -0,0 +1,52 @@
+let mod = null;
+let loading = null;
+// Detect Node WITHOUT a global `process` type — cast globalThis so this stays browser-SDK type-clean
+// (no @types/node, which would let browser code reference Node APIs unchecked).
+function isNode() {
+    const g = globalThis;
+    return typeof g.process?.versions?.node === 'string';
+}
+async function load() {
+    if (mod)
+        return mod;
+    if (!loading) {
+        loading = (async () => {
+            if (isNode()) {
+                // nodejs target — CommonJS, auto-initialized on import. NO init() call. Read the full
+                // module.exports via the dynamic-import `default` (wasm-bindgen CJS named exports are not
+                // reliably hoisted by the ESM↔CJS interop, but `default` is the whole exports object).
+                const ns = (await import('../wasm/node/tessera.js'));
+                mod = ns.default ?? ns;
+            }
+            else {
+                // web target — ESM whose default export is the async init() that loads the .wasm.
+                const web = (await import('../wasm/web/tessera.js'));
+                await web.default();
+                mod = web;
+            }
+            return mod; // assigned in both branches above
+        })();
+    }
+    return loading;
+}
+/** Idempotent: load + initialize the WASM module. Await once before any WASM-backed API. */
+export async function init() {
+    await load();
+}
+function loaded() {
+    if (!mod)
+        throw new Error('tessera: WASM not initialized — await init() first');
+    return mod;
+}
+/** Raw 32-byte blind index from an email (normalization + Argon2id happen inside the WASM core). */
+export function blindIndexBytes(email) {
+    return loaded().blindIndex(email);
+}
+/** Construct an OPAQUE registration handle (single-use; see the WASM binding). */
+export function createRegistrationHandle(password) {
+    return new (loaded().RegistrationHandle)(password);
+}
+/** Construct an OPAQUE login handle (single-use). */
+export function createLoginHandle(password) {
+    return new (loaded().LoginHandle)(password);
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@ciphera-net/tessera",
+  "version": "0.1.3",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "description": "Tessera browser SDK — OPAQUE auth, blind index, vault, BIP-39 recovery, WebAuthn-PRF (WASM + WebCrypto).",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "wasm"
+  ],
+  "scripts": {
+    "build:wasm": "bash scripts/build-wasm.sh",
+    "build:ts": "tsc",
+    "build": "npm run build:wasm && npm run build:ts",
+    "prepack": "rm -f wasm/web/.gitignore wasm/node/.gitignore",
+    "test": "vitest run",
+    "test:browser": "playwright test"
+  },
+  "dependencies": {
+    "@scure/bip39": "^1.3.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.48.0",
+    "tsx": "^4.22.4",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}

package/wasm/node/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "tessera-wasm",
+  "version": "0.0.1",
+  "license": "Apache-2.0",
+  "files": [
+    "tessera_bg.wasm",
+    "tessera.js",
+    "tessera.d.ts"
+  ],
+  "main": "tessera.js",
+  "types": "tessera.d.ts"
+}

package/wasm/node/tessera.d.ts

@@ -0,0 +1,51 @@
+/* tslint:disable */
+/* eslint-disable */
+
+export class LoginFinish {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    readonly exportKey: Uint8Array;
+    readonly finalization: Uint8Array;
+    readonly sessionKey: Uint8Array;
+}
+
+export class LoginHandle {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Finish login (single-use). Returns finalization (relay), session_key, export_key (CLIENT-ONLY).
+     */
+    finish(password: Uint8Array, response: Uint8Array): LoginFinish;
+    constructor(password: Uint8Array);
+    readonly request: Uint8Array;
+}
+
+export class RegistrationFinish {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    readonly exportKey: Uint8Array;
+    readonly upload: Uint8Array;
+}
+
+export class RegistrationHandle {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Finish registration. Consumes the handle's state (single-use; a second call errors). Returns
+     * the upload to relay and the 64-byte export_key (CLIENT-ONLY — caller must never transmit it).
+     */
+    finish(password: Uint8Array, response: Uint8Array): RegistrationFinish;
+    /**
+     * Start registration from a password. `request` carries the RegistrationRequest to relay.
+     */
+    constructor(password: Uint8Array);
+    readonly request: Uint8Array;
+}
+
+/**
+ * Derive the 32-byte blind index from an email. The params/normalization/salt live in the core
+ * crate (`tessera::blind_index`) as the single source of truth; this is a thin binding.
+ */
+export function blindIndex(email: string): Uint8Array;