sealcode 0.3.0 → 1.1.1

package/src/keystore.js

@@ -158,14 +158,37 @@ async function rotatePassphrase(projectRoot, lockedDir, oldPassphrase, newPassph
  * Save unwrapped K to a short-lived session file so subsequent commands skip
  * scrypt. Session is encrypted by a host-binding key derived from machine
  * details + project id, so copying the file to another machine doesn't help.
+ *
+ * `extraMeta` (sealcode@1.0.0+, optional, forward-compatible): merged into
+ * the session meta JSON. Older CLIs that only read `meta.exp` ignore the
+ * extra fields silently. Recognized fields used by sealcode@1.0.0+:
+ *
+ *   source:                "passphrase" | "recovery" | "grant"
+ *   grantId:               server-side grant id (when source === "grant")
+ *   grantCodeHash:         sha-256 hex of the grant code (NEVER the plaintext)
+ *   grantExpiresAt:        ISO-8601 wall-clock expiry
+ *   deviceFingerprint:     opaque device id at unlock time
+ *   watchPidFile:          absolute path to the watcher PID heartbeat file
+ *   strictWatch:           true → cli-guard hard-locks on dead watcher
+ *
+ * None of these are secrets — they're operational hints that let cli-guard,
+ * cli-watch, and the system-service installer coordinate.
  */
-function saveSession(projectRoot, K) {
+function saveSession(projectRoot, K, extraMeta = null) {
   ensureDir(SESSION_DIR);
   const id = projectId(projectRoot);
   const hostBind = sha256Hex(`${os.hostname()}|${os.userInfo().username}|${id}`);
   const sessionKey = Buffer.from(hostBind.slice(0, 64), 'hex');
   const blob = seal(K, sessionKey);
-  const meta = Buffer.from(JSON.stringify({ exp: Date.now() + SESSION_TTL_MS }), 'utf8');
+  const meta = Buffer.from(
+    JSON.stringify({ exp: Date.now() + SESSION_TTL_MS, ...(extraMeta || {}) }),
+    'utf8',
+  );
+  if (meta.length > 0xffff) {
+    // Two-byte length field cap. If we ever blow past this we'd need a
+    // larger header, but 64 KB of metadata is more than we'd ever want.
+    throw new Error('session meta is unreasonably large');
+  }
   const wrapped = Buffer.concat([
     Buffer.from([meta.length & 0xff, (meta.length >> 8) & 0xff]),
     meta,
@@ -174,12 +197,15 @@ function saveSession(projectRoot, K) {
   fs.writeFileSync(path.join(SESSION_DIR, id), wrapped, { mode: 0o600 });
 }
 
-function loadSession(projectRoot) {
+/**
+ * Internal: load + decrypt the session file, returning { K, meta }. Returns
+ * null if missing / expired / tampered / can't unwrap. Used by both the
+ * legacy `loadSession()` (returns K only) and the new `loadSessionMeta()`.
+ */
+function loadSessionRaw(projectRoot) {
   const id = projectId(projectRoot);
   let p = path.join(SESSION_DIR, id);
   if (!fs.existsSync(p)) {
-    // Fall back to the legacy ~/.vaultline/sessions location for users
-    // upgrading from vaultline 1.x.
     const legacy = path.join(LEGACY_SESSION_DIR, id);
     if (!fs.existsSync(legacy)) return null;
     p = legacy;
@@ -209,12 +235,53 @@ function loadSession(projectRoot) {
   const hostBind = sha256Hex(`${os.hostname()}|${os.userInfo().username}|${id}`);
   const sessionKey = Buffer.from(hostBind.slice(0, 64), 'hex');
   try {
-    return open(blob, sessionKey);
+    const K = open(blob, sessionKey);
+    return { K, meta, path: p };
   } catch (_) {
     return null;
   }
 }
 
+function loadSession(projectRoot) {
+  const r = loadSessionRaw(projectRoot);
+  return r ? r.K : null;
+}
+
+/**
+ * sealcode@1.0.0: structured access to the session metadata. Returns null
+ * if there is no live session. Callers MUST handle `meta.source` being
+ * undefined (legacy session files from 0.x are valid "passphrase" sessions
+ * without any source tag).
+ */
+function loadSessionMeta(projectRoot) {
+  const r = loadSessionRaw(projectRoot);
+  if (!r) return null;
+  return {
+    K: r.K,
+    meta: {
+      source: 'passphrase',
+      ...r.meta,
+    },
+  };
+}
+
+/**
+ * sealcode@1.0.0: re-write just the metadata of an existing session
+ * (preserving K). Used after spawning the watcher so we can record its
+ * pid file path back into the session.
+ */
+function updateSessionMeta(projectRoot, patch) {
+  const r = loadSessionRaw(projectRoot);
+  if (!r) return false;
+  const next = { ...r.meta, ...patch };
+  // Re-call saveSession with the merged extras. We pass `next` minus `exp`
+  // so saveSession's own TTL extension still wins (every meta update is
+  // also an activity ping → fresh 8h TTL).
+  const { exp: _exp, ...extras } = next;
+  saveSession(projectRoot, r.K, extras);
+  return true;
+}
+
 function clearSession(projectRoot) {
   const id = projectId(projectRoot);
   for (const dir of [SESSION_DIR, LEGACY_SESSION_DIR]) {
@@ -236,12 +303,15 @@ module.exports = {
   WRAP_PASS_NAME,
   WRAP_RECOVERY_NAME,
   MANIFEST_NAME,
+  SESSION_DIR,
   bootstrap,
   persistBootstrap,
   unwrap,
   rotatePassphrase,
   saveSession,
   loadSession,
+  loadSessionMeta,
+  updateSessionMeta,
   clearSession,
   isInitialized,
   manifestBlobPath,

package/src/open.js

@@ -5,16 +5,57 @@ const path = require('path');
 const { open } = require('./crypto');
 const { readManifest } = require('./manifest');
 const { ensureDir, writeFileEnsuringDir } = require('./util');
+const watermark = require('./watermark');
+const grantPolicy = require('./grant-policy');
 
-async function runUnlock({ projectRoot, config, K, removeStubs = true, log = () => {} }) {
+/**
+ * Unlock the vault into plaintext.
+ *
+ * sealcode@1.1.0 additions (all optional, default to "no policy"):
+ *
+ *   policy.allowedPaths   — only decrypt entries whose path matches one
+ *                            of these POSIX-style prefixes. Other files
+ *                            stay as ciphertext blobs on disk and are
+ *                            simply not materialized.
+ *   policy.mode           — 'ro' chmods every unlocked file to 0444 and
+ *                            (in combination with the watcher) re-locks
+ *                            the project the moment any file is modified.
+ *   policy.watermark      — template string injected as a per-filetype
+ *                            comment at the top of each unlocked file
+ *                            so leaks are traceable back to a grant.
+ *   policy.watermarkCtx   — substitutions for the template
+ *                            ({email}, {grantId}, …).
+ *
+ * Callers that don't pass `policy` get the legacy behavior unchanged.
+ */
+async function runUnlock({
+  projectRoot,
+  config,
+  K,
+  removeStubs = true,
+  log = () => {},
+  policy = null,
+  watermarkCtx = null,
+}) {
+  const p = grantPolicy.normalize(policy || {});
   const manifest = readManifest(projectRoot, config.lockedDir, K);
   const lockedRoot = path.join(projectRoot, config.lockedDir);
 
+  const filesToUnlock = grantPolicy.filterManifestFiles(
+    manifest.files,
+    p.allowedPaths,
+  );
+  const allowedSet = new Set(filesToUnlock.map((f) => f.p));
+  const skippedCount = manifest.files.length - filesToUnlock.length;
+
   if (removeStubs && manifest.stubs) {
     for (const stubPath of Object.keys(manifest.stubs)) {
       const abs = path.join(projectRoot, stubPath);
       const isAlsoSealed = manifest.files.some((f) => f.p === stubPath);
-      if (isAlsoSealed && fs.existsSync(abs)) {
+      // If the stub corresponds to a file we're NOT going to unlock
+      // (because of allowedPaths), leave the stub in place — that way
+      // the contractor still sees a placeholder, not a missing file.
+      if (isAlsoSealed && allowedSet.has(stubPath) && fs.existsSync(abs)) {
         try {
           fs.unlinkSync(abs);
         } catch (_) {
@@ -24,20 +65,42 @@ async function runUnlock({ projectRoot, config, K, removeStubs = true, log = ()
     }
   }
 
-  for (const entry of manifest.files) {
+  for (const entry of filesToUnlock) {
     const lockedAbs = path.join(lockedRoot, entry.l);
     if (!fs.existsSync(lockedAbs)) {
       throw new Error(`unlock: missing locked blob for ${entry.p} (expected ${entry.l})`);
     }
     const blob = fs.readFileSync(lockedAbs);
-    const plain = open(blob, K);
+    let plain = open(blob, K);
+
+    // sealcode@1.1.0 — inject a per-grant watermark before writing the
+    // plaintext to disk. The watermark module is filetype-aware and
+    // skips binaries / unknown syntaxes silently.
+    if (p.watermark) {
+      plain = watermark.applyWatermark(plain, entry.p, p.watermark, watermarkCtx || {});
+    }
+
     const target = path.join(projectRoot, entry.p);
     ensureDir(path.dirname(target));
-    writeFileEnsuringDir(target, plain, entry.m);
+    // Apply RO mode by overriding the manifest's recorded mode with 0444.
+    // (We still pass entry.m for rw to preserve executable bits.)
+    const effectiveMode = p.mode === 'ro' ? 0o444 : entry.m;
+    writeFileEnsuringDir(target, plain, effectiveMode);
+
+    // Even though writeFileEnsuringDir set the mode, some filesystems
+    // strip the bits on a fresh create — re-apply to be sure.
+    if (p.mode === 'ro') {
+      try { fs.chmodSync(target, 0o444); } catch (_) { /* best-effort */ }
+    }
     log(`  unlocked ${entry.p}`);
   }
 
-  return { count: manifest.files.length, sealedAt: manifest.sealedAt };
+  return {
+    count: filesToUnlock.length,
+    skipped: skippedCount,
+    sealedAt: manifest.sealedAt,
+    policy: p,
+  };
 }
 
 module.exports = { runUnlock };

package/src/seal.js

@@ -20,6 +20,8 @@ const {
   nowIso,
   normPath,
 } = require('./util');
+const watermark = require('./watermark');
+const { readManifest } = require('./manifest');
 
 async function collectFiles(projectRoot, cfg) {
   const matches = await fg(cfg.include, {
@@ -71,12 +73,32 @@ async function runLock({
   bootstrapOutput,
   keepOriginals = false,
   log = () => {},
+  // sealcode@1.1.0 — when a contractor's session was scoped (only a
+  // subset of files were ever decrypted), re-locking would otherwise
+  // WIPE the out-of-scope ciphertext blobs because they have no
+  // corresponding plaintext on disk. `preserveUnseen` carries the
+  // previous manifest's blobs forward for any path that isn't currently
+  // on disk as plaintext. The watcher's `finalLock` opts into this
+  // automatically for grant-derived sessions.
+  preserveUnseen = false,
 }) {
   const lockedDir = config.lockedDir;
   const lockedRoot = path.join(projectRoot, lockedDir);
 
+  // Snapshot the existing manifest BEFORE we wipe lockedRoot, so we can
+  // copy unseen-but-still-relevant blobs forward.
+  let prevManifest = null;
+  if (preserveUnseen) {
+    try {
+      prevManifest = readManifest(projectRoot, lockedDir, K);
+    } catch (_) {
+      // No manifest yet (first init) or unreadable — fall through.
+      prevManifest = null;
+    }
+  }
+
   const files = await collectFiles(projectRoot, config);
-  if (files.length === 0) {
+  if (files.length === 0 && !prevManifest) {
     throw new Error('SEALCODE_NOTHING_TO_LOCK');
   }
 
@@ -93,6 +115,23 @@ async function runLock({
   if (existingRecoveryWrap)
     saved[WRAP_RECOVERY_NAME] = fs.readFileSync(path.join(lockedRoot, WRAP_RECOVERY_NAME));
 
+  // Carry forward unseen blobs (sealcode@1.1.0). We hold the BYTES in
+  // memory so we can wipe lockedRoot and re-stage cleanly. For typical
+  // projects this is fine; for very large repos with many GB of unseen
+  // blobs the watcher should switch to a copy-then-rename strategy.
+  const preservedBlobs = []; // [{ entry, bytes }]
+  if (prevManifest && prevManifest.files) {
+    const plaintextSet = new Set(files);
+    for (const entry of prevManifest.files) {
+      if (plaintextSet.has(entry.p)) continue; // we have plaintext for it
+      const oldBlobPath = path.join(lockedRoot, entry.l);
+      if (!fs.existsSync(oldBlobPath)) continue;
+      try {
+        preservedBlobs.push({ entry, bytes: fs.readFileSync(oldBlobPath) });
+      } catch (_) { /* skip */ }
+    }
+  }
+
   rmIfExists(lockedRoot);
   ensureDir(lockedRoot);
 
@@ -113,7 +152,18 @@ async function runLock({
   for (const rel of files) {
     const abs = path.join(projectRoot, rel);
     const stat = fs.statSync(abs);
-    const bytes = fs.readFileSync(abs);
+    // sealcode@1.1.0 — any watermark we injected on unlock is stripped
+    // here so the encrypted blob is identical to what the owner saw
+    // pre-share. This is what keeps repeat lock/unlock cycles from
+    // accumulating stacked watermarks AND keeps the lock idempotent
+    // (a recipient who modifies and re-locks doesn't change the blob
+    // for files they didn't actually touch).
+    const raw = fs.readFileSync(abs);
+    const bytes = watermark.stripWatermark(raw, rel);
+    // If RO mode set 0444, fs.writeFileSync above already failed for the
+    // recipient — they couldn't have modified. For OWNER side this is a
+    // no-op because watermark.stripWatermark returns the input untouched
+    // when no sentinel is found.
 
     const lockedRel = opaqueName(rel, K);
     if (reservedNames.has(lockedRel)) {
@@ -135,12 +185,27 @@ async function runLock({
       p: rel,
       l: lockedRel,
       h: sha256Hex(bytes),
-      m: stat.mode & 0o777,
+      // Persist the OWNER's intended mode (we strip any "RO grant" 0444
+      // that the recipient's CLI applied at unlock time — that's a local
+      // recipient-side enforcement decision, not a property of the file).
+      m: (stat.mode & 0o777) | 0o200, // ensure owner-writable, otherwise
+                                       // a re-lock by the owner would
+                                       // baked-in 0444 forever
       s: bytes.length,
     });
     log(`  locked ${rel}`);
   }
 
+  // Stage the preserved (unseen) blobs back into lockedRoot and append
+  // their original manifest entries. This is what keeps a scoped-grant
+  // re-lock from destroying the project for everyone else.
+  for (const { entry, bytes } of preservedBlobs) {
+    const lockedAbs = path.join(lockedRoot, entry.l);
+    ensureDir(path.dirname(lockedAbs));
+    fs.writeFileSync(lockedAbs, bytes);
+    manifestFiles.push(entry);
+  }
+
   const stubsApplied = applyStubs(projectRoot, config.stubs);
 
   const manifest = {

package/src/share-crypto.js

@@ -0,0 +1,155 @@
+'use strict';
+
+/**
+ * Wrap / unwrap the project master key K for a specific recipient.
+ *
+ * This is the cryptographic core of "team key sharing": the owner runs
+ * `sealcode share --to alice@x.com`, the CLI fetches Alice's pubkey from
+ * the server, wraps K to it, and uploads the opaque blob alongside the
+ * access code. When Alice runs `sealcode redeem <code>` on her machine,
+ * her CLI downloads the blob, unwraps it with her local privkey, and
+ * caches K — no passphrase ever leaves either machine, and the server
+ * never sees K or either party's privkey.
+ *
+ * Construction (lightly inspired by NaCl/libsodium `crypto_box_seal`):
+ *
+ *   1. Sender generates an EPHEMERAL X25519 keypair (eph_priv, eph_pub).
+ *   2. Compute X25519 ECDH: shared = dh(eph_priv, recipient_pub).
+ *   3. Compute kdf_salt = sha256(eph_pub || recipient_pub).
+ *      (Inputs both pubkeys so the AES key is bound to *this* exchange,
+ *      preventing key reuse attacks across grants.)
+ *   4. wrap_key = HKDF-SHA256(shared, salt = kdf_salt, info = "sealcode-share-v1", L = 32).
+ *   5. nonce = 12 random bytes.
+ *   6. ct = AES-256-GCM(plaintext = K, key = wrap_key, iv = nonce, aad = "sealcode-share-v1").
+ *   7. Output: { v:1, algo, ephPub, nonce, ct } — eph_priv is discarded.
+ *
+ * Recipient does the same DH (their_priv, eph_pub) and decrypts.
+ *
+ * Properties:
+ *   - Forward secrecy WRT the sender (ephemeral key destroyed).
+ *   - Server can't decrypt (it has neither privkey).
+ *   - Bound to (eph_pub, recipient_pub) — replaying the same blob to a
+ *     different recipient is computationally infeasible.
+ *   - No new dependencies (Node 18+ stdlib only).
+ */
+
+const crypto = require('crypto');
+const { _rawPublic, _publicFromRaw, _privateFromRaw } = require('./keypair');
+
+const VERSION = 1;
+const ALGO = 'x25519-hkdf-sha256-aes256gcm-v1';
+const AAD = Buffer.from('sealcode-share-v1', 'utf8');
+const INFO = Buffer.from('sealcode-share-v1', 'utf8');
+
+function hkdf(ikm, salt, info, length) {
+  // Node has a built-in HKDF; use it for clarity. Returns ArrayBuffer.
+  return Buffer.from(crypto.hkdfSync('sha256', ikm, salt, info, length));
+}
+
+function sha256(buf) {
+  return crypto.createHash('sha256').update(buf).digest();
+}
+
+/**
+ * Wrap K to a recipient identified only by their published X25519 pubkey.
+ *
+ * @param {Buffer}  K                 32 bytes — the project master key
+ * @param {string}  recipientPubB64   base64(raw 32B X25519 pubkey)
+ * @returns {{ v:number, algo:string, ephPub:string, nonce:string, ct:string }}
+ */
+function wrapForRecipient(K, recipientPubB64) {
+  if (!Buffer.isBuffer(K) || K.length !== 32) {
+    throw new Error('share-crypto: K must be a 32-byte Buffer');
+  }
+  const recipientPubRaw = Buffer.from(recipientPubB64, 'base64');
+  if (recipientPubRaw.length !== 32) {
+    throw new Error('share-crypto: recipient pubkey must be 32 bytes (base64)');
+  }
+
+  // 1. Ephemeral X25519 keypair (discarded after wrap).
+  const { publicKey: ephPubKey, privateKey: ephPrivKey } =
+    crypto.generateKeyPairSync('x25519');
+  const ephPubRaw = _rawPublic(ephPubKey); // 32B
+
+  // 2. ECDH
+  const recipientPubKey = _publicFromRaw(recipientPubRaw);
+  const shared = crypto.diffieHellman({
+    privateKey: ephPrivKey,
+    publicKey: recipientPubKey,
+  });
+
+  // 3. KDF salt binds to BOTH pubkeys
+  const salt = sha256(Buffer.concat([ephPubRaw, recipientPubRaw]));
+
+  // 4. Derive AES key
+  const wrapKey = hkdf(shared, salt, INFO, 32);
+
+  // 5+6. AES-GCM
+  const nonce = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv('aes-256-gcm', wrapKey, nonce);
+  cipher.setAAD(AAD);
+  const enc = Buffer.concat([cipher.update(K), cipher.final()]);
+  const tag = cipher.getAuthTag();
+
+  return {
+    v: VERSION,
+    algo: ALGO,
+    ephPub: ephPubRaw.toString('base64'),
+    nonce: nonce.toString('base64'),
+    ct: Buffer.concat([enc, tag]).toString('base64'),
+  };
+}
+
+/**
+ * Unwrap a blob produced by wrapForRecipient using the recipient's
+ * private key. Throws on tamper / wrong recipient / version mismatch.
+ *
+ * @param {object} blob              { v, algo, ephPub, nonce, ct }
+ * @param {string} recipientPrivB64  base64(raw 32B X25519 privkey)
+ * @param {string} recipientPubB64   base64(raw 32B X25519 pubkey)
+ * @returns {Buffer} 32-byte K
+ */
+function unwrapWithRecipient(blob, recipientPrivB64, recipientPubB64) {
+  if (!blob || blob.v !== VERSION || blob.algo !== ALGO) {
+    throw new Error(`share-crypto: unsupported wrapped_key envelope (v=${blob && blob.v}, algo=${blob && blob.algo})`);
+  }
+  const ephPubRaw = Buffer.from(blob.ephPub, 'base64');
+  const nonce = Buffer.from(blob.nonce, 'base64');
+  const ctTag = Buffer.from(blob.ct, 'base64');
+  if (ephPubRaw.length !== 32 || nonce.length !== 12 || ctTag.length < 17) {
+    throw new Error('share-crypto: malformed wrapped_key fields');
+  }
+  const recipientPubRaw = Buffer.from(recipientPubB64, 'base64');
+  if (recipientPubRaw.length !== 32) {
+    throw new Error('share-crypto: malformed recipient pubkey');
+  }
+
+  // Same DH but from recipient side.
+  const ourPriv = _privateFromRaw(Buffer.from(recipientPrivB64, 'base64'));
+  const theirEphPub = _publicFromRaw(ephPubRaw);
+  const shared = crypto.diffieHellman({
+    privateKey: ourPriv,
+    publicKey: theirEphPub,
+  });
+
+  const salt = sha256(Buffer.concat([ephPubRaw, recipientPubRaw]));
+  const wrapKey = hkdf(shared, salt, INFO, 32);
+
+  const ct = ctTag.subarray(0, ctTag.length - 16);
+  const tag = ctTag.subarray(ctTag.length - 16);
+  const decipher = crypto.createDecipheriv('aes-256-gcm', wrapKey, nonce);
+  decipher.setAAD(AAD);
+  decipher.setAuthTag(tag);
+  const K = Buffer.concat([decipher.update(ct), decipher.final()]);
+  if (K.length !== 32) {
+    throw new Error('share-crypto: unwrapped key is not 32 bytes');
+  }
+  return K;
+}
+
+module.exports = {
+  VERSION,
+  ALGO,
+  wrapForRecipient,
+  unwrapWithRecipient,
+};