prism-mcp-server 20.16.0 → 20.17.0

package/README.md

@@ -138,6 +138,22 @@ or by re-enabling after each run.
 <details>
 <summary>Release history (optional)</summary>
 
+## What's New in v20.17.0
+
+### Cross-Machine Session Handoff — End-to-End Encrypted
+
+- **Resume a session on any of your machines.** With `prism sync enable` (paid,
+  off by default), each `session_save_handoff` seals the handoff to all your
+  account's device keys and relays the CIPHERTEXT; another machine pulls with
+  `sync_pull_handoff` (or `prism sync pull <project>`) and opens it locally.
+- **The relay stores ciphertext only** — X25519 + AES-256-GCM sealed
+  envelopes. No key that opens a handoff ever exists server-side. The channel
+  is deliberately separate from savings sync, which carries counters only.
+- **TOFU device pinning** surfaces a compromised relay: sealing to a key this
+  machine has never seen warns loudly, keyed on the client-derived recipient
+  id so a swapped key can't hide behind a familiar device name.
+- `prism sync status|devices` to inspect; revoke a lost machine from the portal.
+
 ## What's New in v20.16.0
 
 ### See What Local Serving Saves You — Meterable, Auditable, Team-Wide

package/dist/cli.js

@@ -1134,6 +1134,81 @@ program
         process.exit(1);
     }
 });
+// ─── prism sync ───────────────────────────────────────────────
+// Cross-machine handoff sync controls. Push happens automatically on
+// session_save_handoff once enabled; everything E2E lives in src/crypto/.
+program
+    .command('sync <action> [project]')
+    .description('Cross-machine handoff sync: enable | disable | status | pull <project> | devices')
+    .action(async (action, project) => {
+    try {
+        switch (action) {
+            case 'enable':
+            case 'disable': {
+                const { setSetting } = await import('./storage/configStorage.js');
+                await setSetting('PRISM_HANDOFF_SYNC', action === 'enable' ? '1' : '0');
+                console.log(action === 'enable'
+                    ? 'Handoff sync enabled. On each session_save_handoff, the handoff is sealed to your '
+                        + 'account devices (end-to-end encrypted — the relay stores ciphertext only) and uploaded. '
+                        + 'Paid plans; disable anytime with: prism sync disable'
+                    : 'Handoff sync disabled. Nothing further leaves this machine on this channel.');
+                return;
+            }
+            case 'status': {
+                const enabled = process.env.PRISM_HANDOFF_SYNC === '1' ||
+                    (process.env.PRISM_HANDOFF_SYNC !== '0' &&
+                        ['1', 'true'].includes((await (await import('./storage/configStorage.js')).getSetting('PRISM_HANDOFF_SYNC', '')).trim().toLowerCase()));
+                const { loadOrCreateDeviceIdentity } = await import('./crypto/deviceKeys.js');
+                const id = loadOrCreateDeviceIdentity();
+                console.log(`Handoff sync: ${enabled ? 'ENABLED' : 'disabled'}`);
+                console.log(`This device: ${id.keyId}${id.created ? ' (key created just now)' : ''}`);
+                return;
+            }
+            case 'pull': {
+                if (!project) {
+                    console.error('Usage: prism sync pull <project>');
+                    process.exit(1);
+                }
+                const { pullHandoff, renderPulledHandoff } = await import('./sync/handoffSync.js');
+                const r = await pullHandoff(project);
+                console.log(renderPulledHandoff(r));
+                if (!r.ok)
+                    process.exit(1);
+                return;
+            }
+            case 'devices': {
+                const { getSynaluxJwt } = await import('./utils/synaluxJwt.js');
+                const jwt = await getSynaluxJwt();
+                if (!jwt) {
+                    console.error('No portal credentials — sign in first.');
+                    process.exit(1);
+                }
+                const base = (process.env.PRISM_SYNALUX_BASE_URL?.trim() || process.env.SYNALUX_BASE_URL?.trim() ||
+                    (await import('./config.js')).PRISM_SYNALUX_BASE_URL || '').replace(/\/+$/, '');
+                const res = await fetch(`${base}/api/v1/prism/sync/devices`, {
+                    headers: { Authorization: `Bearer ${jwt}` }, signal: AbortSignal.timeout(10_000)
+                });
+                if (!res.ok) {
+                    console.error(`Device list unavailable (HTTP ${res.status}).`);
+                    process.exit(1);
+                }
+                const data = await res.json();
+                for (const d of data.devices) {
+                    console.log(`${d.revoked ? '✗ (revoked)' : '✓'} ${d.device_id}  ${d.label ?? ''}  last seen ${d.last_seen_at}`);
+                }
+                console.log('Revoke a lost machine via the portal dashboard.');
+                return;
+            }
+            default:
+                console.error(`Unknown action "${action}" — expected enable | disable | status | pull | devices.`);
+                process.exit(1);
+        }
+    }
+    catch (err) {
+        console.error(`sync 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/server.js

@@ -124,7 +124,7 @@ ONBOARDING_WIZARD_TOOL, EXTRACT_ENTITIES_TOOL, API_ANALYTICS_TOOL, BACKUP_DATABA
 // v15.5: Knowledge Ingestion
 KNOWLEDGE_INGEST_TOOL, 
 // v19.2: Inference Metrics
-INFERENCE_METRICS_TOOL, SAVINGS_TOOL, sessionSaveLedgerHandler, sessionSaveHandoffHandler, sessionLoadContextHandler, sessionBootstrapHandler, sessionRoutePromptHandler, knowledgeSearchHandler, knowledgeForgetHandler, 
+INFERENCE_METRICS_TOOL, SAVINGS_TOOL, SYNC_PULL_HANDOFF_TOOL, sessionSaveLedgerHandler, sessionSaveHandoffHandler, sessionLoadContextHandler, sessionBootstrapHandler, sessionRoutePromptHandler, knowledgeSearchHandler, knowledgeForgetHandler, 
 // ─── v0.4.0: New tool handlers ───
 compactLedgerHandler, sessionSearchMemoryHandler, backfillEmbeddingsHandler, sessionBackfillLinksHandler, sessionSynthesizeEdgesHandler, sessionCognitiveRouteHandler, 
 // ─── v2.0: Time Travel handlers ───
@@ -241,6 +241,7 @@ function buildSessionMemoryTools() {
         INFERENCE_METRICS_TOOL, // inference_metrics — read-only session delegation stats
         // ─── v20.16: Local-serving meter ───
         SAVINGS_TOOL, // local_savings — tokens displaced by local serving
+        SYNC_PULL_HANDOFF_TOOL, // sync_pull_handoff — E2E cross-machine handoff pull
     ];
 }
 // ─── v0.4.0: Resource Subscription Tracking ──────────────────────
@@ -771,7 +772,9 @@ export function createServer() {
                         // REVIEWER NOTE: v0.4.0 passes the server reference so the
                         // handler can trigger resource update notifications after
                         // a successful save. See notifyResourceUpdate() above.
-                        result = await sessionSaveHandoffHandler(args, server);
+                        result = await sessionSaveHandoffHandler(args, server); // Handoff sync (paid, opt-in, fail-soft): seal to the account's
+                        // devices and relay ciphertext. Gated entirely inside the module.
+                        void import("./sync/handoffSync.js").then(m => m.pushHandoffFromArgs(args)).catch(() => { });
                         break;
                     case "session_load_context":
                         if (!SESSION_MEMORY_ENABLED)
@@ -1031,6 +1034,12 @@ export function createServer() {
                     case "inference_metrics":
                         result = await inferenceMetricsHandler(args);
                         break;
+                    case "sync_pull_handoff": {
+                        const { pullHandoff, renderPulledHandoff } = await import("./sync/handoffSync.js");
+                        const pr = await pullHandoff(String(args?.project ?? ""));
+                        result = { content: [{ type: "text", text: renderPulledHandoff(pr) }], ...(pr.ok ? {} : { isError: true }) };
+                        break;
+                    }
                     case "local_savings":
                         result = await savingsHandler(args);
                         break;

package/dist/sync/handoffSync.js

@@ -0,0 +1,309 @@
+/**
+ * Cross-machine handoff sync — the Phase-2 engine on top of src/crypto/.
+ *
+ * Flow: on session_save_handoff (and only then), if the user opted in, this
+ * seals the handoff to ALL of the account's active device public keys and
+ * PUTs the ciphertext to the portal relay. Another machine pulls, opens with
+ * its own device key, and resumes. The relay stores ciphertext only — see
+ * src/crypto/syncEnvelope.ts for the properties that make that architectural.
+ *
+ * Consent model (mirrors savingsSync, deliberately):
+ *   1. OPT-IN — PRISM_HANDOFF_SYNC (env or stored setting), default OFF.
+ *   2. PAID — client-side plan gate; the portal enforces the real one.
+ *   3. FAIL-SOFT — sync never breaks a save; failures debugLog and return.
+ *
+ * Trust boundary, handled rather than hand-waved: the DEVICE LIST comes from
+ * the portal, and a compromised portal could inject an attacker's public key
+ * to receive readable copies of future blobs. Mitigation is TOFU pinning:
+ * every device keyId this machine has ever sealed to is remembered locally
+ * (~/.prism-mcp/known-sync-devices.json); when the set GROWS, the push still
+ * succeeds (users legitimately add machines) but the result carries a
+ * loud warning naming the new keyIds, and the warning repeats until the user
+ * has seen a push after the growth. Silent key injection is the attack;
+ * unnoticed growth is what TOFU removes.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { debugLog } from "../utils/logger.js";
+import { getEntitlements } from "../utils/entitlements.js";
+import { getSynaluxJwt } from "../utils/synaluxJwt.js";
+import { getSetting } from "../storage/configStorage.js";
+import { loadOrCreateDeviceIdentity } from "../crypto/deviceKeys.js";
+import { sealFor, openSealed, isSealedEnvelope, EnvelopeError, keyIdOf } from "../crypto/syncEnvelope.js";
+import { PRISM_SYNALUX_BASE_URL } from "../config.js";
+const TIMEOUT_MS = 10_000;
+const PROJECT_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/;
+function baseUrl() {
+    return (process.env.PRISM_SYNALUX_BASE_URL?.trim() ||
+        process.env.SYNALUX_BASE_URL?.trim() ||
+        PRISM_SYNALUX_BASE_URL ||
+        "").replace(/\/+$/, "");
+}
+async function syncEnabled() {
+    if (process.env.PRISM_HANDOFF_SYNC === "1")
+        return true;
+    if (process.env.PRISM_HANDOFF_SYNC === "0")
+        return false;
+    const setting = (await getSetting("PRISM_HANDOFF_SYNC", "")).trim();
+    return setting === "1" || setting.toLowerCase() === "true";
+}
+function aadFor(project) {
+    return `prism-sync:v1:${project}:handoff`;
+}
+// ── TOFU pinning ─────────────────────────────────────────────────────────────
+function pinPath() {
+    const dir = process.env.PRISM_DATA_DIR
+        ? resolve(process.env.PRISM_DATA_DIR)
+        : resolve(homedir(), ".prism-mcp");
+    return join(dir, "known-sync-devices.json");
+}
+function readPins() {
+    try {
+        const p = pinPath();
+        if (!existsSync(p))
+            return new Set();
+        const parsed = JSON.parse(readFileSync(p, "utf8"));
+        return new Set(Array.isArray(parsed.device_ids)
+            ? parsed.device_ids.filter((d) => typeof d === "string")
+            : []);
+    }
+    catch {
+        // Unreadable pins fail toward WARNING (everything looks new), never
+        // toward silence.
+        return new Set();
+    }
+}
+function writePins(pins) {
+    try {
+        writeFileSync(pinPath(), JSON.stringify({ device_ids: [...pins].sort() }, null, 2) + "\n", { mode: 0o600 });
+    }
+    catch (e) {
+        debugLog(`[handoff-sync] pin write failed: ${e instanceof Error ? e.message : e}`);
+    }
+}
+let registeredThisProcess = false;
+async function ensureRegistered(jwt, fetchImpl) {
+    if (registeredThisProcess)
+        return true;
+    const device = loadOrCreateDeviceIdentity();
+    const res = await fetchImpl(`${baseUrl()}/api/v1/prism/sync/devices`, {
+        method: "POST",
+        headers: { "Authorization": `Bearer ${jwt}`, "Content-Type": "application/json" },
+        body: JSON.stringify({
+            device_id: device.keyId,
+            public_key: device.rawPublicKey.toString("base64"),
+        }),
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    if (!res.ok) {
+        debugLog(`[handoff-sync] device registration failed: HTTP ${res.status}`);
+        return false;
+    }
+    registeredThisProcess = true;
+    return true;
+}
+/** Test hook. */
+export function _resetHandoffSyncForTest() {
+    registeredThisProcess = false;
+}
+async function fetchActiveDevices(jwt, fetchImpl) {
+    const res = await fetchImpl(`${baseUrl()}/api/v1/prism/sync/devices`, {
+        headers: { "Authorization": `Bearer ${jwt}` },
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    if (!res.ok)
+        return null;
+    const data = (await res.json());
+    if (!Array.isArray(data.devices))
+        return null;
+    const out = [];
+    for (const d of data.devices) {
+        if (typeof d !== "object" || d === null)
+            continue;
+        const r = d;
+        if (typeof r.device_id !== "string" || typeof r.public_key !== "string" || r.revoked)
+            continue;
+        // The adversary this whole module names is a portal that lies in THIS
+        // response. It cannot be trusted to tell the truth about which key
+        // belongs to which device_id, so the asserted device_id is not used as
+        // an identity anywhere downstream: re-derive the kid from the key that
+        // will actually receive the blob. A portal that reuses a pinned
+        // device_id with a swapped key produces a DIFFERENT derivedKid here, so
+        // TOFU sees a new device and warns — the exact injection the header
+        // promises to surface. A portal that also forges the device_id to match
+        // its swapped key still surfaces, because the pin is on the derived kid.
+        let rawKey;
+        try {
+            rawKey = Buffer.from(r.public_key, "base64");
+        }
+        catch {
+            continue;
+        }
+        if (rawKey.length !== 32)
+            continue;
+        let derivedKid;
+        try {
+            derivedKid = keyIdOf(rawKey);
+        }
+        catch {
+            continue;
+        }
+        out.push({ rawKey, derivedKid, assertedId: r.device_id });
+    }
+    return out;
+}
+export async function pushHandoff(project, handoff, fetchImpl = fetch) {
+    try {
+        if (!(await syncEnabled()))
+            return { pushed: false, reason: "disabled" };
+        if (!PROJECT_RE.test(project))
+            return { pushed: false, reason: "bad_project" };
+        const ent = await getEntitlements();
+        if (ent.plan === "free")
+            return { pushed: false, reason: "free_plan" };
+        if (!baseUrl())
+            return { pushed: false, reason: "no_base_url" };
+        const jwt = await getSynaluxJwt();
+        if (!jwt)
+            return { pushed: false, reason: "no_jwt" };
+        if (!(await ensureRegistered(jwt, fetchImpl))) {
+            return { pushed: false, reason: "registration_failed" };
+        }
+        const devices = await fetchActiveDevices(jwt, fetchImpl);
+        if (!devices || devices.length === 0) {
+            return { pushed: false, reason: "device_list_unavailable" };
+        }
+        const self = loadOrCreateDeviceIdentity();
+        // Always seal to SELF from local key material, regardless of the portal
+        // list. A hostile (or merely stale) portal that omits this device would
+        // otherwise make the origin unable to open its own handoff — a
+        // self-inflicted lockout. Deduped by derived kid so a portal that DOES
+        // list us is not a double recipient.
+        const targets = new Map();
+        targets.set(self.keyId, self.rawPublicKey);
+        for (const d of devices)
+            targets.set(d.derivedKid, d.rawKey);
+        // TOFU keys on the DERIVED kid — the same value sealFor puts in the
+        // envelope as the recipient — so a swapped key is a new identity here,
+        // never a silent reuse of a pinned device_id. Self is never "new".
+        const pins = readPins();
+        const newDevices = [...targets.keys()].filter((kid) => kid !== self.keyId && !pins.has(kid));
+        const payload = Buffer.from(JSON.stringify({
+            v: 1,
+            project,
+            saved_at: new Date().toISOString(),
+            origin_device_id: self.keyId,
+            handoff,
+        }), "utf8");
+        const envelope = sealFor([...targets.values()], payload, aadFor(project));
+        const res = await fetchImpl(`${baseUrl()}/api/v1/prism/sync/blob`, {
+            method: "PUT",
+            headers: { "Authorization": `Bearer ${jwt}`, "Content-Type": "application/json" },
+            body: JSON.stringify({ project, kind: "handoff", envelope, origin_device_id: self.keyId }),
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+        if (!res.ok) {
+            debugLog(`[handoff-sync] relay rejected blob: HTTP ${res.status}`);
+            return { pushed: false, reason: "portal_rejected" };
+        }
+        // Pin only AFTER a successful push, so a failed push re-warns next time.
+        if (newDevices.length > 0) {
+            for (const id of newDevices)
+                pins.add(id);
+            writePins(pins);
+            debugLog(`[handoff-sync] ⚠ sealed to ${newDevices.length} device(s) this machine had never seen: ${newDevices.join(", ")}`);
+        }
+        return { pushed: true, reason: "ok", sealed_to: targets.size, ...(newDevices.length ? { new_devices: newDevices } : {}) };
+    }
+    catch (e) {
+        debugLog(`[handoff-sync] push failed: ${e instanceof Error ? e.message : e}`);
+        return { pushed: false, reason: "error" };
+    }
+}
+/** Fire-and-forget adapter for the session_save_handoff dispatch site. */
+export async function pushHandoffFromArgs(args) {
+    if (typeof args !== "object" || args === null)
+        return;
+    const o = args;
+    const project = typeof o.project === "string" ? o.project : null;
+    if (!project)
+        return;
+    const result = await pushHandoff(project, o);
+    if (result.pushed && result.new_devices?.length) {
+        console.error(`[handoff-sync] ⚠ NEW sync device(s) on your account: ${result.new_devices.join(", ")}. ` +
+            `If you did not add a machine, revoke it: prism sync devices`);
+    }
+}
+export async function pullHandoff(project, fetchImpl = fetch) {
+    try {
+        if (!(await syncEnabled()))
+            return { ok: false, reason: "disabled" };
+        if (!PROJECT_RE.test(project))
+            return { ok: false, reason: "bad_project" };
+        if (!baseUrl())
+            return { ok: false, reason: "no_base_url" };
+        const jwt = await getSynaluxJwt();
+        if (!jwt)
+            return { ok: false, reason: "no_jwt" };
+        const res = await fetchImpl(`${baseUrl()}/api/v1/prism/sync/blob?project=${encodeURIComponent(project)}`, { headers: { "Authorization": `Bearer ${jwt}` }, signal: AbortSignal.timeout(TIMEOUT_MS) });
+        if (res.status === 404)
+            return { ok: false, reason: "no_blob" };
+        if (res.status === 401 || res.status === 402 || res.status === 403) {
+            return { ok: false, reason: "not_entitled" };
+        }
+        if (!res.ok)
+            return { ok: false, reason: "portal_error" };
+        const body = (await res.json());
+        if (!isSealedEnvelope(body.envelope))
+            return { ok: false, reason: "bad_envelope" };
+        const self = loadOrCreateDeviceIdentity();
+        let plaintext;
+        try {
+            plaintext = openSealed(body.envelope, self.privateKey, self.rawPublicKey, aadFor(project));
+        }
+        catch (e) {
+            if (e instanceof EnvelopeError && /not a recipient/.test(e.message)) {
+                // Sealed before this device existed (or after it was revoked).
+                // The NEXT save from any current device includes this machine.
+                return { ok: false, reason: "not_recipient" };
+            }
+            return { ok: false, reason: "bad_envelope" };
+        }
+        const payload = JSON.parse(plaintext.toString("utf8"));
+        if (!payload || payload.v !== 1 || payload.project !== project) {
+            return { ok: false, reason: "bad_envelope" };
+        }
+        return {
+            ok: true, reason: "ok", payload,
+            origin_device_id: typeof body.origin_device_id === "string" ? body.origin_device_id : undefined,
+            updated_at: typeof body.updated_at === "string" ? body.updated_at : undefined,
+        };
+    }
+    catch (e) {
+        debugLog(`[handoff-sync] pull failed: ${e instanceof Error ? e.message : e}`);
+        return { ok: false, reason: "error" };
+    }
+}
+/** Human rendering for the tool/CLI pull surfaces. */
+export function renderPulledHandoff(r) {
+    if (!r.ok || !r.payload) {
+        const why = {
+            disabled: "Handoff sync is off on this machine. Enable: prism sync enable",
+            no_blob: "No synced handoff exists for this project yet.",
+            not_recipient: "A handoff exists but was sealed before this device joined — it will include this machine after the next save elsewhere.",
+            not_entitled: "Cross-machine sync needs a paid plan and a signed-in account.",
+            no_jwt: "No portal credentials on this machine — sign in first.",
+            bad_envelope: "The stored blob failed authentication — refusing to use it.",
+        };
+        return `🔄 ${why[r.reason] ?? `Handoff sync unavailable (${r.reason}).`}`;
+    }
+    const p = r.payload;
+    const lines = [
+        `🔄 Synced handoff for ${p.project}`,
+        `  From device ${p.origin_device_id} at ${p.saved_at}`,
+        "",
+        JSON.stringify(p.handoff, null, 2),
+    ];
+    return lines.join("\n");
+}

package/dist/tools/index.js

@@ -63,7 +63,7 @@ export { verifyBehaviorHandler } from "./behavioralVerifierHandler.js";
 // Chunks source code, generates Q&A via Claude Haiku, stores in knowledge graph.
 // Three entry points: MCP tool, REST API, GitHub webhook.
 export { KNOWLEDGE_INGEST_TOOL } from "./ingestDefinitions.js";
-export { INFERENCE_METRICS_TOOL, SAVINGS_TOOL } from "./sessionMemoryDefinitions.js";
+export { INFERENCE_METRICS_TOOL, SAVINGS_TOOL, SYNC_PULL_HANDOFF_TOOL } from "./sessionMemoryDefinitions.js";
 export { knowledgeIngestHandler, handleGitHubWebhook, ingestKnowledge, isIngestArgs } from "./ingestHandler.js";
 // ── v15.4: prism_infer — local-first inference (RAM-gated cascade) ──
 // Always available. Saves caller's cloud tokens by routing to local

package/dist/tools/sessionMemoryDefinitions.js

@@ -1952,6 +1952,22 @@ export const INFERENCE_METRICS_TOOL = {
         },
     },
 };
+// ─── v20.17: Cross-machine handoff sync ────────────────────
+export const SYNC_PULL_HANDOFF_TOOL = {
+    name: "sync_pull_handoff",
+    description: "Pulls this account's synced handoff for a project from the E2E relay and " +
+        "opens it with THIS machine's device key. The relay stores ciphertext only; " +
+        "a handoff is readable here only if it was sealed to this device. Requires " +
+        "handoff sync enabled (prism sync enable), a paid plan, and a signed-in " +
+        "account. Push happens automatically on session_save_handoff.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            project: { type: "string", description: "Project whose handoff to pull." },
+        },
+        required: ["project"],
+    },
+};
 // ─── v20.16: Local-serving meter ───────────────────────────
 export const SAVINGS_TOOL = {
     name: "local_savings",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prism-mcp-server",
-  "version": "20.16.0",
+  "version": "20.17.0",
   "mcpName": "io.github.dcostenco/prism-coder",
   "description": "Persistent session memory for AI coding agents that never leaves your machine — including the on-device model that reasons over it. Restores your prior decisions, open TODOs, and changed files across sessions; adds associative recall of related past work, semantic drift detection, and local inference. Local-first by default. Works with Claude Code, Cursor, and Codex.",
   "module": "index.ts",