@thecrossroads42/crypto 0.1.0

package/KIT-MANIFEST.txt

@@ -0,0 +1,10 @@
+d24a152bb8cf1513b82232acc910690b84616e9f3cb0283fa46ef48efa822456  LICENSE
+3d347bc9a6c493a5d9dbeffe024d27e246508816ef9121ab06d14f234736b095  README.md
+c84f4886dfd5b7a9ab68db9c9ad2fac703190c8dd7400a80b74d8612df27e87f  demo.mjs
+7642bcc1c90141a01dee72e7fc5e7de63ddeb695bdd08de7cdddf156e6fb566c  envelope.js
+1f5ae4748121665a2e8b78dc574a1901c0aa953c2c7936c2687f1ccd40efc7f7  keyring.js
+297407eb85fbe115640b5d08ab282f98e3bd1363b7fbd45cc3877f10add484e4  keyring.mjs
+075a27c3dff8f3936b9e6001a54fd8a29a41dadddb6d20c6da0757a85db458ad  longitudinal.mjs
+1d2c09291b60177cb3a138b7151e1a5c7803141771a495d21efcd631e5ff514d  longitudinalLogic.js
+b53fbb4ad4f85fa5b4af71ab14c57accf6bf6660fef9832936725d8a08d4c817  roundtrip.mjs
+bbf751830bf141d0b1a2fce680568be0fd81fda558a72c30d60f7e7cf2131129  visitEnvelope.js

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Crossroads
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# The Crossroads — client-side encryption (audit kit)
+
+This is the privacy-critical encryption code from
+[The Crossroads](https://thecrossroads.to), published so you can **check our
+claims instead of trusting them**. It is the real code that runs in the
+browser — the part that decides whether your stored record is readable by
+anyone but you — separated from the rest of the app (which stays closed; it
+holds no secret that affects your privacy).
+
+The security here does not depend on this code being secret (Kerckhoffs's
+principle): publishing it costs us nothing and lets you verify it. Licensed
+MIT (see `LICENSE`).
+
+> **One honest limit, stated up front.** Opening this code lets you audit the
+> *design*, and lets you spot-check your *own* session (below). It does **not**
+> cryptographically guarantee that the JavaScript your browser ran on a given
+> day is byte-for-byte this code — a web app serves its code each load, so a
+> compromised or coerced server could serve different code to a targeted user,
+> and this repo would not catch that. That is the standard limit of in-browser
+> crypto. The path to closing it (subresource integrity, reproducible builds, a
+> pinning browser extension, a native client) is on our roadmap; until then,
+> treat web delivery as a *soft* boundary, the same way we label the in-visit
+> moment as soft.
+
+## Run the proofs yourself
+
+No build step, no dependencies beyond Node 20+ and `@noble/hashes`:
+
+```
+node demo.mjs          # the §11 envelope + all three tiers + the re-wrap upgrade
+node roundtrip.mjs     # encrypt-before-PUT round-trip (content opaque at rest, etc.)
+node keyring.mjs       # tier manager: provision / unlock / upgrade / labeling
+node longitudinal.mjs  # the consent gate (a declined read never resurfaces)
+```
+
+Each harness verifies its claims and prints a pass/fail count.
+
+## Claims → code
+
+| Claim | Where it lives |
+|---|---|
+| Stored content is opaque at rest (AES-256-GCM, unique IV per record) | `encryptRecord` / `decryptRecord` in `envelope.js` |
+| A passphrase account is unreadable to the operator | `wrapCEK_passphrase` / `unwrapCEK_passphrase` + `deriveKEKFromPassphrase` (`envelope.js`); the server stores only `{ kdf, salt, iv, wrapped }` — never the passphrase or key |
+| The passphrase key is Argon2id (memory-hard), not a fast hash | `deriveKEKFromPassphrase` (`envelope.js`), params recorded per record |
+| A device account is unreadable to the operator | `wrapCEK_device` / `unwrapCEK_device` (`envelope.js`); the device key never leaves local storage |
+| The managed tier is operator-*readable* by design (the honest soft tier) | `TIER_INFO.managed` (`keyring.js`); its key is held server-side |
+| Switching tiers re-wraps the key without re-encrypting your data | `changeTier` (`keyring.js`) — see `keyring.mjs` step 4 |
+| Consent gate: a rejected read never resurfaces; only accepted reads carry | `reconcilePendingJudgments` (dedup vs **all** statuses) + `confirmedJudgments` (accepted only) in `longitudinalLogic.js` |
+| A forgotten passphrase is unrecoverable (the proof the guarantee is real) | `reset` (`keyring.js`) — see `keyring.mjs` step 6 |
+
+## What the server actually sees
+
+Every stored content object is an envelope `{ v, alg:"AES-GCM", iv, ct }` — `ct`
+is ciphertext. The shapes at rest:
+
+- **Visit:** cleartext operational metadata (`id`, dates, `draft`, `cost`) plus
+  `encrypted:true` and `enc: { card, content }` — both opaque envelopes.
+- **Held forks / judgments, profile, action plan, notes:** stored as
+  `{ encrypted:true, enc }`.
+- **Key record (server-side):** `{ tier, env }`. For **passphrase**, `env` is
+  `{ kdf, salt, iv, wrapped }` — the operator cannot derive the key without your
+  passphrase. For **device**, `env` is `{ iv, wrapped }` and the unwrapping key
+  is only in your browser. For **managed**, the key is held server-side and the
+  operator *can* unwrap (that tier's stated trade).
+
+What the server never receives: your passphrase, the device key, or the
+unwrapped content key, for the passphrase and device tiers.
+
+## Verify your own session (no code required)
+
+Open your browser's dev tools → Network, start and end a visit, and inspect the
+`PUT /api/visits/:id` body: you should see `enc: { content: { iv, ct } }`
+ciphertext and **no** plaintext of what you wrote. Then check that your
+passphrase never appears in any request.
+
+## What's here, and what isn't
+
+**Here:** the pure, security-determining code — `envelope.js`,
+`visitEnvelope.js`, `longitudinalLogic.js`, `keyring.js` — and the runnable
+harnesses.
+
+**Not here (and not where your privacy lives):** the glue that wires this core
+to auth, HTTP, and local storage; the server; and the app's content (the voices
+and prompts). None of that holds a secret that affects whether your stored
+record is readable.
+
+`KIT-MANIFEST.txt` lists the SHA-256 of each file in this kit; `verify-kit.mjs`
+regenerates and checks it, so this published copy can be shown to match the code
+that builds the app.

package/demo.mjs

@@ -0,0 +1,148 @@
+// =============================================================================
+// Client-side encryption — runnable demo (PROTOTYPE)
+//
+//   node frontend/src/services/crypto/demo.mjs
+//
+// Walks the §11 envelope end to end on a real-shaped visit: encrypt content
+// under a per-user CEK, wrap that CEK under each of the three tiers, show what
+// the operator actually has on disk, prove who can and cannot read it, and
+// demonstrate the re-wrap upgrade path. No app, no network, no dependencies.
+// =============================================================================
+
+import {
+  generateCEK, encryptRecord, decryptRecord, generateRawKey,
+  wrapCEK_passphrase, unwrapCEK_passphrase,
+  wrapCEK_device, unwrapCEK_device,
+  wrapCEK_managed, unwrapCEK_managed,
+} from './envelope.js';
+
+const line = (s = '') => console.log(s);
+const h = (s) => { line(); line('\x1b[1m' + s + '\x1b[0m'); };
+const ok = (s) => line('  \x1b[32m✓\x1b[0m ' + s);
+const no = (s) => line('  \x1b[31m✗\x1b[0m ' + s);
+const dim = (s) => '\x1b[2m' + s + '\x1b[0m';
+
+// A visit shaped like the real ones (frontend persists this via PUT /visits/:id).
+// Operational metadata (id/dates/draft/cost) stays cleartext — the §6 envelope.
+// Everything under `content` is what must become opaque at rest.
+const visit = {
+  id: 7,
+  startDate: 1733200000000,
+  endDate: 1733201800000,
+  draft: false,
+  cost: { total: { usd: 0.04 } },
+  content: {
+    name: 'Whether to leave the job',
+    icon: '🪧',
+    messages: [
+      { role: 'user', text: 'I have a stable job but I feel like it is quietly costing me my twenties.' },
+      { role: 'keeper', text: 'Two voices want to take this up — the Steward and the Lever…' },
+    ],
+    summary: {
+      headline: 'Security versus the cost of staying',
+      keyTopics: ['career', 'risk', 'identity'],
+      openThreads: ['What would you regret not having tried at 40?'],
+    },
+    plan: '- Name the worst realistic outcome of leaving\n- Give it a deadline, not an open question',
+  },
+};
+
+function showServerView(stored) {
+  line(dim('  what the operator has on disk:'));
+  line(dim('    enc.content = ' + JSON.stringify(stored.enc.content).slice(0, 72) + '…'));
+  line(dim('    wrappedCEK  = ' + JSON.stringify(stored.wrappedCEK).slice(0, 72) + '…'));
+  // Prove no plaintext leaked into the at-rest blob.
+  const blob = JSON.stringify(stored);
+  const leaked = ['twenties', 'Steward', 'Security versus', 'regret'].filter((w) => blob.includes(w));
+  if (leaked.length === 0) ok('at-rest blob contains no plaintext content');
+  else no('LEAK: plaintext found in blob: ' + leaked.join(', '));
+}
+
+async function tryRead(label, openFn) {
+  try {
+    const cek = await openFn();
+    const content = await decryptRecord(cek, atRest.enc.content);
+    return { read: true, headline: content.summary.headline };
+  } catch {
+    return { read: false };
+  }
+}
+
+let atRest; // the stored blob, reused across reader attempts
+
+line('\x1b[1m═══ Client-side encryption — envelope demo ═══\x1b[0m');
+line(dim('visit #7 plaintext headline: "' + visit.content.summary.headline + '"'));
+
+// --- Encrypt once under a per-user CEK --------------------------------------
+h('1. Encrypt the visit content under a per-user CEK (§3)');
+const cek = await generateCEK();
+const encContent = await encryptRecord(cek, visit.content);
+ok('content encrypted (AES-GCM, unique IV) — CEK never leaves the client');
+
+// =============================================================================
+// TIER 1 — passphrase (the §1/§2 hard guarantee)
+// =============================================================================
+h('2. Tier: PASSPHRASE — operator must not be able to read');
+const passphrase = 'correct horse battery staple';
+const wrappedPass = await wrapCEK_passphrase(cek, passphrase);
+atRest = { id: visit.id, startDate: visit.startDate, draft: visit.draft, cost: visit.cost,
+           enc: { content: encContent }, wrappedCEK: wrappedPass };
+showServerView(atRest);
+
+const operatorNoPass = await tryRead('operator', async () => {
+  // The operator has the full disk but not the passphrase. Best they can do is guess.
+  return unwrapCEK_passphrase(atRest.wrappedCEK, 'password123');
+});
+operatorNoPass.read ? no('operator READ it (should not happen)') : ok('operator cannot read (no passphrase → unwrap fails)');
+
+const userPass = await tryRead('user', () => unwrapCEK_passphrase(atRest.wrappedCEK, passphrase));
+userPass.read ? ok('user unlocks with passphrase → "' + userPass.headline + '"') : no('user could not read (bug)');
+
+// =============================================================================
+// TIER 2 — device key (no-signing default; operator still cannot read)
+// =============================================================================
+h('3. Tier: DEVICE — no passphrase typed; operator still cannot read');
+const deviceKey = generateRawKey(); // lives only on the device (localStorage / PRF in prod)
+const wrappedDev = await wrapCEK_device(cek, deviceKey);
+atRest = { ...atRest, wrappedCEK: wrappedDev };
+showServerView(atRest);
+
+const operatorNoDevice = await tryRead('operator', () => unwrapCEK_device(atRest.wrappedCEK, generateRawKey()));
+operatorNoDevice.read ? no('operator READ it (should not happen)') : ok('operator cannot read (device key never sent to server)');
+
+const userDevice = await tryRead('user', () => unwrapCEK_device(atRest.wrappedCEK, deviceKey));
+userDevice.read ? ok('device unlocks silently → "' + userDevice.headline + '" (no passphrase)') : no('device could not read (bug)');
+
+// =============================================================================
+// TIER 3 — managed / KMS (zero friction; operator CAN read — §12 weaker tier)
+// =============================================================================
+h('4. Tier: MANAGED — operator holds the key, so operator CAN read (weaker tier)');
+const kmsKey = generateRawKey(); // stands in for a server-held KMS/HSM key (§12)
+const wrappedMgd = await wrapCEK_managed(cek, kmsKey);
+atRest = { ...atRest, wrappedCEK: wrappedMgd };
+showServerView(atRest);
+
+const operatorManaged = await tryRead('operator', () => unwrapCEK_managed(atRest.wrappedCEK, kmsKey));
+operatorManaged.read
+  ? ok('operator CAN read → "' + operatorManaged.headline + '"  ' + dim('(expected: this is the recoverable tier)'))
+  : no('operator could not read (bug — managed tier should be operator-readable)');
+line(dim('  §12: this only resists a leak where the KMS key is NOT also taken.'));
+line(dim('       Co-locating kmsKey with the disk (e.g. CREDENTIALS_KEY in env) defeats it.'));
+
+// =============================================================================
+// Re-wrap upgrade path (§11): change tier WITHOUT re-encrypting the records.
+// =============================================================================
+h('5. Upgrade managed → passphrase by RE-WRAPPING the CEK (no re-encryption)');
+const contentBefore = JSON.stringify(atRest.enc.content);
+// Operator-readable today (managed). User upgrades to the hard guarantee:
+const cekRecovered = await unwrapCEK_managed(atRest.wrappedCEK, kmsKey);
+const upgraded = await wrapCEK_passphrase(cekRecovered, 'a brand new passphrase only I know');
+atRest = { ...atRest, wrappedCEK: upgraded };
+const contentAfter = JSON.stringify(atRest.enc.content);
+
+contentBefore === contentAfter ? ok('record ciphertext untouched (only the wrapped CEK changed)') : no('records were rewritten (should not be)');
+const operatorAfter = await tryRead('operator', () => unwrapCEK_managed(atRest.wrappedCEK, kmsKey));
+operatorAfter.read ? no('operator still readable after upgrade (bug)') : ok('operator can no longer read — upgraded to the hard guarantee');
+
+line();
+line('\x1b[1m═══ done ═══\x1b[0m');

package/envelope.js

@@ -0,0 +1,197 @@
+// =============================================================================
+// Client-side encryption — envelope core (PROTOTYPE)
+//
+// Implements §11 of todo/client-side-encryption.md: every record is encrypted
+// at rest under a per-user *content key* (CEK); what differs per account is only
+// how that CEK is *wrapped*. One engine, three tiers, an upgrade path between
+// them by re-wrapping the CEK (no re-encryption of the records).
+//
+//   record plaintext  --AES-GCM(CEK)-->  { iv, ct }      (the at-rest blob)
+//   CEK               --wrap(KEK)----->  wrappedCEK       (the only per-tier part)
+//
+// Tiers (§11):
+//   - passphrase : KEK = KDF(passphrase, salt).  Operator cannot read.   (§1/§2 hard guarantee)
+//   - device     : KEK = a random key held only on the device.            Operator cannot read.
+//   - managed    : KEK = a key the operator/KMS holds.                    Operator CAN read.  (§12 weaker tier)
+//
+// Runs unchanged in the browser and in Node 20+ (both expose globalThis.crypto
+// with SubtleCrypto), so the same module backs the live app and demo.mjs.
+//
+// KDF is Argon2id (memory-hard, @noble/hashes — pure JS, runs in browser + RN +
+// Node). The wrapped record stores the exact params so a record always reproduces
+// its own KEK. Legacy PBKDF2 records (early prototype) are still read, by the
+// `kdf.name` branch in deriveKEKFromPassphrase, so switching the default didn't
+// strand any existing passphrase account.
+//
+// REMAINING PROTOTYPE CAVEAT:
+//   * The device tier uses a random local key as a stand-in for the production
+//     WebAuthn-PRF / non-extractable platform key. Same envelope either way.
+// =============================================================================
+
+import { argon2id } from '@noble/hashes/argon2';
+
+// Optional-chained so this module is import-safe on platforms without Web Crypto
+// (e.g. RN/Hermes). `subtle` is only ever *used* inside functions, which only
+// run when ENCRYPTED_VISITS is on (web). Touching it at import must not throw.
+const subtle = globalThis.crypto?.subtle;
+const randomBytes = (n) => globalThis.crypto.getRandomValues(new Uint8Array(n));
+
+// --- base64 <-> bytes (browser + Node, no Buffer dependency) -----------------
+const b64 = {
+  encode(bytes) {
+    let s = '';
+    for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]);
+    // btoa exists in browsers and in Node 16+ globals.
+    return btoa(s);
+  },
+  decode(str) {
+    const s = atob(str);
+    const out = new Uint8Array(s.length);
+    for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i);
+    return out;
+  },
+};
+
+const utf8 = {
+  encode: (str) => new TextEncoder().encode(str),
+  decode: (bytes) => new TextDecoder().decode(bytes),
+};
+
+// Argon2id parameters (memory-hard). m is KiB → 64 MiB here; t = passes;
+// p = lanes. Stored in the wrapped record so a record reproduces its own KEK;
+// tune for the device class without breaking existing records. Derivation runs
+// once per provision/unlock, not per turn.
+const KDF = { name: 'argon2id', t: 3, m: 65536, p: 1 };
+
+// =============================================================================
+// CEK — the per-user content key (§3, §11). One per account; never changes.
+// Extractable so it can be wrapped under each tier's KEK; the raw bytes only
+// ever exist in memory during wrap/unwrap, never persisted unwrapped.
+// =============================================================================
+
+export async function generateCEK() {
+  return subtle.generateKey({ name: 'AES-GCM', length: 256 }, true, ['encrypt', 'decrypt']);
+}
+
+export async function exportCEKRaw(cek) {
+  return new Uint8Array(await subtle.exportKey('raw', cek));
+}
+
+export async function importCEKRaw(rawBytes) {
+  return subtle.importKey('raw', rawBytes, { name: 'AES-GCM' }, true, ['encrypt', 'decrypt']);
+}
+
+// =============================================================================
+// Per-record content encryption (§3). Unique IV per call — never reused under a
+// key. The output { iv, ct } is exactly what the server stores; it is opaque
+// without the CEK.
+// =============================================================================
+
+export async function encryptRecord(cek, plainObject) {
+  const iv = randomBytes(12);
+  const plaintext = utf8.encode(JSON.stringify(plainObject));
+  const ct = new Uint8Array(await subtle.encrypt({ name: 'AES-GCM', iv }, cek, plaintext));
+  return { v: 1, alg: 'AES-GCM', iv: b64.encode(iv), ct: b64.encode(ct) };
+}
+
+export async function decryptRecord(cek, env) {
+  const iv = b64.decode(env.iv);
+  const ct = b64.decode(env.ct);
+  const plaintext = new Uint8Array(await subtle.decrypt({ name: 'AES-GCM', iv }, cek, ct));
+  return JSON.parse(utf8.decode(plaintext));
+}
+
+// =============================================================================
+// KEK derivation / import. A KEK only ever wraps the CEK — it never touches
+// record content directly.
+// =============================================================================
+
+// Passphrase tier: KEK = KDF(passphrase, salt). The passphrase and KEK never
+// leave the client; the server stores only `salt` (not secret), the KDF params,
+// and the wrapped CEK. `kdf` (from the stored record) selects the algorithm so a
+// record reproduces its own KEK — including legacy PBKDF2 records.
+async function deriveKEKFromPassphrase(passphrase, salt, kdf = KDF) {
+  if (kdf.name === 'PBKDF2') {
+    // Legacy early-prototype records — still readable.
+    const baseKey = await subtle.importKey('raw', utf8.encode(passphrase), 'PBKDF2', false, ['deriveKey']);
+    return subtle.deriveKey(
+      { name: 'PBKDF2', hash: kdf.hash, salt, iterations: kdf.iterations },
+      baseKey,
+      { name: 'AES-GCM', length: 256 },
+      false,
+      ['encrypt', 'decrypt'],
+    );
+  }
+  // Argon2id (default). @noble returns 32 raw bytes → AES-256 key. Awaited so a
+  // platform may swap in an async native Argon2 (RN/libsodium — noble freezes
+  // Hermes); `await` is a no-op on noble's synchronous return.
+  const raw = await argon2id(utf8.encode(passphrase), salt, { t: kdf.t, m: kdf.m, p: kdf.p, dkLen: 32 });
+  return subtle.importKey('raw', raw, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']);
+}
+
+// Device / managed tiers: KEK is a raw 256-bit key (held on the device, or by the
+// operator/KMS). Imported as a non-extractable AES-GCM key used only to wrap.
+async function importRawKEK(rawBytes) {
+  return subtle.importKey('raw', rawBytes, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']);
+}
+
+// A fresh random 256-bit key — used for the device tier (stand-in for WebAuthn-PRF)
+// and to simulate the operator/KMS key in the managed tier.
+export function generateRawKey() {
+  return randomBytes(32);
+}
+
+// =============================================================================
+// Wrap / unwrap the CEK under a KEK. wrappedCEK is AES-GCM(KEK, rawCEK).
+// =============================================================================
+
+async function wrapCEKWithKEK(cek, kek) {
+  const iv = randomBytes(12);
+  const rawCEK = await exportCEKRaw(cek);
+  const wrapped = new Uint8Array(await subtle.encrypt({ name: 'AES-GCM', iv }, kek, rawCEK));
+  return { iv: b64.encode(iv), wrapped: b64.encode(wrapped) };
+}
+
+async function unwrapCEKWithKEK(blob, kek) {
+  const iv = b64.decode(blob.iv);
+  const wrapped = b64.decode(blob.wrapped);
+  const rawCEK = new Uint8Array(await subtle.decrypt({ name: 'AES-GCM', iv }, kek, wrapped));
+  return importCEKRaw(rawCEK);
+}
+
+// --- Tier: passphrase --------------------------------------------------------
+export async function wrapCEK_passphrase(cek, passphrase) {
+  const salt = randomBytes(16);
+  const kek = await deriveKEKFromPassphrase(passphrase, salt);
+  const { iv, wrapped } = await wrapCEKWithKEK(cek, kek);
+  return { tier: 'passphrase', kdf: { ...KDF }, salt: b64.encode(salt), iv, wrapped };
+}
+
+export async function unwrapCEK_passphrase(blob, passphrase) {
+  const kek = await deriveKEKFromPassphrase(passphrase, b64.decode(blob.salt), blob.kdf || KDF);
+  return unwrapCEKWithKEK(blob, kek);
+}
+
+// --- Tier: device (random local key; WebAuthn-PRF is the production upgrade) --
+export async function wrapCEK_device(cek, deviceKeyRaw) {
+  const kek = await importRawKEK(deviceKeyRaw);
+  const { iv, wrapped } = await wrapCEKWithKEK(cek, kek);
+  return { tier: 'device', iv, wrapped };
+}
+
+export async function unwrapCEK_device(blob, deviceKeyRaw) {
+  return unwrapCEKWithKEK(blob, await importRawKEK(deviceKeyRaw));
+}
+
+// --- Tier: managed (operator/KMS-held key) -----------------------------------
+export async function wrapCEK_managed(cek, managedKeyRaw) {
+  const kek = await importRawKEK(managedKeyRaw);
+  const { iv, wrapped } = await wrapCEKWithKEK(cek, kek);
+  return { tier: 'managed', iv, wrapped };
+}
+
+export async function unwrapCEK_managed(blob, managedKeyRaw) {
+  return unwrapCEKWithKEK(blob, await importRawKEK(managedKeyRaw));
+}
+
+export const _internal = { b64, utf8, KDF };

package/keyring.js

@@ -0,0 +1,208 @@
+// =============================================================================
+// Client-side encryption — keyring / tier manager (PROTOTYPE)
+//
+// The single authority over a user's CEK and which §11 tier wraps it. Holds the
+// unlocked CEK in memory for the session.
+//
+// The wrapped-CEK *record* lives SERVER-SIDE (backend/encryption, via keyringApi)
+// so clearing browser storage doesn't lose the key, the passphrase tier works
+// across devices, and the managed tier is operator-recoverable. The one thing
+// that must NOT go to the server is the device tier's KEK — the *device key* —
+// which stays in local storage (that's what keeps the operator out for that
+// tier). Managed is wrapped by a server-held key, so its record carries the raw
+// CEK over the wire (the tier's intended operator-can-read property).
+//
+// The backends are injectable (__setRecordBackend / __setStorageBackend /
+// __setSessionBackend) so the Node harness (keyring.mjs) runs the real logic
+// in-memory. envelope.js is pure.
+// =============================================================================
+
+import {
+  generateCEK, generateRawKey, exportCEKRaw, importCEKRaw, _internal,
+  wrapCEK_passphrase, unwrapCEK_passphrase,
+  wrapCEK_device, unwrapCEK_device,
+} from './envelope.js';
+
+const { b64 } = _internal;
+
+// Honest, scope-bounded labeling copy (§8). `guarantee: 'hard'` = operator
+// cannot read; `'soft'` = operator can read.
+export const TIER_INFO = {
+  passphrase: {
+    label: 'Passphrase',
+    guarantee: 'hard',
+    summary: 'Encrypted with a key only your passphrase unlocks. We never receive the passphrase, so we cannot read your stored record, and it works on any device you sign in from. If you forget the passphrase it is permanently unrecoverable.',
+  },
+  device: {
+    label: 'This device',
+    guarantee: 'hard',
+    summary: 'Encrypted with a key kept on this device — no passphrase to type. We cannot read your stored record. It is tied to this device: Clear this browser / app memory, and the record becomes unreadable.',
+  },
+  managed: {
+    label: 'Managed',
+    guarantee: 'soft',
+    summary: 'Encrypted at rest, but we hold the key, so we can read your records if compelled — but you can never lock yourself out, since there is no passphrase or device key for you to lose. Protects against a data leak.',
+  },
+};
+
+// --- injectable backends -----------------------------------------------------
+// Record backend (server): { get(userId) -> record|null, put(userId, record) }.
+let recordBackend = null;
+export function __setRecordBackend(b) { recordBackend = b; }
+async function records() {
+  if (!recordBackend) recordBackend = await import('./keyringApi.js');
+  return recordBackend;
+}
+const getRecord = async (userId) => (await records()).get(userId);
+const putRecord = async (userId, record) => (await records()).put(userId, record);
+
+// Local storage backend (device key only — must never reach the server).
+let storageBackend = null;
+export function __setStorageBackend(b) { storageBackend = b; }
+async function storage() {
+  if (!storageBackend) storageBackend = (await import('../storage')).storage;
+  return storageBackend;
+}
+const deviceKeyKey = (userId) => `crossroads_enc_devicekey:${userId}`;
+async function loadDeviceKey(userId) {
+  const raw = await (await storage()).getItem(deviceKeyKey(userId));
+  return raw ? b64.decode(raw) : null;
+}
+async function saveDeviceKey(userId, rawBytes) {
+  await (await storage()).setItem(deviceKeyKey(userId), b64.encode(rawBytes));
+}
+
+// Session backend (the *unlocked* CEK, cached so a web refresh doesn't force the
+// passphrase tier to re-unlock — and re-run Argon2 — on every load). Web:
+// sessionStorage (survives refresh, cleared on tab/browser close, never on disk),
+// plus an optional requestFromPeers() that fetches the CEK from another open
+// same-origin tab (so a fresh tab needn't re-prompt); native/Node: in-memory
+// only. Distinct from the device-key (localStorage) backend. Injectable for the
+// harness (which omits requestFromPeers).
+let sessionBackend = null;
+export function __setSessionBackend(b) { sessionBackend = b; }
+async function sessionStore() {
+  if (!sessionBackend) sessionBackend = (await import('../sessionStore')).sessionStore;
+  return sessionBackend;
+}
+const cekKey = (userId) => `crossroads_enc_cek:${userId}`;
+async function cacheUnlockedCEK(userId, cek) {
+  try { await (await sessionStore()).setItem(cekKey(userId), b64.encode(await exportCEKRaw(cek))); }
+  catch { /* session cache is best-effort — never block an unlock on it */ }
+}
+async function clearUnlockedCEK(userId) {
+  try { await (await sessionStore()).removeItem(cekKey(userId)); } catch { /* ignore */ }
+}
+async function clearAllUnlockedCEKs() {
+  try { await (await sessionStore()).clear(); } catch { /* ignore */ }
+}
+
+// In-memory unlocked CEKs (cleared on lock / logout).
+const unlocked = new Map();
+
+// Build the server record for a CEK under a tier (mints + stores the device key
+// locally for the device tier; emits the raw CEK for managed).
+async function buildRecord(userId, cek, tier, opts = {}) {
+  if (tier === 'device') {
+    const dk = generateRawKey();
+    await saveDeviceKey(userId, dk);
+    return { tier: 'device', env: await wrapCEK_device(cek, dk) };
+  }
+  if (tier === 'passphrase') {
+    if (!opts.passphrase) throw new Error('PASSPHRASE_REQUIRED');
+    return { tier: 'passphrase', env: await wrapCEK_passphrase(cek, opts.passphrase) };
+  }
+  if (tier === 'managed') {
+    return { tier: 'managed', cek: b64.encode(await exportCEKRaw(cek)) };
+  }
+  throw new Error(`UNKNOWN_TIER:${tier}`);
+}
+
+async function cekFromRecord(userId, rec, opts = {}) {
+  if (rec.tier === 'device') {
+    const dk = await loadDeviceKey(userId);
+    if (!dk) throw new Error('NO_DEVICE_KEY'); // device-tier record, but not this device
+    return unwrapCEK_device(rec.env, dk);
+  }
+  if (rec.tier === 'passphrase') {
+    if (!opts.passphrase) throw new Error('PASSPHRASE_REQUIRED');
+    return unwrapCEK_passphrase(rec.env, opts.passphrase);
+  }
+  if (rec.tier === 'managed') {
+    return importCEKRaw(b64.decode(rec.cek)); // server already unwrapped
+  }
+  throw new Error(`UNKNOWN_TIER:${rec.tier}`);
+}
+
+// --- public API --------------------------------------------------------------
+export async function getTier(userId) { return (await getRecord(userId))?.tier ?? null; }
+export function getTierInfo(tier) { return TIER_INFO[tier] ?? null; }
+export async function isProvisioned(userId) { return (await getRecord(userId)) != null; }
+export function getUnlockedCEK(userId) { return unlocked.get(userId) ?? null; }
+export function lock(userId) { unlocked.delete(userId); clearUnlockedCEK(userId); }
+export function lockAll() { unlocked.clear(); clearAllUnlockedCEKs(); }
+
+// Re-hydrate the unlocked CEK so the passphrase tier doesn't re-prompt: from this
+// tab's session cache (after a web refresh wiped memory), or — failing that —
+// from an already-open same-origin tab over the session backend's peer channel
+// (a fresh tab has its own empty sessionStorage). A peer answer is cached locally
+// so later refreshes in this tab are fast. No-op if it's already in memory or
+// nothing is available anywhere. Returns the CEK, or null.
+export async function restoreSession(userId) {
+  const live = unlocked.get(userId);
+  if (live) return live;
+  const store = await sessionStore();
+  const key = cekKey(userId);
+  let raw;
+  try { raw = await store.getItem(key); } catch { return null; }
+  if (!raw && store.requestFromPeers) {
+    try { raw = await store.requestFromPeers(key); } catch { raw = null; }
+    if (raw) { try { await store.setItem(key, raw); } catch { /* best-effort local cache */ } }
+  }
+  if (!raw) return null;
+  const cek = await importCEKRaw(b64.decode(raw));
+  unlocked.set(userId, cek);
+  return cek;
+}
+
+export async function provision(userId, tier, opts = {}) {
+  const cek = await generateCEK();
+  await putRecord(userId, await buildRecord(userId, cek, tier, opts));
+  unlocked.set(userId, cek);
+  await cacheUnlockedCEK(userId, cek);
+  return cek;
+}
+
+export async function unlock(userId, opts = {}) {
+  const rec = await getRecord(userId);
+  if (!rec) throw new Error('NOT_PROVISIONED');
+  const cek = await cekFromRecord(userId, rec, opts);
+  unlocked.set(userId, cek);
+  await cacheUnlockedCEK(userId, cek);
+  return cek;
+}
+
+// Default no-signing path: device tier, auto-provisioned then auto-unlocked.
+export async function ensureDevice(userId) {
+  if (unlocked.has(userId)) return unlocked.get(userId);
+  const rec = await getRecord(userId);
+  if (!rec) return provision(userId, 'device');
+  return unlock(userId);
+}
+
+// Move tiers by RE-WRAPPING the in-memory CEK (no re-encryption of records).
+export async function changeTier(userId, newTier, opts = {}) {
+  const cek = unlocked.get(userId);
+  if (!cek) throw new Error('LOCKED');
+  await putRecord(userId, await buildRecord(userId, cek, newTier, opts));
+  return cek;
+}
+
+// Forgotten-passphrase escape: discard the old record + device key and provision
+// a fresh device-tier CEK. The old record stays unreadable (unrecoverable, by
+// design — the proof the passphrase guarantee was real). Caller warns first.
+export async function reset(userId) {
+  lock(userId);
+  await (await storage()).removeItem(deviceKeyKey(userId));
+  return provision(userId, 'device'); // overwrites the server record
+}

package/keyring.mjs

@@ -0,0 +1,106 @@
+// =============================================================================
+// Client-side encryption — keyring/tier verification (PROTOTYPE)
+//
+//   node frontend/src/services/crypto/keyring.mjs
+//
+// Exercises the REAL keyring against an injected in-memory store: provision /
+// lock / unlock per tier, the passphrase gate, the device no-signing path, the
+// managed auto-unlock, the re-wrap upgrade (same CEK, no re-encryption), and the
+// honest per-tier labeling (§8).
+// =============================================================================
+
+import { encryptRecord, decryptRecord } from './envelope.js';
+import * as keyring from './keyring.js';
+
+// In-memory local storage backend (device key only).
+const mem = new Map();
+keyring.__setStorageBackend({
+  async getItem(k) { return mem.has(k) ? mem.get(k) : null; },
+  async setItem(k, v) { mem.set(k, v); },
+  async removeItem(k) { mem.delete(k); },
+});
+// In-memory record backend (stands in for the server-side keyring store; passes
+// records through verbatim, incl. managed's raw cek — the real server wraps it).
+const recs = new Map();
+keyring.__setRecordBackend({
+  async get(uid) { return recs.has(uid) ? recs.get(uid) : null; },
+  async put(uid, record) { recs.set(uid, record); },
+});
+// In-memory session backend (stands in for web sessionStorage — the unlocked-CEK
+// cache that lets a refresh skip re-unlock).
+const sess = new Map();
+keyring.__setSessionBackend({
+  async getItem(k) { return sess.has(k) ? sess.get(k) : null; },
+  async setItem(k, v) { sess.set(k, v); },
+  async removeItem(k) { sess.delete(k); },
+  async clear() { sess.clear(); },
+});
+
+let pass = 0, fail = 0;
+const ok = (c, m) => { if (c) { pass++; console.log('  \x1b[32m✓\x1b[0m ' + m); } else { fail++; console.log('  \x1b[31m✗ ' + m + '\x1b[0m'); } };
+async function throws(fn, code, m) {
+  try { await fn(); ok(false, m + ' (did not throw)'); }
+  catch (e) { ok(e.message.startsWith(code) || e.name === code, m + ' → ' + (e.name === code ? e.name : e.message)); }
+}
+// Prove a CEK works by round-tripping a record through it.
+async function cekReads(cek, env) { try { return (await decryptRecord(cek, env)).t === 'secret'; } catch { return false; } }
+
+console.log('\x1b[1m═══ keyring / tier manager ═══\x1b[0m');
+
+// --- device tier (no-signing default) ---------------------------------------
+console.log('\n1. Device tier — auto-provision, lock, auto-unlock');
+const dCek = await keyring.ensureDevice('user_dev');
+const dEnv = await encryptRecord(dCek, { t: 'secret' });
+ok(await keyring.getTier('user_dev') === 'device', 'provisioned as device');
+keyring.lock('user_dev');
+ok(keyring.getUnlockedCEK('user_dev') === null, 'lock clears in-memory CEK');
+const dCek2 = await keyring.ensureDevice('user_dev'); // auto-unlock, no secret
+ok(await cekReads(dCek2, dEnv), 'device auto-unlock recovers the SAME CEK (no passphrase)');
+
+// --- passphrase tier (hard guarantee + gate) --------------------------------
+console.log('\n2. Passphrase tier — gate on the passphrase');
+const pCek = await keyring.provision('user_pp', 'passphrase', { passphrase: 'right pass' });
+const pEnv = await encryptRecord(pCek, { t: 'secret' });
+keyring.lock('user_pp');
+await throws(() => keyring.unlock('user_pp'), 'PASSPHRASE_REQUIRED', 'unlock without passphrase refused');
+await throws(() => keyring.unlock('user_pp', { passphrase: 'wrong' }), 'OperationError', 'unlock with wrong passphrase fails');
+const pCek2 = await keyring.unlock('user_pp', { passphrase: 'right pass' });
+ok(await cekReads(pCek2, pEnv), 'unlock with correct passphrase recovers the CEK');
+
+// --- managed tier (operator-held key; auto-unlock, recoverable) -------------
+console.log('\n3. Managed tier — recoverable, no user secret');
+const mCek = await keyring.provision('user_mg', 'managed');
+const mEnv = await encryptRecord(mCek, { t: 'secret' });
+keyring.lock('user_mg');
+const mCek2 = await keyring.unlock('user_mg'); // no secret needed
+ok(await cekReads(mCek2, mEnv), 'managed unlock needs no user secret (recoverable tier)');
+
+// --- re-wrap upgrade (§11): managed → passphrase, same CEK, no re-encryption -
+console.log('\n4. Upgrade managed → passphrase by re-wrapping');
+const upEnv = await encryptRecord(keyring.getUnlockedCEK('user_mg'), { t: 'secret' });
+await keyring.changeTier('user_mg', 'passphrase', { passphrase: 'new secret' });
+ok(await keyring.getTier('user_mg') === 'passphrase', 'tier is now passphrase');
+ok(await cekReads(keyring.getUnlockedCEK('user_mg'), upEnv), 'pre-upgrade ciphertext still decrypts (same CEK — no re-encryption)');
+keyring.lock('user_mg');
+await throws(() => keyring.unlock('user_mg'), 'PASSPHRASE_REQUIRED', 'after upgrade, unlock now demands the passphrase');
+ok(await cekReads(await keyring.unlock('user_mg', { passphrase: 'new secret' }), upEnv), 'unlocks with the new passphrase');
+
+// --- honest labeling (§8) ----------------------------------------------------
+console.log('\n5. Per-account labeling guarantees (§8)');
+ok(keyring.getTierInfo('passphrase').guarantee === 'hard', 'passphrase = hard guarantee');
+ok(keyring.getTierInfo('device').guarantee === 'hard', 'device = hard guarantee');
+ok(keyring.getTierInfo('managed').guarantee === 'soft', 'managed = soft guarantee (operator can read)');
+ok(/cannot read/.test(keyring.getTierInfo('passphrase').summary), 'passphrase copy states operator cannot read');
+ok(/we hold the key/.test(keyring.getTierInfo('managed').summary), 'managed copy states operator holds the key');
+
+// --- reset (forgotten passphrase) — fresh key, old data abandoned -----------
+console.log('\n6. Reset (forgotten passphrase) — fresh key, old record abandoned');
+const rCek = await keyring.provision('user_rs', 'passphrase', { passphrase: 'the old one' });
+const rEnv = await encryptRecord(rCek, { t: 'secret' });
+keyring.lock('user_rs');
+const freshCek = await keyring.reset('user_rs');
+ok(await keyring.getTier('user_rs') === 'device', 'reset drops to the device (no-signing) tier');
+ok(!(await cekReads(freshCek, rEnv)), 'pre-reset ciphertext is unreadable under the fresh CEK (unrecoverable, by design)');
+
+console.log(`\n\x1b[1m═══ ${fail === 0 ? '\x1b[32mall ' + pass + ' checks passed' : '\x1b[31m' + fail + ' FAILED'}\x1b[0m\x1b[1m ═══\x1b[0m`);
+process.exit(fail === 0 ? 0 : 1);

package/longitudinal.mjs

@@ -0,0 +1,76 @@
+// =============================================================================
+// Client-side encryption — longitudinal consent-gate verification (PROTOTYPE)
+//
+//   node frontend/src/services/crypto/longitudinal.mjs
+//
+// Locks the consent gate at the client-side pure-logic level — the same claims
+// backend/discussion/carry-path.test.js makes server-side: a declined read never
+// resurfaces, only accepted reads carry, resolved forks leave the greeting set.
+// Plus the store-encryption round-trip (the array encrypts opaque and restores).
+// =============================================================================
+
+import {
+  reconcileHeldForks, updateHeldFork, openForks,
+  reconcilePendingJudgments, decideJudgment, confirmedJudgments,
+} from './longitudinalLogic.js';
+import { generateCEK, encryptRecord, decryptRecord } from './envelope.js';
+
+let pass = 0, fail = 0;
+const ok = (c, m) => { if (c) { pass++; console.log('  \x1b[32m✓\x1b[0m ' + m); } else { fail++; console.log('  \x1b[31m✗ ' + m + '\x1b[0m'); } };
+
+console.log('\x1b[1m═══ longitudinal consent gate (client-side) ═══\x1b[0m');
+
+// --- judgments: the consent gate --------------------------------------------
+console.log('\n1. Judgments — rejected never resurfaces, only accepted carries');
+let J = [];
+J = reconcilePendingJudgments(J, 1, [{ text: 'You avoid conflict', basis: '...' }, { text: 'You over-plan', basis: '...' }]);
+ok(J.length === 2 && J.every(j => j.status === 'pending'), 'two reads land as pending');
+ok(confirmedJudgments(J).length === 0, 'pending reads do NOT carry');
+
+// User rejects the first, accepts the second.
+J = decideJudgment(J, J[0].id, 'rejected').store;
+J = decideJudgment(J, J[1].id, 'accepted').store;
+ok(confirmedJudgments(J).length === 1 && confirmedJudgments(J)[0].text === 'You over-plan', 'only the accepted read carries');
+
+// A later visit re-proposes BOTH (stateless summary). The gate must not resurface them.
+const before = J.length;
+J = reconcilePendingJudgments(J, 2, [{ text: 'You avoid conflict' }, { text: 'You over-plan' }]);
+ok(J.length === before, 'a re-proposed rejected/accepted read is NOT re-added (dedup vs ALL statuses)');
+ok(!confirmedJudgments(J).some(j => j.text === 'You avoid conflict'), 'the rejected read never enters the carry set');
+
+// A genuinely new read still lands.
+J = reconcilePendingJudgments(J, 2, [{ text: 'You seek others approval' }]);
+ok(J.some(j => j.text === 'You seek others approval' && j.status === 'pending'), 'a new read still lands as pending');
+
+// --- held forks: open-only carry, resolved may recur ------------------------
+console.log('\n2. Held forks — greeting revisits OPEN only; resolved may recur');
+let F = [];
+F = reconcileHeldForks(F, 1, [{ fork: 'Stay vs leave', valueQuestion: 'security vs growth' }]);
+ok(openForks(F).length === 1, 'fork lands open');
+const dup = reconcileHeldForks(F, 2, [{ fork: 'Stay vs leave', valueQuestion: 'security vs growth' }]);
+ok(dup.length === 1, 'duplicate of an OPEN fork is not re-added');
+
+// User resolves it → leaves the greeting set.
+F = updateHeldFork(F, F[0].id, { status: 'resolved', resolution: 'left' }).store;
+ok(openForks(F).length === 0, 'resolved fork drops out of the greeting open set');
+// The same tension genuinely recurs later → allowed to re-open.
+F = reconcileHeldForks(F, 3, [{ fork: 'Stay vs leave', valueQuestion: 'security vs growth' }]);
+ok(openForks(F).length === 1, 'a resolved fork may re-open when it recurs');
+ok(F.length === 2, 'reconcile is append-only (old resolved entry retained)');
+
+// reconcile never mutates an existing entry's user-owned status.
+const resolvedStill = F.find(f => f.status === 'resolved');
+ok(!!resolvedStill, 'reconcile never flipped the resolved entry back to open');
+
+// --- store encryption round-trip --------------------------------------------
+console.log('\n3. Encrypted store round-trip');
+const cek = await generateCEK();
+const env = await encryptRecord(cek, J);
+const blob = JSON.stringify(env);
+ok(!blob.includes('over-plan') && !blob.includes('approval'), 'encrypted judgments store is opaque at rest');
+const restored = await decryptRecord(cek, env);
+ok(JSON.stringify(restored) === JSON.stringify(J), 'store decrypts back exactly');
+ok(confirmedJudgments(restored).length === confirmedJudgments(J).length, 'consent gate intact after round-trip');
+
+console.log(`\n\x1b[1m═══ ${fail === 0 ? '\x1b[32mall ' + pass + ' checks passed' : '\x1b[31m' + fail + ' FAILED'}\x1b[0m\x1b[1m ═══\x1b[0m`);
+process.exit(fail === 0 ? 0 : 1);

package/longitudinalLogic.js

@@ -0,0 +1,99 @@
+// =============================================================================
+// Client-side encryption — longitudinal logic, ported pure (PROTOTYPE)
+//
+// When the longitudinal stores (heldForks / judgments) are client-encrypted,
+// the server can't read them, so the reconcile + consent-gate logic that lives
+// in backend/longitudinal/db.js must run CLIENT-SIDE. This is that logic, ported
+// as pure array→array functions (no fs, no per-user paths) so it is identical in
+// behavior and Node-verifiable (longitudinal.mjs).
+//
+// The load-bearing invariants preserved verbatim from the server:
+//   * Held forks: append-only; status (resolve/retire) is user-only and never
+//     touched by reconcile; dedup against OPEN forks only (a resolved fork may
+//     legitimately re-open).
+//   * Judgments (consent gate): dedup against ALL statuses incl. `rejected`, so
+//     a declined read is never silently re-surfaced; only `accepted` judgments
+//     are ever eligible to carry into a prompt.
+// =============================================================================
+
+const uuid = () => globalThis.crypto.randomUUID();
+const nowMs = () => Date.now();
+
+function normalize(s) {
+  return String(s || '').toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+}
+
+// --- held forks --------------------------------------------------------------
+export function reconcileHeldForks(store, fromVisitId, newForks) {
+  if (!Array.isArray(newForks) || newForks.length === 0) return store;
+  const next = [...store];
+  const openKeys = new Set(
+    next.filter(f => f.status === 'open').map(f => `${normalize(f.fork)}|${normalize(f.valueQuestion)}`)
+  );
+  const now = nowMs();
+  for (const f of newForks) {
+    if (!f || !f.fork) continue;
+    const key = `${normalize(f.fork)}|${normalize(f.valueQuestion)}`;
+    if (openKeys.has(key)) continue;
+    openKeys.add(key);
+    next.push({
+      id: `hf_${uuid()}`,
+      fork: f.fork, sideA: f.sideA || '', sideB: f.sideB || '', valueQuestion: f.valueQuestion || '',
+      fromVisitId, createdAt: now, status: 'open', resolution: null, updatedAt: now,
+    });
+  }
+  return next;
+}
+
+const HELD_FORK_STATUSES = new Set(['open', 'resolved', 'retired']);
+
+export function updateHeldFork(store, id, updates) {
+  const next = store.map(f => ({ ...f }));
+  const entry = next.find(f => f.id === id);
+  if (!entry) return { store, entry: null };
+  if (updates.status !== undefined) {
+    if (!HELD_FORK_STATUSES.has(updates.status)) throw new Error(`Invalid status: ${updates.status}`);
+    entry.status = updates.status;
+  }
+  if (updates.resolution !== undefined) entry.resolution = updates.resolution;
+  entry.updatedAt = nowMs();
+  return { store: next, entry };
+}
+
+// Open forks, for the returning greeting (the only forks it should revisit).
+export function openForks(store) {
+  return store.filter(f => f.status === 'open');
+}
+
+// --- judgments (consent gate) ------------------------------------------------
+export function reconcilePendingJudgments(store, fromVisitId, newJudgments) {
+  if (!Array.isArray(newJudgments) || newJudgments.length === 0) return store;
+  const next = [...store];
+  const seen = new Set(next.map(j => normalize(j.text))); // ALL statuses, incl. rejected
+  const now = nowMs();
+  for (const j of newJudgments) {
+    if (!j || !j.text) continue;
+    const key = normalize(j.text);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    next.push({ id: `jd_${uuid()}`, text: j.text, basis: j.basis || '', fromVisitId, status: 'pending', createdAt: now, decidedAt: null });
+  }
+  return next;
+}
+
+const JUDGMENT_DECISIONS = new Set(['accepted', 'rejected']);
+
+export function decideJudgment(store, id, status) {
+  if (!JUDGMENT_DECISIONS.has(status)) throw new Error(`Invalid decision: ${status}`);
+  const next = store.map(j => ({ ...j }));
+  const entry = next.find(j => j.id === id);
+  if (!entry) return { store, entry: null };
+  entry.status = status;
+  entry.decidedAt = nowMs();
+  return { store: next, entry };
+}
+
+// The ONLY judgments eligible to carry into a prompt (the consent gate).
+export function confirmedJudgments(store) {
+  return store.filter(j => j.status === 'accepted');
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@thecrossroads42/crypto",
+  "version": "0.1.0",
+  "description": "The Crossroads — client-side encryption primitives (audit kit). AES-GCM record envelope with Argon2id passphrase / device / managed key tiers. The privacy-critical code, published so the claims can be verified rather than trusted.",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    "./envelope": "./envelope.js",
+    "./keyring": "./keyring.js",
+    "./visitEnvelope": "./visitEnvelope.js",
+    "./longitudinalLogic": "./longitudinalLogic.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "envelope.js",
+    "keyring.js",
+    "visitEnvelope.js",
+    "longitudinalLogic.js",
+    "demo.mjs",
+    "keyring.mjs",
+    "longitudinal.mjs",
+    "roundtrip.mjs",
+    "verify-kit.mjs",
+    "KIT-MANIFEST.txt",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@noble/hashes": "^1.4.0"
+  },
+  "scripts": {
+    "verify": "node verify-kit.mjs",
+    "test": "node roundtrip.mjs && node keyring.mjs && node longitudinal.mjs && node demo.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thecrossroads42/crypto.git"
+  },
+  "keywords": [
+    "encryption",
+    "client-side-encryption",
+    "argon2",
+    "aes-gcm",
+    "crypto",
+    "thecrossroads"
+  ]
+}

package/roundtrip.mjs

@@ -0,0 +1,135 @@
+// =============================================================================
+// Client-side encryption — Layer 2 round-trip verification (PROTOTYPE)
+//
+//   node frontend/src/services/crypto/roundtrip.mjs
+//
+// Drives the REAL pure transform (envelope.js + visitEnvelope.js) through a
+// simulated client<->server cycle and asserts the Layer 2 contract:
+//   * content stored on the server is opaque (no plaintext leaks)
+//   * the server retains no cleartext content keys
+//   * partial updates merge correctly client-side (the moved field-merge)
+//   * GET round-trips to the exact original content
+//   * the list card decrypts for display
+//
+// The RN-coupled wrapper (visitCrypto.js / session.js) is exercised only when
+// the app runs with ENCRYPTED_VISITS=true; here we inject the CEK + a plain Map
+// cache and mirror the ~4 lines of server merge/strip so the test runs in Node.
+// =============================================================================
+
+import { generateCEK } from './envelope.js';
+import { splitContent, encryptUpdate, decryptFullVisit, decryptCard, CONTENT_FIELDS } from './visitEnvelope.js';
+
+let pass = 0, fail = 0;
+const ok = (c, m) => { if (c) { pass++; console.log('  \x1b[32m✓\x1b[0m ' + m); } else { fail++; console.log('  \x1b[31m✗ ' + m + '\x1b[0m'); } };
+const eq = (a, b, m) => ok(JSON.stringify(a) === JSON.stringify(b), m);
+
+const cek = await generateCEK();
+
+// --- client side: merge cache (mirrors session.mergeContent) ----------------
+const cache = new Map();
+function mergeContent(id, partial) {
+  const merged = { ...(cache.get(id) || {}), ...partial };
+  cache.set(id, merged);
+  return merged;
+}
+async function clientEncryptUpdate(id, updates) {
+  const { content, meta } = splitContent(updates);
+  return encryptUpdate(cek, meta, mergeContent(id, content));
+}
+
+// --- server side: store + merge/strip (mirrors handleUpdateVisit) -----------
+const disk = new Map();
+function serverPut(id, wire) {
+  const existing = disk.get(id) || { id, draft: true, cost: { total: { usd: 0 } } };
+  const { cost, ...body } = wire; // cost is server-authoritative
+  const updated = { ...existing, ...body, id };
+  if (updated.encrypted) {
+    for (const f of ['messages', 'name', 'icon', 'summary', 'plan']) delete updated[f];
+  }
+  disk.set(id, updated);
+}
+function serverGet(id) { return disk.get(id); }
+function serverListEntry(id) {
+  const v = disk.get(id);
+  return v.encrypted
+    ? { id: v.id, startDate: v.startDate, endDate: v.endDate, encrypted: true, enc: { card: v.enc?.card } }
+    : { id: v.id, name: v.name, icon: v.icon, summary: v.summary };
+}
+
+console.log('\x1b[1m═══ Layer 2 round-trip (encrypt-before-PUT) ═══\x1b[0m');
+
+const ID = 42;
+disk.set(ID, { id: ID, startDate: 111, draft: true, cost: { total: { usd: 0 } } });
+
+// 1. First save: just messages (the chat turn).
+console.log('\n1. First save — messages only');
+serverPut(ID, await clientEncryptUpdate(ID, {
+  draft: false,
+  messages: [
+    { role: 'user', text: 'I feel my stable job is costing me my twenties.' },
+    { role: 'keeper', text: 'The Steward and the Lever both want this…' },
+  ],
+}));
+const after1 = serverGet(ID);
+ok(after1.encrypted === true, 'visit marked encrypted on disk');
+ok(after1.draft === false, 'cleartext meta (draft) passed through');
+ok(!('messages' in after1), 'no cleartext `messages` key on disk');
+ok(after1.cost.total.usd === 0, 'server-authoritative cost preserved (not clobbered)');
+
+// 2. Second save: partial — adds end/summary/name/icon/plan (visit conclusion).
+console.log('\n2. Second save — partial fields merge client-side');
+serverPut(ID, await clientEncryptUpdate(ID, {
+  endDate: 222,
+  name: 'Whether to leave the job',
+  icon: '🪧',
+  summary: { headline: 'Security versus the cost of staying', keyTopics: ['career', 'risk'], outcome: 'leaning toward a deadline' },
+  plan: '- Name the worst realistic outcome\n- Give it a deadline',
+}));
+const after2 = serverGet(ID);
+ok(after2.endDate === 222, 'cleartext meta (endDate) passed through');
+for (const f of CONTENT_FIELDS) ok(!(f in after2), `no cleartext \`${f}\` key on disk`);
+
+// 3. Opaqueness: no plaintext anywhere in the stored blob.
+console.log('\n3. At-rest opaqueness');
+const blob = JSON.stringify(after2);
+const leaked = ['twenties', 'Steward', 'Security versus', 'deadline', 'career'].filter(w => blob.includes(w));
+ok(leaked.length === 0, 'stored blob contains no plaintext content' + (leaked.length ? ' (LEAKED: ' + leaked + ')' : ''));
+
+// 4. GET round-trip: decrypt back to the exact merged content.
+console.log('\n4. GET round-trip (decrypt)');
+const { visit } = await decryptFullVisit(cek, serverGet(ID));
+eq(visit.messages?.length, 2, 'messages restored');
+eq(visit.name, 'Whether to leave the job', 'name restored');
+eq(visit.summary.headline, 'Security versus the cost of staying', 'summary restored');
+eq(visit.plan?.startsWith('- Name'), true, 'plan restored');
+ok(visit.endDate === 222 && visit.draft === false, 'meta + content both present after decrypt');
+
+// 5. List card decrypts for display.
+console.log('\n5. List row card');
+const row = await decryptCard(cek, serverListEntry(ID));
+eq(row.name, 'Whether to leave the job', 'card name decrypts');
+eq(row.icon, '🪧', 'card icon decrypts');
+eq(row.summary.headline, 'Security versus the cost of staying', 'card headline decrypts');
+
+// 6. Wrong key cannot read (sanity: a different CEK can't recover the content).
+//    Decryption degrades gracefully (no throw) — the record is marked
+//    undecryptable and the plaintext is not exposed.
+console.log('\n6. Wrong key cannot read');
+const otherCek = await generateCEK();
+const wrong = await decryptFullVisit(otherCek, serverGet(ID));
+ok(wrong.undecryptable === true, 'a different CEK is rejected (record marked undecryptable, no throw)');
+ok(!wrong.visit.messages?.length && wrong.visit.name === 'Unreadable visit', 'no plaintext leaks; shows an unreadable placeholder');
+
+// 7. Layer 3b contract: a decrypted visit, shaped as buildClientContext does,
+//    exposes the fields the server's formatSummaryEntries reads for the
+//    mega-batch prior-context block.
+console.log('\n7. Layer 3b — client-supplied prior summary shape');
+const dv = (await decryptFullVisit(cek, serverGet(ID))).visit;
+const shaped = { id: dv.id, startDate: dv.startDate, endDate: dv.endDate, ...dv.summary };
+ok(shaped.id === ID && typeof shaped.startDate !== 'undefined', 'shaped entry carries id + startDate (server reads these)');
+ok(typeof shaped.headline === 'string', 'shaped entry carries summary.headline (the Focus line)');
+ok(Array.isArray(shaped.keyTopics), 'shaped entry carries summary.keyTopics (the Topics line)');
+ok(!('enc' in shaped) && !('messages' in shaped), 'shaped entry leaks no ciphertext / raw messages');
+
+console.log(`\n\x1b[1m═══ ${fail === 0 ? '\x1b[32mall ' + pass + ' checks passed' : '\x1b[31m' + fail + ' FAILED'}\x1b[0m\x1b[1m ═══\x1b[0m`);
+process.exit(fail === 0 ? 0 : 1);

package/verify-kit.mjs

@@ -0,0 +1,76 @@
+// =============================================================================
+// Audit-kit drift guard
+//
+//   node verify-kit.mjs            # check files against KIT-MANIFEST.txt (exit 1 on drift)
+//   node verify-kit.mjs --write    # (re)generate KIT-MANIFEST.txt
+//
+// KIT-MANIFEST.txt is the SHA-256 of every file in the published audit kit. It
+// is the bridge between this repo and the public mirror: CI here runs `--check`
+// so the committed manifest always reflects the real files, and anyone with the
+// mirror can run the same check (or a bare `sha256sum`) to confirm the mirror
+// is byte-for-byte these files. See README.md for the trust model and its limit.
+// =============================================================================
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { createHash } from 'crypto';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const DIR = dirname(fileURLToPath(import.meta.url));
+const MANIFEST = 'KIT-MANIFEST.txt';
+
+// The published kit. Excludes this script and the manifest itself.
+const KIT = [
+  'LICENSE',
+  'README.md',
+  'envelope.js',
+  'visitEnvelope.js',
+  'longitudinalLogic.js',
+  'keyring.js',
+  'demo.mjs',
+  'roundtrip.mjs',
+  'keyring.mjs',
+  'longitudinal.mjs',
+].sort();
+
+function sha256(relPath) {
+  return createHash('sha256').update(readFileSync(join(DIR, relPath))).digest('hex');
+}
+
+function currentManifest() {
+  return KIT.map((f) => `${sha256(f)}  ${f}`).join('\n') + '\n';
+}
+
+const write = process.argv.includes('--write');
+
+if (write) {
+  writeFileSync(join(DIR, MANIFEST), currentManifest());
+  console.log(`wrote ${MANIFEST} (${KIT.length} files)`);
+  process.exit(0);
+}
+
+// --check (default)
+const manifestPath = join(DIR, MANIFEST);
+if (!existsSync(manifestPath)) {
+  console.error(`✗ ${MANIFEST} missing — run: node verify-kit.mjs --write`);
+  process.exit(1);
+}
+const expected = readFileSync(manifestPath, 'utf-8').trim();
+const actual = currentManifest().trim();
+
+if (expected === actual) {
+  console.log(`✓ audit kit matches ${MANIFEST} (${KIT.length} files)`);
+  process.exit(0);
+}
+
+// Report the specific drift.
+const exp = new Map(expected.split('\n').map((l) => { const [h, f] = l.split(/\s+/); return [f, h]; }));
+const act = new Map(actual.split('\n').map((l) => { const [h, f] = l.split(/\s+/); return [f, h]; }));
+console.error(`✗ audit kit drifted from ${MANIFEST}:`);
+for (const f of KIT) {
+  if (!exp.has(f)) console.error(`   + ${f} (not in manifest)`);
+  else if (exp.get(f) !== act.get(f)) console.error(`   ~ ${f} (changed)`);
+}
+for (const f of exp.keys()) if (!act.has(f)) console.error(`   - ${f} (in manifest, file gone)`);
+console.error('   run: node verify-kit.mjs --write  (after intended changes)');
+process.exit(1);

package/visitEnvelope.js

@@ -0,0 +1,89 @@
+// =============================================================================
+// Client-side encryption — pure visit transform (PROTOTYPE, Layer 2)
+//
+// The content-split / encrypt / decrypt logic, with NO React-Native or session
+// coupling: every function takes an explicit CEK. visitCrypto.js is the thin
+// wrapper that resolves the userId + session CEK and calls these. Keeping this
+// pure means it runs in Node for the round-trip test (roundtrip.mjs) and is the
+// actual code under test, not a re-implementation.
+// =============================================================================
+
+import { encryptRecord, decryptRecord } from './envelope.js';
+
+// Fields that are CONTENT (encrypted). Everything else is cleartext operational
+// metadata (§6) and passes through.
+export const CONTENT_FIELDS = ['messages', 'name', 'icon', 'summary', 'plan'];
+
+export function splitContent(obj) {
+  const content = {};
+  const meta = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (CONTENT_FIELDS.includes(k)) content[k] = v;
+    else meta[k] = v;
+  }
+  return { content, meta };
+}
+
+// The lightweight digest the History/Landing list needs (§6: minimize what the
+// list reads). Decrypted per row instead of the full content.
+export function cardOf(content) {
+  return {
+    name: content.name ?? null,
+    icon: content.icon ?? null,
+    headline: content.summary?.headline ?? null,
+    keyTopics: content.summary?.keyTopics ?? null,
+    outcome: content.summary?.outcome ?? null,
+  };
+}
+
+// Build the encrypted wire body from cleartext meta + the FULL merged content.
+export async function encryptUpdate(cek, meta, fullContent) {
+  return {
+    ...meta,
+    encrypted: true,
+    enc: {
+      card: await encryptRecord(cek, cardOf(fullContent)),
+      content: await encryptRecord(cek, fullContent),
+    },
+  };
+}
+
+// Decrypt a full visit back into plaintext fields. Returns { meta, content } so
+// the caller can seed its cache with the content. Pass-through marker if not
+// encrypted.
+export async function decryptFullVisit(cek, wireVisit) {
+  if (!wireVisit?.encrypted || !wireVisit.enc?.content) {
+    return { passthrough: true, visit: wireVisit };
+  }
+  const { enc, encrypted, ...meta } = wireVisit;
+  try {
+    const content = await decryptRecord(cek, wireVisit.enc.content);
+    return { passthrough: false, content, visit: { ...meta, ...content } };
+  } catch (err) {
+    // Wrong/rotated key or corrupt ciphertext — degrade instead of throwing, so
+    // one undecryptable record can't break the screen (or, in a list, the
+    // readable records alongside it). The cleartext metadata still renders.
+    console.warn(`Visit ${meta.id}: content could not be decrypted (${err?.name || 'error'}) — key mismatch?`);
+    return { passthrough: false, undecryptable: true, content: {}, visit: { ...meta, undecryptable: true, name: 'Unreadable visit', messages: [] } };
+  }
+}
+
+// Decrypt a list row's card into display fields. Pass-through if not encrypted.
+export async function decryptCard(cek, entry) {
+  if (!entry?.encrypted || !entry.enc?.card) return entry;
+  const { enc, encrypted, ...meta } = entry;
+  try {
+    const card = await decryptRecord(cek, entry.enc.card);
+    return {
+      ...meta,
+      name: card.name,
+      icon: card.icon,
+      summary: meta.summary || (card.headline
+        ? { headline: card.headline, keyTopics: card.keyTopics, outcome: card.outcome }
+        : null),
+    };
+  } catch (err) {
+    console.warn(`Visit ${meta.id}: card could not be decrypted (${err?.name || 'error'}) — key mismatch?`);
+    return { ...meta, name: 'Unreadable visit', icon: '🔒', summary: null, undecryptable: true };
+  }
+}