@massu/core 1.4.0 → 1.5.1

package/src/lib/installLock.ts

@@ -8,49 +8,29 @@
  * `runConfigRefresh` path AND the watcher auto-trigger. Without
  * serialization, two concurrent callers can race on `.claude/commands/`
  * file writes. proper-lockfile gives us atomic mkdir-based locks that
- * work cross-platform; we wrap it to:
+ * work cross-platform.
  *
- *   1. mkdirSync the lock dir (fresh repos may not have `.massu/`)
- *   2. surface ELOCKED (POSIX) and EBUSY (Windows) as the same error
- *   3. keep installAll() synchronous (lockSync, not lock)
+ * Plan 3c gap-59 / Rule 0 single-source-of-truth refactor (commit pending,
+ * 2026-05-07): the proper-lockfile-wrapping logic + manual retry loop +
+ * .pid sidecar bookkeeping now lives in `lib/fileLock.ts:withFileLockSync`.
+ * This file is a thin domain-specific wrapper that:
+ *   1. Computes the project-root-anchored lockPath
+ *   2. Delegates to withFileLockSync via an `errorFactory` that returns
+ *      `InstallLockBusyError` (preserving the exact error message format
+ *      Plan 3a §243 specified and the install-lock tests assert)
  *
- * Plan §190 retry behavior: "second caller blocks up to 30s, then bails".
- * proper-lockfile's `lockSync` REJECTS `retries>0` (see node_modules/
- * proper-lockfile/lib/adapter.js: `Cannot use retries with the sync api`).
- * We implement the retry-block manually via a `lockfile.checkSync` /
- * `lockSync` loop with a busy-wait sleep.
- *
- * iter-3 (third pass, G3-iter3-1+2): align error message with plan §243
- * format `"installAll already running (PID=X) — try again in <N>s"` AND
- * add the manual retry-block loop.
+ * Plan 3a §190 retry behavior preserved: "second caller blocks up to 30s,
+ * then bails". InstallLockBusyError instances continue to expose
+ * `lockPath`, `holderPid`, `retryAfterSeconds`, `causeCode` — backwards-
+ * compatible for any caller that does `instanceof InstallLockBusyError`.
  */
 
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
-import { dirname, resolve } from 'path';
-import * as lockfile from 'proper-lockfile';
+import { resolve } from 'path';
+import { withFileLockSync, type FileLockOpts } from './fileLock.js';
 
-export interface InstallLockOpts {
-  /** Default 30s — proper-lockfile considers a lock stale after this elapses. */
-  staleMs?: number;
-  /**
-   * How long the manual retry loop should block waiting for the holder to
-   * release before bailing with `InstallLockBusyError`. Default 30s per
-   * plan §190 ("second caller blocks up to 30s, then bails").
-   * Pass `0` to bail immediately (used in tests).
-   */
-  blockMs?: number;
-  /** Sleep granularity inside the retry loop. Default 100ms. */
-  pollIntervalMs?: number;
-  /**
-   * Backwards-compat: legacy callers pass `retries: 0` to mean "do not
-   * block". When set to a positive integer, used by tests that want to
-   * exercise a specific retry count instead of the default time-based loop.
-   */
-  retries?: number;
-  /** Override clock (test seam). */
-  now?: () => number;
-  /** Override sleep (test seam). Defaults to a busy-wait spinloop. */
-  sleep?: (ms: number) => void;
+export interface InstallLockOpts extends FileLockOpts {
+  // No additional fields — all options come from FileLockOpts. This alias
+  // preserves the public surface for any caller that imported `InstallLockOpts`.
 }
 
 export class InstallLockBusyError extends Error {
@@ -67,113 +47,20 @@ export class InstallLockBusyError extends Error {
 }
 
 /**
- * Best-effort: read the PID of the current lock holder. proper-lockfile
- * stores the lock as a directory at `<lockPath>` containing nothing PID-
- * identifying, so we look at our own sidecar `<lockPath>.pid` file (written
- * by the lock acquirer below). On any read error we return null so the
- * error message degrades gracefully to `(PID=unknown)`.
- */
-function readHolderPid(lockPath: string): number | null {
-  try {
-    const raw = readFileSync(`${lockPath}.pid`, 'utf-8').trim();
-    const pid = Number.parseInt(raw, 10);
-    if (!Number.isFinite(pid) || pid <= 0) return null;
-    return pid;
-  } catch {
-    return null;
-  }
-}
-
-function busyWaitSync(ms: number): void {
-  const end = Date.now() + ms;
-  // Atomics.wait against a SharedArrayBuffer is the cleanest portable sync
-  // sleep; fall back to a tight loop if SharedArrayBuffer is unavailable
-  // (older runtimes / sandboxed envs).
-  if (typeof SharedArrayBuffer !== 'undefined' && typeof Atomics !== 'undefined') {
-    const sab = new SharedArrayBuffer(4);
-    const view = new Int32Array(sab);
-    Atomics.wait(view, 0, 0, ms);
-    return;
-  }
-  while (Date.now() < end) {
-    // Spin — this should never run on modern Node, kept as belt-and-suspenders.
-  }
-}
-
-/**
- * Acquire the lock, run `fn`, release on every exit path.
- * Synchronous all the way through so installAll() keeps its sync signature.
+ * Acquire the install lock for `projectRoot`, run `fn`, release on every
+ * exit path. Throws `InstallLockBusyError` when the lock is held beyond
+ * `blockMs`. See `lib/fileLock.ts:withFileLockSync` for the underlying
+ * primitive.
  */
 export function withInstallLock<T>(projectRoot: string, fn: () => T, opts: InstallLockOpts = {}): T {
   const lockPath = resolve(projectRoot, '.massu', 'installAll.lock');
-  // iter-3 G3-A11: ensure parent dir exists (fresh repo case).
-  mkdirSync(dirname(lockPath), { recursive: true });
-
-  const staleMs = opts.staleMs ?? 30_000;
-  // `retries: 0` legacy path = bail immediately, no wait.
-  // Otherwise default to plan §190's 30s block.
-  const blockMs = opts.retries === 0
-    ? 0
-    : (opts.blockMs ?? 30_000);
-  const pollIntervalMs = opts.pollIntervalMs ?? 100;
-  const now = opts.now ?? Date.now;
-  const sleep = opts.sleep ?? busyWaitSync;
-
-  let release: (() => void) | null = null;
-  const deadline = now() + blockMs;
-  let lastErr: NodeJS.ErrnoException | null = null;
-
-  // Manual retry loop. proper-lockfile.lockSync forbids retries>0, so we
-  // wrap it ourselves: try → on ELOCKED/EBUSY, sleep → try again until
-  // deadline. This satisfies plan §190 "second caller blocks up to 30s".
-  for (;;) {
-    try {
-      release = lockfile.lockSync(lockPath, {
-        stale: staleMs,
-        retries: 0,
-        realpath: false,
-      });
-      // Persist our PID alongside the lock so the next contender can include
-      // it in the user-friendly error per plan §243 format.
-      try {
-        writeFileSync(`${lockPath}.pid`, String(process.pid), 'utf-8');
-      } catch {
-        // best-effort
-      }
-      break;
-    } catch (err) {
-      lastErr = err as NodeJS.ErrnoException;
-      const code = lastErr.code;
-      if (code !== 'ELOCKED' && code !== 'EBUSY') {
-        throw err;
-      }
-      if (now() >= deadline) {
-        const holderPid = readHolderPid(lockPath);
-        const remainingMs = Math.max(0, deadline - now());
-        // Surface a hint about how long the *next* poll cycle should wait.
-        // When `blockMs=0` the user got bail-immediately semantics; report
-        // the staleness window so they know the lock auto-releases in N s.
-        const retryAfterSeconds = blockMs === 0
-          ? Math.round(staleMs / 1000)
-          : Math.round(remainingMs / 1000);
-        throw new InstallLockBusyError(lockPath, holderPid, retryAfterSeconds, code);
-      }
-      sleep(pollIntervalMs);
-    }
-  }
-
-  try {
-    return fn();
-  } finally {
-    try {
-      if (release) release();
-    } catch {
-      // best-effort
-    }
-    try {
-      rmSync(`${lockPath}.pid`, { force: true });
-    } catch {
-      // best-effort
-    }
-  }
+  return withFileLockSync(
+    lockPath,
+    fn,
+    {
+      ...opts,
+      errorFactory: (path, pid, retrySeconds, code) =>
+        new InstallLockBusyError(path, pid, retrySeconds, code),
+    },
+  );
 }

package/src/memory-file-ingest.ts

@@ -42,6 +42,7 @@ export function ingestMemoryFile(
 
   if (frontmatterMatch) {
     try {
+      // pattern-scanner-allow: yaml-parse — reason: parses YAML FRONTMATTER from markdown memory files (NOT massu.config.yaml). This is document metadata parsing, not application config access; getConfig() does not apply.
       const fm = parseYaml(frontmatterMatch[1]) as Record<string, unknown>;
       name = (fm.name as string) ?? basename;
       description = (fm.description as string) ?? '';

package/src/security/adapter-origin.ts

@@ -0,0 +1,130 @@
+/**
+ * Three-class adapter trust model (Plan 3c gap-47 + gap-48 + gap-50 deliverable).
+ *
+ * Every adapter that the loader is asked to load MUST classify into exactly
+ * ONE of the three classes below. The verifier dispatches per origin; an
+ * adapter that classifies into ZERO classes (or matches multiple) is REFUSED
+ * to load with a clear stderr message.
+ *
+ * The three classes:
+ *
+ * 1. CORE-BUNDLED — adapters that ship inside @massu/core itself at
+ *    packages/core/src/detect/adapters/*.ts. Trust derives from @massu/core's
+ *    own npm publish (provenance attestations) + the prepublish-check.sh
+ *    audit + the user's explicit `npm install @massu/core` choice. These
+ *    adapters do NOT appear in manifest.json (they have no package, no
+ *    separate version, no separate tarball). Loader skips signature
+ *    verification AND emits no warning — this is the trusted baseline.
+ *    Plan 3b shipped 4 (FastAPI, Django, tRPC, SwiftUI); Phase 7 ships 31
+ *    more (35 total).
+ *
+ * 2. REGISTRY-VERIFIED — third-party npm packages that EITHER match
+ *    `@massu/adapter-*` glob OR declare `"massu-adapter": true` in their
+ *    package.json. Trust derives from the manifest.json allowlist + per-
+ *    package sha256 + Ed25519 manifest signature. The 5 first-shipped
+ *    `@massu`-org packages (rails, phoenix, aspnet, spring, go-chi) live
+ *    in this class — being `@massu`-org-published does NOT exempt them
+ *    from manifest signing (gap-48 named-resolution).
+ *
+ * 3. LOCAL-EXPLICIT — TypeScript / JavaScript files listed by the user in
+ *    `massu.config.yaml > adapters.local`. Trust derives from the user's
+ *    explicit per-path entry + the postinstall-poisoning fingerprint check
+ *    (gap-32 / gap-58). Loader emits a one-time stderr note per startup
+ *    naming the loaded local path.
+ *
+ * Concretely, getAdapterOrigin() returns the union type below. Anything
+ * that doesn't match exactly one class is the unclassified branch — the
+ * verifier MUST refuse to load.
+ */
+
+export type AdapterOrigin = 'core-bundled' | 'registry-verified' | 'local-explicit';
+
+export interface AdapterDescriptor {
+  /**
+   * Stable identifier the loader uses to address this adapter. For
+   * CORE-BUNDLED: the filename without `.ts` (e.g. `python-fastapi`).
+   * For REGISTRY-VERIFIED: the npm package name (e.g. `@massu/adapter-rails`).
+   * For LOCAL-EXPLICIT: the POSIX-normalized path from `adapters.local`.
+   */
+  id: string;
+  origin: AdapterOrigin;
+  /**
+   * For REGISTRY-VERIFIED only: package version (semver). Undefined for
+   * CORE-BUNDLED (which inherits @massu/core's version) and LOCAL-EXPLICIT
+   * (which has no semver — local files don't publish).
+   */
+  version?: string;
+  /**
+   * For REGISTRY-VERIFIED only: absolute path to the package directory in
+   * node_modules (or wherever the discovery scan found it). Used to compute
+   * the load-time sha256 (gap-37 install-time + load-time verification).
+   * Undefined for CORE-BUNDLED (resolved inside the @massu/core bundle) and
+   * LOCAL-EXPLICIT (use the path from adapters.local directly).
+   */
+  packageDir?: string;
+}
+
+export interface AdapterOriginInput {
+  /** The id under inspection. */
+  id: string;
+  /**
+   * Set of adapter ids that ship CORE-BUNDLED in @massu/core itself. The
+   * loader produces this set via `import.meta.glob`-style scan of
+   * packages/core/src/detect/adapters/*.ts. Pass ['python-fastapi',
+   * 'python-django', 'nextjs-trpc', 'swift-swiftui'] today; Phase 7 grows
+   * this to 35 entries.
+   */
+  coreBundledIds: ReadonlySet<string>;
+  /**
+   * Optional: the npm package metadata (when id matches a discovered
+   * node_modules package). When present + `id` matches an `@massu/adapter-*`
+   * pattern OR `massuAdapter === true`, this is REGISTRY-VERIFIED.
+   */
+  npmPackage?: {
+    name: string;
+    version: string;
+    massuAdapter: boolean;
+  };
+  /**
+   * Optional: set of POSIX-normalized adapter paths from
+   * `getConfig().adapters?.local ?? []`. When present + id matches one of
+   * these entries, this is LOCAL-EXPLICIT.
+   */
+  configLocalPaths?: ReadonlySet<string>;
+}
+
+/**
+ * Classify an adapter id into exactly one of the three trust classes, or
+ * return null if the id does not match any class. Loader MUST refuse to
+ * load null-classified adapters.
+ *
+ * Multi-class collision (id matches more than one class) is an error
+ * condition — caller should treat it as null + emit a clear stderr note
+ * naming all the matching classes. This shouldn't happen in practice
+ * because CORE-BUNDLED ids are kebab-case framework names while REGISTRY-
+ * VERIFIED ids start with `@` (npm scope) and LOCAL-EXPLICIT ids are file
+ * paths — they don't intersect under normal config.
+ */
+export function getAdapterOrigin(input: AdapterOriginInput): AdapterOrigin | null {
+  const matches: AdapterOrigin[] = [];
+
+  if (input.coreBundledIds.has(input.id)) {
+    matches.push('core-bundled');
+  }
+
+  if (input.npmPackage) {
+    const isMassuOrgAdapter = /^@massu\/adapter-/.test(input.npmPackage.name);
+    const declaresMassuAdapter = input.npmPackage.massuAdapter === true;
+    if ((isMassuOrgAdapter || declaresMassuAdapter) && input.npmPackage.name === input.id) {
+      matches.push('registry-verified');
+    }
+  }
+
+  if (input.configLocalPaths && input.configLocalPaths.has(input.id)) {
+    matches.push('local-explicit');
+  }
+
+  // Exactly one match → that class. Zero or multiple → unclassified (refuse).
+  if (matches.length === 1) return matches[0]!;
+  return null;
+}

package/src/security/adapter-verifier.ts

@@ -0,0 +1,319 @@
+/**
+ * Adapter manifest signature + integrity verifier.
+ *
+ * Plan 3c Phase 5 deliverable (5F). The center of the supply-chain trust
+ * chain: every REGISTRY-VERIFIED adapter load (per the three-class trust
+ * model in adapter-origin.ts) goes through this module before the loader
+ * accepts it. Verification fails CLOSED — any failure path returns
+ * { ok: false, reason } and the loader refuses to load.
+ *
+ * Verification chain (all checks MUST pass):
+ *
+ * 1. Envelope shape passes EnvelopeSchema (manifest, manifest_b64,
+ *    signature, manifest_sha256, signed_at, signing_key_id all present
+ *    and well-typed).
+ * 2. base64-decode(envelope.manifest_b64) yields raw bytes B.
+ * 3. sha256(B) hex == envelope.manifest_sha256.
+ * 4. JSON.parse(B as utf-8) succeeds.
+ * 5. The parsed JSON deep-equals envelope.manifest (defense against
+ *    publisher swapping the manifest_b64 and manifest fields independently).
+ * 6. ManifestBodySchema accepts the parsed JSON.
+ * 7. nacl.sign.detached.verify(B, base64-decode(signature), publicKey)
+ *    returns true. publicKey is the bundled REGISTRY_PUBKEY_ED25519
+ *    (caller passes it; default is the bundle from registry-pubkey.generated.ts).
+ * 8. envelope.signing_key_id == sha256(publicKey hex). This is the
+ *    drift-detection mechanism for key rotation (Plan 3c gap-54): a
+ *    stale @massu/core that holds an old pubkey reading a manifest
+ *    signed by the new pubkey will see signing_key_id mismatch and
+ *    refuse — the cache is then marked STALE-DUE-TO-ROTATION (handled
+ *    by the cache module, not here).
+ * 9. manifest.manifest_schema_version >= MIN_KNOWN_SCHEMA_VERSION (else
+ *    REFUSE — a future v2 that drops fields v1 expects is incompatible).
+ *    > KNOWN_MAX_SCHEMA_VERSION → continue with warning (additive
+ *    forward-compat per gap-56).
+ *
+ * Why every step matters:
+ * - Step 3 catches manifest_b64 tampering (someone swapped the bytes
+ *   between the publisher's signing and the consumer's verify).
+ * - Step 5 catches publisher bugs that emit two non-equal views of
+ *   the same field (this is the canonicalization-gap class — the
+ *   publisher's self-check at registry-publish.sh enforces the same
+ *   invariant before deploy, but we re-check on the consumer side).
+ * - Step 7 is the actual signature verification.
+ * - Step 8 protects against attackers who know an old key — they can
+ *   sign a valid manifest under the old key, but signing_key_id will
+ *   mismatch the bundled pubkey and the loader refuses.
+ *
+ * Test fixtures sign against the real Phase D Ed25519 private key via
+ * `bash scripts/sign-fixture-manifest.sh` (operator-runs, reads from
+ * macOS Keychain) producing signed envelopes that round-trip the verifier
+ * end-to-end without needing the live registry.
+ */
+import { createHash } from 'node:crypto';
+import nacl from 'tweetnacl';
+import { z } from 'zod';
+import {
+  EnvelopeSchema,
+  ManifestBodySchema,
+  KNOWN_MAX_SCHEMA_VERSION,
+  MIN_KNOWN_SCHEMA_VERSION,
+  type Envelope,
+  type ManifestBody,
+} from './manifest-schema.js';
+import {
+  REGISTRY_PUBKEY_ED25519,
+  REGISTRY_PUBKEY_FINGERPRINT_HEX,
+  KNOWN_PUBKEY_FINGERPRINTS,
+} from './registry-pubkey.generated.js';
+
+/**
+ * CR-9 audit L2 fix: assert at module init that the bundled pubkey's
+ * fingerprint is in the historically-trusted allowlist. A bundled key
+ * that doesn't appear here would refuse to load — defense against a
+ * future build that swaps the pem to an unauthorized key without
+ * updating the allowlist (which would otherwise pass --check at build
+ * time only if KNOWN_PUBKEY_FINGERPRINTS was also tampered).
+ */
+if (!KNOWN_PUBKEY_FINGERPRINTS.has(REGISTRY_PUBKEY_FINGERPRINT_HEX)) {
+  throw new Error(
+    `@massu/core: bundled pubkey fingerprint ${REGISTRY_PUBKEY_FINGERPRINT_HEX.slice(0, 16)}... ` +
+    `is not in KNOWN_PUBKEY_FINGERPRINTS. This @massu/core build appears tampered. ` +
+    `Refusing to load.`,
+  );
+}
+
+export interface VerifyManifestInput {
+  /** Raw envelope JSON, parsed but not yet validated. */
+  envelope: unknown;
+  /**
+   * The bundled Ed25519 public key (32 raw bytes). Caller passes the
+   * bundled key from registry-pubkey.generated.ts. Test-only override
+   * to swap keys for fixture signing.
+   */
+  publicKey?: Uint8Array;
+}
+
+export type VerifyManifestResult =
+  | { ok: true; envelope: Envelope; manifest: ManifestBody; warnings: string[] }
+  | { ok: false; reason: string };
+
+/**
+ * Compute sha256 hex of raw bytes. Helper used at multiple verification
+ * steps; centralized to avoid drift between callsites.
+ */
+function sha256Hex(bytes: Uint8Array): string {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+/**
+ * JSON.parse reviver that strips prototype-pollution keys. CR-9 audit H2
+ * fix: a malicious-but-signed manifest could include `"__proto__":{...}`
+ * as an own enumerable key that the schema's `.passthrough()` would
+ * preserve into downstream consumers. Returning undefined from a reviver
+ * tells JSON.parse to omit that key entirely.
+ */
+function reviver(key: string, value: unknown): unknown {
+  if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+    return undefined;
+  }
+  return value;
+}
+
+/**
+ * Deep-equal check for the parsed JSON tree of envelope.manifest vs the
+ * JSON parsed from base64-decode(envelope.manifest_b64). Both inputs come
+ * from the same envelope so they MUST be deep-equal — any mismatch is a
+ * publisher bug or active tampering. Uses canonical JSON.stringify with
+ * sorted keys so the comparison ignores key-order differences.
+ */
+function jsonDeepEqualByCanonical(a: unknown, b: unknown): boolean {
+  const ca = canonicalJsonStringify(a);
+  const cb = canonicalJsonStringify(b);
+  return ca === cb;
+}
+
+function canonicalJsonStringify(value: unknown): string {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) {
+    return '[' + value.map(canonicalJsonStringify).join(',') + ']';
+  }
+  if (typeof value === 'object' && value !== undefined) {
+    const obj = value as Record<string, unknown>;
+    const keys = Object.keys(obj).sort();
+    return '{' + keys.map((k) => JSON.stringify(k) + ':' + canonicalJsonStringify(obj[k])).join(',') + '}';
+  }
+  return JSON.stringify(value);
+}
+
+/**
+ * Verify a registry adapter manifest envelope. See module-level doc for the
+ * full chain. Returns ok=true with parsed envelope+manifest+warnings on
+ * success, or ok=false with a specific reason on any failure.
+ *
+ * This function does NOT cache, NOT fetch, and NOT mutate any state. Pure
+ * verification of a given input. The caller (cache module + CLI) is
+ * responsible for cache I/O and refusing-to-load semantics.
+ */
+export function verifyManifest(input: VerifyManifestInput): VerifyManifestResult {
+  const publicKey = input.publicKey ?? REGISTRY_PUBKEY_ED25519;
+  const warnings: string[] = [];
+
+  // Step 1 — envelope shape
+  const envelopeParsed = EnvelopeSchema.safeParse(input.envelope);
+  if (!envelopeParsed.success) {
+    const issues = envelopeParsed.error.issues
+      .map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
+      .join('; ');
+    return { ok: false, reason: `envelope shape invalid: ${issues}` };
+  }
+  const envelope = envelopeParsed.data;
+
+  // Step 2 — base64-decode manifest_b64
+  let manifestBytes: Buffer;
+  try {
+    manifestBytes = Buffer.from(envelope.manifest_b64, 'base64');
+  } catch (err) {
+    return { ok: false, reason: `manifest_b64 base64 decode failed: ${err instanceof Error ? err.message : String(err)}` };
+  }
+  if (manifestBytes.length === 0) {
+    return { ok: false, reason: 'manifest_b64 decoded to zero bytes' };
+  }
+
+  // Step 3 — sha256 round-trip
+  const computedSha = sha256Hex(manifestBytes);
+  if (computedSha !== envelope.manifest_sha256) {
+    return {
+      ok: false,
+      reason:
+        `manifest_sha256 mismatch: computed ${computedSha}, envelope claims ${envelope.manifest_sha256}. ` +
+        `manifest_b64 was tampered with after signing.`,
+    };
+  }
+
+  // Step 4 — JSON.parse manifest_b64 bytes.
+  // CR-9 audit H2 fix: the JSON.parse reviver strips __proto__/constructor/
+  // prototype keys at parse time so they cannot be smuggled through the
+  // verifier into downstream consumers. Without this, a malicious-but-
+  // signed manifest could plant prototype-pollution-shaped values that
+  // .passthrough() preserves verbatim.
+  let manifestFromBytes: unknown;
+  try {
+    manifestFromBytes = JSON.parse(manifestBytes.toString('utf-8'), reviver);
+  } catch (err) {
+    return {
+      ok: false,
+      reason: `manifest_b64 does not decode to valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  // Step 6 — manifest body schema (run BEFORE step-5 deep-equal so both
+  // sides of the deep-equal comparison go through the same Zod defaults +
+  // transforms; otherwise an additive optional field with `.default()` on
+  // one side but not the other would cause spurious deep-equal failures).
+  // CR-9 audit M2 fix.
+  const manifestParsed = ManifestBodySchema.safeParse(manifestFromBytes);
+  if (!manifestParsed.success) {
+    const issues = manifestParsed.error.issues
+      .map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
+      .join('; ');
+    return { ok: false, reason: `manifest body shape invalid: ${issues}` };
+  }
+  const manifest = manifestParsed.data;
+
+  // Step 5 — deep-equal vs envelope.manifest. Compare AFTER both sides
+  // have been parsed by ManifestBodySchema so defaults are applied
+  // identically.
+  if (!jsonDeepEqualByCanonical(manifest, envelope.manifest)) {
+    return {
+      ok: false,
+      reason:
+        `manifest_b64 (decoded) does not deep-equal envelope.manifest field. ` +
+        `Publisher emitted inconsistent envelope — refusing to trust either view.`,
+    };
+  }
+
+  // Step 7 — Ed25519 signature verify
+  let signatureBytes: Buffer;
+  try {
+    signatureBytes = Buffer.from(envelope.signature, 'base64');
+  } catch (err) {
+    return { ok: false, reason: `signature base64 decode failed: ${err instanceof Error ? err.message : String(err)}` };
+  }
+  if (signatureBytes.length !== nacl.sign.signatureLength) {
+    return {
+      ok: false,
+      reason: `signature byte length ${signatureBytes.length} != expected ${nacl.sign.signatureLength}`,
+    };
+  }
+  if (publicKey.length !== nacl.sign.publicKeyLength) {
+    return {
+      ok: false,
+      reason: `publicKey byte length ${publicKey.length} != expected ${nacl.sign.publicKeyLength}`,
+    };
+  }
+  const sigOk = nacl.sign.detached.verify(
+    new Uint8Array(manifestBytes),
+    new Uint8Array(signatureBytes),
+    publicKey,
+  );
+  if (!sigOk) {
+    return {
+      ok: false,
+      reason: `Ed25519 signature verification failed against bundled public key ` +
+        `(fingerprint ${sha256Hex(publicKey).slice(0, 16)}...). ` +
+        `Manifest was either signed by a different key OR the signature is corrupt.`,
+    };
+  }
+
+  // Step 8 — signing_key_id matches sha256(publicKey)
+  const expectedKeyId = sha256Hex(publicKey);
+  if (envelope.signing_key_id !== expectedKeyId) {
+    return {
+      ok: false,
+      reason:
+        `signing_key_id mismatch: envelope claims ${envelope.signing_key_id}, ` +
+        `bundled pubkey sha256 is ${expectedKeyId}. ` +
+        `This indicates a key rotation; cache must refresh from the live registry, ` +
+        `or @massu/core must be upgraded to a version with the new bundled pubkey.`,
+    };
+  }
+
+  // Step 8b — every manifest entry's signing_key_id MUST equal the envelope's
+  // signing_key_id. CR-9 audit M3 fix: per-entry signing_key_id was parsed
+  // but never validated. v1 always uses the single registry key per
+  // SECURITY.md; a future federated v2 may countersign per-entry, in which
+  // case this check moves into a per-entry-key verification loop. Today,
+  // any divergence between entry.signing_key_id and envelope.signing_key_id
+  // indicates either a publisher bug or a mixed-signing-key attack.
+  for (const entry of manifest.adapters) {
+    if (entry.signing_key_id !== envelope.signing_key_id) {
+      return {
+        ok: false,
+        reason:
+          `manifest entry ${entry.package} has signing_key_id ${entry.signing_key_id} ` +
+          `which does not match envelope signing_key_id ${envelope.signing_key_id}. ` +
+          `v1 manifests use a single registry key for every entry; this divergence ` +
+          `indicates either a publisher bug or mixed-key attack — refusing.`,
+      };
+    }
+  }
+
+  // Step 9 — schema version compat
+  if (manifest.manifest_schema_version < MIN_KNOWN_SCHEMA_VERSION) {
+    return {
+      ok: false,
+      reason:
+        `manifest_schema_version ${manifest.manifest_schema_version} < MIN ${MIN_KNOWN_SCHEMA_VERSION}. ` +
+        `This @massu/core does not support reading this manifest; upgrade required.`,
+    };
+  }
+  if (manifest.manifest_schema_version > KNOWN_MAX_SCHEMA_VERSION) {
+    warnings.push(
+      `Adapter registry uses schema v${manifest.manifest_schema_version}, this @massu/core ` +
+      `supports up to v${KNOWN_MAX_SCHEMA_VERSION}. Some adapter metadata may be ignored. ` +
+      `Upgrade @massu/core to access new features.`,
+    );
+  }
+
+  return { ok: true, envelope, manifest, warnings };
+}