@massu/core 1.4.0 → 1.5.1

package/src/security/local-fingerprint.ts

@@ -0,0 +1,225 @@
+/**
+ * adapters.local postinstall-poisoning fingerprint (Plan 3c gap-32).
+ *
+ * Threat model: a malicious npm package's `postinstall` script could mutate
+ * `massu.config.yaml > adapters.local` to add a path pointing at attacker-
+ * controlled code. Local adapters bypass the registry-signed allowlist
+ * entirely (operator opt-in per-path), so the only defense is verifying
+ * that the operator INTENDED the mutation. The mechanism:
+ *
+ * 1. Every time the operator runs `massu adapters add-local <path>`,
+ *    `massu adapters remove-local <path>`, or `massu adapters resync-local-
+ *    fingerprint`, this module writes a sentinel file at
+ *    `~/.massu/adapters-local-fingerprint.json` recording:
+ *      { fingerprint: <sha256-hex of canonical-stringified sorted array>,
+ *        source:      "cli" | "cli-resync",
+ *        ts:          ISO8601-string }
+ *
+ * 2. At loader startup, discoverAdapters compares the CURRENT
+ *    massu.config.yaml.adapters.local content's fingerprint against the
+ *    sentinel. If they differ, the loader REFUSES to load any local
+ *    adapter and emits a stderr warning naming the additions/removals
+ *    that diverged from the last operator-acknowledged state.
+ *
+ * 3. Operators can re-acknowledge the current state by running
+ *    `massu adapters resync-local-fingerprint` — which recomputes the
+ *    fingerprint over whatever adapters.local currently holds (regardless
+ *    of how it got there) and writes the sentinel anew. This is
+ *    explicitly a "trust me, I know what I edited" CLI escape hatch.
+ *
+ * Why a SEPARATE file (not stored inside the cache, not stored in the
+ * yaml itself):
+ * - In yaml: a postinstall script could update both the entry AND the
+ *   fingerprint, defeating detection.
+ * - In ~/.massu/adapter-manifest.json (signed cache): the cache wraps
+ *   registry data, mixing operator-trust state into it would conflate
+ *   two different security domains.
+ * - Standalone: the file's path is well-known + stable; CLI-only
+ *   writes are the explicit acknowledgment signal.
+ *
+ * File mode: 0o600 (gap-37 — security-relevant cache files are owner-only).
+ *
+ * Drift-prevention (CR-46 / Rule 0 self-attest #2): the SAME canonical-
+ * fingerprint computation is used at write time AND at check time —
+ * `computeLocalFingerprint` is the single source of truth. A future
+ * caller that hashes locally-different bytes would silently drift; this
+ * module's API makes that impossible by exposing only the high-level
+ * write/check primitives, not the raw sha256 step.
+ */
+import { existsSync, readFileSync, lstatSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve, isAbsolute } from 'node:path';
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { atomicWrite } from './atomic-write.js';
+import { PrintableAsciiStringSchema } from './manifest-schema.js';
+
+export const FINGERPRINT_PATH = resolve(homedir(), '.massu', 'adapters-local-fingerprint.json');
+
+/**
+ * Canonical fingerprint: sha256 hex of `[path, sha256(content)]` tuples for
+ * each adapters.local entry, sorted by path. CR-9 audit C3 fix: hashing path
+ * STRINGS only (the prior shape) let a postinstall script swap the FILE at
+ * an already-acknowledged path with full bypass — fingerprint matched even
+ * though the file content changed. This implementation hashes BOTH the path
+ * AND the current file content, so swapping the file (even with a same-
+ * length payload) triggers drift on the very next discovery + the loader
+ * refuses until the operator runs `massu adapters resync-local-fingerprint`.
+ *
+ * Path inputs MUST be the AdapterLocalPathSchema-validated + POSIX-normalized
+ * content from getConfig().adapters?.local. `projectRoot` is the absolute
+ * path to the project so we can resolve relative entries to disk reads.
+ *
+ * Missing files: the fingerprint includes a sentinel string `<missing>` for
+ * any adapters.local entry that does not resolve to a regular file at
+ * fingerprint time. This means an absent file is part of the fingerprint
+ * — adding the file later is a drift event the operator must explicitly
+ * acknowledge. Symbolic links are detected via lstatSync + treated as
+ * `<symlink>` (also a sentinel; the link target is NEVER followed for
+ * hashing — a malicious symlink to /etc/shadow does not exfiltrate that
+ * file's content into the fingerprint).
+ */
+export function computeLocalFingerprint(
+  localPaths: ReadonlyArray<string>,
+  projectRoot: string,
+): string {
+  const tuples: Array<{ path: string; contentTag: string }> = [];
+  for (const p of localPaths) {
+    const abs = isAbsolute(p) ? p : resolve(projectRoot, p);
+    let contentTag: string;
+    try {
+      const lst = lstatSync(abs);
+      if (lst.isSymbolicLink()) {
+        contentTag = '<symlink>';
+      } else if (!lst.isFile()) {
+        contentTag = '<not-a-file>';
+      } else {
+        contentTag = createHash('sha256').update(readFileSync(abs)).digest('hex');
+      }
+    } catch {
+      contentTag = '<missing>';
+    }
+    tuples.push({ path: p, contentTag });
+  }
+  tuples.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  const canonical = JSON.stringify(tuples);
+  return createHash('sha256').update(canonical).digest('hex');
+}
+
+const FingerprintSentinelSchema = z.object({
+  fingerprint: z.string().regex(/^[0-9a-f]{64}$/),
+  source: z.enum(['cli', 'cli-resync']),
+  // CR-9 iter-5 audit LOW-NEW5-1 fix: ts is rendered to stderr in the
+  // drift warning at line 214 (`${sentinel.source} at ${sentinel.ts}`);
+  // a same-user attacker writing the sentinel file with control chars
+  // in ts would log-inject. Same vector iter-3 closed for
+  // InstallEntrySchema.ts; closing the parallel sentinel schema for
+  // single-source-of-truth consistency.
+  ts: PrintableAsciiStringSchema,
+}).strict();
+export type FingerprintSentinel = z.infer<typeof FingerprintSentinelSchema>;
+
+/**
+ * Read the on-disk sentinel. Returns null when:
+ * - file is absent (no operator action has ever been recorded)
+ * - file is present but unparseable (treat as absent — caller should
+ *   surface a stderr warning about the corrupt sentinel)
+ * - file's shape doesn't match the strict schema
+ *
+ * Caller decides what to do with `null` (typically: refuse all
+ * LOCAL-EXPLICIT loading until `massu adapters resync-local-fingerprint`
+ * is run).
+ */
+export function readFingerprintSentinel(path: string = FINGERPRINT_PATH): FingerprintSentinel | null {
+  if (!existsSync(path)) return null;
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(path, 'utf-8'));
+  } catch {
+    return null;
+  }
+  const parsed = FingerprintSentinelSchema.safeParse(raw);
+  if (!parsed.success) return null;
+  return parsed.data;
+}
+
+export type FingerprintWriteResult = { written: true } | { written: false; error: string };
+
+/**
+ * Atomically write the sentinel with the given paths' fingerprint + source
+ * tag. Mode 0o600; parent dir 0o700. Uses the shared atomicWrite primitive
+ * so torn writes are impossible.
+ */
+export function writeFingerprintSentinel(
+  localPaths: ReadonlyArray<string>,
+  source: FingerprintSentinel['source'],
+  projectRoot: string,
+  path: string = FINGERPRINT_PATH,
+): FingerprintWriteResult {
+  const sentinel: FingerprintSentinel = {
+    fingerprint: computeLocalFingerprint(localPaths, projectRoot),
+    source,
+    ts: new Date().toISOString(),
+  };
+  const result = atomicWrite(path, JSON.stringify(sentinel, null, 2), {
+    mode: 0o600,
+    ensureParentDirMode: 0o700,
+  });
+  if (!result.written) {
+    return { written: false, error: result.error ?? 'unknown atomicWrite error' };
+  }
+  return { written: true };
+}
+
+export type FingerprintCheckResult =
+  | { kind: 'match'; sentinel: FingerprintSentinel }
+  | { kind: 'no-sentinel'; reason: string }
+  | { kind: 'drift'; sentinel: FingerprintSentinel; currentFingerprint: string; reason: string };
+
+/**
+ * Compare the current adapters.local fingerprint to the on-disk sentinel.
+ * Caller (typically discoverAdapters) interprets the result:
+ *   - 'match'        — proceed to load LOCAL-EXPLICIT adapters
+ *   - 'no-sentinel'  — refuse all LOCAL-EXPLICIT; tell operator to run
+ *                       `massu adapters resync-local-fingerprint` once
+ *   - 'drift'        — refuse all LOCAL-EXPLICIT; surface the additions/
+ *                       removals so the operator can audit + ack via
+ *                       `massu adapters resync-local-fingerprint`
+ *
+ * Note: `localPaths` MUST be the AdapterLocalPathSchema-validated +
+ * POSIX-normalized content from getConfig() — passing a non-normalized
+ * array will produce a fingerprint that doesn't match what the CLI
+ * wrote. Drift-prevention from the schema side: AdapterLocalPathSchema
+ * runs at config-parse time, so any code path reading
+ * cfg.adapters.local always sees the canonical form.
+ */
+export function checkFingerprintDrift(
+  localPaths: ReadonlyArray<string>,
+  projectRoot: string,
+  path: string = FINGERPRINT_PATH,
+): FingerprintCheckResult {
+  const sentinel = readFingerprintSentinel(path);
+  if (!sentinel) {
+    return {
+      kind: 'no-sentinel',
+      reason:
+        `no adapters-local-fingerprint sentinel at ${path}. ` +
+        `If you have entries in adapters.local, run \`massu adapters resync-local-fingerprint\` ` +
+        `to acknowledge them once.`,
+    };
+  }
+  const currentFingerprint = computeLocalFingerprint(localPaths, projectRoot);
+  if (currentFingerprint === sentinel.fingerprint) {
+    return { kind: 'match', sentinel };
+  }
+  return {
+    kind: 'drift',
+    sentinel,
+    currentFingerprint,
+    reason:
+      `adapters.local fingerprint drift: sentinel was ${sentinel.fingerprint.slice(0, 16)}... ` +
+      `(written by ${sentinel.source} at ${sentinel.ts}); current is ${currentFingerprint.slice(0, 16)}.... ` +
+      `If you edited massu.config.yaml directly OR a postinstall script may have mutated adapters.local, ` +
+      `audit the diff and run \`massu adapters resync-local-fingerprint\` to acknowledge.`,
+  };
+}

package/src/security/manifest-cache.ts

@@ -0,0 +1,333 @@
+/**
+ * Adapter manifest cache (Plan 3c Phase 5 5F.3 — gap-37 + gap-54 + gap-59).
+ *
+ * Persists the verified registry manifest at `~/.massu/adapter-manifest.json`
+ * so subsequent `npx massu adapters *` invocations do NOT re-fetch (and the
+ * watcher daemon's auto-refresh-on-quiescence path is fast). The cache is
+ * self-validating: every read goes back through verifyManifest against the
+ * bundled Ed25519 pubkey, so a tampered cache file refuses to load.
+ *
+ * Concurrency model (gap-59):
+ * - Reader path: NO lock acquired. POSIX renameSync inside atomicWrite
+ *   guarantees readers see EITHER old OR new content, never torn. Multiple
+ *   parallel readers (CLI + watcher + coverage) read concurrently with no
+ *   serialization cost.
+ * - Writer path: acquires `~/.massu/.adapter-manifest.lock` via the shared
+ *   `withFileLockSync` primitive. Two concurrent `refreshManifest` invocations
+ *   both perform the async fetch in parallel (independent network operations),
+ *   then serialize on the lock for the brief atomicWrite call. The later
+ *   write wins; both contents are equally valid (manifest is signed; the
+ *   later signed-at timestamp is fresher).
+ * - Lock is held ONLY for the sync atomicWrite — never around the async
+ *   fetch — so contention bounded to ~1ms even under heavy load.
+ *
+ * Rotation drift detection (gap-54):
+ * - Cache wrapper records `bundled_pubkey_fingerprint` at write time
+ *   (sha256 hex of REGISTRY_PUBKEY_ED25519 the writer was bundling).
+ * - On read, if the cache's recorded fingerprint != currently-running
+ *   @massu/core's bundled pubkey fingerprint, mark cache STALE-DUE-TO-
+ *   ROTATION (separate from staleness-by-age). Caller must force refresh
+ *   to pick up the new pubkey's signed manifest.
+ *
+ * Staleness model:
+ * - `fetched_at` records the cache write time (NOT the manifest's
+ *   `signed_at`, which the publisher controls).
+ * - `MAX_FRESH_MS` (24h) — cache is considered fresh; reads short-circuit.
+ * - `MAX_STALE_MS` (7 days) — cache may be used offline. Caller surfaces
+ *   the staleness in UX.
+ * - Beyond 7 days — refuse to use any new adapter from this cache; require
+ *   manual `npx massu adapters refresh`.
+ *
+ * File mode (gap-37): cache file is mode 0o600; ~/.massu/ parent dir is 0o700.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+import { atomicWrite } from './atomic-write.js';
+import { withFileLockSync } from '../lib/fileLock.js';
+import { verifyManifest, type VerifyManifestResult } from './adapter-verifier.js';
+import { EnvelopeSchema, PrintableAsciiStringSchema, type Envelope } from './manifest-schema.js';
+import {
+  REGISTRY_PUBKEY_ED25519,
+  REGISTRY_PUBKEY_FINGERPRINT_HEX,
+} from './registry-pubkey.generated.js';
+import { fetchUrl } from './fetcher.js';
+
+export const MAX_FRESH_MS = 24 * 60 * 60 * 1000;       // 24h
+export const MAX_STALE_MS = 7 * 24 * 60 * 60 * 1000;   // 7 days
+export const REGISTRY_MANIFEST_URL = 'https://registry.massu.ai/adapters/manifest.json';
+
+/**
+ * Wrapper format persisted to ~/.massu/adapter-manifest.json. The envelope
+ * is the verified registry envelope (post-verifyManifest); fetched_at is the
+ * client-side timestamp; bundled_pubkey_fingerprint records which @massu/core
+ * pubkey signed this cache entry (rotation detection per gap-54).
+ */
+const CacheWrapperSchema = z.object({
+  envelope: EnvelopeSchema,
+  // CR-9 iter-6 audit LOW-NEW6-1 fix: fetched_at flows into the
+  // 'fetched_at not parseable as Date' reason render at line 163 → wrapped
+  // by getManifest into 'cache invalid: ...' → reaches stderr in
+  // commands/adapters.ts. Same control-char log-injection vector iter-3
+  // closed for InstallEntrySchema.ts AND iter-5 closed for
+  // FingerprintSentinelSchema.ts. Third sibling closure; the new AST
+  // drift-guard test (test_security_schemas_printable_ascii_drift.test.ts)
+  // makes this class of bug structurally impossible to recur.
+  fetched_at: PrintableAsciiStringSchema,
+  bundled_pubkey_fingerprint: z.string().regex(/^[0-9a-f]{64}$/),
+}).strict();
+export type CacheWrapper = z.infer<typeof CacheWrapperSchema>;
+
+export type CacheReadResult =
+  | { kind: 'fresh'; envelope: Envelope; ageMs: number; warnings: string[] }
+  | { kind: 'stale'; envelope: Envelope; ageMs: number; warnings: string[]; reason: string }
+  | { kind: 'expired'; ageMs: number; reason: string }
+  | { kind: 'rotation-detected'; reason: string }
+  | { kind: 'absent' }
+  | { kind: 'invalid'; reason: string };
+
+export interface CachePaths {
+  cachePath: string;
+  lockPath: string;
+}
+
+/**
+ * Compute the canonical cache + lock paths under the user's home directory.
+ * Exported so tests can reuse the same logic with a sandboxed home.
+ */
+export function defaultCachePaths(): CachePaths {
+  const dir = resolve(homedir(), '.massu');
+  return {
+    cachePath: resolve(dir, 'adapter-manifest.json'),
+    lockPath: resolve(dir, '.adapter-manifest.lock'),
+  };
+}
+
+/**
+ * Read + validate the cached manifest. Returns a tagged result the caller
+ * dispatches on:
+ *   - 'fresh'             — cache is valid + signed + age < MAX_FRESH_MS
+ *   - 'stale'             — cache is valid + signed + age < MAX_STALE_MS
+ *                            (caller may use; should surface staleness in UX)
+ *   - 'expired'           — age > MAX_STALE_MS; caller MUST refresh
+ *   - 'rotation-detected' — bundled_pubkey_fingerprint mismatch; caller MUST
+ *                            refresh under the new bundled pubkey
+ *   - 'absent'            — no cache file
+ *   - 'invalid'           — file exists but failed parse / signature verify;
+ *                            treat as 'absent' but surface reason for logs
+ */
+export function loadCachedManifest(paths: CachePaths = defaultCachePaths()): CacheReadResult {
+  if (!existsSync(paths.cachePath)) {
+    return { kind: 'absent' };
+  }
+
+  let raw: unknown;
+  try {
+    const content = readFileSync(paths.cachePath, 'utf-8');
+    raw = JSON.parse(content);
+  } catch (err) {
+    return {
+      kind: 'invalid',
+      reason: `cache JSON parse failed: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  const wrapperParsed = CacheWrapperSchema.safeParse(raw);
+  if (!wrapperParsed.success) {
+    const issues = wrapperParsed.error.issues
+      .map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
+      .join('; ');
+    return { kind: 'invalid', reason: `cache wrapper shape invalid: ${issues}` };
+  }
+  const wrapper = wrapperParsed.data;
+
+  // Rotation detection (gap-54): if the cache's recorded bundled-pubkey
+  // fingerprint does NOT match the currently-running @massu/core's pubkey,
+  // the cache was signed under a different key and we can't verify it
+  // with our current bundle. Caller MUST refresh.
+  if (wrapper.bundled_pubkey_fingerprint !== REGISTRY_PUBKEY_FINGERPRINT_HEX) {
+    return {
+      kind: 'rotation-detected',
+      reason:
+        `cache was written under @massu/core bundled pubkey ` +
+        `${wrapper.bundled_pubkey_fingerprint.slice(0, 16)}... but this @massu/core ` +
+        `bundles ${REGISTRY_PUBKEY_FINGERPRINT_HEX.slice(0, 16)}.... Cache must be ` +
+        `refreshed under the current bundled pubkey.`,
+    };
+  }
+
+  // Verify the envelope via the canonical 9-step verifier. Pure, no I/O.
+  const verifyResult: VerifyManifestResult = verifyManifest({
+    envelope: wrapper.envelope,
+    publicKey: REGISTRY_PUBKEY_ED25519,
+  });
+  if (!verifyResult.ok) {
+    return { kind: 'invalid', reason: `cached envelope failed verify: ${verifyResult.reason}` };
+  }
+
+  const fetchedAtMs = Date.parse(wrapper.fetched_at);
+  if (!Number.isFinite(fetchedAtMs)) {
+    return { kind: 'invalid', reason: `fetched_at not parseable as Date: ${wrapper.fetched_at}` };
+  }
+  const ageMs = Date.now() - fetchedAtMs;
+  if (ageMs < MAX_FRESH_MS) {
+    return { kind: 'fresh', envelope: verifyResult.envelope, ageMs, warnings: verifyResult.warnings };
+  }
+  if (ageMs < MAX_STALE_MS) {
+    return {
+      kind: 'stale',
+      envelope: verifyResult.envelope,
+      ageMs,
+      warnings: verifyResult.warnings,
+      reason: `cache is ${Math.floor(ageMs / 3600_000)}h old; consider refreshing`,
+    };
+  }
+  return {
+    kind: 'expired',
+    ageMs,
+    reason: `cache is ${Math.floor(ageMs / 86400_000)}d old (> 7d); refusing to use`,
+  };
+}
+
+/**
+ * Atomic write of a verified envelope to the cache file under the writer
+ * lock. Returns void on success; throws if (a) the lock cannot be acquired
+ * within the configured block, or (b) the atomicWrite fails.
+ *
+ * Caller is responsible for ensuring the envelope is verified BEFORE
+ * calling this function — cacheManifest does NOT re-verify (the verify
+ * already happens inside refreshManifest before writing).
+ */
+export function cacheManifest(envelope: Envelope, paths: CachePaths = defaultCachePaths()): void {
+  const wrapper: CacheWrapper = {
+    envelope,
+    fetched_at: new Date().toISOString(),
+    bundled_pubkey_fingerprint: REGISTRY_PUBKEY_FINGERPRINT_HEX,
+  };
+  withFileLockSync(paths.lockPath, () => {
+    const result = atomicWrite(paths.cachePath, JSON.stringify(wrapper, null, 2), {
+      mode: 0o600,
+      ensureParentDirMode: 0o700,
+    });
+    if (!result.written) {
+      throw new Error(`cacheManifest: atomicWrite failed: ${result.error}`);
+    }
+  });
+}
+
+export type RefreshResult =
+  | { kind: 'refreshed'; envelope: Envelope; warnings: string[] }
+  | { kind: 'fetch-failed'; reason: string }
+  | { kind: 'verify-failed'; reason: string };
+
+/**
+ * Fetch + verify the live registry manifest, write to cache. Returns a
+ * tagged result. The caller decides whether to surface refresh failures
+ * as fatal (stale-cache > 7d) or non-fatal (cache fresh but stale-by-age).
+ */
+export async function refreshManifest(
+  paths: CachePaths = defaultCachePaths(),
+  fetchFn: typeof fetchUrl = fetchUrl,
+): Promise<RefreshResult> {
+  let body: string;
+  try {
+    const response = await fetchFn(REGISTRY_MANIFEST_URL);
+    if (response.status !== 200) {
+      return { kind: 'fetch-failed', reason: `registry returned HTTP ${response.status}` };
+    }
+    body = response.body;
+  } catch (err) {
+    return {
+      kind: 'fetch-failed',
+      reason: `fetch ${REGISTRY_MANIFEST_URL} failed: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(body);
+  } catch (err) {
+    return {
+      kind: 'fetch-failed',
+      reason: `registry response not JSON: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  const verified = verifyManifest({ envelope: parsed, publicKey: REGISTRY_PUBKEY_ED25519 });
+  if (!verified.ok) {
+    return { kind: 'verify-failed', reason: verified.reason };
+  }
+
+  cacheManifest(verified.envelope, paths);
+  return { kind: 'refreshed', envelope: verified.envelope, warnings: verified.warnings };
+}
+
+/**
+ * High-level getter: try cache → if fresh, return. Else refresh + return new
+ * envelope. If `force=true`, skip cache entirely. If refresh fails AND a
+ * stale cache is available (< 7d), return it with a `staleAcceptedReason`.
+ * If everything fails, returns null + error reasons in the result object.
+ */
+export interface GetManifestOpts {
+  paths?: CachePaths;
+  force?: boolean;
+  fetchFn?: typeof fetchUrl;
+}
+
+export type GetManifestResult =
+  | { kind: 'ok'; envelope: Envelope; source: 'cache-fresh' | 'cache-stale' | 'refreshed'; warnings: string[]; staleReason?: string }
+  | { kind: 'fail'; reasons: string[] };
+
+export async function getManifest(opts: GetManifestOpts = {}): Promise<GetManifestResult> {
+  const paths = opts.paths ?? defaultCachePaths();
+  const fetchFn = opts.fetchFn ?? fetchUrl;
+  const reasons: string[] = [];
+
+  if (!opts.force) {
+    const cacheRead = loadCachedManifest(paths);
+    if (cacheRead.kind === 'fresh') {
+      return { kind: 'ok', envelope: cacheRead.envelope, source: 'cache-fresh', warnings: cacheRead.warnings };
+    }
+    if (cacheRead.kind === 'stale') {
+      // Try refresh first; fall back to stale cache if refresh fails.
+      const refreshed = await refreshManifest(paths, fetchFn);
+      if (refreshed.kind === 'refreshed') {
+        return { kind: 'ok', envelope: refreshed.envelope, source: 'refreshed', warnings: refreshed.warnings };
+      }
+      reasons.push(`refresh failed: ${refreshed.kind === 'fetch-failed' ? refreshed.reason : refreshed.reason}`);
+      return {
+        kind: 'ok',
+        envelope: cacheRead.envelope,
+        source: 'cache-stale',
+        warnings: cacheRead.warnings,
+        staleReason: cacheRead.reason,
+      };
+    }
+    if (cacheRead.kind === 'invalid') {
+      reasons.push(`cache invalid: ${cacheRead.reason}`);
+    } else if (cacheRead.kind === 'rotation-detected') {
+      reasons.push(`rotation: ${cacheRead.reason}`);
+    } else if (cacheRead.kind === 'expired') {
+      reasons.push(`expired: ${cacheRead.reason}`);
+    }
+  }
+
+  // Fall through to refresh (force=true OR cache absent/invalid/rotation/expired).
+  const refreshed = await refreshManifest(paths, fetchFn);
+  if (refreshed.kind === 'refreshed') {
+    return { kind: 'ok', envelope: refreshed.envelope, source: 'refreshed', warnings: refreshed.warnings };
+  }
+  reasons.push(`refresh failed: ${refreshed.kind === 'fetch-failed' ? refreshed.reason : refreshed.reason}`);
+  return { kind: 'fail', reasons };
+}
+
+/**
+ * Helper for tests + telemetry observability: returns the on-disk file
+ * mode of the cache file (or null if absent). Used to assert gap-37
+ * file-mode discipline post-write.
+ */
+export function getCacheFileMode(paths: CachePaths = defaultCachePaths()): number | null {
+  if (!existsSync(paths.cachePath)) return null;
+  return statSync(paths.cachePath).mode & 0o777;
+}

package/src/security/manifest-schema.ts

@@ -0,0 +1,129 @@
+/**
+ * Zod schemas for the registry adapter manifest envelope and body.
+ *
+ * Plan 3c Phase 5 deliverable. The publisher (registry-publish.sh, version
+ * with manifest_b64 — see project_plan_3c_phase5_canonicalization_gap.md
+ * memory + commit 1b724d3) emits envelopes matching EnvelopeSchema; the
+ * verifier (adapter-verifier.ts) consumes ParsedEnvelope. The body inside
+ * manifest_b64 (base64-decoded) parses against ManifestBodySchema.
+ *
+ * Forward-compatibility model (Plan 3c gap-56):
+ * - Manifest body has `manifest_schema_version: 1` (integer, default 1 if
+ *   absent for legacy pre-3c manifests).
+ * - Schemas use `.passthrough()` so unknown additive keys (gap-57
+ *   `deprecated`, `unpublished`, future `revoked_at` etc.) are preserved
+ *   on parse — verifier emits a one-time stderr warning when
+ *   manifest_schema_version > KNOWN_MAX (NOT a refusal — additive
+ *   forward-compat).
+ * - manifest_schema_version < MIN_KNOWN_VERSION → verifier REFUSES (a
+ *   future v2 may drop fields v1 consumers expect).
+ *
+ * Single source of truth: this is the ONLY definition of the envelope and
+ * manifest shapes in @massu/core. Other modules (verifier, cache, CLI) MUST
+ * import these schemas + their inferred types instead of re-declaring.
+ */
+import { z } from 'zod';
+
+/** Minimum schema version this @massu/core build accepts. Below this → refuse. */
+export const MIN_KNOWN_SCHEMA_VERSION = 1 as const;
+/** Maximum schema version this @massu/core build understands. Above this → warn + continue. */
+export const KNOWN_MAX_SCHEMA_VERSION = 1 as const;
+
+/** sha256 hex string. 64 lowercase hex chars. */
+const Sha256HexSchema = z.string().regex(/^[0-9a-f]{64}$/, 'sha256 hex must be 64 lowercase hex chars');
+
+/**
+ * Printable ASCII string — 0x20 to 0x7e, length 1+. Rejects control
+ * characters (including ESC \x1b for ANSI escapes), tabs, newlines, and
+ * any non-ASCII Unicode. Used for fields that get rendered to stderr or
+ * stdout in the CLI; without this constraint, an attacker could embed
+ * ANSI escape sequences in (manifest entry version, package.json name,
+ * sidecar version, etc.) to log-inject CI/operator-terminal output.
+ *
+ * CR-9 iter-4 audit single-source-of-truth (LOW-NEW4-1/2/3 fix): every
+ * schema field that's downstream of a stderr/stdout emit MUST use this
+ * type instead of bare z.string(). Adding a new string field that's
+ * later rendered in CLI output without reaching for this type is a
+ * regression worth catching at code review.
+ */
+export const PrintableAsciiStringSchema = z.string().min(1).regex(
+  /^[\x20-\x7e]+$/,
+  'must be printable ASCII (0x20-0x7e); control characters like ESC, tab, newline, and non-ASCII are rejected to prevent log injection',
+);
+
+/**
+ * Standard base64 (RFC 4648) — alphabet [A-Za-z0-9+/], length must be a
+ * multiple of 4 (with up to two `=` padding chars), no newlines.
+ * CR-9 audit L1 fix: the prior `^[A-Za-z0-9+/]*={0,2}$` regex permitted a
+ * lone `=` (decodes to zero bytes) which downstream code would parse as
+ * a valid empty input. The strict RFC 4648 form below rejects malformed
+ * base64 at the schema layer instead of relying on a downstream length
+ * check.
+ */
+const Base64Schema = z.string()
+  .regex(
+    /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{4})$/,
+    'must be standard base64 (RFC 4648; length divisible by 4 with optional == or = padding)',
+  )
+  .min(1);
+
+/**
+ * Single adapter entry in the manifest. Plan 3c gap-31 + gap-57:
+ * - `package` + `version` + `sha256` are the install-time + load-time
+ *   verification primitives.
+ * - `signing_key_id` is the sha256 fingerprint of the pubkey that signed
+ *   THIS entry (per gap-61, v1 always uses the single registry key).
+ * - `deprecated` (gap-57) — additive optional. Loader warns + still loads.
+ * - `unpublished` (gap-57) — additive optional. Loader REFUSES to load.
+ * - `.passthrough()` preserves unknown additive fields (gap-56 forward-compat).
+ */
+export const AdapterEntrySchema = z.object({
+  // CR-9 iter-4 audit LOW-NEW4-3 fix: every string field rendered in CLI
+  // output (discover.ts deprecation warning + adapters.ts search status)
+  // uses PrintableAsciiStringSchema to prevent log-injection from a
+  // compromised registry. The trust model assumes the registry can be
+  // adversarial pre-signing; the verifier's signature check + this
+  // schema together neutralize that vector.
+  package: PrintableAsciiStringSchema,
+  version: PrintableAsciiStringSchema,
+  sha256: Sha256HexSchema,
+  signing_key_id: Sha256HexSchema,
+  deprecated: z.object({
+    since: PrintableAsciiStringSchema,
+    replacement: PrintableAsciiStringSchema.nullable().optional(),
+    reason: PrintableAsciiStringSchema,
+  }).optional(),
+  unpublished: z.boolean().optional(),
+}).passthrough();
+export type AdapterEntry = z.infer<typeof AdapterEntrySchema>;
+
+/**
+ * Manifest body — the JSON object inside base64-decoded `manifest_b64`.
+ * Plan 3c gap-56: schema_version is a numeric integer. Defaults to 1 if
+ * absent (legacy pre-3c manifests) so the verifier can still read them
+ * during the rollout transition.
+ */
+export const ManifestBodySchema = z.object({
+  manifest_schema_version: z.number().int().positive().default(1),
+  issued_at: z.string().min(1),
+  adapters: z.array(AdapterEntrySchema),
+}).passthrough();
+export type ManifestBody = z.infer<typeof ManifestBodySchema>;
+
+/**
+ * Full envelope as served by registry.massu.ai/adapters/manifest.json AND
+ * cached at ~/.massu/adapter-manifest.json. Plan 3c canonicalization-gap
+ * fix (commit 1b724d3): manifest_b64 is the byte-equal-to-signed-input
+ * field; verifier MUST consume manifest_b64 (NOT the parsed `manifest`
+ * field, which is a human-readable re-serialization that does NOT round-
+ * trip to the signed bytes).
+ */
+export const EnvelopeSchema = z.object({
+  manifest: ManifestBodySchema,
+  manifest_b64: Base64Schema,
+  signature: Base64Schema,
+  manifest_sha256: Sha256HexSchema,
+  signed_at: z.string().min(1),
+  signing_key_id: Sha256HexSchema,
+}).passthrough();
+export type Envelope = z.infer<typeof EnvelopeSchema>;