phaedo-mcp 0.1.0

package/pairing.js

@@ -0,0 +1,184 @@
+// MCP server self-pairing (P3, plan: mcp-revocable-approval-plan.md).
+//
+// The server is a real, independent client: its own long-term X25519 identity,
+// its own SAS-confirmed pairing with the phone vault, listed + revocable on the
+// phone (spec §8.4 v0.1.6 multi-client). This obviates the manual pairing-record
+// export — `phaedo-mcp pair` produces `pairing.json` itself.
+//
+// Direct port of the extension's popup.js autoPair: LAN auto-discovery first
+// (same Wi-Fi → no code typing, just the SAS confirm on the phone), else the
+// relay typed-code rendezvous (D3: LAN + relay). The artifact is never touched
+// here — only the pairing handshake; the fingerprint is pulled later by
+// phone-source.js using the record this writes.
+
+import { writeFileSync } from 'fs';
+import { resolve } from 'path';
+import { networkInterfaces } from 'os';
+import { Phaedo, b64uEnc, b64uDec } from './lib/phaedo-crypto.js';
+import { installNodeVault } from './lib/node-vault.js';
+
+const { Identity, Kdf, Protocol } = Phaedo;
+const RELAY_BASE = 'https://phaedo-relay.fly.dev';
+const API_PORT   = 7432;
+const PUBKEY_SIZE = Protocol.SIZES.X25519_PUBKEY;
+// Crockford base32 (no I/L/O/U — unambiguous when typed), matching the extension.
+const ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+
+export function generatePairingCode() {
+  const bytes = crypto.getRandomValues(new Uint8Array(8));
+  let s = '';
+  for (let i = 0; i < 8; i++) s += ALPHABET[bytes[i] & 31];
+  return s;
+}
+
+export function formatCode(code) {
+  return `${code.slice(0, 4)}-${code.slice(4)}`;
+}
+
+function localSubnets() {
+  const out = new Set();
+  for (const list of Object.values(networkInterfaces())) {
+    for (const ni of list || []) {
+      if (ni.family === 'IPv4' && !ni.internal) out.add(ni.address.split('.').slice(0, 3).join('.'));
+    }
+  }
+  return [...out];
+}
+
+// Scan the local /24(s) for a phone answering /v1/health on :7432.
+export async function discoverPhone() {
+  for (const subnet of localSubnets()) {
+    const ips = Array.from({ length: 254 }, (_, i) => `${subnet}.${i + 1}`);
+    try {
+      return await Promise.any(ips.map(ip =>
+        fetch(`http://${ip}:${API_PORT}/v1/health`, { signal: AbortSignal.timeout(800) })
+          .then(r => (r.ok ? ip : Promise.reject(new Error('no'))))
+          .catch(() => Promise.reject(new Error('no')))
+      ));
+    } catch { /* no phone on this subnet — try the next */ }
+  }
+  return null;
+}
+
+async function fetchRelayOffer(code, timeoutMs = 120000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`${RELAY_BASE}/pair-offer/${encodeURIComponent(code)}`, { signal: AbortSignal.timeout(5000) });
+      if (res.ok) {
+        const b = await res.json().catch(() => ({}));
+        if (b.relay_device_id) return b;
+      }
+    } catch { /* keep polling */ }
+    await new Promise(r => setTimeout(r, 3000));
+  }
+  return null;
+}
+
+async function pollPairVerification(endpoint, client_id, client_secret, timeoutMs = 120000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`${endpoint}/v1/pair-status`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ client_id, client_secret }),
+        signal: AbortSignal.timeout(4000),
+      });
+      if (res.status === 401) return 'denied';
+      if (res.ok) {
+        const b = await res.json().catch(() => ({}));
+        if (b.denied) return 'denied';
+        if (b.verified) return 'verified';
+      }
+    } catch { /* phone briefly unreachable — keep polling */ }
+    await new Promise(r => setTimeout(r, 1500));
+  }
+  return 'timeout';
+}
+
+// Core handshake against a resolved endpoint. Returns the pairing record (the
+// caller persists it). Exported so tests can drive it against a mock phone.
+export async function pairAtEndpoint(endpoint, { code, relayDeviceId = null, log = () => {} } = {}) {
+  const extPub     = await Identity.getPublicKey();
+  const extPubB64u = b64uEnc(extPub);
+
+  const res = await fetch(`${endpoint}/v1/pair`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      pairing_token: code,
+      client_name:   'Phaedo MCP Server',
+      client_type:   'mcp',
+      ext_pub:       extPubB64u,
+    }),
+    signal: AbortSignal.timeout(32000),
+  });
+  if (!res.ok) throw new Error(`pair request failed (HTTP ${res.status})`);
+  const body = await res.json();
+  if (!body.vault_pub) throw new Error('pair response missing vault_pub');
+
+  const vaultPub = b64uDec(body.vault_pub);
+  if (vaultPub.length !== PUBKEY_SIZE) throw new Error(`vault_pub wrong size (${vaultPub.length})`);
+
+  // Long-term ECDH → pair_key; SAS (the MITM anchor) over both pubkeys.
+  const shared  = await Identity.deriveSharedWithPeer(vaultPub);
+  const pairKey = await Kdf.derivePairKey(shared, body.client_id);
+  const sas     = Kdf.formatSAS(await Kdf.deriveSAS(extPub, vaultPub));
+
+  log('');
+  log('  Compare this code with the one on your phone:');
+  log('');
+  log(`        ${sas}`);
+  log('');
+  log('  If they match, tap "Codes match" on your phone.');
+
+  const outcome = await pollPairVerification(endpoint, body.client_id, body.client_secret);
+  if (outcome === 'denied')  throw new Error('pairing was denied on the phone');
+  if (outcome === 'timeout') throw new Error('timed out waiting for phone confirmation');
+
+  return {
+    endpoint,
+    client_id:     body.client_id,
+    client_secret: body.client_secret,
+    pair_key:      b64uEnc(pairKey),
+    vault_pub:     body.vault_pub,
+    sas,
+    ...(relayDeviceId ? { relay_device_id: relayDeviceId } : {}),
+  };
+}
+
+// Full flow: ensure identity → resolve endpoint (LAN → relay) → pair → persist.
+export async function pair({ identityPath, pairingPath, log = console.log } = {}) {
+  installNodeVault(identityPath);
+  const code = generatePairingCode();
+
+  log('Looking for your phone on the local network…');
+  const ip = await discoverPhone();
+
+  let record;
+  if (ip) {
+    log(`Found your phone at ${ip}. Approve "Phaedo MCP Server" on your phone.`);
+    record = await pairAtEndpoint(`http://${ip}:${API_PORT}`, { code, log });
+  } else {
+    log('');
+    log("Couldn't find your phone on this network — pairing over the relay.");
+    log('');
+    log(`  On your phone:  Pair with code  →   ${formatCode(code)}`);
+    log('');
+    log('Waiting for you to enter the code on your phone…');
+    const offer = await fetchRelayOffer(code);
+    if (!offer) throw new Error('timed out waiting for the phone to enter the code');
+    record = await pairAtEndpoint(`${RELAY_BASE}/relay/${offer.relay_device_id}`, {
+      code, relayDeviceId: offer.relay_device_id, log,
+    });
+  }
+
+  // sas is display-only (the MITM compare already happened) — phone-source.js
+  // doesn't need it; persist the record fields it reads.
+  const { sas, ...persist } = record;
+  writeFileSync(resolve(pairingPath), JSON.stringify(persist, null, 2), { mode: 0o600 });
+  log('');
+  log(`✓ Paired. Wrote ${pairingPath}`);
+  return record;
+}

package/pairing.sample.json

@@ -0,0 +1,8 @@
+{
+  "_comment": "Phase 1b pairing record (Option B: shared with the extension). Copy to mcp/pairing.json (gitignored) or point PHAEDO_PAIRING at it. These are the fields from the extension's phaedo_local_pairing. pair_key is a long-term secret — never commit a real one.",
+  "endpoint": "http://192.168.1.50:7432",
+  "client_id": "REPLACE_WITH_EXTENSION_client_id",
+  "client_secret": "REPLACE_WITH_EXTENSION_client_secret",
+  "pair_key": "REPLACE_WITH_EXTENSION_pair_key_base64url_32_bytes",
+  "vault_pub": "REPLACE_WITH_phone_vault_pub_base64url"
+}

package/phone-source.js

@@ -0,0 +1,141 @@
+// MCP Phase 1b — real key boundary (Option B: share the extension's pairing).
+//
+// Given a pairing record that already holds `pair_key` (exported from the paired
+// extension), this runs the spec-faithful authorize → pull → decrypt flow — a
+// direct port of popup.js reAuthorize (:745) + silentSync (:883):
+//
+//   authorize: fresh ephemeral X25519, HMAC-bound to pair_key, POST /v1/authorize,
+//              verify the vault's reply MAC, ECDH → HKDF session_key
+//   pull:      GET /v1/profile (Bearer session_token) → Envelope.unwrap → fingerprint
+//
+// No long-term private key and no phaedoVault are needed (pair_key suffices), so
+// nothing browser-only is touched. The decrypted fingerprint is returned to the
+// caller and never written to disk (the 1b at-rest cache is a later increment).
+//
+// Session is cached in memory and re-authorized on expiry — fully autonomous
+// after the one-time pairing.
+
+import { readFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+import { Phaedo, b64uEnc, b64uDec } from './lib/phaedo-crypto.js';
+
+const { Identity, Kdf, Envelope } = Phaedo;
+const EXPIRY_SKEW_MS = 30 * 1000; // re-auth this early to avoid edge-of-expiry races
+const TIMEOUT_MS = 5000;          // fail fast when the phone is unreachable → cache fallback
+
+// ── Pairing record (Option B: exported from the extension's phaedo_local_pairing)
+// { endpoint, client_id, client_secret, pair_key (b64url 32B), vault_pub, ... }
+export async function loadPairingRecord(baseDir) {
+  const path = process.env.PHAEDO_PAIRING
+    ? resolve(process.cwd(), process.env.PHAEDO_PAIRING)
+    : resolve(baseDir, 'pairing.json');
+  const rec = JSON.parse(await readFile(path, 'utf8'));
+  for (const k of ['endpoint', 'client_id', 'client_secret', 'pair_key']) {
+    if (!rec[k]) throw new Error(`Pairing record at ${path} is missing "${k}".`);
+  }
+  return rec;
+}
+
+// True iff a pairing record is configured (→ use the phone source over local JSON).
+export function hasPairingRecord(baseDir) {
+  if (process.env.PHAEDO_PAIRING) return true;
+  return existsSync(resolve(baseDir, 'pairing.json'));
+}
+
+// In-memory session cache, keyed by endpoint. Holds session_key (never persisted).
+const _sessions = new Map();
+
+async function authorize(rec, deps) {
+  const { fetch, now } = deps;
+  const pairKey = b64uDec(rec.pair_key);
+
+  const eph = await Identity.generateEphemeral();                 // {publicKey, privateKey}
+  const extMac = await Kdf.authEphemeral(pairKey, 'ext', eph.publicKey);
+
+  const res = await fetch(`${rec.endpoint}/v1/authorize`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      client_id: rec.client_id,
+      client_secret: rec.client_secret,
+      scopes: ['profile:full'],
+      eph_ext_pub: b64uEnc(eph.publicKey),
+      eph_mac: b64uEnc(extMac),
+    }),
+    signal: AbortSignal.timeout(TIMEOUT_MS),
+  });
+  if (!res.ok) throw new PhoneError(`authorize failed (${res.status})`, res.status);
+  const body = await res.json();
+
+  const ephVaultPub = b64uDec(body.eph_vault_pub);
+  const macOk = await Kdf.verifyAuthEphemeral(pairKey, 'vault', ephVaultPub, b64uDec(body.eph_mac));
+  if (!macOk) throw new PhoneError('vault eph_mac verification failed (possible MITM)', 0);
+
+  const shared = await Identity.deriveEphemeralShared(eph.privateKey, ephVaultPub);
+  const sessionKey = await Kdf.deriveSessionKey(shared, body.session_token);
+  shared.fill(0);
+
+  const session = { token: body.session_token, sessionKey, expiresAt: Date.parse(body.expires_at) || (now() + 3600000) };
+  _sessions.set(rec.endpoint, session);
+  return session;
+}
+
+async function getSession(rec, deps) {
+  const cached = _sessions.get(rec.endpoint);
+  if (cached && deps.now() < cached.expiresAt - EXPIRY_SKEW_MS) return cached;
+  return authorize(rec, deps);
+}
+
+// Map the §9-profile inner plaintext to the vault payload shape the projection
+// expects. Profile inner is { data: <fingerprint>, metrics: {signals, ling,
+// sessions}, scopes } (mobile localServer handleProfile + popup restoreMetrics).
+function toVaultPayload(inner) {
+  const m = inner.metrics || {};
+  return {
+    phaedo_fingerprint: inner.data,
+    phaedo_behavioral_signals: m.signals || {},
+    phaedo_linguistic_profile: m.ling || {},
+    phaedo_session_metrics: m.sessions || {},
+  };
+}
+
+async function pull(rec, session, deps) {
+  const res = await deps.fetch(`${rec.endpoint}/v1/profile`, {
+    headers: { authorization: `Bearer ${session.token}` },
+    signal: AbortSignal.timeout(TIMEOUT_MS),
+  });
+  if (res.status === 401) throw new PhoneError('session rejected', 401);
+  if (!res.ok) throw new PhoneError(`profile failed (${res.status})`, res.status);
+  const body = await res.json();
+  const plaintext = await Envelope.unwrap(body.envelope, session.sessionKey);
+  const inner = JSON.parse(new TextDecoder().decode(plaintext));
+  plaintext.fill(0);
+  if (!inner || !inner.data) throw new PhoneError('profile envelope missing data', 0);
+  return toVaultPayload(inner);
+}
+
+export class PhoneError extends Error {
+  constructor(message, status) { super(message); this.status = status; }
+}
+
+// Pull + decrypt the live fingerprint from the phone. Re-authorizes once if the
+// cached session is rejected (e.g. the phone restarted). `deps` is injectable for
+// tests: { fetch, now }.
+export async function loadFingerprintFromPhone(rec, deps = {}) {
+  const d = { fetch: deps.fetch || globalThis.fetch, now: deps.now || Date.now };
+  let session = await getSession(rec, d);
+  try {
+    return await pull(rec, session, d);
+  } catch (err) {
+    if (err instanceof PhoneError && err.status === 401) {
+      _sessions.delete(rec.endpoint);          // stale session → re-authorize once
+      session = await authorize(rec, d);
+      return pull(rec, session, d);
+    }
+    throw err;
+  }
+}
+
+// test/maintenance helper
+export function _clearSessions() { _sessions.clear(); }

package/policy-editor.html

@@ -0,0 +1,146 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Phaedo — Consultation Deference Policies</title>
+<style>
+  :root { --ink:#1a1a1a; --mut:#666; --line:#e3e3e3; --acc:#2b6cb0; --bg:#fafafa; --warn:#b45309; }
+  * { box-sizing: border-box; }
+  body { font: 15px/1.55 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; color: var(--ink); margin: 0; background: var(--bg); }
+  .wrap { max-width: 860px; margin: 0 auto; padding: 28px 20px 80px; }
+  h1 { font-size: 22px; margin: 0 0 4px; }
+  .sub { color: var(--mut); margin: 0 0 20px; }
+  .card { background:#fff; border:1px solid var(--line); border-radius:10px; padding:16px 18px; margin-bottom:16px; }
+  label { display:block; font-weight:600; font-size:13px; margin:10px 0 4px; }
+  .hint { color:var(--mut); font-weight:400; font-size:12px; }
+  input[type=text], select { width:100%; padding:8px 10px; border:1px solid var(--line); border-radius:7px; font-size:14px; background:#fff; }
+  .row { display:grid; grid-template-columns:1fr 1fr 1fr; gap:12px; }
+  .row2 { display:grid; grid-template-columns:1fr 1fr; gap:12px; }
+  button { font:inherit; cursor:pointer; border-radius:7px; border:1px solid var(--line); background:#fff; padding:8px 14px; }
+  button.primary { background:var(--acc); color:#fff; border-color:var(--acc); font-weight:600; }
+  button.danger { color:#b00; border-color:#f0caca; }
+  .rules { list-style:none; padding:0; margin:0; }
+  .rule { border:1px solid var(--line); border-radius:8px; padding:10px 12px; margin-bottom:8px; display:flex; justify-content:space-between; gap:12px; align-items:flex-start; }
+  .rule .desc { font-size:14px; }
+  .rule .meta { color:var(--mut); font-size:12px; margin-top:2px; }
+  .badge { display:inline-block; font-size:11px; font-weight:700; padding:1px 7px; border-radius:20px; background:#eef2f7; color:var(--acc); }
+  .badge.force { background:#fdecec; color:#b00; }
+  pre { background:#0f1419; color:#d7e0e8; padding:14px; border-radius:8px; overflow:auto; font-size:12.5px; }
+  .actions { display:flex; gap:10px; flex-wrap:wrap; margin-top:10px; }
+  .ok { color:#1a7a3a; font-weight:600; }
+  code { background:#eef2f7; padding:1px 5px; border-radius:4px; font-size:12.5px; }
+  .steps { background:#fff8ec; border:1px solid #f0e0c0; border-radius:8px; padding:12px 16px; font-size:13.5px; }
+</style>
+</head>
+<body>
+<div class="wrap">
+  <h1>Phaedo — Consultation deference policies</h1>
+  <p class="sub">Author standing rules that <strong>override</strong> what an agent infers about how you'd decide. e.g. <em>always escalate irreversible spend/legal</em>, <em>auto-proceed low-stakes writing</em>. Nothing here leaves this page until you save the file.</p>
+
+  <div class="card">
+    <strong>Add a rule</strong>
+    <label>When the action's domain contains any of <span class="hint">(comma-separated keywords; leave blank to match any domain)</span></label>
+    <input type="text" id="domains" placeholder="financial, payment, legal" />
+    <div class="row">
+      <div><label>Magnitude min</label><select id="magmin"><option value="">any</option><option>low</option><option>medium</option><option>high</option></select></div>
+      <div><label>Magnitude max</label><select id="magmax"><option value="">any</option><option>low</option><option>medium</option><option>high</option></select></div>
+      <div><label>Reversible?</label><select id="rev"><option value="">any</option><option value="true">reversible only</option><option value="false">irreversible only</option></select></div>
+    </div>
+    <div class="row2">
+      <div>
+        <label>Then…</label>
+        <select id="effect">
+          <option value="escalate">escalate — surface to a human</option>
+          <option value="decline">decline — refuse the action</option>
+          <option value="autoproceed">autoproceed — pre-approve</option>
+          <option value="require_human">require_human — (= escalate)</option>
+          <option value="bias_cautious">bias cautious — nudge one step safer</option>
+          <option value="bias_bold">bias bold — nudge one step bolder</option>
+        </select>
+      </div>
+      <div><label>Note <span class="hint">(shown to the agent as the reason)</span></label><input type="text" id="note" placeholder="Irreversible money goes to a human" /></div>
+    </div>
+    <div class="actions"><button class="primary" id="add">Add rule</button></div>
+  </div>
+
+  <div class="card">
+    <strong>Your rules</strong> <span class="hint">— first matching force-rule wins</span>
+    <ul class="rules" id="rules"></ul>
+    <p class="hint" id="empty">No rules yet.</p>
+  </div>
+
+  <div class="card">
+    <strong>consult-policies.json</strong>
+    <pre id="json"></pre>
+    <div class="actions">
+      <button class="primary" id="copy">Copy JSON</button>
+      <button id="download">Download consult-policies.json</button>
+      <span id="copied" class="ok" style="display:none">copied ✓</span>
+    </div>
+    <div class="steps" style="margin-top:12px">
+      <strong>To use it (desktop / MCP):</strong>
+      <ol style="margin:6px 0 0; padding-left:18px">
+        <li>Save the file as <code>~/phaedo/mcp/consult-policies.json</code> (the server auto-reads it — no env needed).</li>
+        <li>Restart your AI client (Cmd-Q Claude Desktop, or a new Claude Code session).</li>
+        <li>Call <code>phaedo_consult</code> for a matching action — the signal should reflect your rule, with the reason in <code>rationale_hint</code>.</li>
+      </ol>
+      <span class="hint">Portable alt: paste the <code>rules</code> into your vault under <code>phaedo_consult_policies</code> so they travel with you (authoring-in-app is a follow-up).</span>
+    </div>
+  </div>
+</div>
+
+<script>
+  const rules = [];
+  const $ = (id) => document.getElementById(id);
+  const val = (id) => $(id).value.trim();
+
+  function describe(r) {
+    const m = r.match || {};
+    const dom = (m.domains && m.domains.length) ? `domain ∈ {${m.domains.join(', ')}}` : 'any domain';
+    const mag = [m.magnitude_min ? `≥${m.magnitude_min}` : '', m.magnitude_max ? `≤${m.magnitude_max}` : ''].filter(Boolean).join(' ') || 'any magnitude';
+    const rev = (m.reversible === true) ? 'reversible' : (m.reversible === false) ? 'irreversible' : 'any reversibility';
+    return `${dom} · ${mag} · ${rev}`;
+  }
+  const FORCE = new Set(['escalate','decline','autoproceed','require_human']);
+
+  function render() {
+    const ul = $('rules'); ul.innerHTML = '';
+    $('empty').style.display = rules.length ? 'none' : 'block';
+    rules.forEach((r, i) => {
+      const li = document.createElement('li'); li.className = 'rule';
+      const left = document.createElement('div');
+      const badge = `<span class="badge ${FORCE.has(r.effect) ? 'force' : ''}">${r.effect}</span>`;
+      left.innerHTML = `<div class="desc">${badge} ${r.note ? r.note : ''}</div><div class="meta">${describe(r)}</div>`;
+      const rm = document.createElement('button'); rm.className = 'danger'; rm.textContent = 'Remove';
+      rm.onclick = () => { rules.splice(i, 1); render(); };
+      li.appendChild(left); li.appendChild(rm); ul.appendChild(li);
+    });
+    $('json').textContent = JSON.stringify(doc(), null, 2);
+  }
+  function doc() { return { version: '0.1', rules }; }
+
+  $('add').onclick = () => {
+    const match = {};
+    const domains = val('domains').split(',').map(s => s.trim().toLowerCase()).filter(Boolean);
+    if (domains.length) match.domains = domains;
+    if (val('magmin')) match.magnitude_min = val('magmin');
+    if (val('magmax')) match.magnitude_max = val('magmax');
+    if ($('rev').value) match.reversible = $('rev').value === 'true';
+    const rule = { id: 'rule-' + (rules.length + 1), match, effect: $('effect').value };
+    if (val('note')) rule.note = val('note');
+    rules.push(rule);
+    $('domains').value = ''; $('note').value = ''; $('magmin').value = ''; $('magmax').value = ''; $('rev').value = ''; $('effect').value = 'escalate';
+    render();
+  };
+  $('copy').onclick = async () => {
+    try { await navigator.clipboard.writeText(JSON.stringify(doc(), null, 2)); const c = $('copied'); c.style.display = 'inline'; setTimeout(() => c.style.display = 'none', 1500); } catch (e) {}
+  };
+  $('download').onclick = () => {
+    const blob = new Blob([JSON.stringify(doc(), null, 2)], { type: 'application/json' });
+    const a = document.createElement('a'); a.href = URL.createObjectURL(blob); a.download = 'consult-policies.json'; a.click(); URL.revokeObjectURL(a.href);
+  };
+  render();
+</script>
+</body>
+</html>

package/projection.js

@@ -0,0 +1,115 @@
+// Phaedo §9 Injection projection for the MCP binding.
+//
+// Reuses context-block.js (PhaedoContext) — the SAME renderer the Chrome
+// extension injects — so MCP injection is byte-identical to web injection.
+// Wraps the rendered block in the §9.3 Injection Response shape.
+
+import { createRequire } from 'module';
+import { existsSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+const require = createRequire(import.meta.url);
+// context-block.js is the shared renderer; in the dev repo it lives at the root
+// (one source of truth with the extension). For a self-contained npm package,
+// `npm run build` / prepack copies it next to this file — prefer the local copy
+// when present, else fall back to the repo root.
+const HERE = dirname(fileURLToPath(import.meta.url));
+const vendored = join(HERE, 'vendor', 'context-block.js');
+require(existsSync(vendored) ? vendored : '../context-block.js');
+const PhaedoContext = globalThis.PhaedoContext;
+if (!PhaedoContext || !PhaedoContext.renderContextBlock) {
+  throw new Error('context-block.js did not expose PhaedoContext.renderContextBlock');
+}
+
+// §9.5 error codes (the six v0.1 codes) + PhaedoError now live in errors.js so the
+// pure consultation core can share the class without importing this renderer.
+// Re-exported here so existing `import { … } from './projection.js'` sites are
+// unchanged and `instanceof PhaedoError` holds across the package.
+import { ERROR_CODES, PhaedoError } from './errors.js';
+export { ERROR_CODES, PhaedoError };
+
+const DEFAULT_TTL_MS = 60 * 60 * 1000; // 1h, mirrors the session-scoped boundary
+
+// persona_strength [0,1]: prefer a stored value; otherwise a bounded, monotone
+// v0.1 estimate from the same axes the fingerprint sharpens along (NOT claimed
+// calibrated — placeholder pending the calibration track).
+function estimatePersonaStrength(vd) {
+  const fp = vd.phaedo_fingerprint || {};
+  if (typeof fp.persona_strength === 'number') return Math.max(0, Math.min(1, fp.persona_strength));
+  const layers = fp.layers || {};
+  let answered = 0, total = 0;
+  for (const layer of Object.values(layers)) {
+    const resp = layer.responses || [];
+    total += resp.length;
+    answered += resp.filter(r => (r.answer || '').trim()).length;
+  }
+  const ling = vd.phaedo_linguistic_profile || {};
+  const answeredRatio = total ? answered / total : 0;
+  const msgFactor = 1 - Math.exp(-((ling.messageCount || 0) / 200));
+  return Math.round((0.5 * answeredRatio + 0.5 * msgFactor) * 100) / 100;
+}
+
+// Filter the vault payload's fingerprint to a requested layer subset (canonical
+// layer ids). Returns { vd, included }. ["all"] (or empty) → full passthrough.
+function selectLayers(vd, requestedLayers) {
+  const wantAll = !requestedLayers || requestedLayers.length === 0 || requestedLayers.includes('all');
+  const layers = (vd.phaedo_fingerprint && vd.phaedo_fingerprint.layers) || {};
+  if (wantAll) return { vd, included: Object.keys(layers) };
+
+  const included = requestedLayers.filter(id => layers[id]);
+  if (!included.length) {
+    throw new PhaedoError('layer_not_available', `None of the requested layers exist: ${requestedLayers.join(', ')}`);
+  }
+  const filteredLayers = {};
+  for (const id of included) filteredLayers[id] = layers[id];
+  const filteredVd = {
+    ...vd,
+    phaedo_fingerprint: { ...vd.phaedo_fingerprint, layers: filteredLayers },
+  };
+  return { vd: filteredVd, included };
+}
+
+// Build a §9.3 Injection Response from a vault payload + a §9.2-shaped request.
+// `now` is injectable for deterministic tests. Throws PhaedoError on §9.5 cases.
+export function buildInjectionResponse(vd, request = {}, now = Date.now()) {
+  if (!vd || !vd.phaedo_fingerprint) {
+    throw new PhaedoError('decryption_failed', 'No fingerprint available from the configured source.');
+  }
+  const mode = request.mode || 'standard';
+  if (mode === 'enhanced_privacy') {
+    throw new PhaedoError('mode_not_supported', 'Enhanced privacy mode is not available in this build.');
+  }
+  if (mode !== 'standard') {
+    throw new PhaedoError('request_malformed', `Unknown mode: ${mode}`);
+  }
+  if (request.requested_layers != null && !Array.isArray(request.requested_layers)) {
+    throw new PhaedoError('request_malformed', 'requested_layers must be an array or ["all"].');
+  }
+
+  const { vd: selectedVd, included } = selectLayers(vd, request.requested_layers);
+  const projection = PhaedoContext.renderContextBlock(selectedVd);
+  if (!projection) {
+    throw new PhaedoError('decryption_failed', 'Fingerprint produced no projection (empty or missing layers).');
+  }
+
+  const fp = vd.phaedo_fingerprint;
+  return {
+    phaedo_response_version: '0.1',
+    request_type: 'injection',
+    fingerprint_id: fp.fingerprint_id || fp.id || null,
+    mode: 'standard',
+    projection,
+    layers_included: included,
+    persona_strength: estimatePersonaStrength(vd),
+    expires_at: new Date(now + DEFAULT_TTL_MS).toISOString(),
+  };
+}
+
+export function errorResponse(err, requestType = 'injection') {
+  const code = err instanceof PhaedoError ? err.code : 'internal_error';
+  return {
+    phaedo_response_version: '0.1',
+    request_type: requestType,
+    error: { code, message: err.message || code },
+  };
+}

package/pull.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// Debug check: pull the fingerprint via the configured source (phone pairing.json
+// → live authorize/pull/decrypt, or the at-rest cache) and print a NON-sensitive
+// confirmation — no profile content. Verifies the pairing works end to end.
+//
+//   npm run pull
+
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import { loadFingerprint } from './fingerprint-source.js';
+
+const BASE_DIR = dirname(fileURLToPath(import.meta.url));
+
+loadFingerprint(BASE_DIR)
+  .then((vd) => {
+    const fp = (vd && vd.phaedo_fingerprint) || {};
+    const layers = fp.layers ? Object.keys(fp.layers).length : 0;
+    process.stdout.write(
+      `✓ Read your profile from the phone — fingerprint ${fp.fingerprint_id || '(no id)'}, ${layers} layer(s).\n`
+    );
+    process.exit(0);
+  })
+  .catch((err) => {
+    process.stderr.write(`✗ Couldn't read your profile: ${err.message}\n`);
+    process.exit(1);
+  });