prism-mcp-server 20.14.0 → 20.16.0

package/README.md

@@ -1,6 +1,6 @@
 # Prism Coder
 
-**Give your AI agent memory that lasts.** Persistent sessions, knowledge graphs, and offline tool-routing — fully local and free.
+**Give your AI agent memory that lasts — and see the cloud tokens it never had to spend.** Persistent sessions, knowledge graphs, offline tool-routing, and an auditable savings meter. Fully local and free.
 
 [![npm](https://img.shields.io/npm/v/prism-mcp-server?color=cb0000&label=npm)](https://www.npmjs.com/package/prism-mcp-server)
 [![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-00ADD8)](https://github.com/modelcontextprotocol/servers)
@@ -11,7 +11,7 @@
   <img src="docs/mind-palace-dashboard-v20.8.png" alt="Prism Mind Palace dashboard v20.8.0 — project state with handoff summary, pending TODOs, intent health, neural graph, and time-travel history" width="700" />
 </p>
 
-Prism Coder is an [MCP server](https://modelcontextprotocol.io) that gives Claude, Cursor, and other AI tools long-term memory that survives across sessions. It ships with the open-weight `prism-coder` model fleet (2B–27B) for fast, offline tool-routing — no cloud required.
+Prism Coder is an [MCP server](https://modelcontextprotocol.io) that gives Claude, Cursor, and other AI tools long-term memory that survives across sessions. It ships with the open-weight `prism-coder` model fleet (2B–27B) for fast, offline tool-routing — no cloud required. And it keeps score: every call served locally is metered, so `prism savings` shows the token volume that never reached your cloud model — [measured honestly, in tokens](#local_savings--what-local-serving-actually-displaced).
 
 **No account needed. No API keys. Runs on your machine.**  
 A paid subscription adds cloud sync, higher model tiers, and team features through the [Synalux portal](https://synalux.ai).
@@ -25,6 +25,11 @@ A paid subscription adds cloud sync, higher model tiers, and team features throu
 - **Local-first inference** — bounded work is routed through local Ollama models
   first, with automatic 2B/4B/9B/27B selection based on installed models,
   available RAM, context fit, and subscription entitlements.
+- **A savings meter you can audit** — `prism savings` (or the `local_savings`
+  tool from any host) reports the token volume local serving kept off your
+  cloud model: headline, local share, per-model breakdown. It reports tokens,
+  never an invented dollar figure, and prints its assumptions and known
+  undercounts inline — a number you can check, not marketing.
 - **Route-output enforcement** — route mode returns only well-formed calls to
   tools the host actually advertised. Standard and higher plans can add
   authenticated deterministic correction; `route_guard: "local"` keeps the
@@ -56,6 +61,23 @@ Prism works locally without an account, API key, or cloud subscription. Add a
 Synalux subscription when you want cloud memory, paid-tier skills, or team
 features.
 
+After a few sessions, ask what it's been worth:
+
+```bash
+prism savings --period month
+```
+
+```
+💾 Local serving — LAST 30 DAYS
+  ~510K tokens kept off your cloud model
+  53 call(s) served locally of 58 routed (91%)
+```
+
+Your numbers will differ — that's the point: it reports what *your* machine
+actually served, not a projection. Full report anatomy and the honesty rules
+behind it are in the
+[`local_savings` section](#local_savings--what-local-serving-actually-displaced).
+
 ### Install as a plugin
 
 Prism also ships as a plugin, which registers the MCP server and the startup
@@ -116,6 +138,25 @@ or by re-enabling after each run.
 <details>
 <summary>Release history (optional)</summary>
 
+## What's New in v20.16.0
+
+### See What Local Serving Saves You — Meterable, Auditable, Team-Wide
+
+- **`local_savings` tool + `prism savings` CLI** — the token volume local
+  serving kept off your cloud model: all time, trailing 30/7 days, or any
+  `--days N` window. Tokens, never an invented dollar figure, with the
+  assumptions and known undercounts printed inline.
+- **Team roll-up (paid)** — `prism savings --sync-enable` uploads per-day
+  counters only (never content; the payload is a closed field set the server
+  also enforces); `prism savings --team` shows the workspace-wide total with
+  per-member share. Off by default.
+- **E2E sync foundation** — sealed multi-recipient envelopes (X25519 +
+  HKDF-SHA256 + AES-256-GCM on node:crypto, no new dependency) and per-device
+  identities, adversarially reviewed: cross-machine session sync will ship on
+  a relay that only ever stores ciphertext.
+- **Push-time public-leak guard** — outgoing diffs AND commit messages are
+  scanned before anything leaves the machine.
+
 ## What's New in v20.12.1
 
 - **`prism connect --refresh` now converges every registration it owns**, not
@@ -724,6 +765,12 @@ Every conversation feeds a persistent store. The next session loads the right co
 
 The dashboard shows your current project state, pending TODOs, intent health, and a neural knowledge graph — all built automatically from your agent sessions.
 
+It runs on loopback and is gated by a per-startup token by default — open the
+tokenized URL printed in the startup log (`http://localhost:3000/?token=…`).
+Requests with an untrusted `Host`/`Origin` are refused, closing the DNS-rebinding
+exposure fixed in GHSA-9cvx-7x8q-3g6m. See [docs/IDE_SETUP.md](docs/IDE_SETUP.md#securing-the-dashboard)
+to pin the token, disable it, or configure Basic Auth / JWKS.
+
 ### Export — read the record outside the agent
 
 `session_export_memory` writes your memory out as plain files you can read,
@@ -1055,6 +1102,7 @@ Prism exposes 40+ MCP tools. The core memory loop:
 | `knowledge_ingest` | Teach Prism a codebase or document |
 | `prism_infer` | Local-first inference (route/chat/code modes, thinking, cloud escalation) |
 | `inference_metrics` | Session delegation or persisted MCP + VS Code panel local/cloud stats |
+| `local_savings` | Token volume local serving kept off your cloud model, all time / 30 days / session |
 
 ### `query_memory_natural` — memory first, current sources when needed
 
@@ -1112,6 +1160,68 @@ The same block also appears automatically in `session_save_ledger` and `session_
 
 **Note:** The default session view tracks this MCP process's `prism_infer` delegation. The all-time view combines persisted MCP calls with Synalux VS Code panel inference. Neither view includes the host agent's own token spend; use that host's native usage reporting when available.
 
+### `local_savings` — what local serving actually displaced
+
+`inference_metrics` reports raw counters. `local_savings` answers the question
+behind them: how much work never reached your cloud model. Call the tool in any
+host, or run `prism savings` from a terminal — `--period all|month|week|session`,
+`--days N` for any custom trailing window (e.g. `--days 90` for a quarter), and
+`--json` for machine-readable output:
+
+```
+💾 Local serving — LAST 30 DAYS (2026-08-02 → 2026-08-26)
+
+  ~510K tokens kept off your cloud model
+  53 call(s) served locally of 58 routed (91%)
+  Breakdown: 461,400 prompt + 48,400 completion
+
+  By model:
+    prism-coder:9b: 41 call(s), ~505K tokens
+    prism-coder:4b: 12 call(s), ~4.8K tokens
+
+  Counts tokens a local model handled instead of your cloud model. On the token
+  axis, the token count is measured — a floor, with known undercounts listed
+  when present. On the displacement axis, prism cannot observe the call your
+  host would have made, so whether all of it would have hit the cloud is an
+  assumption. Read it as: at most this much displacement, of at least this
+  token volume.
+
+  Caveats:
+    · 12 local call(s) hit the KV cache, so Ollama reported 0 prompt tokens for
+      context that was really submitted — prompt tokens are undercounted.
+    · 3 refused call(s) excluded — nothing was served, so nothing was displaced.
+```
+
+**Why tokens and not money.** Prism reports token volume and never a dollar
+figure, because it cannot honestly produce one: published rates change and a
+bundled price table would be wrong on a timer; prism never observes which model
+your host would have used, and that choice alone is a multiple-fold spread on
+the same tokens; and most users are on flat plans where a currency figure means
+nothing at all. Tokens are the one unit prism measured itself. If you know your
+own effective rate, multiply — the split is printed for exactly that reason.
+
+Refused calls are excluded, the VS Code panel-playground share is disclosed
+separately, and the known sources of undercount are listed inline rather than
+left implicit — so the durable (`week`/`month`/`all`/`--days`) headline is a
+measured floor rather than a number that merely looks precise. Figures are
+per-machine: each machine reports its own local ledger.
+
+**Team roll-up (paid).** On paid plans, `prism savings --sync-enable` opts this
+machine into savings sync: once a session, prism uploads per-day **counters** —
+call counts and token totals, never prompts, completions, project names, or
+model output (the upload payload is a closed field set; the server rejects
+anything else). `prism savings --team` (or the `local_savings` tool with
+`scope: "team"`) then shows the roll-up across your workspace: total tokens
+kept off cloud models, per-member share, device counts. Members who haven't
+opted in simply aren't counted, so the team figure is a floor. Sync is off by
+default, `--sync-disable` stops it, and the deeper session-content sync
+(handoffs) is a separate channel with end-to-end encryption — the two are
+deliberately not unified, because an E2E blob cannot be aggregated and a
+counter channel must never carry content. The `session` view is the one
+exception: on KV-cache hits it estimates submitted prompt tokens from text
+(the ledger counts the measured 0 instead), so it is marked `(est.)` and says
+so whenever that happens.
+
 ### Local-model delegation (default)
 
 Prism routes qualifying bounded work—bulk classification, field extraction,

package/dist/cli.js

@@ -1040,6 +1040,100 @@ scmCmd
         process.exit(1);
     }
 });
+// ─── prism savings ────────────────────────────────────────────
+// Surfaces the local-serving meter outside an MCP host. Reports TOKENS, not
+// money — see the header of tools/savingsHandler.ts for why a dollar figure
+// would be fabricated.
+program
+    .command('savings')
+    .description('Show token volume displaced by local serving (all time by default)')
+    .option('-p, --period <period>', 'Window: all | month | week | session', 'all')
+    .option('-d, --days <n>', 'Custom trailing window in days (overrides --period)')
+    .option('--team', 'Show the team roll-up from the portal (paid; members who opted in)')
+    .option('--workspace <id>', 'Workspace id for --team')
+    .option('--sync-enable', 'Opt in to savings sync (paid): daily COUNTERS only, never content')
+    .option('--sync-disable', 'Opt out of savings sync')
+    .option('--sync-now', 'Push the trailing window of daily counters now (requires sync enabled first)')
+    .option('--json', 'Emit machine-readable JSON output')
+    .action(async (options) => {
+    try {
+        if (options.syncEnable || options.syncDisable) {
+            const { setSetting } = await import('./storage/configStorage.js');
+            await setSetting('PRISM_SAVINGS_SYNC', options.syncEnable ? '1' : '0');
+            console.log(options.syncEnable
+                ? 'Savings sync enabled. What leaves this machine: per-day call/token COUNTERS only — '
+                    + 'never prompts, completions, or project names. Disable anytime with --sync-disable.'
+                : 'Savings sync disabled. Nothing further leaves this machine on this channel.');
+            if (!options.syncNow)
+                return;
+        }
+        if (options.syncNow) {
+            const { pushSavings } = await import('./sync/savingsSync.js');
+            const r = await pushSavings();
+            if (r.pushed) {
+                console.log(`Pushed ${r.days} day row(s) of counters.`);
+                return;
+            }
+            console.error(`Not pushed: ${r.reason}`);
+            process.exit(r.reason === 'nothing_to_push' || r.reason === 'disabled' ? 0 : 1);
+        }
+        if (options.team) {
+            const { fetchTeamSavings, renderTeamSavings } = await import('./sync/savingsSync.js');
+            const teamDays = options.days !== undefined ? Math.floor(Number(options.days)) : 30;
+            if (!Number.isFinite(teamDays) || teamDays <= 0) {
+                console.error(`--days expects a positive number, got "${options.days}".`);
+                process.exit(1);
+            }
+            const result = await fetchTeamSavings(options.workspace, teamDays);
+            if (!result.ok) {
+                console.error(result.reason === 'not_entitled'
+                    ? 'Team savings needs a paid plan with team features and workspace membership.'
+                    : `Team savings unavailable: ${result.reason}`);
+                process.exit(1);
+            }
+            console.log(options.json ? JSON.stringify(result.team, null, 2) : renderTeamSavings(result.team));
+            return;
+        }
+        const { queryLocalSavings } = await import('./storage/inferMetricsLedger.js');
+        const { renderSavings, sessionSavings, windowStart } = await import('./tools/savingsHandler.js');
+        const raw = (options.days !== undefined && options.period === undefined ? 'all' : (options.period ?? 'all')).toLowerCase();
+        if (!['all', 'month', 'week', 'session'].includes(raw)) {
+            console.error(`Unknown period "${raw}" — expected all, month, week, or session.`);
+            process.exit(1);
+        }
+        const period = raw;
+        let days;
+        if (options.days !== undefined) {
+            days = Number(options.days);
+            if (!Number.isFinite(days) || days <= 0) {
+                console.error(`--days expects a positive number, got "${options.days}".`);
+                process.exit(1);
+            }
+            days = Math.floor(days);
+        }
+        // A CLI invocation is a fresh process, so the in-memory session
+        // accumulators are always empty here. Say so rather than printing a
+        // truthful-but-useless zero that reads as "local serving does nothing".
+        if (period === 'session') {
+            console.error('Note: `prism savings --period session` runs in a new process with no ' +
+                'session history. Use the local_savings MCP tool inside a host session, ' +
+                'or --period month/all for the durable ledger.');
+        }
+        const data = period === 'session'
+            ? sessionSavings()
+            : await queryLocalSavings(windowStart(period, Date.now(), days));
+        if (!data) {
+            console.error('Inference ledger unavailable — no durable figure can be reported.');
+            process.exit(1);
+        }
+        const rendered = renderSavings(data, period, days);
+        console.log(options.json ? JSON.stringify(rendered.data, null, 2) : rendered.text);
+    }
+    catch (err) {
+        console.error(`savings failed: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+});
 // ─── prism update-models ──────────────────────────────────────
 // Standalone model convergence: pull each installed prism-coder tier from
 // the registry and repair its local alias. connect runs this automatically;

package/dist/crypto/deviceKeys.js

@@ -0,0 +1,76 @@
+/**
+ * Device identity for E2E sync — one X25519 keypair per machine.
+ *
+ * The private key is generated here, written with 0600 permissions, and NEVER
+ * leaves this machine — not to the portal, not into a blob, not into logs.
+ * Only the PUBLIC key is published (at device registration) so other devices
+ * can seal envelopes to it. Losing the file means this device can no longer
+ * open blobs sealed to it; that is the designed failure mode, strictly better
+ * than any recovery path that would require the key to exist somewhere else.
+ *
+ * Storage: <dataDir>/sync-device-key.pem (PKCS8 PEM), alongside the config DB.
+ * Resolution mirrors the ledger's: PRISM_DATA_DIR (test sandbox / relocation)
+ * else ~/.prism-mcp. Tests must never touch a real device key.
+ */
+import { createPrivateKey, createPublicKey, generateKeyPairSync, } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { keyIdOf, rawFromPublicKey, EnvelopeError } from "./syncEnvelope.js";
+const KEY_FILENAME = "sync-device-key.pem";
+function keyPath() {
+    const dir = process.env.PRISM_DATA_DIR
+        ? resolve(process.env.PRISM_DATA_DIR)
+        : resolve(homedir(), ".prism-mcp");
+    return resolve(dir, KEY_FILENAME);
+}
+/**
+ * Load this machine's device key, creating it on first use.
+ *
+ * Never overwrites: an existing file is authoritative even if unreadable as a
+ * key — failing loudly beats silently rotating an identity that other devices
+ * have already sealed blobs to.
+ */
+export function loadOrCreateDeviceIdentity() {
+    const path = keyPath();
+    if (existsSync(path)) {
+        let privateKey;
+        try {
+            privateKey = createPrivateKey(readFileSync(path, "utf8"));
+        }
+        catch (e) {
+            throw new EnvelopeError(`device key at ${path} exists but cannot be parsed — refusing to rotate an established ` +
+                `identity automatically (${e instanceof Error ? e.message : e})`);
+        }
+        if (privateKey.asymmetricKeyType !== "x25519") {
+            throw new EnvelopeError(`device key at ${path} is ${privateKey.asymmetricKeyType}, expected x25519`);
+        }
+        const publicKey = createPublicKey(privateKey);
+        const rawPublicKey = rawFromPublicKey(publicKey);
+        return { privateKey, publicKey, rawPublicKey, keyId: keyIdOf(rawPublicKey), created: false };
+    }
+    const { privateKey, publicKey } = generateKeyPairSync("x25519");
+    const pem = privateKey.export({ format: "pem", type: "pkcs8" });
+    const dir = resolve(path, "..");
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    // 'wx' = exclusive create: two concurrent first-runs cannot silently
+    // overwrite each other's identity, and a dangling symlink pre-planted at
+    // the path fails with EEXIST instead of being followed. Then chmod,
+    // because writeFileSync's mode is masked by umask and a device key
+    // readable by group/other for even a moment is a defect. (On Windows,
+    // POSIX modes are advisory — the profile directory ACL is the boundary.)
+    try {
+        writeFileSync(path, pem, { mode: 0o600, flag: "wx" });
+    }
+    catch (e) {
+        if (e.code === "EEXIST") {
+            // Lost the creation race — the other writer's identity wins.
+            return loadOrCreateDeviceIdentity();
+        }
+        throw e;
+    }
+    chmodSync(path, 0o600);
+    const rawPublicKey = rawFromPublicKey(publicKey);
+    return { privateKey, publicKey, rawPublicKey, keyId: keyIdOf(rawPublicKey), created: true };
+}

package/dist/crypto/syncEnvelope.js

@@ -0,0 +1,226 @@
+/**
+ * Sealed envelope for cross-machine sync — the E2E foundation of Phase 2.
+ *
+ * The local-first contract this enforces: the sync relay stores CIPHERTEXT
+ * ONLY. A blob is encrypted to the set of the user's registered DEVICE public
+ * keys before it leaves the machine; the server never holds a key that opens
+ * anything. That property is what makes "your agent's memory never exists
+ * unencrypted off your machines" a statement of architecture rather than of
+ * policy, so nothing in this module may weaken it for convenience:
+ *
+ *   - No shared master secret exists, so nothing secret is ever transported.
+ *     Adding a device means publishing its PUBLIC key; each blob carries the
+ *     content key wrapped once per recipient device (the age/libsodium
+ *     sealed-box model).
+ *   - Everything is node:crypto (X25519 + HKDF-SHA256 + AES-256-GCM). No new
+ *     dependency: a wasm/native crypto package would widen the supply-chain
+ *     surface of an npm-distributed MCP server for zero capability gain.
+ *   - Envelopes are versioned and self-describing. v1 is the only version;
+ *     opening anything else fails loudly rather than guessing.
+ *   - The AAD binds a context string (e.g. "prism-sync:v1:<project>") into the
+ *     payload AEAD, so a valid blob replayed under a different project fails
+ *     authentication instead of decrypting somewhere it does not belong.
+ *
+ * Wire shapes are JSON-safe (base64 strings) because blobs travel through the
+ * portal API and land in a database column.
+ */
+import { createCipheriv, createDecipheriv, createHash, createPrivateKey, createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync, randomBytes, } from "node:crypto";
+export const ENVELOPE_VERSION = 1;
+export const ENVELOPE_ALG = "x25519-hkdf-sha256+aes-256-gcm";
+/** Raw X25519 public keys are exactly 32 bytes. */
+const X25519_RAW_LEN = 32;
+const GCM_NONCE_LEN = 12;
+const GCM_TAG_LEN = 16;
+const CEK_LEN = 32;
+/** DER prefix for an X25519 SubjectPublicKeyInfo — lets us accept raw 32-byte
+ *  keys at the API boundary while node:crypto works with SPKI objects. */
+const X25519_SPKI_PREFIX = Buffer.from("302a300506032b656e032100", "hex");
+export class EnvelopeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EnvelopeError";
+    }
+}
+/** Key id every party derives identically from the raw public key. */
+export function keyIdOf(rawPublicKey) {
+    if (rawPublicKey.length !== X25519_RAW_LEN) {
+        throw new EnvelopeError(`public key must be ${X25519_RAW_LEN} raw bytes, got ${rawPublicKey.length}`);
+    }
+    return createHash("sha256").update(rawPublicKey).digest("hex").slice(0, 16);
+}
+function publicKeyFromRaw(raw) {
+    if (raw.length !== X25519_RAW_LEN) {
+        throw new EnvelopeError(`public key must be ${X25519_RAW_LEN} raw bytes, got ${raw.length}`);
+    }
+    return createPublicKey({
+        key: Buffer.concat([X25519_SPKI_PREFIX, raw]),
+        format: "der",
+        type: "spki",
+    });
+}
+export function rawFromPublicKey(key) {
+    const der = key.export({ format: "der", type: "spki" });
+    const raw = der.subarray(der.length - X25519_RAW_LEN);
+    if (der.length < X25519_RAW_LEN || raw.length !== X25519_RAW_LEN) {
+        throw new EnvelopeError("could not extract raw X25519 key from SPKI");
+    }
+    return Buffer.from(raw);
+}
+/**
+ * KEK derivation. The salt commits to BOTH public keys so a key confusion
+ * between recipients (or a swapped ephemeral) derives a different KEK and the
+ * GCM unwrap fails authentication instead of silently decrypting.
+ */
+function deriveKek(shared, ephemeralRaw, recipientRaw) {
+    const salt = createHash("sha256")
+        .update("prism-sync-v1")
+        .update(ephemeralRaw)
+        .update(recipientRaw)
+        .digest();
+    return Buffer.from(hkdfSync("sha256", shared, salt, "prism-sync-kek-v1", CEK_LEN));
+}
+function gcmSeal(key, nonce, plaintext, aad) {
+    const cipher = createCipheriv("aes-256-gcm", key, nonce);
+    cipher.setAAD(aad);
+    const ct = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    return Buffer.concat([ct, cipher.getAuthTag()]);
+}
+function gcmOpen(key, nonce, sealed, aad) {
+    if (sealed.length < GCM_TAG_LEN)
+        throw new EnvelopeError("ciphertext shorter than a GCM tag");
+    const ct = sealed.subarray(0, sealed.length - GCM_TAG_LEN);
+    const tag = sealed.subarray(sealed.length - GCM_TAG_LEN);
+    // Every crypto call sits INSIDE the try. An adversarial review measured
+    // that createDecipheriv on a 0-byte IV (base64 is lenient — a relay can
+    // set n:"" and Buffer.from decodes it to 0 bytes) threw a raw TypeError
+    // from outside the old try, breaking the uniform-EnvelopeError contract.
+    try {
+        const decipher = createDecipheriv("aes-256-gcm", key, nonce);
+        decipher.setAAD(aad);
+        decipher.setAuthTag(tag);
+        return Buffer.concat([decipher.update(ct), decipher.final()]);
+    }
+    catch {
+        // Deliberately indistinguishable: wrong key, tampered ciphertext,
+        // malformed nonce, and swapped-context AAD all present identically.
+        throw new EnvelopeError("authentication failed");
+    }
+}
+/**
+ * Seal `plaintext` for every recipient device.
+ *
+ * @param recipientRawPublicKeys raw 32-byte X25519 public keys (the shapes
+ *   devices publish at registration)
+ * @param aadContext cleartext routing context bound into the AEAD, e.g.
+ *   "prism-sync:v1:<project>". Opening with a different context fails.
+ */
+export function sealFor(recipientRawPublicKeys, plaintext, aadContext) {
+    if (recipientRawPublicKeys.length === 0) {
+        throw new EnvelopeError("refusing to seal for zero recipients — the blob would be unopenable");
+    }
+    if (!aadContext) {
+        throw new EnvelopeError("aadContext is required — unbound blobs can be replayed across contexts");
+    }
+    const cek = randomBytes(CEK_LEN);
+    const payloadNonce = randomBytes(GCM_NONCE_LEN);
+    const aad = Buffer.from(aadContext, "utf8");
+    const ct = gcmSeal(cek, payloadNonce, plaintext, aad);
+    const recipients = recipientRawPublicKeys.map((recipientRaw) => {
+        const recipientKey = publicKeyFromRaw(recipientRaw);
+        const eph = generateKeyPairSync("x25519");
+        const ephRaw = rawFromPublicKey(eph.publicKey);
+        const shared = diffieHellman({ privateKey: eph.privateKey, publicKey: recipientKey });
+        const kek = deriveKek(shared, ephRaw, recipientRaw);
+        const kid = keyIdOf(recipientRaw);
+        const wrapNonce = randomBytes(GCM_NONCE_LEN);
+        const ck = gcmSeal(kek, wrapNonce, cek, Buffer.from(kid, "utf8"));
+        return {
+            kid,
+            epk: ephRaw.toString("base64"),
+            n: wrapNonce.toString("base64"),
+            ck: ck.toString("base64"),
+        };
+    });
+    return {
+        v: ENVELOPE_VERSION,
+        alg: ENVELOPE_ALG,
+        recipients,
+        n: payloadNonce.toString("base64"),
+        ct: ct.toString("base64"),
+        aad: aadContext,
+    };
+}
+/**
+ * Open an envelope with this device's private key.
+ *
+ * @param expectedAadContext the context the CALLER expects this blob to belong
+ *   to. Passed explicitly rather than read from the envelope: trusting the
+ *   attacker-controlled `aad` field would turn the binding into decoration.
+ */
+export function openSealed(envelope, devicePrivateKey, deviceRawPublicKey, expectedAadContext) {
+    if (envelope.v !== ENVELOPE_VERSION) {
+        throw new EnvelopeError(`unsupported envelope version ${envelope.v}`);
+    }
+    if (envelope.alg !== ENVELOPE_ALG) {
+        throw new EnvelopeError(`unsupported algorithm ${envelope.alg}`);
+    }
+    if (envelope.aad !== expectedAadContext) {
+        throw new EnvelopeError("envelope context does not match the expected context");
+    }
+    const ourKid = keyIdOf(deviceRawPublicKey);
+    const entry = envelope.recipients.find((r) => r.kid === ourKid);
+    if (!entry) {
+        throw new EnvelopeError("this device is not a recipient of this envelope");
+    }
+    const ephRaw = Buffer.from(entry.epk, "base64");
+    let shared;
+    try {
+        // Node rejects low-order X25519 points by THROWING a raw OpenSSL
+        // error (it never returns an all-zero secret). The epk is
+        // relay-controlled, so that throw must collapse to the uniform
+        // failure like every other adversarial-input path.
+        const ephKey = publicKeyFromRaw(ephRaw);
+        shared = diffieHellman({ privateKey: devicePrivateKey, publicKey: ephKey });
+    }
+    catch {
+        throw new EnvelopeError("authentication failed");
+    }
+    const kek = deriveKek(shared, ephRaw, deviceRawPublicKey);
+    const cek = gcmOpen(kek, Buffer.from(entry.n, "base64"), Buffer.from(entry.ck, "base64"), Buffer.from(ourKid, "utf8"));
+    return gcmOpen(cek, Buffer.from(envelope.n, "base64"), Buffer.from(envelope.ct, "base64"), Buffer.from(expectedAadContext, "utf8"));
+}
+/** More devices than any user has; far below any allocation hazard. */
+export const MAX_ENVELOPE_RECIPIENTS = 64;
+/** Handoff/ledger blobs are text; 16 MiB of base64 is well past any real one. */
+export const MAX_ENVELOPE_CT_CHARS = 16 * 1024 * 1024;
+/** Structural validation for envelopes arriving off the wire. Bounds sizes so
+ *  a hostile relay cannot make the opener allocate unbounded memory before
+ *  any authentication happens. */
+export function isSealedEnvelope(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const o = value;
+    if (o.v !== ENVELOPE_VERSION || o.alg !== ENVELOPE_ALG)
+        return false;
+    if (typeof o.n !== "string" || typeof o.ct !== "string" || typeof o.aad !== "string")
+        return false;
+    if (o.n.length > 64 || o.aad.length > 512)
+        return false;
+    if (o.ct.length > MAX_ENVELOPE_CT_CHARS)
+        return false;
+    if (!Array.isArray(o.recipients) || o.recipients.length === 0)
+        return false;
+    if (o.recipients.length > MAX_ENVELOPE_RECIPIENTS)
+        return false;
+    return o.recipients.every((r) => {
+        if (typeof r !== "object" || r === null)
+            return false;
+        const e = r;
+        return typeof e.kid === "string" && e.kid.length <= 32 &&
+            typeof e.epk === "string" && e.epk.length <= 64 &&
+            typeof e.n === "string" && e.n.length <= 64 &&
+            typeof e.ck === "string" && e.ck.length <= 256;
+    });
+}
+/** Re-exported for deviceKeys; not part of the public sealing API. */
+export const _internal = { publicKeyFromRaw, createPrivateKey };

package/dist/dashboard/dashboardToken.js

@@ -0,0 +1,43 @@
+import { randomBytes } from "crypto";
+import { safeCompare } from "./authUtils.js";
+function isTruthy(v) {
+    const s = (v || "").trim().toLowerCase();
+    return s === "1" || s === "true" || s === "yes" || s === "on";
+}
+/**
+ * Resolve the active dashboard token, or null when token mode is off. A pinned
+ * token wins over a random one so operators can share a stable URL; an empty or
+ * whitespace-only pin is ignored (falls back to a random token).
+ */
+export function resolveDashboardToken(cfg) {
+    if (cfg.authEnabled)
+        return null; // real auth is the gate
+    if (isTruthy(cfg.optOut))
+        return null; // explicit opt-out (Host guard still applies)
+    const pinned = (cfg.pinnedToken || "").trim();
+    if (pinned)
+        return pinned;
+    return randomBytes(32).toString("hex");
+}
+/** Extract the prism_dashboard_token cookie value, if present. */
+export function tokenFromCookie(cookieHeader) {
+    // Capture the whole value (any run of non-";", non-space) so pinned tokens
+    // with hyphens/underscores match; the name is anchored to start-or-"; " so a
+    // look-alike cookie (evil_prism_dashboard_token=…) cannot match.
+    const m = (cookieHeader || "").match(/(?:^|;\s*)prism_dashboard_token=([^;\s]+)/);
+    return m ? m[1] : null;
+}
+/**
+ * True when the request presents the active token via the cookie, the
+ * X-Prism-Dashboard-Token header, or a ?token= query param. Every comparison is
+ * timing-safe and only runs against the single active token.
+ */
+export function requestHasToken(headers, queryToken, activeToken) {
+    const candidates = [tokenFromCookie(headers.cookie), headers.headerToken ?? null, queryToken];
+    return candidates.some((c) => c !== null && safeCompare(c, activeToken));
+}
+/** Build the Set-Cookie value that stores the token for a browser session. */
+export function buildTokenCookie(token, maxAgeMs, secure) {
+    return (`prism_dashboard_token=${token}; Path=/; HttpOnly; SameSite=Strict; ` +
+        `Max-Age=${Math.floor(maxAgeMs / 1000)}${secure ? "; Secure" : ""}`);
+}