@ciphera-net/tessera 0.2.2 → 0.3.0

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).
 
+### Keeping the vault unlocked across page loads (0.3.0, additive)
+
+`Session.vault` is a pair of **closures**, so a `Session` cannot be persisted —
+functions are not structured-cloneable. `Session.vaultKey` exposes the VMK
+itself, which is a `CryptoKey` and therefore *can* be stored (IndexedDB), and
+`vaultOpsFor` rebuilds the same `seal`/`open` pair from it:
+
+```ts
+import { vaultOpsFor, type VaultKey } from '@ciphera-net/tessera';
+
+// after a ceremony — store the key, not the session
+if (session.vaultKey.extractable) throw new Error('refusing to persist an extractable key');
+await idbPut('vault-keys', userId, session.vaultKey);
+
+// on a later page load — no ceremony, no password
+const key = (await idbGet('vault-keys', userId)) as VaultKey | undefined;
+const vault = key ? vaultOpsFor(key) : null;
+const plaintext = await vault?.open('address', envelope);
+```
+
+🔴 **The key is always non-extractable** — every `VaultKey` is produced by
+`importVaultKey`, which imports with `extractable: false` and usage
+`['deriveKey']`. There are no key bytes in JS to read or copy: a holder gets
+*use* of the key on that device, never a copy of it. Assert `extractable ===
+false` before storing anyway, so a future regression fails loudly rather than
+quietly persisting exportable key material.
+
+⚠️ **Whether to persist it is YOUR decision and YOUR threat model.** Storing the
+key does not weaken zero-knowledge against the server — it still never sees the
+key or the plaintext. It weakens it against **whoever holds the unlocked
+device**, and it widens the window for a script that gets onto the page, from
+"can wait for an unlock" to "can open the vault immediately". If you do store
+it, the minimum discipline is: clear it on sign-out in the same call that clears
+the session; key it by user id and clear it when that id changes; give it a
+lifetime no longer than your refresh token's; IndexedDB only, never
+`localStorage` (which cannot hold a `CryptoKey` at all, so anything that made it
+fit would mean serialising key bytes); and tell the user which state they are
+in, with a way to undo it.
+
 ### OPAQUE ceremony errors
 
 The register/login ceremonies raise two further classes. Both carry a fixed
@@ -411,6 +450,8 @@ AAD = [0x01] ‖ utf8(context)
 
 ### What the SDK cannot guarantee
 
+**A persisted key removes the wait, not the ceiling.** Since 0.3.0 `Session.vaultKey` lets a host keep the vault unlocked across page loads. That does not hand a page any capability it lacked — a page holding a `Session` could already `seal` and `open` at will — but it removes the requirement that a *user action* happen first. See "Keeping the vault unlocked across page loads" for the trade and the minimum discipline.
+
 **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.

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { Tessera, type Session, type RecoverySession } from './tessera.js';
+export { Tessera, vaultOpsFor, type Session, type RecoverySession, type VaultOps, } from './tessera.js';
+export type { VaultKey } from './vault.js';
 export { init } from './wasm.js';
 export { blindIndexString } from './blindIndex.js';
 export { newRecoveryPhrase, recoveryPhrasePassword } from './recovery.js';

package/dist/index.js

@@ -1,5 +1,5 @@
 // Public API of @ciphera-net/tessera.
-export { Tessera } from './tessera.js';
+export { Tessera, vaultOpsFor, } from './tessera.js';
 export { init } from './wasm.js';
 export { blindIndexString } from './blindIndex.js';
 export { newRecoveryPhrase, recoveryPhrasePassword } from './recovery.js';

package/dist/tessera.d.ts

@@ -3,11 +3,50 @@ import { type VaultKey } from './vault.js';
 import type { Transport } from './transport.js';
 export interface Session {
     sessionKeyB64: string | null;
-    vault: {
-        seal(context: string, plaintext: Uint8Array): Promise<Uint8Array>;
-        open(context: string, envelope: Uint8Array): Promise<Uint8Array>;
-    };
+    vault: VaultOps;
+    /**
+     * The VMK that backs `vault`, exposed so a host can PERSIST the unlocked state.
+     *
+     * This grants no capability the host did not already have: anything holding a
+     * Session can already call `vault.open()` and `vault.seal()`. What it adds is
+     * REACHABILITY — `vault` is a pair of closures, and functions are not
+     * structured-cloneable, so a Session cannot be put in IndexedDB. A `VaultKey`
+     * is a `CryptoKey` and can be, which is the whole difference between "unlocked
+     * for this page" and "unlocked on this device".
+     *
+     * 🔴 IT IS ALWAYS NON-EXTRACTABLE. Every VaultKey in this SDK is produced by
+     * `importVaultKey`, which imports with `extractable: false` and usage
+     * `['deriveKey']`. So there are no key bytes in JS to read, copy or exfiltrate
+     * — a holder gets USE of the key on that device, never a copy of it. A host
+     * that stores one should nonetheless assert `extractable === false` on the way
+     * in, so that a future SDK regression fails loudly instead of quietly
+     * persisting exportable key material.
+     *
+     * ⚠️ WHETHER TO PERSIST IT IS THE HOST'S DECISION, AND ITS THREAT MODEL.
+     * Storing it does not weaken zero-knowledge against the server: the server
+     * still never sees the key or the plaintext. It weakens it against whoever
+     * holds the unlocked device, and it widens the window for a script that gets
+     * onto the page — from "can wait for an unlock" to "can open the vault
+     * immediately". This SDK takes no position; it stops hiding the object.
+     *
+     * Rebuild the ops from a stored key with `vaultOpsFor(vaultKey)`.
+     */
+    vaultKey: VaultKey;
+}
+/** The seal/open pair a `VaultKey` backs. Named so a host can type a rebuilt pair. */
+export interface VaultOps {
+    seal(context: string, plaintext: Uint8Array): Promise<Uint8Array>;
+    open(context: string, envelope: Uint8Array): Promise<Uint8Array>;
 }
+/**
+ * Rebuild `Session['vault']` from a `VaultKey` — for a host that persisted the
+ * key and wants the same ops back without re-running a ceremony.
+ *
+ * This is exactly what every Session is built with; it is exported so that a
+ * restored key and a freshly unlocked one produce the SAME object shape, rather
+ * than each host re-implementing the pair and drifting on the context argument.
+ */
+export declare function vaultOpsFor(vaultKey: VaultKey): VaultOps;
 export interface RecoverySession extends Session {
     /** Re-key auth to a new password. Preserves the vault (the SAME VMK is re-wrapped under the new
      *  export_key — the vault content is never re-encrypted). Single-use: the recovery secret is zeroed

package/dist/tessera.js

@@ -12,15 +12,26 @@ 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;
-function sessionFor(vmk, sessionKeyB64) {
+/**
+ * Rebuild `Session['vault']` from a `VaultKey` — for a host that persisted the
+ * key and wants the same ops back without re-running a ceremony.
+ *
+ * This is exactly what every Session is built with; it is exported so that a
+ * restored key and a freshly unlocked one produce the SAME object shape, rather
+ * than each host re-implementing the pair and drifting on the context argument.
+ */
+export function vaultOpsFor(vaultKey) {
     return {
-        sessionKeyB64,
-        vault: {
-            seal: (context, plaintext) => vaultSeal(vmk, context, plaintext),
-            open: (context, envelope) => vaultOpen(vmk, context, envelope),
-        },
+        seal: (context, plaintext) => vaultSeal(vaultKey, context, plaintext),
+        open: (context, envelope) => vaultOpen(vaultKey, context, envelope),
     };
 }
+function sessionFor(vmk, sessionKeyB64) {
+    // ONE construction site for every Session this SDK returns, which is why
+    // adding `vaultKey` here covers register, login, recovery and the passkey
+    // unlock without touching any of them.
+    return { sessionKeyB64, vault: vaultOpsFor(vmk), vaultKey: vmk };
+}
 export class Tessera {
     transport;
     constructor(transport) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ciphera-net/tessera",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",