wyvrnpm 2.3.2 → 2.8.1

package/src/download.js

@@ -12,6 +12,7 @@ const { getProvider }           = require('./providers');
 const { evaluateCompat, pickBestCandidate, summarizeReasons } = require('./compat');
 const { buildFromSource }       = require('./build');
 const { uploadSourceBuiltArtefact } = require('./upload-built');
+const { assertAllSafeZipEntryNames } = require('./zip-safe');
 const log                       = require('./logger');
 
 // ---------------------------------------------------------------------------
@@ -59,17 +60,11 @@ async function tryDownloadFromSources(name, version, packageSources, platform, h
 //
 // PLAN-BUILD-MISSING phase 1: strict-by-default resolution.
 //
-// The v2 path is split in two:
-//
-//   tryV2Exact  — ONLY attempts the exact profile-hash match. Also returns
-//                 the versions index if the package exists in v2 (so the
-//                 caller can distinguish "v2 knows this package but not your
-//                 profile" from "v2 doesn't know this package at all").
-//
-//   tryV2Compat — the old OS+arch compatibility fallback. Now dead code on
-//                 the default path; only reachable via the escape-hatch env
-//                 var WYVRNPM_ALLOW_LOOSE_COMPAT=1 (deprecated — prints a
-//                 warning when used). Will be deleted in a future release.
+// tryV2Exact attempts the exact profile-hash match and, when it misses,
+// returns the versions index so the caller can distinguish "v2 knows this
+// package but not your profile" from "v2 doesn't know this package at all".
+// The declarative compat path (findCompatibleBuild) and the source-build
+// path consume that index.
 //
 
 /**
@@ -94,9 +89,43 @@ async function tryDownloadFromSources(name, version, packageSources, platform, h
  *   result?:            { contentSha256: string|null, gitSha: string|null, gitRepo: string|null, profileHash: string, source: string },
  *   indexFoundInSource: string|null,    // which source returned a versions index (null = none did)
  *   availableProfiles:  string[],       // profile hashes the registry HAS, for the error message
- *   versionsIndex?:     object,         // pre-fetched index, reusable by tryV2Compat
+ *   versionsIndex?:     object,         // pre-fetched index, reused by findCompatibleBuild + source-build
  * }>}
  */
+/**
+ * Locate a v2 versions.json index for (name, version) across the configured
+ * sources WITHOUT attempting to download the exact-match artefact. Used by
+ * the `--build=always` path (F9) where the registry index is needed purely
+ * to look up `gitRepo` / `gitSha` for source-build.
+ *
+ * Returns the same shape as tryV2Exact's miss case.
+ *
+ * @param {{ name: string, version: string }} dep
+ * @param {string[]} packageSources
+ * @param {object}   authOptions   { awsProfile?, token? }
+ */
+async function findV2Index(dep, packageSources, authOptions = {}) {
+  const { name, version } = dep;
+  const { awsProfile, token } = authOptions;
+
+  for (const source of packageSources) {
+    let provider;
+    try { provider = getProvider(source); } catch { continue; }
+
+    const idx = await provider.v2GetVersionsIndex({ source, name, awsProfile, token });
+    if (idx?.versions?.[version]?.profiles) {
+      return {
+        found:              false,
+        indexFoundInSource: source,
+        versionsIndex:      idx,
+        availableProfiles:  Object.keys(idx.versions[version].profiles),
+      };
+    }
+  }
+
+  return { found: false, indexFoundInSource: null, versionsIndex: null, availableProfiles: [] };
+}
+
 async function tryV2Exact(dep, packageSources, destZipPath, timeoutMs, authOptions = {}) {
   const { name, version, profileHash } = dep;
   const { awsProfile, token } = authOptions;
@@ -209,7 +238,7 @@ async function findCompatibleBuild({ name, version, consumerProfile, consumerOpt
          : packageProfile);
 
     const rawCompat = meta.compatibility ?? null;
-    const { compatible, reasons } = evaluateCompat(consumerFull, packageFull, rawCompat);
+    const { compatible, reasons } = evaluateCompat(consumerFull, packageFull, rawCompat, meta.kind);
     if (compatible) {
       candidates.push({ profileHash, packageProfile, reasons, buildEntry, meta });
     }
@@ -229,69 +258,20 @@ async function findCompatibleBuild({ name, version, consumerProfile, consumerOpt
   };
 }
 
-/**
- * LEGACY compat fallback — scan versions.json for a build with the same OS +
- * arch as the consumer's profile and use it. Reachable only via
- * WYVRNPM_ALLOW_LOOSE_COMPAT=1. Prints a deprecation warning whenever it
- * succeeds. Will be removed after one release cycle.
- *
- * @param {{ name: string, version: string, profile: import('./profile').WyvrnProfile }} dep
- * @param {object} versionsIndex     pre-fetched from tryV2Exact
- * @param {string} source            source URL that returned the index
- * @param {string} destZipPath
- * @param {number} timeoutMs
- * @param {object} authOptions
- * @returns {Promise<object|null>}   same shape as tryV2Exact.result, or null
- */
-async function tryV2Compat(dep, versionsIndex, source, destZipPath, timeoutMs, authOptions = {}) {
-  const { name, version, profile } = dep;
-  const { awsProfile, token } = authOptions;
-
-  let provider;
-  try { provider = getProvider(source); } catch { return null; }
-
-  const versionEntry = versionsIndex?.versions?.[version];
-  if (!versionEntry?.profiles) return null;
-
-  for (const [ph, buildEntry] of Object.entries(versionEntry.profiles)) {
-    const bp = buildEntry.buildSettings ?? buildEntry.profile;
-    if (!bp) continue;
-    if (bp.os   !== profile.os)   continue;
-    if (bp.arch !== profile.arch) continue;
-
-    log.warn(
-      `⚠  DEPRECATED loose-compat fallback (WYVRNPM_ALLOW_LOOSE_COMPAT=1):\n` +
-      `  ${name}@${version} — using build [${ph}] (${bp.compiler} ${bp['compiler.version']})\n` +
-      `  cppstd/runtime may differ from your profile. This fallback will be removed in the next release.`,
-    );
-    const ok = await provider.v2DownloadZip({ source, name, version, profileHash: ph, awsProfile, token }, destZipPath, timeoutMs);
-    if (ok) {
-      return {
-        contentSha256: buildEntry.contentSha256   ?? null,
-        gitSha:        versionEntry.source?.gitSha  ?? null,
-        gitRepo:       versionEntry.source?.gitRepo ?? null,
-        profileHash:   ph,
-        source,
-      };
-    }
-  }
-  return null;
-}
-
 /**
  * Build the structured error message shown when a package exists in the v2
  * registry but no build matches the consumer's profileHash.
  */
-function buildStrictMissMessage({ name, version, profileHash, availableProfiles, buildMode, loose }) {
+function buildStrictMissMessage({ name, version, profileHash, availableProfiles, buildMode }) {
   const lines = [
     `no v2 build of ${name}@${version} matches profile [${profileHash}]`,
     availableProfiles.length > 0
       ? `  Available builds on the registry: ${availableProfiles.map((p) => `[${p}]`).join(' ')}`
       : `  The registry lists no builds for this version.`,
   ];
-  if (buildMode === 'missing') {
+  if (buildMode === 'missing' || buildMode === 'always') {
     lines.push(
-      `  --build=missing source-build was attempted but did not produce a usable binary. ` +
+      `  --build=${buildMode} source-build was attempted but did not produce a usable binary. ` +
       `See the error above for details (missing git metadata, missing "build" section in source manifest, or compile failure).`,
     );
   } else {
@@ -299,11 +279,6 @@ function buildStrictMissMessage({ name, version, profileHash, availableProfiles,
       `  Fix: publish a build for your profile, switch to a compatible one, or rerun with --build=missing to source-build.`,
     );
   }
-  if (!loose) {
-    lines.push(
-      `  Escape hatch: WYVRNPM_ALLOW_LOOSE_COMPAT=1 (deprecated — accepts same OS+arch with possibly-different cppstd/runtime).`,
-    );
-  }
   return lines.join('\n');
 }
 
@@ -313,8 +288,17 @@ function buildStrictMissMessage({ name, version, profileHash, availableProfiles,
 
 async function extractZip(destZipPath, extractDir) {
   const zip = new StreamZip.async({ file: destZipPath });
-  await zip.extract(null, extractDir);
-  await zip.close();
+  try {
+    // Zip Slip defense-in-depth (EVALUATION.md S2): pre-scan entry names
+    // before handing them to node-stream-zip. Library is currently not
+    // known-vulnerable, but registry zips are the single most untrusted
+    // input on this path.
+    const entries = await zip.entries();
+    assertAllSafeZipEntryNames(Object.keys(entries), path.basename(destZipPath));
+    await zip.extract(null, extractDir);
+  } finally {
+    await zip.close();
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -328,12 +312,13 @@ async function extractZip(destZipPath, extractDir) {
  *   1. Exact profile-hash match from any configured v2 source → use it.
  *   2. Otherwise, if the package exists in v2 (versions.json returned an
  *      entry for this version) but nothing matches our profile:
- *        - Default: STRICT FAIL with a structured error. Does not fall back
- *          to v1 (that would silently accept a build with different settings).
- *        - `buildMode === 'missing'`: same strict fail for now; error hints
- *          at PLAN-BUILD-MISSING phase 3.
- *        - WYVRNPM_ALLOW_LOOSE_COMPAT=1 (deprecated escape hatch): try the
- *          old OS+arch compat fallback with a deprecation warning.
+ *        - Try declarative per-package compatibility (PLAN-BUILD-MISSING
+ *          phase 2); use the best compatible build if any.
+ *        - With `buildMode === 'missing'` and nothing compatible: clone the
+ *          source at gitRepo@gitSha and build it locally (phase 3).
+ *        - Otherwise: STRICT FAIL with a structured error. Does not fall
+ *          back to v1 (that would silently accept a build with different
+ *          settings).
  *   3. Otherwise (v2 doesn't know the package at all) → v1 legacy fallback.
  *
  * Legacy deps (plain `Map<name, version>`, no profile info) skip v2 entirely
@@ -362,15 +347,6 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
     uploadStats,
   } = options;
 
-  if (buildMode === 'always') {
-    throw new Error(
-      '--build=always is not implemented (requires PLAN-BUILD-MISSING phase 3). ' +
-      'Use --build=never (default) or --build=missing.',
-    );
-  }
-
-  const looseCompatAllowed = process.env.WYVRNPM_ALLOW_LOOSE_COMPAT === '1';
-
   if (!fs.existsSync(razerDir)) {
     fs.mkdirSync(razerDir, { recursive: true });
   }
@@ -385,6 +361,11 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
     const profileHash = isLegacyEntry ? null : (depInfoOrVersion.profileHash ?? null);
     const profile     = isLegacyEntry ? null : (depInfoOrVersion.profile     ?? null);
     const options     = isLegacyEntry ? null : (depInfoOrVersion.options     ?? null);
+    const pinnedSource = isLegacyEntry ? null : (depInfoOrVersion.pinnedSource ?? null);
+    // Per-dep source pin (EVALUATION.md S4). When set, restrict every
+    // lookup for this package to the pinned URL; no fan-out across
+    // configured sources.
+    const depSources = pinnedSource ? [pinnedSource.url] : packageSources;
 
     const extractDir  = path.join(razerDir, name);
     const versionFile = path.join(extractDir, '.wyvrn-version');
@@ -398,36 +379,43 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
       continue;
     }
 
-    // Skip if already at correct version + profile hash
+    // Skip if already at correct version + profile hash. `--build=always`
+    // (F9) bypasses this cache so the forced rebuild actually fires.
     if (fs.existsSync(extractDir)) {
-      const installedVersion = fs.existsSync(versionFile)
-        ? fs.readFileSync(versionFile, 'utf8').trim()
-        : null;
-      const installedMeta = fs.existsSync(metaFile)
-        ? JSON.parse(fs.readFileSync(metaFile, 'utf8'))
-        : null;
-
-      const sameVersion = installedVersion === version;
-      const sameProfile = !profileHash || installedMeta?.profileHash === profileHash;
-
-      if (sameVersion && sameProfile) {
-        log.info(`Already present: ${name}@${version}${profileHash ? ` [${installedMeta?.profileHash}]` : ''} — skipping`);
-        lockEntries.set(name, {
-          version,
-          profileHash:   installedMeta?.profileHash   ?? null,
-          contentSha256: installedMeta?.contentSha256 ?? null,
-          gitSha:        installedMeta?.gitSha        ?? null,
-          resolvedFrom:  installedMeta?.resolvedFrom  ?? 'cached',
-          ...(options ? { options } : {}),
-        });
-        continue;
-      }
-      if (!sameVersion) {
-        log.info(`Version changed: ${name} ${installedVersion} → ${version}, re-downloading`);
+      if (buildMode === 'always') {
+        log.info(`--build=always: removing existing ${name}@${version} to force source-build`);
+        fs.rmSync(extractDir, { recursive: true, force: true });
       } else {
-        log.info(`Profile changed for ${name}@${version}, re-downloading`);
+        const installedVersion = fs.existsSync(versionFile)
+          ? fs.readFileSync(versionFile, 'utf8').trim()
+          : null;
+        const installedMeta = fs.existsSync(metaFile)
+          ? JSON.parse(fs.readFileSync(metaFile, 'utf8'))
+          : null;
+
+        const sameVersion = installedVersion === version;
+        const sameProfile = !profileHash || installedMeta?.profileHash === profileHash;
+
+        if (sameVersion && sameProfile) {
+          log.info(`Already present: ${name}@${version}${profileHash ? ` [${installedMeta?.profileHash}]` : ''} — skipping`);
+          lockEntries.set(name, {
+            version,
+            profileHash:   installedMeta?.profileHash   ?? null,
+            contentSha256: installedMeta?.contentSha256 ?? null,
+            gitSha:        installedMeta?.gitSha        ?? null,
+            resolvedFrom:  installedMeta?.resolvedFrom  ?? 'cached',
+            ...(options      ? { options }                   : {}),
+            ...(pinnedSource ? { source: pinnedSource.name } : {}),
+          });
+          continue;
+        }
+        if (!sameVersion) {
+          log.info(`Version changed: ${name} ${installedVersion} → ${version}, re-downloading`);
+        } else {
+          log.info(`Profile changed for ${name}@${version}, re-downloading`);
+        }
+        fs.rmSync(extractDir, { recursive: true, force: true });
       }
-      fs.rmSync(extractDir, { recursive: true, force: true });
     }
 
     log.info(`Downloading: ${name}@${version}`);
@@ -439,26 +427,38 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
 
     // ── Try v2 exact ────────────────────────────────────────────────────────
     if (profileHash && profile) {
-      const v2 = await tryV2Exact(
-        { name, version, profileHash },
-        packageSources,
-        destZipPath,
-        timeoutMs,
-        { awsProfile, token },
-      );
+      // --build=always skips every registry-binary path (exact match, compat
+      // match) and goes straight to source-build. Fetch just the versions
+      // index so source-build can find gitRepo/gitSha. EVALUATION.md F9.
+      const v2 = (buildMode === 'always')
+        ? await findV2Index(
+            { name, version },
+            depSources,
+            { awsProfile, token },
+          )
+        : await tryV2Exact(
+            { name, version, profileHash },
+            depSources,
+            destZipPath,
+            timeoutMs,
+            { awsProfile, token },
+          );
 
       if (v2.found) {
         downloadResult = v2.result;
         resolvedFrom   = 'v2';
       } else if (v2.indexFoundInSource) {
-        // v2 knows this package but no exact profile match. Do NOT fall back
-        // to v1 — that would silently accept a binary with different build
-        // settings. Try declarative compatibility first (phase 2), then the
-        // deprecated env-var escape hatch, then fail strictly.
+        // v2 knows this package but no exact profile match (or --build=always
+        // forced the path here). Do NOT fall back to v1 — that would silently
+        // accept a binary with different build settings. Try declarative
+        // compatibility first (phase 2) unless always-mode, then source-build
+        // when --build=missing|always, then fail strictly.
         skipV1Fallback = true;
 
         // ── Phase 2: declarative per-package compatibility ─────────────────
-        const compatResult = await findCompatibleBuild({
+        // Skip under --build=always: the whole point of that flag is to
+        // produce a fresh source-build, not to accept a registry binary.
+        const compatResult = (buildMode === 'always') ? null : await findCompatibleBuild({
           name, version,
           consumerProfile:  profile,
           consumerOptions:  options,
@@ -490,8 +490,8 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
           }
         }
 
-        // ── Phase 3: source-build when `--build=missing` is active ─────────
-        if (!downloadResult && buildMode === 'missing') {
+        // ── Phase 3: source-build when `--build=missing` or `--build=always` ──
+        if (!downloadResult && (buildMode === 'missing' || buildMode === 'always')) {
           const sourceInfo = v2.versionsIndex?.versions?.[version]?.source;
           if (sourceInfo?.gitRepo && sourceInfo?.gitSha) {
             try {
@@ -531,33 +531,16 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
           }
         }
 
-        // ── Deprecated escape hatch: WYVRNPM_ALLOW_LOOSE_COMPAT=1 ──────────
-        if (!downloadResult && looseCompatAllowed) {
-          const compat = await tryV2Compat(
-            { name, version, profile },
-            v2.versionsIndex,
-            v2.indexFoundInSource,
-            destZipPath,
-            timeoutMs,
-            { awsProfile, token },
-          );
-          if (compat) {
-            downloadResult = compat;
-            resolvedFrom   = 'v2-compat-deprecated';
-          }
-        }
-
         if (!downloadResult) {
           log.error(buildStrictMissMessage({
             name, version, profileHash,
             availableProfiles: v2.availableProfiles,
             buildMode,
-            loose: looseCompatAllowed,
           }));
           lockEntries.set(name, {
             version,
             profileHash,
-            resolvedFrom: buildMode === 'missing' ? 'source-build-failed' : 'no-exact-match',
+            resolvedFrom: (buildMode === 'missing' || buildMode === 'always') ? 'source-build-failed' : 'no-exact-match',
             availableProfiles: v2.availableProfiles,
           });
           continue;
@@ -568,7 +551,7 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
 
     // ── Fall back to v1 ─────────────────────────────────────────────────────
     if (!downloadResult && !skipV1Fallback) {
-      const ok = await tryDownloadFromSources(name, version, packageSources, platform, httpClient, timeoutMs, destZipPath);
+      const ok = await tryDownloadFromSources(name, version, depSources, platform, httpClient, timeoutMs, destZipPath);
       if (!ok) {
         log.warn(`package ${name}@${version} was not found in any configured source`);
         lockEntries.set(name, { version, resolvedFrom: 'not-found' });
@@ -631,7 +614,12 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
         profileHash:   downloadResult?.profileHash   ?? null,
         contentSha256: downloadResult?.contentSha256 ?? null,
         gitSha:        downloadResult?.gitSha        ?? null,
-        ...(options ? { options } : {}),
+        ...(options      ? { options }                        : {}),
+        // S4: record the pinned source name on the lock entry so a
+        // reviewer reading wyvrn.lock can confirm the artefact came
+        // from the declared source. Absent on non-pinned deps so
+        // pre-S4 lockfiles remain byte-identical.
+        ...(pinnedSource ? { source: pinnedSource.name }      : {}),
       });
 
       // ── Upload freshly source-built artefact back to the registry ────────

package/src/logger.js

@@ -11,6 +11,32 @@
 
 const PREFIX = '[wyvrn]';
 
+// ── Sensitive-value redaction (EVALUATION.md S8) ──────────────────────────────
+// Defense-in-depth against a token leaking into logs or error traces. Nothing
+// in wyvrnpm deliberately logs tokens today, but callers sometimes paste full
+// commands + error output into bug reports, and some future error path might
+// stringify argv. Two narrow patterns cover every format we handle:
+//
+//   `--token <value>`                    — CLI leak
+//   `Authorization: Bearer <value>`      — HTTP header leak
+//   `Bearer <value>` (standalone)        — header fragment leak
+//
+// Redaction is a last-line mitigation — the primary fix is `--token-env` and
+// per-source `tokenEnv` so the literal value never lands in argv to begin with.
+const TOKEN_PATTERNS = [
+  [/(--token(?:-env)?[= ]+)\S+/g,                          '$1***'],
+  [/(Authorization\s*:\s*Bearer\s+)\S+/gi,                 '$1***'],
+  [/(\bBearer\s+)[A-Za-z0-9._\-+/=]{16,}/g,                '$1***'],
+];
+
+function redactSensitive(text) {
+  let out = String(text);
+  for (const [pattern, replacement] of TOKEN_PATTERNS) {
+    out = out.replace(pattern, replacement);
+  }
+  return out;
+}
+
 const ANSI = {
   reset:  '\x1b[0m',
   bold:   '\x1b[1m',
@@ -49,7 +75,9 @@ function paint(text, code, stream) {
 function emit(stream, consoleFn, coloredPrefix, message) {
   // Every line in a multi-line message gets the prefix — so multi-line errors
   // line up visually without the caller having to repeat `[wyvrn]` per line.
-  const out = String(message)
+  // Redaction runs before the prefix/colour is applied so patterns like
+  // `--token xyz` match regardless of how the caller formatted the line.
+  const out = redactSensitive(message)
     .split('\n')
     .map((line) => `${coloredPrefix} ${line}`)
     .join('\n');
@@ -91,4 +119,4 @@ function debug(message) {
   emit(process.stderr, console.error, `${p} ${tag}`, message);
 }
 
-module.exports = { info, warn, error, success, debug, setJsonMode, isJsonMode };
+module.exports = { info, warn, error, success, debug, setJsonMode, isJsonMode, redactSensitive };

package/src/manifest.js

@@ -3,6 +3,8 @@
 const fs = require('fs');
 const path = require('path');
 
+const { readRecipeConf } = require('./conf');
+
 /** Current manifest schema version emitted by v2 tooling. */
 const SCHEMA_VERSION = 2;
 
@@ -52,18 +54,21 @@ function defaultManifest(name) {
 
 /**
  * Normalise the raw `dependencies` field from a manifest into a consistent
- * `{ name → { version, settings, options } }` map, regardless of input format:
+ * `{ name → { version, settings, options, source? } }` map, regardless of
+ * input format:
  *
- *   • String value  : "1.0.0"                         → { version: "1.0.0", settings: {}, options: {} }
- *   • Object value  : { version, settings?, options? } → kept (missing keys default to {})
- *   • Array format  : [{ Name, Version }]              → converted (no settings/options)
+ *   • String value  : "1.0.0"                                 → { version: "1.0.0", settings: {}, options: {} }
+ *   • Object value  : { version, settings?, options?, source? } → kept (missing keys default to {})
+ *   • Array format  : [{ Name, Version }]                      → converted (no settings/options)
  *
  * `settings` merges on top of the active profile for this dep only.
  * `options` maps to the recipe's declared options; validated against
  * the recipe's `allowed` list at resolve time (see src/options.js).
+ * `source` (EVALUATION.md S4) pins the dep to a named install source
+ * (e.g. `"primary-s3"`); absent = fan out across all configured sources.
  *
  * @param {object|Array|undefined} rawDeps
- * @returns {Record<string, { version: string, settings: object, options: object }>}
+ * @returns {Record<string, { version: string, settings: object, options: object, source?: string }>}
  */
 function normalizeDependencies(rawDeps) {
   if (!rawDeps || typeof rawDeps !== 'object') return {};
@@ -83,11 +88,17 @@ function normalizeDependencies(rawDeps) {
     if (typeof value === 'string') {
       result[n] = { version: value, settings: {}, options: {} };
     } else if (value && typeof value === 'object') {
-      result[n] = {
+      const entry = {
         version:  value.version ?? value.Version ?? '',
         settings: value.settings ?? {},
         options:  value.options  ?? {},
       };
+      // Per-package source pin (S4). Only keep it if it's a non-empty
+      // string so {} / null / 0 don't silently pin to a nonsense value.
+      if (typeof value.source === 'string' && value.source.length > 0) {
+        entry.source = value.source;
+      }
+      result[n] = entry;
     }
   }
   return result;
@@ -106,11 +117,27 @@ function readManifest(manifestPath) {
     throw new Error(`Manifest not found: ${resolved}`);
   }
   const raw = fs.readFileSync(resolved, 'utf8');
+  let parsed;
   try {
-    return JSON.parse(raw);
+    parsed = JSON.parse(raw);
   } catch (err) {
     throw new Error(`Failed to parse manifest at ${resolved}: ${err.message}`);
   }
+
+  // Validate the `conf` block (PLAN-CONF.md phase 1.2). Only runs for
+  // local manifests — registry-side manifests fetched via resolve.js /
+  // download.js go through fetch().json() and deliberately skip this so
+  // a consumer with an older wyvrnpm doesn't fail on a publisher's
+  // forward-compatible conf keys.
+  if (parsed && typeof parsed === 'object' && parsed.conf !== undefined) {
+    try {
+      readRecipeConf(parsed);
+    } catch (err) {
+      throw new Error(`Invalid \`conf\` block in ${resolved}: ${err.message}`);
+    }
+  }
+
+  return parsed;
 }
 
 /**