fieldlog 0.15.0

package/src/auth.ts

@@ -0,0 +1,297 @@
+// auth.ts — ed25519 device keys, revocable scopes, countersign threshold.
+// No PKI: devices are raw public keys; an authority key signs scope grants.
+import { generateKeyPairSync, randomUUID, sign, verify } from 'node:crypto';
+import { canonicalOf, hashFor, type LogEvent } from './log.js';
+/**
+ * Device identity.
+ *
+ * `deviceId` is the lowercase hex encoding of the ed25519 public key's
+ * SPKI DER bytes (`publicKey.export({ type: 'spki', format: 'der' })`
+ * rendered as hex). Registry maps, scope grants, capability tokens, and
+ * countersignatures key on this exact string — never the PEM. An explicit
+ * `deviceId` override (e.g. a named authority such as 'hq' in tests)
+ * bypasses the derivation and is NOT SPKI-DER hex; production devices
+ * always use the derived form.
+ */
+export interface DeviceKeypair {
+  deviceId: string; // lowercase hex of the ed25519 public key (SPKI DER)
+  publicKeyPem: string;
+  privateKeyPem: string;
+}
+
+export function generateDeviceKey(deviceId?: string): DeviceKeypair {
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+  const pubDer = publicKey.export({ type: 'spki', format: 'der' });
+  const pubPem = publicKey.export({ type: 'spki', format: 'pem' }) as string;
+  const privPem = privateKey.export({ type: 'pkcs8', format: 'pem' }) as string;
+  return {
+    deviceId: deviceId ?? (pubDer as Buffer).toString('hex'),
+    publicKeyPem: pubPem,
+    privateKeyPem: privPem,
+  };
+}
+
+export function signBytes(privateKeyPem: string, data: Uint8Array | string): string {
+  const bytes = typeof data === 'string' ? Buffer.from(data, 'utf8') : Buffer.from(data);
+  return sign(null, bytes, privateKeyPem).toString('hex');
+}
+
+export function verifyBytes(publicKeyPem: string, data: Uint8Array | string, signatureHex: string): boolean {
+  try {
+    const bytes = typeof data === 'string' ? Buffer.from(data, 'utf8') : Buffer.from(data);
+    return verify(null, bytes, publicKeyPem, Buffer.from(signatureHex, 'hex'));
+  } catch {
+    return false;
+  }
+}
+
+/** Sign the event's hash-chain hash: signature covers the whole causal history. */
+export function signEvent(privateKeyPem: string, ev: LogEvent): string {
+  return signBytes(privateKeyPem, ev.hash);
+}
+
+export function verifyEvent(publicKeyPem: string, ev: LogEvent, signatureHex: string): boolean {
+  const { hash } = ev;
+  // Recompute the chain hash so a signature can't be transplanted onto edited bytes.
+  // The auth envelope itself is never hashed (signature covers the hash).
+  const { hash: _drop, signature: _s, countersignatures: _c, ...core } = ev;
+  void _drop;
+  void _s;
+  void _c;
+  if (hashFor(core) !== hash) return false;
+  return verifyBytes(publicKeyPem, hash, signatureHex);
+}
+
+// Named TTLs: single source for grant/capability lifetimes. The relay path
+// uses the short capability default; callers needing longer sessions pass
+// an explicit ttlMs rather than forking a second magic number.
+export const GRANT_TTL_MS = 24 * 3600 * 1000;
+export const CAP_TOKEN_TTL_MS = 15 * 60 * 1000;
+
+ // Scopes: revocable capability grants signed by an authority key.
+export interface ScopeGrant {
+  id: string;
+  deviceId: string;
+  scopes: string[]; // e.g. ['entries:append', 'entries:resolve']
+  issuedBy: string; // authority deviceId / name
+  issuedAt: number;
+  expiresAt: number;
+  signature?: string; // authority signature over the canonical grant
+}
+
+export function canonicalGrant(g: Omit<ScopeGrant, 'signature'>): string {
+  return JSON.stringify({
+    id: g.id,
+    deviceId: g.deviceId,
+    scopes: [...g.scopes].sort(),
+    issuedBy: g.issuedBy,
+    issuedAt: g.issuedAt,
+    expiresAt: g.expiresAt,
+  });
+}
+
+export function issueGrant(
+  authorityPrivatePem: string,
+  issuedBy: string,
+  deviceId: string,
+  scopes: string[],
+  ttlMs = GRANT_TTL_MS,
+  now = Date.now(),
+): ScopeGrant {
+  const grant: Omit<ScopeGrant, 'signature'> = {
+    id: randomUUID(),
+    deviceId,
+    scopes,
+    issuedBy,
+    issuedAt: now,
+    expiresAt: now + ttlMs,
+  };
+  return { ...grant, signature: signBytes(authorityPrivatePem, canonicalGrant(grant)) };
+}
+
+export class RevocationList {
+  private revoked = new Set<string>(); // grant ids; dynamic membership → Set
+  revoke(grantId: string): void {
+    this.revoked.add(grantId);
+  }
+  isRevoked(grantId: string): boolean {
+    return this.revoked.has(grantId);
+  }
+  get size(): number {
+    return this.revoked.size;
+  }
+}
+
+export function verifyGrant(
+  authorityPublicPem: string,
+  grant: ScopeGrant,
+  scope: string,
+  revocations?: RevocationList,
+  now = Date.now(),
+): boolean {
+  if (!grant.signature) return false;
+  if (grant.expiresAt <= grant.issuedAt) return false; // malformed lifetime: fail closed
+  if (now < grant.issuedAt) return false; // not-before: usable only from issuance
+  if (now > grant.expiresAt) return false;
+  if (revocations?.isRevoked(grant.id)) return false;
+  const { signature, ...core } = grant;
+  if (!verifyBytes(authorityPublicPem, canonicalGrant(core), signature)) return false;
+  return grant.scopes.includes(scope);
+}
+
+// Capability tokens: the device key itself signs a scope+expiry token.
+// The relay holds a deviceId -> publicKey registry and verifies the
+// signature + scope + expiry on every push/pull. No authority key involved.
+// Self-signed limit: possession of a valid token equals the device key for
+// its scopes until expiry or revocation — see docs/capability-token.md.
+
+export interface CapToken {
+  id: string; // per-token id: revocation is granular, never whole-device only
+  deviceId: string;
+  scopes: string[]; // e.g. ['relay:push', 'relay:pull']
+  issuedAt: number;
+  expiresAt: number;
+  notBefore?: number; // optional activation floor: now < notBefore → not yet valid
+  signature?: string; // device signature over the canonical token
+}
+export function canonicalCapToken(t: Omit<CapToken, 'signature'>): string {
+  return JSON.stringify({
+    id: t.id,
+    deviceId: t.deviceId,
+    scopes: [...t.scopes].sort(),
+    issuedAt: t.issuedAt,
+    expiresAt: t.expiresAt,
+    ...(t.notBefore !== undefined ? { notBefore: t.notBefore } : {}),
+  });
+}
+
+export function mintCapToken(
+  privateKeyPem: string,
+  deviceId: string,
+  scopes: string[],
+  ttlMs = CAP_TOKEN_TTL_MS,
+  now = Date.now(),
+): CapToken {
+  const core: Omit<CapToken, 'signature'> = {
+    id: randomUUID(),
+    deviceId,
+    scopes,
+    issuedAt: now,
+    expiresAt: now + ttlMs,
+  };
+  return { ...core, signature: signBytes(privateKeyPem, canonicalCapToken(core)) };
+}
+
+/** Per-token-id revocation for capability tokens (granular: one token dies, siblings live). */
+export class CapRevocationList {
+  private revoked = new Set<string>(); // token ids; dynamic membership → Set
+  revoke(tokenId: string): void {
+    this.revoked.add(tokenId);
+  }
+  isRevoked(tokenId: string): boolean {
+    return this.revoked.has(tokenId);
+  }
+  get size(): number {
+    return this.revoked.size;
+  }
+}
+
+export function verifyCapToken(
+  publicKeyPem: string,
+  token: CapToken,
+  scope: string,
+  revocations?: CapRevocationList,
+  now = Date.now(),
+): boolean {
+  if (!token.signature) return false;
+  if (!token.id) return false; // id-less legacy token: fail closed, re-mint
+  if (token.expiresAt <= token.issuedAt) return false;
+  if (token.notBefore !== undefined && now < token.notBefore) return false;
+  if (now > token.expiresAt) return false;
+  if (revocations?.isRevoked(token.id)) return false;
+  const { signature, ...core } = token;
+  if (!verifyBytes(publicKeyPem, canonicalCapToken(core), signature)) return false;
+  return token.scopes.includes(scope);
+}
+
+export type AuthorizeVerdict = { ok: true } | { ok: false; reason: string };
+
+/**
+ * Authorize a relay op against a capability token: device tombstone first,
+ * then per-token-id revocation, signature, expiry, and scope — in that order
+ * so revoked callers never reach crypto. This is the authorize path the relay
+ * mirrors (see WsRelayServer.authorize in src/relay.ts, read-only here).
+ */
+export function authorizeCapToken(opts: {
+  publicKeyPem: string | undefined;
+  token: CapToken | undefined;
+  scope: string;
+  revocations?: CapRevocationList;
+  revokedDevices?: Set<string> | string[];
+  now?: number;
+}): AuthorizeVerdict {
+  const now = opts.now ?? Date.now();
+  if (!opts.token) return { ok: false, reason: 'missing capability token' };
+  const revoked = opts.revokedDevices instanceof Set ? opts.revokedDevices : new Set(opts.revokedDevices ?? []);
+  if (revoked.has(opts.token.deviceId)) return { ok: false, reason: `device revoked: ${opts.token.deviceId}` };
+  if (!opts.publicKeyPem) return { ok: false, reason: `unknown device: ${opts.token.deviceId}` };
+  if (!verifyCapToken(opts.publicKeyPem, opts.token, opts.scope, opts.revocations, now)) {
+    return { ok: false, reason: `capability rejected for ${opts.scope}` };
+  }
+  return { ok: true };
+}
+
+/**
+ * Authorize an entry-scoped op against an authority-signed grant. Wires the
+ * previously call-site-free verifyGrant into the authorize path so entry
+ * scopes (entries:append, entries:resolve) are gated per grant id, not assumed.
+ */
+export function authorizeGrant(opts: {
+  authorityPublicPem: string;
+  grant: ScopeGrant | undefined;
+  scope: string;
+  revocations?: RevocationList;
+  now?: number;
+}): AuthorizeVerdict {
+  const now = opts.now ?? Date.now();
+  if (!opts.grant) return { ok: false, reason: 'missing scope grant' };
+  if (!verifyGrant(opts.authorityPublicPem, opts.grant, opts.scope, opts.revocations, now)) {
+    return { ok: false, reason: `grant rejected for ${opts.scope}` };
+  }
+  return { ok: true };
+}
+
+// Countersign: high-value moves need ≥ threshold distinct authorized signatures.
+
+export interface Countersignature {
+  deviceId: string;
+  signatureHex: string;
+}
+
+export function countersignEvent(privateKeyPem: string, deviceId: string, ev: LogEvent): Countersignature {
+  return { deviceId, signatureHex: signEvent(privateKeyPem, ev) };
+}
+
+export function checkThreshold(
+  registry: Map<string, string>, // deviceId -> publicKeyPem
+  ev: LogEvent,
+  signatures: Countersignature[],
+  threshold: number,
+): { valid: number; thresholdMet: boolean } {
+  if (!Number.isInteger(threshold) || threshold < 1 || threshold > registry.size) {
+    throw new RangeError(`checkThreshold: threshold ${threshold} out of range 1..${registry.size}`);
+  }
+  const seen = new Set<string>();
+  let valid = 0;
+  for (const s of signatures) {
+    if (seen.has(s.deviceId)) continue; // one vote per device
+    const pub = registry.get(s.deviceId);
+    if (!pub) continue; // unknown device: not a vote
+    if (!verifyEvent(pub, ev, s.signatureHex)) continue;
+    seen.add(s.deviceId);
+    valid += 1;
+  }
+  return { valid, thresholdMet: valid >= threshold };
+}
+
+export { canonicalOf };

package/src/cas.ts

@@ -0,0 +1,357 @@
+// cas.ts — skill-14 cas-store port (stable) for fieldlog.
+//
+// Content-addressed blob store: the sha256 of the bytes IS the key, so the
+// same attachment stored twice costs one blob plus a refcount. Refs are
+// explicit (put/link add one, unlink drops one); the blob dies at zero.
+// Reads re-hash and quarantine on mismatch, mirroring hashchain.ts.
+//
+// Layout under <dir>:
+//   sha/<ab>/<cdef...>  blob bytes, key = ab+cdef...
+//   cas.json            { refs: { <key>: <count> } }, atomic rename per mutation
+//   quarantine/<key>    blobs that failed re-hash on read (forensics, never served)
+import { createHash } from 'node:crypto';
+import {
+  closeSync,
+  existsSync,
+  fsyncSync,
+  fstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  unlinkSync,
+  writeSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+
+const KEY_RE = /^[0-9a-f]{64}$/;
+
+/** sha256 hex of the bytes. The key, no registry, no counter. */
+export function casKeyFor(data: Uint8Array | string): string {
+  return createHash('sha256').update(data).digest('hex');
+}
+
+/** Shard two hex chars deep so one directory never holds every blob. */
+export function casShardFor(key: string): string {
+  return key.slice(0, 2);
+}
+
+/** Blob path for a key under a cas dir. */
+export function casPathFor(dir: string, key: string): string {
+  return join(dir, 'sha', casShardFor(key), key.slice(2));
+}
+
+/** Forensic sidecar for blobs that failed re-hash on read. */
+export function casQuarantinePathFor(dir: string, key: string): string {
+  return join(dir, 'quarantine', key);
+}
+
+function manifestPathFor(dir: string): string {
+  return join(dir, 'cas.json');
+}
+
+export interface CasStat {
+  key: string;
+  size: number;
+  refcount: number;
+}
+
+export interface CasStore {
+  readonly dir: string;
+  /** Blobs quarantined for hash mismatch since open. */
+  quarantined: number;
+  /** Store bytes, add one ref. Same bytes twice = one blob, refcount 2. */
+  put(data: Uint8Array | string): string;
+  /** Blob bytes, or null when missing/unreadable/mismatched. Never throws on data. */
+  get(key: string): Buffer | null;
+  has(key: string): boolean;
+  stat(key: string): CasStat | null;
+  /** Add one ref to a stored key. Throws on unknown key (fail fast, no phantom refs). */
+  link(key: string): void;
+  /** Drop one ref; deletes the blob at zero. True when a blob died. */
+  unlink(key: string): boolean;
+  /** Sweep crash orphans: blobs with no ref entry, entries with no blob. Returns dead keys. */
+  gc(): string[];
+  close(): void;
+}
+
+function checkKey(key: string): void {
+  if (!KEY_RE.test(key)) throw new Error(`bad cas key (want sha256 hex): ${key.slice(0, 32)}`);
+}
+/** Best-effort directory fsync so creates/renames survive a crash. Never throws. */
+function fsyncDir(path: string): void {
+  let fd: number | undefined;
+  try {
+    fd = openSync(path, 'r');
+    fsyncSync(fd);
+  } catch {
+    // Best effort: some platforms refuse dir fsync; durability hint only.
+  } finally {
+    if (fd !== undefined) {
+      try {
+        closeSync(fd);
+      } catch {
+        // Ignore close errors on a durability hint.
+      }
+    }
+  }
+}
+
+/** Atomic manifest persist: write tmp + fsync + rename, same cutover as retain.ts. */
+function persistManifest(dir: string, refs: Record<string, number>, quarantined: Set<string>): void {
+  const path = manifestPathFor(dir);
+  const tmp = path + '.tmp';
+  const fd = openSync(tmp, 'w');
+  try {
+    writeSync(fd, JSON.stringify({ refs, quarantined: [...quarantined].sort() }));
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  renameSync(tmp, path);
+  fsyncDir(dir);
+}
+
+/**
+ * Open a cas store at `dir` (created when missing). The manifest loads once;
+ * every ref mutation persists it atomically, so a kill between ops loses at
+ * most nothing committed — refs never point at a half-written blob because
+ * the blob is exclusively created BEFORE the manifest names it.
+ */
+export function openCas(dir: string): CasStore {
+  mkdirSync(join(dir, 'sha'), { recursive: true });
+  mkdirSync(join(dir, 'quarantine'), { recursive: true });
+  let refs: Record<string, number> = {};
+  const quarantined = new Set<string>();
+  const mpath = manifestPathFor(dir);
+  if (existsSync(mpath)) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(readFileSync(mpath, 'utf8'));
+    } catch {
+      throw new Error('corrupt cas manifest (not json, refusing to guess refs)');
+    }
+    if (!parsed || typeof parsed !== 'object' || !('refs' in parsed) || typeof parsed.refs !== 'object' || parsed.refs === null) {
+      throw new Error('corrupt cas manifest (no refs table, refusing to guess refs)');
+    }
+    for (const [k, v] of Object.entries(parsed.refs as Record<string, unknown>)) {
+      if (!KEY_RE.test(k) || typeof v !== 'number' || !Number.isInteger(v) || v < 0) {
+        throw new Error('corrupt cas manifest (bad key or count, refusing to guess refs)');
+      }
+      if (v > 0) refs[k] = v;
+    }
+    // Quarantine section: keys whose blobs failed re-hash (fail-closed evidence).
+    // Optional for backward compat; validated strictly when present.
+    const qraw = (parsed as Record<string, unknown>).quarantined;
+    if (qraw !== undefined) {
+      if (!Array.isArray(qraw) || qraw.some((k) => typeof k !== 'string' || !KEY_RE.test(k))) {
+        throw new Error('corrupt cas manifest (bad quarantine section, refusing to guess refs)');
+      }
+      for (const k of qraw as string[]) quarantined.add(k);
+    }
+  } else {
+    persistManifest(dir, refs, quarantined);
+  }
+  const store: CasStore & { quarantined: number } = {
+    dir,
+    quarantined: 0,
+    put(data: Uint8Array | string): string {
+      const key = casKeyFor(data);
+      const blob = casPathFor(dir, key);
+      mkdirSync(dirname(blob), { recursive: true });
+      for (let attempt = 0; ; attempt += 1) {
+        try {
+          const fd = openSync(blob, 'wx');
+          try {
+            if (typeof data === 'string') writeSync(fd, data);
+            else writeSync(fd, data);
+            fsyncSync(fd);
+          } finally {
+            closeSync(fd);
+          }
+          fsyncDir(dirname(blob));
+          break;
+        } catch (err) {
+          const code = (err as NodeJS.ErrnoException)?.code;
+          // Concurrent same-key winner already created the blob: adopt it.
+          // Windows reports the loser as EPERM/EACCES/EBUSY when the winner
+          // still holds the file, so those mean EEXIST when the blob exists.
+          if (code === 'EEXIST') break;
+          if (code === 'EPERM' || code === 'EACCES' || code === 'EBUSY') {
+            if (existsSync(blob)) break;
+            if (attempt < 100) continue;
+          }
+          throw err;
+        }
+      }
+      refs[key] = (refs[key] ?? 0) + 1;
+      quarantined.delete(key);
+      persistManifest(dir, refs, quarantined);
+      return key;
+    },
+
+    get(key: string): Buffer | null {
+      if (!KEY_RE.test(key)) return null;
+      if (!(key in refs)) return null;
+      const blob = casPathFor(dir, key);
+      if (!existsSync(blob)) return null;
+      let bytes: Buffer;
+      try {
+        bytes = readFileSync(blob);
+      } catch {
+        return null;
+      }
+      if (casKeyFor(bytes) !== key) {
+        const qpath = casQuarantinePathFor(dir, key);
+        try {
+          mkdirSync(dirname(qpath), { recursive: true });
+          renameSync(blob, qpath);
+        } catch (err) {
+          const code = (err as NodeJS.ErrnoException)?.code;
+          if (code === 'EEXIST' || code === 'EPERM') {
+            // A previous quarantine already occupies the sidecar (Windows
+            // rename refuses to overwrite): drop the loser copy rather than
+            // serving corrupt bytes or throwing on the data path.
+            try {
+              unlinkSync(qpath);
+              renameSync(blob, qpath);
+            } catch {
+              try {
+                unlinkSync(blob);
+              } catch {
+                // Blob already gone; refs cleanup below still applies.
+              }
+            }
+          } else if (code !== 'ENOENT') {
+            try {
+              unlinkSync(blob);
+            } catch {
+              // Blob already gone; refs cleanup below still applies.
+            }
+          }
+        }
+        fsyncDir(dirname(blob));
+        fsyncDir(dirname(qpath));
+        quarantined.add(key);
+        persistManifest(dir, refs, quarantined);
+        store.quarantined += 1;
+        return null;
+      }
+      return bytes;
+    },
+
+    has(key: string): boolean {
+      if (!KEY_RE.test(key)) return false;
+      if (!(key in refs) || quarantined.has(key)) return false;
+      return existsSync(casPathFor(dir, key));
+    },
+
+    stat(key: string): CasStat | null {
+      if (!KEY_RE.test(key)) return null;
+      const n = refs[key];
+      if (n === undefined) return null;
+      if (quarantined.has(key)) {
+        let size = 0;
+        try {
+          const fd = openSync(casQuarantinePathFor(dir, key), 'r');
+          try {
+            size = fstatSync(fd).size;
+          } finally {
+            try { closeSync(fd); } catch { /* ignore */ }
+          }
+        } catch { size = 0; }
+        return { key, size, refcount: n };
+      }
+      const blob = casPathFor(dir, key);
+      let fd: number | undefined;
+      try {
+        fd = openSync(blob, 'r');
+        const size = fstatSync(fd).size;
+        return { key, size, refcount: n };
+      } catch {
+        return null;
+      } finally {
+        if (fd !== undefined) {
+          try {
+            closeSync(fd);
+          } catch {
+            // Ignore close errors on a read-only stat probe.
+          }
+        }
+      }
+    },
+
+    link(key: string): void {
+      checkKey(key);
+      if (!(key in refs)) throw new Error('link of unknown cas key (put first, no phantom refs)');
+      refs[key] += 1;
+      persistManifest(dir, refs, quarantined);
+    },
+
+    unlink(key: string): boolean {
+      checkKey(key);
+      const n = refs[key];
+      if (n === undefined) throw new Error('unlink of unknown cas key (no phantom refs)');
+      if (n <= 1) {
+        delete refs[key];
+        quarantined.delete(key);
+        const blob = casPathFor(dir, key);
+        if (existsSync(blob)) unlinkSync(blob);
+        try { unlinkSync(casQuarantinePathFor(dir, key)); } catch { /* no sidecar */ }
+        persistManifest(dir, refs, quarantined);
+        return true;
+      }
+      refs[key] = n - 1;
+      persistManifest(dir, refs, quarantined);
+      return false;
+    },
+
+    gc(): string[] {
+      const dead: string[] = [];
+      for (const key of Object.keys(refs)) {
+        if (quarantined.has(key)) continue;
+        if (!existsSync(casPathFor(dir, key))) {
+          delete refs[key];
+          dead.push(key);
+        }
+      }
+      // Crash window: the blob was exclusively created but the manifest
+      // never named it (kill between blob write and persist). Sweep blobs
+      // with no ref entry so they never leak silently.
+      let shards: string[] = [];
+      try {
+        shards = readdirSync(join(dir, 'sha'));
+      } catch {
+        shards = [];
+      }
+      for (const shard of shards) {
+        let names: string[] = [];
+        try {
+          names = readdirSync(join(dir, 'sha', shard));
+        } catch {
+          continue;
+        }
+        for (const rest of names) {
+          const key = shard + rest;
+          if (!KEY_RE.test(key)) continue;
+          if (key in refs) continue;
+          try {
+            unlinkSync(join(dir, 'sha', shard, rest));
+          } catch {
+            continue;
+          }
+          dead.push(key);
+        }
+      }
+      persistManifest(dir, refs, quarantined);
+      return dead;
+    },
+
+    close(): void {
+      persistManifest(dir, refs, quarantined);
+    },
+  };
+  return store;
+}