@massu/core 1.4.0 → 1.5.1

package/src/security/atomic-write.ts

@@ -0,0 +1,164 @@
+/**
+ * Atomic write-then-rename primitive for security-relevant state files.
+ *
+ * Plan 3c gap-37 + gap-41 deliverable: extracted from init.ts:writeConfigAtomic
+ * (which used to inline this pattern with a hardcoded 0o644 mode and a
+ * config-specific YAML/Zod validation step) so that BOTH init.ts and the new
+ * Phase 5 security modules import the same helper. CR-46 / Rule 0 compliance:
+ * no parallel third atomic-write helper exists in the codebase.
+ *
+ * Guarantees:
+ * 1. Parent directory is created (recursively) with `ensureParentDirMode` if
+ *    passed (typically 0o700 for ~/.massu/ per gap-37). Existing parent dirs
+ *    are NOT chmod'd — that would clobber an operator's deliberate widening.
+ * 2. Content is written to `${path}.tmp` via openSync + writeSync + fsyncSync
+ *    + closeSync. The fsync is REQUIRED (xfs / ext4 `data=writeback` will
+ *    rename-before-data on crash without it; init.ts iter-7 fix codified this).
+ * 3. After tmp is durably on disk, renameSync moves it to the final path
+ *    atomically (POSIX guarantees readers see EITHER old OR new, never torn).
+ * 4. If `mode` is provided, chmodSync is applied AFTER rename so the final
+ *    mode is exact (openSync's third arg is masked by the process umask;
+ *    explicit chmod is the only way to guarantee 0o600 on systems with
+ *    umask 0o022 or stricter).
+ * 5. ANY error during the write/rename sequence triggers tmp cleanup before
+ *    the error propagates. Original file at `path` is untouched on error.
+ *
+ * Concurrency:
+ * - Reader side: NO lock acquired. POSIX renameSync is atomic; readers see
+ *   EITHER old OR new content, never torn. This is sufficient for the cache
+ *   read paths (manifest cache, fingerprint cache).
+ * - Writer side: this helper does NOT serialize concurrent writers. If two
+ *   processes call atomicWrite on the same path concurrently, both will
+ *   succeed but the second will silently overwrite the first. For Phase 5's
+ *   manifest cache (where racing `adapters refresh` invocations from the 3a
+ *   watcher + manual install + coverage CLI are plausible per gap-59), the
+ *   caller must acquire the advisory lock at `~/.massu/.adapter-manifest.lock`
+ *   FIRST via `withFileLock()` (sibling helper). This module's job is just
+ *   the write atomicity, not write serialization.
+ *
+ * Use this helper for any file that:
+ * - Gates security decisions (cache invalidation, signature verification,
+ *   path fingerprinting), OR
+ * - Must survive crash / SIGKILL / power loss without ending up zero-byte, OR
+ * - Has concurrent readers that must never see partial content.
+ */
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeSync,
+} from 'node:fs';
+import { dirname } from 'node:path';
+
+export interface AtomicWriteOptions {
+  /**
+   * File mode applied to the final path via chmodSync after rename.
+   * Defaults to undefined (existing-mode preservation, or system default for
+   * new files). Pass 0o600 for security-relevant cache files (manifest,
+   * fingerprint, etc.) per Plan 3c gap-37.
+   */
+  mode?: number;
+  /**
+   * If passed AND the parent directory does NOT exist, mkdirSync creates it
+   * with this mode. Pass 0o700 for ~/.massu/ per Plan 3c gap-37 deliverable.
+   * Existing parent directories are NOT chmod'd — operators may have
+   * deliberately widened the dir for sharing/sync.
+   */
+  ensureParentDirMode?: number;
+}
+
+export interface AtomicWriteResult {
+  /** True when the rename succeeded and the final mode (if requested) is in place. */
+  written: boolean;
+  /** Error message when written is false. */
+  error?: string;
+}
+
+/**
+ * Atomically write `content` to `path`. See module-level doc for guarantees.
+ *
+ * Returns `{ written: true }` on success, `{ written: false, error }` on
+ * failure (tmp file is cleaned up; original `path` is untouched).
+ */
+export function atomicWrite(
+  path: string,
+  content: string | Buffer,
+  opts: AtomicWriteOptions = {},
+): AtomicWriteResult {
+  const tmpPath = `${path}.tmp`;
+  const parentDir = dirname(path);
+
+  try {
+    if (!existsSync(parentDir)) {
+      const mkdirOpts: { recursive: true; mode?: number } = { recursive: true };
+      if (opts.ensureParentDirMode !== undefined) {
+        mkdirOpts.mode = opts.ensureParentDirMode;
+      }
+      mkdirSync(parentDir, mkdirOpts);
+    }
+
+    const buf = typeof content === 'string' ? Buffer.from(content, 'utf-8') : content;
+    const openMode = opts.mode ?? 0o644;
+    const fd = openSync(tmpPath, 'w', openMode);
+    try {
+      writeSync(fd, buf, 0, buf.length, 0);
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+
+    if (opts.mode !== undefined) {
+      // CR-9 audit M1 fix: chmod the TMP file BEFORE rename so the final
+      // file appears with the correct mode atomically. Without this, the
+      // prior post-rename chmod left a microsecond TOCTOU window where the
+      // file existed at the final path with umask-default mode (e.g.
+      // 0o644) — an attacker process polling the cache file could read
+      // the contents before chmod fires. With chmod-before-rename, the
+      // rename atomically delivers a file already at mode 0o600.
+      chmodSync(tmpPath, opts.mode);
+    }
+
+    renameSync(tmpPath, path);
+
+    return { written: true };
+  } catch (err) {
+    if (existsSync(tmpPath)) {
+      try {
+        rmSync(tmpPath, { force: true });
+      } catch {
+        // Tmp cleanup is best-effort; primary error wins.
+      }
+    }
+    return { written: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/**
+ * Stat a path and return whether it is group-writable or world-writable.
+ * Used by Plan 3c gap-37 deliverable to emit a stderr warning when ~/.massu/
+ * is shared across users via NFS / symlink / chmod widening — security-
+ * relevant cache files MUST NOT be readable by other accounts on shared
+ * systems.
+ *
+ * CR-9 audit L4 fix: returns `null` (unknown) on stat error instead of
+ * `false` (definitely-not-writable). Caller treats unknown as "warn"
+ * since a stat error could itself indicate adversarial filesystem state
+ * (mounted by another user, ownership flip, etc.). Returning false
+ * silently in that path was a defense-bypass.
+ */
+export function isGroupOrWorldWritable(path: string): boolean | null {
+  if (!existsSync(path)) return false;
+  try {
+    const mode = statSync(path).mode;
+    // 0o020 = group-write, 0o002 = other-write
+    return (mode & 0o022) !== 0;
+  } catch {
+    return null;
+  }
+}

package/src/security/fetcher.ts

@@ -0,0 +1,200 @@
+/**
+ * HTTPS fetch helper with strict host allowlist + bounded timeout.
+ *
+ * Plan 3c Phase 5 deliverable (gap-3 / Phase 5 deps line 114). The Phase 5
+ * adapter-verifier is the only consumer; fetching from arbitrary URLs is
+ * forbidden. Allowlist:
+ *   - registry.massu.ai (manifest fetch)
+ *   - telemetry.massu.ai (adapter-discovery telemetry)
+ *
+ * Why an allowlist: an unrestricted fetch primitive in @massu/core would
+ * be a supply-chain liability — a future bug or compromised adapter could
+ * exfiltrate data to attacker-controlled hosts. The allowlist lives in
+ * THIS module's source code (single source of truth), not in
+ * massu.config.yaml — operators cannot widen it without auditing this
+ * file.
+ *
+ * Why this module instead of a third-party http lib: Node 18+ has a built-in
+ * fetch (per Plan 3c gap-3 audit-fact line 46 — "no deps for `node-fetch`").
+ * This module wraps it with the allowlist + timeout + JSON parsing in a
+ * single typed surface. The verifier doesn't need redirects, retry, or
+ * streaming — those features are attack surface we don't want.
+ */
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+/**
+ * CR-9 audit H3 fix: hard cap on response body size. Without this, a
+ * compromised CDN (or TLS-MITM) could serve a multi-GB body that exceeds
+ * available heap before the timeout fires. The manifest is on the order
+ * of KB; even with 1000 adapter entries it should fit comfortably under
+ * 1 MB. The 10 MB ceiling here is generous enough to never affect
+ * legitimate manifests AND tight enough to bound damage from a malicious
+ * upstream.
+ */
+const DEFAULT_MAX_BODY_BYTES = 10 * 1024 * 1024;
+
+/**
+ * Allowlist of hosts the fetcher will GET from. Exported for unit testing
+ * but intentionally read-only (`as const`) — runtime mutation is impossible.
+ * To widen the allowlist for a new use case, edit this constant in source
+ * and ship a `@massu/core` minor release.
+ */
+export const ALLOWED_HOSTS = [
+  'registry.massu.ai',
+  'telemetry.massu.ai',
+] as const;
+
+export interface FetchUrlOptions {
+  /** Maximum time the request may take, in milliseconds. Defaults to 10s. */
+  timeoutMs?: number;
+  /**
+   * Override the allowlist for tests. Production code MUST NOT pass this —
+   * the default ALLOWED_HOSTS is the production contract. Test-only.
+   */
+  allowedHosts?: readonly string[];
+  /**
+   * Override the response body size cap (test-only). Defaults to 10 MB.
+   * CR-9 audit H3 fix: bounds OOM exposure from a malicious upstream.
+   */
+  maxBodyBytes?: number;
+}
+
+export interface FetchUrlResult {
+  status: number;
+  /** Response body as UTF-8 string. */
+  body: string;
+}
+
+export class FetchAllowlistError extends Error {
+  constructor(public readonly url: string, public readonly host: string) {
+    super(
+      `Refusing to fetch ${url}: host '${host}' is not in the @massu/core ` +
+      `fetcher allowlist. Allowed hosts: ${ALLOWED_HOSTS.join(', ')}. ` +
+      `Widening the allowlist requires editing packages/core/src/security/fetcher.ts ` +
+      `at the source level.`,
+    );
+    this.name = 'FetchAllowlistError';
+  }
+}
+
+export class FetchTimeoutError extends Error {
+  constructor(public readonly url: string, public readonly timeoutMs: number) {
+    super(`Fetch of ${url} timed out after ${timeoutMs}ms`);
+    this.name = 'FetchTimeoutError';
+  }
+}
+
+export class FetchBodySizeError extends Error {
+  constructor(public readonly url: string, public readonly maxBodyBytes: number) {
+    super(
+      `Fetch of ${url} exceeded body size cap of ${maxBodyBytes} bytes. ` +
+      `This indicates either a malicious upstream OR an unexpectedly large ` +
+      `legitimate response. Refusing to load.`,
+    );
+    this.name = 'FetchBodySizeError';
+  }
+}
+
+/**
+ * GET an HTTPS URL with allowlist enforcement + timeout. Returns the response
+ * body as a string (caller is responsible for JSON.parse + schema validation).
+ *
+ * Throws:
+ * - FetchAllowlistError if the URL's host is not in ALLOWED_HOSTS (or the
+ *   test override). Includes the host name in the error so operators can
+ *   debug misconfigurations.
+ * - FetchTimeoutError if the request exceeds the timeout.
+ * - TypeError if the URL does not parse as a valid URL.
+ * - Error (with .cause set to the underlying network error) for other failures.
+ */
+export async function fetchUrl(url: string, opts: FetchUrlOptions = {}): Promise<FetchUrlResult> {
+  const allowedHosts = opts.allowedHosts ?? ALLOWED_HOSTS;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const maxBodyBytes = opts.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch (err) {
+    throw new TypeError(`fetchUrl: invalid URL: ${url}`);
+  }
+
+  if (parsed.protocol !== 'https:') {
+    throw new FetchAllowlistError(url, parsed.host);
+  }
+
+  if (!allowedHosts.includes(parsed.host as (typeof ALLOWED_HOSTS)[number])) {
+    throw new FetchAllowlistError(url, parsed.host);
+  }
+
+  const controller = new AbortController();
+  const timeoutHandle = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(url, {
+      method: 'GET',
+      signal: controller.signal,
+      redirect: 'error', // refuse redirects — would defeat the allowlist
+    });
+
+    // CR-9 audit H3 fix: stream the body with a hard byte cap. Without this,
+    // a malicious upstream could OOM the host with a multi-GB response
+    // before the wall-clock timeout fires. content-length header check is
+    // a fast pre-filter; the streaming reader is the actual enforcement.
+    // Headers can be absent in test mocks; treat missing as "no pre-filter".
+    if (response.headers && typeof response.headers.get === 'function') {
+      const contentLengthHeader = response.headers.get('content-length');
+      if (contentLengthHeader !== null && contentLengthHeader !== undefined) {
+        const declared = Number.parseInt(contentLengthHeader, 10);
+        if (Number.isFinite(declared) && declared > maxBodyBytes) {
+          throw new FetchBodySizeError(url, maxBodyBytes);
+        }
+      }
+    }
+
+    const body = response.body;
+    if (body && typeof body.getReader === 'function') {
+      // Streaming path: bound the read by maxBodyBytes. Used in production
+      // (Node 18+ fetch returns a ReadableStream).
+      const reader = body.getReader();
+      const chunks: Uint8Array[] = [];
+      let received = 0;
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        if (value) {
+          received += value.byteLength;
+          if (received > maxBodyBytes) {
+            try { await reader.cancel(); } catch { /* best effort */ }
+            throw new FetchBodySizeError(url, maxBodyBytes);
+          }
+          chunks.push(value);
+        }
+      }
+      const merged = new Uint8Array(received);
+      let offset = 0;
+      for (const chunk of chunks) {
+        merged.set(chunk, offset);
+        offset += chunk.byteLength;
+      }
+      return { status: response.status, body: new TextDecoder().decode(merged) };
+    }
+
+    // Fallback when response.body is not a ReadableStream (e.g. test
+    // mocks that only stub `text()`). The size cap is still enforced
+    // post-read because the text length is the byte length for ASCII +
+    // a strict upper bound for UTF-8 content.
+    const text = await response.text();
+    if (text.length > maxBodyBytes) {
+      throw new FetchBodySizeError(url, maxBodyBytes);
+    }
+    return { status: response.status, body: text };
+  } catch (err) {
+    if (err instanceof Error && err.name === 'AbortError') {
+      throw new FetchTimeoutError(url, timeoutMs);
+    }
+    throw err;
+  } finally {
+    clearTimeout(timeoutHandle);
+  }
+}

package/src/security/install-tracking.ts

@@ -0,0 +1,319 @@
+/**
+ * Install-time + load-time sha256 verification of REGISTRY-VERIFIED adapter
+ * package contents (Plan 3c gap-37).
+ *
+ * Two checks defend against post-install tampering:
+ *
+ * 1. INSTALL-time: when the operator runs `npx massu adapters install <pkg>`,
+ *    this module walks the installed package's directory, computes a content-
+ *    addressed sha256, AND verifies it equals the sha256 the signed registry
+ *    manifest entry pinned. On match → record in
+ *    ~/.massu/adapter-manifest-installed.json with the version + timestamp.
+ *    Mismatch → refuse to register; the operator should `npm uninstall` the
+ *    suspicious package.
+ *
+ * 2. LOAD-time: discovery (detect/adapters/discover.ts) re-computes the
+ *    package's sha256 on every startup, compares to the install-time recorded
+ *    hash from the sidecar file. Mismatch → REFUSE to load (post-install
+ *    tampering of unpacked files in node_modules). The load-time check
+ *    compares to the LOCAL sidecar, NOT the live registry — re-fetching
+ *    from the registry every startup would be a network dependency on the
+ *    boot path (per Plan 3c gap-3 deliverable: NO network on boot).
+ *
+ * Why content-addressed (not tarball sha256):
+ * The published tarball's sha256 is a moving target — npm tarballs include
+ * timestamps + permission bits that vary across operating systems. The
+ * SAME tarball extracted to two different machines produces different
+ * tarball hashes but identical FILE CONTENT hashes. Content-addressed
+ * hashing (sha256 of canonical-stringified path:fileSha pairs, sorted by
+ * path) is stable across machines + filesystems.
+ *
+ * Per CR-46 / Rule 0 single-source-of-truth: this is the ONLY recursive
+ * directory hashing in @massu/core. Future modules that need to hash
+ * directories MUST consume sha256OfDir from here, not re-implement.
+ */
+import { readFileSync, readdirSync, lstatSync, existsSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { atomicWrite } from './atomic-write.js';
+
+export const INSTALLED_MANIFEST_PATH = resolve(homedir(), '.massu', 'adapter-manifest-installed.json');
+
+/**
+ * Compute a content-addressed sha256 of a directory recursively. Stable
+ * across machines + filesystems: sorts files by relative POSIX path,
+ * hashes each file's bytes, concatenates `<path>\0<sha256-hex>\n` per
+ * file, then sha256s the whole concatenation.
+ *
+ * Symlinks are NOT followed (they're hashed as their target path content).
+ * Directory entries (themselves) are NOT hashed (their content is implied
+ * by the files inside). Files exceeding `maxFileBytes` (default 64 MB)
+ * abort with an error — adapter packages should not ship huge binary
+ * blobs; the cap is a sanity ceiling against accidental misuse.
+ *
+ * Excluded patterns (NEVER hashed; they are install-time artifacts that
+ * vary across machines):
+ *   - .git/
+ *   - node_modules/  (transitive deps; their integrity is npm's concern)
+ *   - any path containing /.cache/ or /.tmp/
+ */
+const DEFAULT_MAX_FILE_BYTES = 64 * 1024 * 1024;
+/**
+ * Directory names that sha256OfDir EXCLUDES from hashing — these are
+ * install-time artifacts that vary across machines (.git history,
+ * transitive deps, build caches, scratch dirs). Their CONTENT is not
+ * part of the adapter package's content-addressable hash.
+ *
+ * CR-9 audit M5 + iter-2 audit MED-NEW-1/-2 enforcement: a published
+ * npm tarball MUST NOT ship these directories. Any package that does
+ * is refused at install + resign + load-time discovery via
+ * `containsHiddenDirs()` below. Without these refusals, a malicious
+ * tarball could smuggle payload files under `.git/payload.js` (excluded
+ * from the hash) and have them require()'d by the legitimate adapter
+ * at runtime — hash matches, payload runs.
+ */
+export const EXCLUDED_DIR_NAMES: ReadonlySet<string> = new Set(['.git', 'node_modules', '.cache', '.tmp']);
+
+/**
+ * Returns the first hidden-dir name found in `packageDir`, or null if
+ * none are present. Caller (install / resign / discovery) refuses the
+ * package on non-null return.
+ */
+export function containsHiddenDirs(packageDir: string): string | null {
+  for (const hidden of EXCLUDED_DIR_NAMES) {
+    if (existsSync(`${packageDir}/${hidden}`)) {
+      return hidden;
+    }
+  }
+  return null;
+}
+
+export interface Sha256OfDirOpts {
+  /** Override the file-size cap (test-only). */
+  maxFileBytes?: number;
+}
+
+export function sha256OfDir(dir: string, opts: Sha256OfDirOpts = {}): string {
+  const maxFileBytes = opts.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
+  const files: Array<{ relativePath: string; absPath: string }> = [];
+
+  function walk(currentDir: string): void {
+    let entries: string[];
+    try {
+      entries = readdirSync(currentDir);
+    } catch {
+      return;
+    }
+    for (const entry of entries.sort()) {
+      const absPath = join(currentDir, entry);
+      let lst;
+      try {
+        // CR-9 audit H1 fix: lstatSync (not statSync) so symlinks are
+        // detected + skipped without following. Following symlinks would
+        // expose a read-anywhere primitive (a malicious dist/x.js -> /etc/shadow
+        // would have the target's content captured into the hash) AND would
+        // cause readFileSync to block on named-pipe targets.
+        lst = lstatSync(absPath);
+      } catch {
+        continue;
+      }
+      if (lst.isSymbolicLink()) {
+        // Skip symlinks entirely — they're not part of the package's
+        // content-addressable hash. A package author who legitimately wants
+        // to ship a symlink (rare) must replace it with a real file at
+        // publish time.
+        continue;
+      }
+      if (lst.isDirectory()) {
+        if (EXCLUDED_DIR_NAMES.has(entry)) continue;
+        walk(absPath);
+        continue;
+      }
+      if (!lst.isFile()) continue;
+      if (lst.size > maxFileBytes) {
+        throw new Error(
+          `sha256OfDir: file ${absPath} exceeds maxFileBytes (${lst.size} > ${maxFileBytes}); ` +
+          `adapter packages should not ship files this large.`,
+        );
+      }
+      const rel = relative(dir, absPath).split(sep).join('/');
+      files.push({ relativePath: rel, absPath });
+    }
+  }
+  walk(dir);
+
+  // Sort by relative POSIX path so the hash is stable regardless of
+  // readdir order (some filesystems return entries in inode order).
+  files.sort((a, b) => (a.relativePath < b.relativePath ? -1 : a.relativePath > b.relativePath ? 1 : 0));
+
+  const top = createHash('sha256');
+  for (const f of files) {
+    const fileHash = createHash('sha256').update(readFileSync(f.absPath)).digest('hex');
+    top.update(f.relativePath, 'utf-8');
+    top.update('\0', 'utf-8');
+    top.update(fileHash, 'utf-8');
+    top.update('\n', 'utf-8');
+  }
+  return top.digest('hex');
+}
+
+/**
+ * Per-package install record. Keyed by package name in the sidecar's
+ * top-level object.
+ */
+const InstallEntrySchema = z.object({
+  // CR-9 iter-3 audit LOW-NEW3-1 fix: reject control characters in version.
+  // Without this, a same-user attacker writing the install-tracking
+  // sidecar could embed ANSI escapes (or other control chars) in version,
+  // log-injecting via runAdaptersResign's `${name}@${entry.version}`
+  // stderr emits. The regex permits printable ASCII (0x20-0x7e) plus
+  // common semver characters; control chars (0x00-0x1f, 0x7f) are
+  // rejected at parse time. Schema-level validation closes the vector
+  // at every callsite that reads the sidecar — no per-callsite escaping
+  // gymnastics needed.
+  version: z.string().min(1).regex(/^[\x20-\x7e]+$/, 'version must be printable ASCII (no control characters)'),
+  installed_sha256: z.string().regex(/^[0-9a-f]{64}$/),
+  manifest_sha256: z.string().regex(/^[0-9a-f]{64}$/),
+  ts: z.string().min(1).regex(/^[\x20-\x7e]+$/, 'ts must be printable ASCII (no control characters)'),
+}).strict();
+export type InstallEntry = z.infer<typeof InstallEntrySchema>;
+
+const InstalledManifestSchema = z.record(z.string(), InstallEntrySchema);
+export type InstalledManifest = z.infer<typeof InstalledManifestSchema>;
+
+/**
+ * Read the install-tracking sidecar at ~/.massu/adapter-manifest-installed.json.
+ * Returns an empty object when the file is absent OR fails parse / schema —
+ * caller should treat absent + corrupt the same way (no install records, so
+ * REGISTRY-VERIFIED adapters cannot satisfy the load-time check + are refused
+ * until reinstalled via `npx massu adapters install`).
+ */
+export function readInstalledManifest(path: string = INSTALLED_MANIFEST_PATH): InstalledManifest {
+  if (!existsSync(path)) return {};
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(path, 'utf-8'));
+  } catch {
+    return {};
+  }
+  const parsed = InstalledManifestSchema.safeParse(raw);
+  return parsed.success ? parsed.data : {};
+}
+
+export type InstallTrackingWriteResult = { written: true } | { written: false; error: string };
+
+/**
+ * Write a single package's install entry to the sidecar (additive). Reads
+ * the current sidecar, updates the named key, writes back atomically with
+ * mode 0o600. Concurrent calls to this function for DIFFERENT package
+ * names are NOT serialized — the manifest cache lock at
+ * ~/.massu/.adapter-manifest.lock applies only to the cache, not this
+ * sidecar. Since the install flow runs interactively (one CLI invocation
+ * at a time per shell), racing writes are not a practical concern.
+ */
+export function writeInstalledManifestEntry(
+  packageName: string,
+  entry: InstallEntry,
+  path: string = INSTALLED_MANIFEST_PATH,
+): InstallTrackingWriteResult {
+  // CR-9 iter-4 audit LOW-NEW4-1 fix: validate entry against the schema
+  // BEFORE writing. TypeScript types do NOT enforce Zod regex constraints
+  // at runtime; without this .parse(), a caller passing a control-char-
+  // contaminated entry (e.g. version from an attacker-controlled
+  // node_modules package.json) would write the malformed entry to disk,
+  // and the corresponding stderr emit at the install/resign callsite
+  // would log-inject before the next read-time validation could catch it.
+  const validated = InstallEntrySchema.safeParse(entry);
+  if (!validated.success) {
+    const issues = validated.error.issues
+      .map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
+      .join('; ');
+    return { written: false, error: `install-tracking entry shape invalid: ${issues}` };
+  }
+  const current = readInstalledManifest(path);
+  current[packageName] = validated.data;
+  const result = atomicWrite(path, JSON.stringify(current, null, 2), {
+    mode: 0o600,
+    ensureParentDirMode: 0o700,
+  });
+  if (!result.written) {
+    return { written: false, error: result.error ?? 'unknown atomicWrite error' };
+  }
+  return { written: true };
+}
+
+/**
+ * Remove a single package's install entry from the sidecar. Used by
+ * `npx massu adapters resign --uninstall` (or by future cleanup tooling).
+ * No-op if the entry is absent; sidecar file persists.
+ */
+export function removeInstalledManifestEntry(
+  packageName: string,
+  path: string = INSTALLED_MANIFEST_PATH,
+): InstallTrackingWriteResult {
+  const current = readInstalledManifest(path);
+  if (!(packageName in current)) {
+    return { written: true };
+  }
+  delete current[packageName];
+  const result = atomicWrite(path, JSON.stringify(current, null, 2), {
+    mode: 0o600,
+    ensureParentDirMode: 0o700,
+  });
+  if (!result.written) {
+    return { written: false, error: result.error ?? 'unknown atomicWrite error' };
+  }
+  return { written: true };
+}
+
+export type IntegrityCheckResult =
+  | { kind: 'ok'; entry: InstallEntry }
+  | { kind: 'no-entry'; reason: string }
+  | { kind: 'drift'; entry: InstallEntry; computedSha: string; reason: string };
+
+/**
+ * Load-time integrity check for an installed REGISTRY-VERIFIED adapter
+ * package. Compares the package directory's CURRENT sha256OfDir output
+ * to the install-time hash recorded in the sidecar. Mismatch → drift,
+ * caller refuses to load.
+ *
+ * Caller (typically discoverAdapters) interprets:
+ *   - 'ok'        → load is safe
+ *   - 'no-entry'  → package is in node_modules but never registered via
+ *                    `massu adapters install`; refuse + tell operator to run install
+ *   - 'drift'     → contents tampered after install; REFUSE; tell operator
+ *                    to `npm uninstall` + `npm install` + `massu adapters install`
+ */
+export function verifyInstalledIntegrity(
+  packageName: string,
+  packageDir: string,
+  sidecarPath: string = INSTALLED_MANIFEST_PATH,
+): IntegrityCheckResult {
+  const installed = readInstalledManifest(sidecarPath);
+  const entry = installed[packageName];
+  if (!entry) {
+    return {
+      kind: 'no-entry',
+      reason:
+        `${packageName} is in node_modules but has no install-tracking entry in ~/.massu/adapter-manifest-installed.json. ` +
+        `Run \`npx massu adapters install ${packageName}\` to register it.`,
+    };
+  }
+  const computedSha = sha256OfDir(packageDir);
+  if (computedSha !== entry.installed_sha256) {
+    return {
+      kind: 'drift',
+      entry,
+      computedSha,
+      reason:
+        `${packageName}@${entry.version} contents changed after install: ` +
+        `expected sha256 ${entry.installed_sha256.slice(0, 16)}..., got ${computedSha.slice(0, 16)}.... ` +
+        `This indicates post-install tampering of the package files. Recover by running ` +
+        `\`npm uninstall ${packageName} && npm install ${packageName} && npx massu adapters install ${packageName}\`.`,
+    };
+  }
+  return { kind: 'ok', entry };
+}