sealcode 0.3.0 → 1.1.1

package/src/cli.js

@@ -45,7 +45,13 @@ const {
   runEscrowDisable,
   runEscrowRecover,
 } = require('./cli-escrow');
-const { runWatch } = require('./cli-watch');
+const { runWatch, spawnDaemonWatcher } = require('./cli-watch');
+const { runGuard } = require('./cli-guard');
+const {
+  runInstallService,
+  runUninstallService,
+  runSupervise,
+} = require('./cli-service');
 const ui = require('./ui');
 
 function logger(verbose) {
@@ -169,6 +175,21 @@ function build() {
     .option('-p, --project <dir>', 'project root (default: nearest ancestor with .sealcoderc.json)')
     .addHelpText('beforeAll', ui.banner(pkg.version) + '\n');
 
+  // sealcode@1.0.0: run cli-guard before every command. The guard
+  // enforces strict-watch — if a grant-derived session's watcher died
+  // and the user is about to run a sensitive command (`unlock`,
+  // `verify`, etc.), we re-lock the project before that command sees
+  // plaintext. Best-effort + zero-config; never throws.
+  program.hook('preAction', async (thisCommand, actionCommand) => {
+    try {
+      const commandName = actionCommand.name();
+      const projectRoot = resolveProject(program.opts());
+      await runGuard({ commandName, projectRoot });
+    } catch (_) {
+      // Guard MUST NOT block the user's command on a bug in itself.
+    }
+  });
+
   // -------- init --------
   program
     .command('init')
@@ -253,6 +274,7 @@ function build() {
     .option('-v, --verbose', 'log each file as it is processed', false)
     .option('--recovery', 'use recovery code instead of passphrase', false)
     .option('--keep-stubs', 'do not remove stub files', false)
+    .option('--no-watcher', 'skip auto-spawning the watcher (grant-derived sessions)')
     .action(async (opts) => {
       try {
         const projectRoot = resolveProject(program.opts());
@@ -261,11 +283,27 @@ function build() {
         ui.step(`unlocking ${ui.c.dim(projectRoot)}`);
         const sp = new ui.Spinner('decrypting').start();
         let n = 0;
+        // sealcode@1.1.0 — for grant-derived sessions, propagate the
+        // policy bundle into unlock so paths/ro/watermark are enforced
+        // even on a manual `sealcode unlock` (not just the auto-unlock
+        // performed by `sealcode redeem`).
+        const { loadSessionMeta: _lsm } = require('./keystore');
+        const _sm = _lsm(projectRoot);
+        const _policy = (_sm && _sm.meta && _sm.meta.policy) || null;
+        const _wctx = _policy && _policy.watermark ? {
+          email: (_sm && _sm.meta && _sm.meta.recipientEmail) || '',
+          grantId: (_sm && _sm.meta && _sm.meta.grantId) || '',
+          projectName: (_sm && _sm.meta && _sm.meta.projectName) || '',
+          date: new Date().toISOString().slice(0, 10),
+          fingerprint: (_sm && _sm.meta && _sm.meta.deviceFingerprint) || '',
+        } : null;
         const res = await runUnlock({
           projectRoot,
           config,
           K,
           removeStubs: !opts.keepStubs,
+          policy: _policy,
+          watermarkCtx: _wctx,
           log: (msg) => {
             n += 1;
             const file = String(msg).replace(/^\s*unlocked\s+/, '');
@@ -275,7 +313,41 @@ function build() {
             }
           },
         });
-        sp.succeed(`unlocked ${ui.c.bold(res.count)} files ${ui.c.dim(`(locked at ${res.sealedAt})`)}`);
+        const _skipped = res.skipped > 0 ? ` ${ui.c.dim(`(${res.skipped} outside grant scope)`)}` : '';
+        sp.succeed(`unlocked ${ui.c.bold(res.count)} files${_skipped} ${ui.c.dim(`(locked at ${res.sealedAt})`)}`);
+        if (res.policy && res.policy.mode === 'ro') {
+          ui.hint('  Read-only grant: files set to 0444. Any edit triggers an immediate re-lock.');
+        }
+        if (res.policy && res.policy.watermark) {
+          ui.hint('  Files are watermarked — leaks are traceable to your grant.');
+        }
+
+        // sealcode@1.0.0: if this unlock came from a grant-derived
+        // session, auto-spawn a detached watcher so the contractor
+        // can't accidentally leave the project plaintext after revoke.
+        // The watcher writes its heartbeat to a sidecar file that
+        // cli-guard inspects on subsequent commands.
+        if (opts.watcher !== false) {
+          const { loadSessionMeta } = require('./keystore');
+          const sm = loadSessionMeta(projectRoot);
+          if (sm && sm.meta.source === 'grant' && sm.meta.grantCodeHash) {
+            // We can't recover the plaintext access code from the hash
+            // alone — it lives only with the user. So we ask: do we
+            // already know it via env (SEALCODE_GRANT_CODE) or were we
+            // invoked right after `sealcode redeem <code>` in the same
+            // shell (in which case the code is in argv of the parent)?
+            //
+            // Simpler: print a clear nudge. In the future this could
+            // be wired through `sealcode redeem` itself triggering
+            // unlock + watch as a single transactional flow.
+            ui.hint(
+              `  ⤷ this session came from a temp-access code. To keep it strictly enforceable, run:`,
+            );
+            process.stdout.write(
+              `    ${ui.c.cyan('sealcode watch <code> --daemon &')}\n`,
+            );
+          }
+        }
       } catch (err) {
         process.exitCode = reportError(err);
       }
@@ -608,6 +680,17 @@ function build() {
     .option('--strict', 'lock the project root read-only between heartbeats', false)
     .option('--heartbeat <seconds>', 'how often the client must heartbeat', (v) => parseInt(v, 10), 300)
     .option('--offline-grace <seconds>', 'how long a heartbeat may be late before auto-lock', (v) => parseInt(v, 10), 1800)
+    // sealcode@1.1.0 — admin precision controls
+    .option('--paths <list>', 'comma-separated allowed path prefixes (e.g. "src/api/,tests/")', (v) =>
+      v.split(',').map((s) => s.trim()).filter(Boolean),
+    )
+    .option('--mode <rw|ro>', 'access mode: rw (read+write, default) or ro (read-only, watcher-enforced)', 'rw')
+    .option('--watermark <template>', 'inject this comment at the top of every unlocked file (supports {email} {grantId} {projectName} {date} {fingerprint})')
+    .option('--idle <minutes>', 'auto-lock after N minutes of no file activity (0 = disabled)', (v) => parseInt(v, 10), 0)
+    .option('--allow-ip <cidr...>', 'restrict redeem/heartbeat to these CIDRs (repeatable)')
+    .option('--allow-country <iso2...>', 'restrict to these ISO-2 country codes (requires Cloudflare)')
+    .option('--single-device', 'absolutely reject a second device fingerprint (default: warn in lenient, block in strict)', false)
+    .option('--nda <text>', 'require the recipient to type "I agree" to this text before unlocking')
     .option('--json', 'machine-readable output', false)
     .action(async (opts) => {
       try {
@@ -622,7 +705,16 @@ function build() {
           strict: !!opts.strict,
           heartbeatSec: opts.heartbeat,
           offlineGraceSec: opts.offlineGrace,
+          paths: opts.paths || null,
+          mode: opts.mode === 'ro' ? 'ro' : 'rw',
+          watermark: opts.watermark || null,
+          idleAutoLockMinutes: opts.idle || 0,
+          allowedIpCidrs: opts.allowIp || null,
+          allowedCountries: opts.allowCountry || null,
+          singleDeviceEnforce: !!opts.singleDevice,
+          ndaText: opts.nda || null,
           json: !!opts.json,
+          resolveKey,
         });
       } catch (err) {
         process.exitCode = reportError(err);
@@ -656,6 +748,21 @@ function build() {
       }
     });
 
+  // -------- lockdown (sealcode@1.1.0) --------
+  program
+    .command('lockdown')
+    .description('Project panic button — revoke ALL active access codes for this project in one shot. All connected watchers re-lock within ~1 second.')
+    .option('--yes', 'skip the interactive confirmation', false)
+    .action(async (opts) => {
+      try {
+        const projectRoot = resolveProject(program.opts());
+        const { runLockdown } = require('./cli-grants');
+        await runLockdown({ projectRoot, confirm: !opts.yes });
+      } catch (err) {
+        process.exitCode = reportError(err);
+      }
+    });
+
   // -------- redeem --------
   program
     .command('redeem')
@@ -664,7 +771,12 @@ function build() {
     .option('--json', 'machine-readable output', false)
     .action(async (code, opts) => {
       try {
-        await runRedeem({ code, json: !!opts.json });
+        // Pass projectRoot so runRedeem can cache an unwrapped K against
+        // this repo when the grant was team-shared. If the user is NOT
+        // inside a project root, resolveProject returns the cwd, and
+        // runRedeem just won't cache (it checks isInitialized).
+        const projectRoot = resolveProject(program.opts());
+        await runRedeem({ projectRoot, code, json: !!opts.json });
       } catch (err) {
         process.exitCode = reportError(err);
       }
@@ -678,6 +790,8 @@ function build() {
     .option('--interval <seconds>', 'override server-suggested heartbeat interval', (v) => parseInt(v, 10))
     .option('-v, --verbose', 'print every heartbeat (instead of a single live status line)', false)
     .option('--json', 'machine-readable JSONL output (one event per line)', false)
+    .option('--daemon', 'detach from the terminal and log to ~/.sealcode/logs/', false)
+    .option('--no-exfil', 'disable filesystem exfiltration heuristics (debug only)')
     .action(async (code, opts) => {
       try {
         const projectRoot = resolveProject(program.opts());
@@ -687,12 +801,49 @@ function build() {
           intervalSec: opts.interval,
           verbose: !!opts.verbose,
           json: !!opts.json,
+          daemon: !!opts.daemon,
+          exfil: opts.exfil !== false,
         });
       } catch (err) {
         process.exitCode = reportError(err);
       }
     });
 
+  // -------- install-service / uninstall-service / supervise --------
+  // Per-user supervisor that re-launches dead grant watchers across
+  // reboots (macOS launchd / Linux systemd user units). Optional but
+  // recommended for any machine that redeems strict-mode grants.
+  program
+    .command('install-service')
+    .description('Install a per-user supervisor so the strict-watch daemon survives reboots.')
+    .action(async () => {
+      try {
+        runInstallService();
+      } catch (err) {
+        process.exitCode = reportError(err);
+      }
+    });
+  program
+    .command('uninstall-service')
+    .description('Remove the per-user supervisor installed by `install-service`.')
+    .action(async () => {
+      try {
+        runUninstallService();
+      } catch (err) {
+        process.exitCode = reportError(err);
+      }
+    });
+  program
+    .command('supervise')
+    .description('(internal) Called every minute by launchd/systemd to sweep dead watchers.')
+    .action(async () => {
+      try {
+        runSupervise();
+      } catch (err) {
+        process.exitCode = reportError(err);
+      }
+    });
+
   // -------- ci-token --------
   const ciToken = program
     .command('ci-token')

package/src/device.js

@@ -0,0 +1,163 @@
+'use strict';
+
+/**
+ * Stable per-machine device fingerprint.
+ *
+ * Used by sealcode@1.0.0+ for:
+ *   - Binding a temp-access grant to the first machine that redeems it
+ *     (so the contractor can't sidestep revoke by cloning the unlocked
+ *     project folder onto a second laptop).
+ *   - Tagging audit events with "which laptop did this come from".
+ *
+ * Design constraints:
+ *   - Must be stable across reboots and software upgrades on the same
+ *     machine (otherwise we'd lock contractors out for no reason after a
+ *     restart).
+ *   - Must be unstable across different machines, even ones with the same
+ *     hostname (e.g. two MacBooks both named "Sayem's MacBook").
+ *   - Must NOT leak PII off the device. We never send hostname, MAC, or
+ *     machine-id over the wire — only the sha-256-truncated fingerprint.
+ *
+ * Inputs (best-effort, ranked by stability):
+ *   1. /etc/machine-id / /var/lib/dbus/machine-id  (Linux, very stable)
+ *   2. ioreg IOPlatformUUID                        (macOS, very stable)
+ *   3. First non-loopback MAC address              (everywhere, fairly stable)
+ *   4. os.hostname() + os.userInfo().username      (fallback, weakest)
+ *
+ * The fingerprint is base32(sha-256(joined inputs)) truncated to 16 chars
+ * — that's 80 bits of entropy, enough that collisions across the entire
+ * sealcode userbase are statistically impossible. Truncation also makes
+ * the fingerprint look like other sealcode IDs (manifest hashes, etc.).
+ */
+
+const fs = require('fs');
+const os = require('os');
+const { execFileSync } = require('child_process');
+const { sha256Hex } = require('./crypto');
+
+// Cache the fingerprint for the life of the process so we don't shell out
+// to ioreg / read machine-id repeatedly. The fingerprint is constant for
+// the duration of the process anyway.
+let cachedFingerprint = null;
+let cachedDetails = null;
+
+function readFirstLine(path) {
+  try {
+    return fs.readFileSync(path, 'utf8').split('\n')[0].trim();
+  } catch (_) {
+    return null;
+  }
+}
+
+function readMachineId() {
+  if (process.platform === 'linux') {
+    return readFirstLine('/etc/machine-id') || readFirstLine('/var/lib/dbus/machine-id');
+  }
+  if (process.platform === 'darwin') {
+    try {
+      const out = execFileSync('/usr/sbin/ioreg', ['-rd1', '-c', 'IOPlatformExpertDevice'], {
+        encoding: 'utf8',
+        timeout: 1500,
+        stdio: ['ignore', 'pipe', 'ignore'],
+      });
+      const m = /"IOPlatformUUID"\s*=\s*"([^"]+)"/i.exec(out);
+      return m ? m[1] : null;
+    } catch (_) {
+      return null;
+    }
+  }
+  if (process.platform === 'win32') {
+    try {
+      const out = execFileSync('reg', ['query', 'HKLM\\SOFTWARE\\Microsoft\\Cryptography', '/v', 'MachineGuid'], {
+        encoding: 'utf8',
+        timeout: 1500,
+        stdio: ['ignore', 'pipe', 'ignore'],
+      });
+      const m = /MachineGuid\s+REG_SZ\s+([0-9a-f-]+)/i.exec(out);
+      return m ? m[1] : null;
+    } catch (_) {
+      return null;
+    }
+  }
+  return null;
+}
+
+function firstNonLoopbackMac() {
+  const ifaces = os.networkInterfaces();
+  // Sort interface names for determinism — different boot orders on the
+  // same machine occasionally list interfaces in a different order, but
+  // alphabetical is stable.
+  const names = Object.keys(ifaces).sort();
+  for (const name of names) {
+    for (const addr of ifaces[name] || []) {
+      if (!addr.internal && addr.mac && addr.mac !== '00:00:00:00:00:00') {
+        return addr.mac.toLowerCase();
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Convert hex sha-256 to short opaque base32 fingerprint.
+ * 16 chars of Crockford-ish base32 = 80 bits.
+ */
+function shortFingerprint(hex) {
+  // Use 0-9 a-z minus look-alikes (no l, o, i, u — matches sealcode's
+  // existing recovery-code alphabet style).
+  const alphabet = '0123456789abcdefghjkmnpqrstvwxyz';
+  const bytes = Buffer.from(hex.slice(0, 32), 'hex'); // 16 bytes = 128 bits
+  let bits = 0;
+  let acc = 0;
+  let out = '';
+  for (const b of bytes) {
+    acc = (acc << 8) | b;
+    bits += 8;
+    while (bits >= 5) {
+      bits -= 5;
+      out += alphabet[(acc >> bits) & 0x1f];
+    }
+  }
+  return out.slice(0, 16);
+}
+
+function compute() {
+  const machineId = readMachineId();
+  const mac = firstNonLoopbackMac();
+  const host = os.hostname() || '';
+  const user = (os.userInfo().username || '');
+  const platform = `${os.platform()}-${os.arch()}`;
+
+  // We deliberately include MORE than one input so a missing one (e.g. no
+  // machine-id on a fresh container) still produces a stable fingerprint.
+  const material = ['sealcode-device-v1', machineId || '', mac || '', host, user, platform].join('|');
+  const fp = shortFingerprint(sha256Hex(material));
+  cachedDetails = { hostname: host, platform, hasMachineId: !!machineId, hasMac: !!mac };
+  return fp;
+}
+
+function getDeviceFingerprint() {
+  if (cachedFingerprint) return cachedFingerprint;
+  cachedFingerprint = compute();
+  return cachedFingerprint;
+}
+
+/**
+ * Non-secret descriptive info about the device. Used by `sealcode where`
+ * and shown in audit logs. We never send `machineId` or `mac` over the
+ * wire — only the derived fingerprint plus the hostname/platform pair.
+ */
+function getDeviceInfo() {
+  getDeviceFingerprint();
+  return {
+    fingerprint: cachedFingerprint,
+    hostname: cachedDetails.hostname,
+    platform: cachedDetails.platform,
+    sourcesUsed: {
+      machineId: cachedDetails.hasMachineId,
+      mac: cachedDetails.hasMac,
+    },
+  };
+}
+
+module.exports = { getDeviceFingerprint, getDeviceInfo };

package/src/grant-policy.js

@@ -0,0 +1,119 @@
+'use strict';
+
+/**
+ * Grant policy: the in-memory representation of the admin-control bundle
+ * shipped in sealcode@1.1.0.
+ *
+ * A "policy" is the subset of a temp-access grant that *changes how the
+ * recipient's CLI behaves* once the grant is in force:
+ *
+ *   - allowedPaths        what subset of the project they can unlock
+ *   - mode                'rw' (default) or 'ro' (chmod 0444 + watcher
+ *                         re-locks on detected modifications)
+ *   - watermark           template injected as a per-filetype comment
+ *                         at the top of every unlocked file
+ *   - idleAutoLockMinutes lock after N minutes of no fs activity
+ *   - ndaText             prompt the recipient must accept on redeem
+ *
+ * The server hands the policy back inside the /redeem response. The CLI
+ * stashes it in the session meta and reads it again in unlock, watcher,
+ * and guard. Older 1.0 CLIs that don't know about these fields just
+ * ignore them — backward-compat by design.
+ */
+
+const PATH_SEP = '/';
+
+/**
+ * @typedef {object} GrantPolicy
+ * @property {string[]|null} allowedPaths    POSIX prefixes; null = full project
+ * @property {'rw'|'ro'}     mode            access mode
+ * @property {string|null}   watermark       comment template
+ * @property {number}        idleAutoLockMinutes  0 = disabled
+ * @property {string|null}   ndaText         prompt; null = no NDA
+ */
+
+/**
+ * @param {object} raw    server JSON (the `policy` block of /redeem response)
+ * @returns {GrantPolicy}
+ */
+function normalize(raw) {
+  const r = raw || {};
+  return {
+    allowedPaths: Array.isArray(r.allowedPaths) && r.allowedPaths.length
+      ? r.allowedPaths.map(normalizePrefix)
+      : null,
+    mode: r.mode === 'ro' ? 'ro' : 'rw',
+    watermark: typeof r.watermark === 'string' && r.watermark.trim()
+      ? r.watermark.trim()
+      : null,
+    idleAutoLockMinutes: Math.max(0, Math.floor(Number(r.idleAutoLockMinutes) || 0)),
+    ndaText: typeof r.ndaText === 'string' && r.ndaText.trim()
+      ? r.ndaText.trim()
+      : null,
+  };
+}
+
+/**
+ * Coerce a path prefix into the form we compare against manifest paths:
+ *   - normalize Windows slashes to forward slashes
+ *   - strip leading "./" and absolute-style leading slash
+ *   - guarantee a trailing slash so "src/api" doesn't match "src/api2/..."
+ */
+function normalizePrefix(p) {
+  let s = String(p || '').replace(/\\/g, PATH_SEP);
+  if (s.startsWith('./')) s = s.slice(2);
+  while (s.startsWith(PATH_SEP)) s = s.slice(1);
+  if (!s.endsWith(PATH_SEP) && s !== '') s += PATH_SEP;
+  return s;
+}
+
+/**
+ * Does the (already-POSIX-normalized) entry path fall inside any of the
+ * grant's allowed prefixes? Empty/null allowedPaths means no restriction.
+ *
+ * The watcher and unlock both call this — never the server, because the
+ * server can't see decrypted paths. The trust boundary is the signed CLI
+ * binary.
+ */
+function isPathAllowed(entryPath, allowedPaths) {
+  if (!allowedPaths || allowedPaths.length === 0) return true;
+  const p = String(entryPath || '').replace(/\\/g, PATH_SEP).replace(/^\.\//, '');
+  return allowedPaths.some((prefix) => p === prefix.slice(0, -1) || p.startsWith(prefix));
+}
+
+/**
+ * Filter a parsed manifest's `files` array down to the allowed subset.
+ * Returns a NEW array; doesn't mutate the input.
+ */
+function filterManifestFiles(files, allowedPaths) {
+  if (!allowedPaths || allowedPaths.length === 0) return files;
+  return files.filter((f) => isPathAllowed(f.p, allowedPaths));
+}
+
+/**
+ * Render a one-line summary of the policy for the CLI banner / dashboard.
+ * Pure presentation — no behavior depends on this.
+ */
+function describe(policy) {
+  const bits = [];
+  if (policy.mode === 'ro') bits.push('read-only');
+  if (policy.allowedPaths && policy.allowedPaths.length) {
+    bits.push(
+      `scoped to ${policy.allowedPaths.length} path${policy.allowedPaths.length === 1 ? '' : 's'}`,
+    );
+  }
+  if (policy.watermark) bits.push('watermarked');
+  if (policy.idleAutoLockMinutes > 0) {
+    bits.push(`idle-lock ${policy.idleAutoLockMinutes}m`);
+  }
+  if (policy.ndaText) bits.push('NDA');
+  return bits.join(' · ') || 'standard';
+}
+
+module.exports = {
+  normalize,
+  normalizePrefix,
+  isPathAllowed,
+  filterManifestFiles,
+  describe,
+};

package/src/keypair.js

@@ -0,0 +1,159 @@
+'use strict';
+
+/**
+ * Per-user X25519 keypair used for team key sharing.
+ *
+ *   ~/.sealcode/keypair.json   (mode 0600)
+ *     {
+ *       "algo":       "x25519-v1",
+ *       "publicKey":  "<base64 32B raw>",
+ *       "privateKey": "<base64 32B raw>",
+ *       "createdAt":  "2026-05-19T18:00:00Z"
+ *     }
+ *
+ * The PRIVATE key never leaves this machine. The PUBLIC key is uploaded
+ * to sealcode.dev on `sealcode login` and used by other users to wrap the
+ * project master key K when they `sealcode share --to your-email`.
+ *
+ * Rotation: deleting keypair.json forces a fresh keypair on next login.
+ * Old grants wrapped to the old pubkey will fail to unwrap and the user
+ * will need a fresh share — same UX as losing your laptop. We treat that
+ * as acceptable because a private key never being exfiltrated is more
+ * valuable than convenience around rotation.
+ *
+ * We use Node's built-in crypto (no new dependencies):
+ *   - generateKeyPairSync('x25519')
+ *   - createPrivateKey / createPublicKey
+ *   - diffieHellman()  (raw 32-byte X25519 ECDH shared secret)
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+const CONFIG_DIR = path.join(os.homedir(), '.sealcode');
+const KEYPAIR_PATH = path.join(CONFIG_DIR, 'keypair.json');
+const ALGO = 'x25519-v1';
+
+function ensureConfigDir() {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+}
+
+/**
+ * Raw 32-byte X25519 key extraction. Node's KeyObject only gives DER/PEM
+ * by default; we strip the SPKI/PKCS#8 prefix to get the raw bytes that
+ * libsodium / age / browser WebCrypto all interoperate with.
+ *
+ * For X25519 the DER prefixes are constant lengths:
+ *   - SPKI (public)  prefix: 12 bytes  → raw key is last 32 bytes
+ *   - PKCS#8 (priv)  prefix: 16 bytes  → raw key is last 32 bytes
+ */
+function rawPublic(keyObject) {
+  const der = keyObject.export({ type: 'spki', format: 'der' });
+  return Buffer.from(der.subarray(der.length - 32));
+}
+function rawPrivate(keyObject) {
+  const der = keyObject.export({ type: 'pkcs8', format: 'der' });
+  return Buffer.from(der.subarray(der.length - 32));
+}
+
+function publicFromRaw(raw32) {
+  // Wrap raw 32 bytes back into an SPKI-formatted DER so Node accepts it
+  // as a peer's pubkey for ECDH.
+  const SPKI_PREFIX = Buffer.from('302a300506032b656e032100', 'hex');
+  return crypto.createPublicKey({
+    key: Buffer.concat([SPKI_PREFIX, raw32]),
+    format: 'der',
+    type: 'spki',
+  });
+}
+function privateFromRaw(raw32) {
+  const PKCS8_PREFIX = Buffer.from('302e020100300506032b656e04220420', 'hex');
+  return crypto.createPrivateKey({
+    key: Buffer.concat([PKCS8_PREFIX, raw32]),
+    format: 'der',
+    type: 'pkcs8',
+  });
+}
+
+function generate() {
+  const { publicKey, privateKey } = crypto.generateKeyPairSync('x25519');
+  return {
+    algo: ALGO,
+    publicKey: rawPublic(publicKey).toString('base64'),
+    privateKey: rawPrivate(privateKey).toString('base64'),
+    createdAt: new Date().toISOString(),
+  };
+}
+
+function read() {
+  if (!fs.existsSync(KEYPAIR_PATH)) return null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(KEYPAIR_PATH, 'utf8'));
+    if (!parsed || parsed.algo !== ALGO || !parsed.publicKey || !parsed.privateKey) {
+      return null;
+    }
+    return parsed;
+  } catch (_) {
+    return null;
+  }
+}
+
+function write(kp) {
+  ensureConfigDir();
+  const tmp = KEYPAIR_PATH + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(kp, null, 2) + '\n', { mode: 0o600 });
+  try {
+    fs.chmodSync(tmp, 0o600);
+  } catch (_) { /* windows ok */ }
+  fs.renameSync(tmp, KEYPAIR_PATH);
+}
+
+/**
+ * Read the existing keypair or generate + persist a fresh one. Returns
+ * the parsed JSON struct including the private key.
+ */
+function ensureKeypair() {
+  const existing = read();
+  if (existing) return existing;
+  const fresh = generate();
+  write(fresh);
+  return fresh;
+}
+
+/** Just the pubkey (algo + base64), suitable to upload to the server. */
+function publicKey() {
+  const kp = ensureKeypair();
+  return { algo: kp.algo, publicKey: kp.publicKey };
+}
+
+/** Compute raw 32-byte X25519 shared secret. Internal helper for share-crypto. */
+function sharedSecret(ourPrivateB64, theirPublicB64) {
+  const ourPriv = privateFromRaw(Buffer.from(ourPrivateB64, 'base64'));
+  const theirPub = publicFromRaw(Buffer.from(theirPublicB64, 'base64'));
+  return crypto.diffieHellman({ privateKey: ourPriv, publicKey: theirPub });
+}
+
+function clear() {
+  try {
+    fs.unlinkSync(KEYPAIR_PATH);
+  } catch (_) { /* ignore */ }
+}
+
+module.exports = {
+  KEYPAIR_PATH,
+  ALGO,
+  ensureKeypair,
+  read,
+  publicKey,
+  sharedSecret,
+  generate,
+  write,
+  clear,
+  // exposed for share-crypto only
+  _rawPublic: rawPublic,
+  _rawPrivate: rawPrivate,
+  _publicFromRaw: publicFromRaw,
+  _privateFromRaw: privateFromRaw,
+};