sealcode 0.1.0 → 1.1.0

package/src/cli.js

@@ -34,6 +34,24 @@ const { exportBundle, importBundle } = require('./bundle');
 const { runLogin, runSignout, runWhoami } = require('./cli-auth');
 const { runLink, runUnlink, runLinkInfo } = require('./cli-link');
 const { runShare, runGrants, runRevoke, runRedeem } = require('./cli-grants');
+const {
+  runCiCreate,
+  runCiList,
+  runCiRevoke,
+} = require('./cli-ci-tokens');
+const {
+  runEscrowStatus,
+  runEscrowEnable,
+  runEscrowDisable,
+  runEscrowRecover,
+} = require('./cli-escrow');
+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) {
@@ -157,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')
@@ -241,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());
@@ -249,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+/, '');
@@ -263,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);
       }
@@ -596,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 {
@@ -610,6 +705,14 @@ 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,
         });
       } catch (err) {
@@ -644,6 +747,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')
@@ -652,7 +770,180 @@ 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);
+      }
+    });
+
+  // -------- watch --------
+  program
+    .command('watch')
+    .argument('<code>', 'access code to monitor (the one you redeemed)')
+    .description('Stay online and self-lock if the owner revokes this code or it expires.')
+    .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());
+        await runWatch({
+          projectRoot,
+          code,
+          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')
+    .description('Manage CI/CD short-lived tokens for the linked project (Pro feature).');
+
+  ciToken
+    .command('create')
+    .description('Create a new CI token. Shown once — save it to your CI secret store.')
+    .requiredOption('--label <text>', 'human-readable label (e.g. "GitHub Actions · deploy")')
+    .option('--ttl <duration>', 'lifetime: 1h, 8h, 1d, 1w (default 24h)', '24h')
+    .option('--scope <scope>', 'read | unlock (default unlock)', 'unlock')
+    .option('--json', 'machine-readable output', false)
+    .action(async (opts) => {
+      try {
+        const projectRoot = resolveProject(program.opts());
+        await runCiCreate({
+          projectRoot,
+          label: opts.label,
+          ttl: opts.ttl,
+          scope: opts.scope,
+          json: !!opts.json,
+        });
+      } catch (err) {
+        process.exitCode = reportError(err);
+      }
+    });
+
+  ciToken
+    .command('list')
+    .description('List CI tokens for the linked project.')
+    .option('--json', 'machine-readable output', false)
+    .action(async (opts) => {
+      try {
+        const projectRoot = resolveProject(program.opts());
+        await runCiList({ projectRoot, json: !!opts.json });
+      } catch (err) {
+        process.exitCode = reportError(err);
+      }
+    });
+
+  ciToken
+    .command('revoke')
+    .argument('<id>', 'CI token id (see `sealcode ci-token list`)')
+    .description('Revoke a CI token immediately.')
+    .action(async (id) => {
+      try {
+        await runCiRevoke({ tokenId: id });
+      } catch (err) {
+        process.exitCode = reportError(err);
+      }
+    });
+
+  // -------- escrow --------
+  const escrow = program
+    .command('escrow')
+    .description('Cloud key escrow: a passphrase-recovery safety net (Pro feature).');
+
+  escrow
+    .command('status')
+    .description('Print whether escrow is enabled for the linked project.')
+    .option('--json', 'machine-readable output', false)
+    .action(async (opts) => {
+      try {
+        const projectRoot = resolveProject(program.opts());
+        await runEscrowStatus({ projectRoot, json: !!opts.json });
+      } catch (err) {
+        process.exitCode = reportError(err);
+      }
+    });
+
+  escrow
+    .command('enable')
+    .description('Wrap the master key with a separate recovery passphrase and upload the ciphertext.')
+    .action(async () => {
+      try {
+        const projectRoot = resolveProject(program.opts());
+        await runEscrowEnable({ projectRoot });
+      } catch (err) {
+        process.exitCode = reportError(err);
+      }
+    });
+
+  escrow
+    .command('disable')
+    .description('Delete the server-side escrow blob. The local vault is unaffected.')
+    .action(async () => {
+      try {
+        const projectRoot = resolveProject(program.opts());
+        await runEscrowDisable({ projectRoot });
+      } catch (err) {
+        process.exitCode = reportError(err);
+      }
+    });
+
+  escrow
+    .command('recover')
+    .description('On a new machine: download the blob, decrypt with the recovery passphrase, cache K.')
+    .action(async () => {
+      try {
+        const projectRoot = resolveProject(program.opts());
+        await runEscrowRecover({ projectRoot });
       } catch (err) {
         process.exitCode = reportError(err);
       }

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/errors.js

@@ -54,6 +54,24 @@ const CODES = {
       'The free CLI handles lock / unlock / verify forever. Pro adds team key sharing, key rotation across N projects, audit log sync, and cloud key escrow.',
     try: 'Try: visit https://sealcode.dev/pro     (start a free 14-day trial)',
   },
+  SEALCODE_WATCH_NO_CODE: {
+    headline: 'sealcode watch needs an access code.',
+    detail:
+      'Pass the access code shared with you (the one you got from sealcode share / redeem).',
+    try: 'Try: sealcode watch SC-XXXX-XXXX-XXXX-XXXX',
+  },
+  SEALCODE_WATCH_BAD_CODE: {
+    headline: 'The server rejected that access code.',
+    detail:
+      "The code may be malformed, already expired, revoked, or it doesn't exist on this server.",
+    try: 'Try: sealcode redeem <code>            (re-validate the code first)',
+  },
+  SEALCODE_WATCH_OFFLINE: {
+    headline: "I couldn't reach sealcode.dev to start watching.",
+    detail:
+      'The first heartbeat failed. We refuse to start the watcher without confirming the code is reachable — otherwise a revoke would never be observed.',
+    try: 'Try: check connectivity, then re-run `sealcode watch <code>`.',
+  },
 };
 
 class SealcodeError extends Error {

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,
+};