chati-dev 4.5.16 → 4.5.27

package/src/installer-v2/catalog-client.js

@@ -1,9 +1,12 @@
-import { createPublicKey, verify as cryptoVerify } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { createPublicKey, randomUUID, verify as cryptoVerify } from 'node:crypto';
+import {
+  closeSync, constants, fstatSync, fsyncSync, linkSync, lstatSync,
+  mkdirSync, openSync, readFileSync, readSync, realpathSync, renameSync, unlinkSync, writeSync,
+} from 'node:fs';
+import { basename, dirname, join, parse, relative, resolve, sep } from 'node:path';
 import { isIP } from 'node:net';
 import { fileURLToPath } from 'node:url';
-import { canonicalSerialize, ContractError } from '@chati/core';
+import { canonicalize, canonicalSerialize, ContractError, sha256 } from '@chati/core';
 import { validateCapabilitySnapshot } from '@chati/provider-registry';
 
 const moduleDir = dirname(fileURLToPath(import.meta.url));
@@ -13,11 +16,406 @@ export const CATALOG_CACHE_PATH = '.chati/v2/cache/model-catalog.json';
 export const BUNDLED_CATALOG_PATH = join(moduleDir, 'model-catalog.json');
 export const BUNDLED_CATALOG_SIGNATURE_PATH = join(moduleDir, 'model-catalog.sig');
 const PUBLIC_KEY_PATH = join(moduleDir, '..', 'installer', 'signing-public-key.pem');
+const INSTALLATION_MAX_BYTES = 4 * 1024 * 1024;
+const CATALOG_CACHE_MAX_BYTES = 4 * 1024 * 1024;
+const INSTALLATION_STORAGE_SECURITY_TEST_HOOKS = Symbol.for('chati.installation-storage.security-test-hooks');
+
+function runInstallationStorageSecurityTestHook(name, details) {
+  const hook = globalThis[INSTALLATION_STORAGE_SECURITY_TEST_HOOKS]?.[name];
+  if (typeof hook === 'function') hook(details);
+}
 
 function catalogError(code, message, details = {}) {
   return new ContractError(code, message, details);
 }
 
+function sameIdentity(left, right) {
+  return left?.dev === right?.dev && left?.ino === right?.ino;
+}
+
+function sameSnapshot(left, right) {
+  return sameIdentity(left, right)
+    && left?.size === right?.size
+    && left?.mode === right?.mode
+    && left?.nlink === right?.nlink
+    && left?.mtimeNs === right?.mtimeNs
+    && left?.ctimeNs === right?.ctimeNs;
+}
+
+function descriptorDirectoryPath(descriptor) {
+  return process.platform === 'linux' ? `/proc/self/fd/${descriptor}` : null;
+}
+
+function linuxDescriptorAnchor(absolute) {
+  if (process.platform !== 'linux') return null;
+  const match = absolute.match(/^\/proc\/self\/fd\/([1-9][0-9]*)(?:\/(.*))?$/);
+  if (!match) return null;
+  const descriptor = Number(match[1]);
+  let stat;
+  try { stat = fstatSync(descriptor); }
+  catch { throw catalogError('UNSAFE_INSTALLATION_DIRECTORY', 'installation storage directory anchor is not open'); }
+  if (!stat.isDirectory()) {
+    throw catalogError('UNSAFE_INSTALLATION_DIRECTORY', 'installation storage directory anchor must be a real directory');
+  }
+  return Object.freeze({ descriptor, segments: (match[2] || '').split(sep).filter(Boolean) });
+}
+
+function linuxWorkingDirectoryAnchor(absolute) {
+  if (process.platform !== 'linux') return null;
+  let descriptor;
+  try {
+    descriptor = openSync('.', constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
+    const workingDirectory = realpathSync(`/proc/self/fd/${descriptor}`);
+    const remainder = relative(workingDirectory, absolute);
+    if (remainder === '..' || remainder.startsWith(`..${sep}`)) {
+      closeSync(descriptor);
+      return null;
+    }
+    return Object.freeze({ descriptor, segments: remainder.split(sep).filter(Boolean) });
+  } catch {
+    if (descriptor !== undefined) closeSync(descriptor);
+    return null;
+  }
+}
+
+function openPinnedInstallationDirectory(path, { create = false, allowDirectDirectoryFallback = false } = {}) {
+  const absolute = resolve(path);
+  const root = parse(absolute).root;
+  const descriptorAnchor = linuxDescriptorAnchor(absolute);
+  const workingDirectoryAnchor = descriptorAnchor ? null : linuxWorkingDirectoryAnchor(absolute);
+  const anchor = descriptorAnchor || workingDirectoryAnchor;
+  const segments = anchor ? anchor.segments : absolute.slice(root.length).split(sep).filter(Boolean);
+  if (process.platform === 'linux') {
+    let descriptor;
+    let directDirectoryFallback = false;
+    try {
+      if (anchor) {
+        descriptor = openSync(descriptorDirectoryPath(anchor.descriptor), constants.O_RDONLY | (constants.O_DIRECTORY || 0));
+      } else {
+        try {
+          descriptor = openSync(root, constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
+        } catch (error) {
+          // A strict sandbox may grant a pre-authorized external directory
+          // without granting the root descriptor needed for a normal
+          // component-by-component traversal. Keep this narrowly opt-in: the
+          // final directory remains O_NOFOLLOW-pinned, and malformed chains
+          // never take the fallback.
+          if (!allowDirectDirectoryFallback || error?.code !== 'EACCES') throw error;
+          descriptor = openSync(absolute, constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
+          directDirectoryFallback = true;
+        }
+      }
+    } finally {
+      if (workingDirectoryAnchor) closeSync(workingDirectoryAnchor.descriptor);
+    }
+    try {
+      for (const segment of directDirectoryFallback ? [] : segments) {
+        const parentPath = descriptorDirectoryPath(descriptor);
+        const childPath = join(parentPath, segment);
+        let childDescriptor;
+        try {
+          childDescriptor = openSync(childPath, constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
+        } catch (error) {
+          if (error?.code !== 'ENOENT' || !create) {
+            if (['ELOOP', 'ENOTDIR'].includes(error?.code)) {
+              throw catalogError('UNSAFE_INSTALLATION_DIRECTORY', 'installation storage directory chain must contain only real directories');
+            }
+            throw error;
+          }
+          try { mkdirSync(childPath, { mode: 0o700 }); }
+          catch (mkdirError) { if (mkdirError?.code !== 'EEXIST') throw mkdirError; }
+          childDescriptor = openSync(childPath, constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
+        }
+        const childStat = fstatSync(childDescriptor);
+        if (!childStat.isDirectory()) {
+          closeSync(childDescriptor);
+          throw catalogError('UNSAFE_INSTALLATION_DIRECTORY', 'installation storage directory chain must contain only real directories');
+        }
+        closeSync(descriptor);
+        descriptor = childDescriptor;
+      }
+      return Object.freeze({
+        absolute,
+        descriptor,
+        identity: fstatSync(descriptor),
+        reference: descriptorDirectoryPath(descriptor),
+      });
+    } catch (error) {
+      closeSync(descriptor);
+      throw error;
+    }
+  }
+  let current = root;
+  for (const segment of segments) {
+    current = resolve(current, segment);
+    let stat;
+    try { stat = lstatSync(current); }
+    catch (error) {
+      if (error?.code !== 'ENOENT' || !create) throw error;
+      try { mkdirSync(current, { mode: 0o700 }); }
+      catch (mkdirError) { if (mkdirError?.code !== 'EEXIST') throw mkdirError; }
+      stat = lstatSync(current);
+    }
+    if (stat.isSymbolicLink() || !stat.isDirectory()) throw catalogError('UNSAFE_INSTALLATION_DIRECTORY', 'installation storage directory chain must contain only real directories');
+  }
+  const descriptor = openSync(absolute, constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
+  return Object.freeze({ absolute, descriptor, identity: fstatSync(descriptor), reference: absolute });
+}
+
+function assertPinnedInstallationDirectory(directory) {
+  const current = fstatSync(directory.descriptor);
+  if (!current.isDirectory() || !sameIdentity(current, directory.identity)) {
+    throw catalogError('UNSAFE_INSTALLATION_DIRECTORY', 'installation storage directory descriptor changed');
+  }
+  if (directory.reference === directory.absolute) {
+    const pathStat = lstatSync(directory.absolute);
+    if (pathStat.isSymbolicLink() || !pathStat.isDirectory() || !sameIdentity(pathStat, directory.identity)) {
+      throw catalogError('UNSAFE_INSTALLATION_DIRECTORY', 'installation storage directory changed during the operation');
+    }
+  }
+}
+
+function installationEntryPath(directory, name) {
+  if (basename(name) !== name || name === '.' || name === '..') {
+    throw catalogError('UNSAFE_INSTALLATION_FILE', 'installation storage entry must be a single path segment');
+  }
+  return join(directory.reference, name);
+}
+
+function readSafeInstallationEntry(directory, name, {
+  allowMissing = false,
+  unsafeCode = 'UNSAFE_INSTALLATION_FILE',
+  sizeCode = 'INSTALLATION_ARTIFACT_SIZE_LIMIT',
+  label = 'installation artifact',
+  maxBytes = INSTALLATION_MAX_BYTES,
+  encoding = 'utf8',
+} = {}) {
+  let descriptor;
+  const path = installationEntryPath(directory, name);
+  try {
+    descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
+  } catch (error) {
+    if (allowMissing && error?.code === 'ENOENT') return null;
+    if (['ELOOP', 'ENXIO', 'EISDIR'].includes(error?.code)) {
+      throw catalogError(unsafeCode, `${label} must not be a symlink, FIFO or directory`);
+    }
+    throw error;
+  }
+  try {
+    const stat = fstatSync(descriptor, { bigint: true });
+    if (!stat.isFile() || stat.nlink !== 1n) {
+      throw catalogError(unsafeCode, `${label} must be a regular single-link file`);
+    }
+    if (stat.size > BigInt(maxBytes)) {
+      throw catalogError(sizeCode, `${label} exceeds the 4 MiB safety limit`);
+    }
+    runInstallationStorageSecurityTestHook('afterFileStat', { path, label, maxBytes });
+    const chunks = [];
+    let total = 0;
+    while (true) {
+      const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, maxBytes + 1 - total));
+      const bytesRead = readSync(descriptor, chunk, 0, chunk.length, null);
+      if (bytesRead === 0) break;
+      total += bytesRead;
+      if (total > maxBytes) throw catalogError(sizeCode, `${label} exceeds the 4 MiB safety limit`);
+      chunks.push(chunk.subarray(0, bytesRead));
+    }
+    const after = fstatSync(descriptor, { bigint: true });
+    if (!sameSnapshot(stat, after)) {
+      throw catalogError('INSTALLATION_STORAGE_CONFLICT', `${label} changed while it was being read`);
+    }
+    const bytes = Buffer.concat(chunks, total);
+    return { content: encoding === null ? bytes : bytes.toString(encoding), stat };
+  } finally { closeSync(descriptor); }
+}
+
+function readSafeInstallationFile(path, options = {}) {
+  let directory;
+  try {
+    directory = openPinnedInstallationDirectory(dirname(path), {
+      allowDirectDirectoryFallback: options.allowDirectDirectoryFallback === true,
+    });
+  }
+  catch (error) {
+    if (options.allowMissing && error?.code === 'ENOENT') return null;
+    throw error;
+  }
+  try { return readSafeInstallationEntry(directory, basename(path), options); }
+  finally { closeSync(directory.descriptor); }
+}
+
+function writeAll(descriptor, bytes) {
+  let offset = 0;
+  while (offset < bytes.length) offset += writeSync(descriptor, bytes, offset, bytes.length - offset);
+}
+
+function persistImmutableInstallationBackup(path, content, {
+  conflictCode = 'INSTALLATION_BACKUP_CONFLICT',
+  label = 'installation backup',
+  maxBytes = INSTALLATION_MAX_BYTES,
+} = {}) {
+  const bytes = Buffer.isBuffer(content) ? content : Buffer.from(content);
+  if (bytes.length > maxBytes) {
+    throw catalogError('INSTALLATION_ARTIFACT_SIZE_LIMIT', `${label} exceeds the 4 MiB safety limit`);
+  }
+  const directory = openPinnedInstallationDirectory(dirname(path), { create: true });
+  const name = basename(path);
+  const existing = readSafeInstallationEntry(directory, name, { allowMissing: true, encoding: null, label, maxBytes });
+  if (existing !== null) {
+    closeSync(directory.descriptor);
+    if (!existing.content.equals(bytes)) throw catalogError(conflictCode, `${label} exists with different material`);
+    return false;
+  }
+  const temporaryName = `${name}.${process.pid}.${randomUUID()}.tmp`;
+  const temporary = installationEntryPath(directory, temporaryName);
+  const destination = installationEntryPath(directory, name);
+  let temporaryDescriptor;
+  try {
+    temporaryDescriptor = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), 0o600);
+    writeAll(temporaryDescriptor, bytes);
+    fsyncSync(temporaryDescriptor);
+    closeSync(temporaryDescriptor);
+    temporaryDescriptor = undefined;
+    runInstallationStorageSecurityTestHook('beforeImmutableCommit', { path, directory: directory.absolute });
+    assertPinnedInstallationDirectory(directory);
+    try { linkSync(temporary, destination); }
+    catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      const raced = readSafeInstallationEntry(directory, name, { encoding: null, label, maxBytes });
+      if (!raced.content.equals(bytes)) throw catalogError(conflictCode, `${label} raced with different material`);
+      return false;
+    }
+    return true;
+  } finally {
+    if (temporaryDescriptor !== undefined) closeSync(temporaryDescriptor);
+    try { unlinkSync(temporary); } catch { /* preserve the primary result */ }
+    fsyncSync(directory.descriptor);
+    closeSync(directory.descriptor);
+  }
+}
+
+function replaceInstallationArtifact(path, content, source) {
+  const bytes = Buffer.from(content);
+  if (bytes.length > INSTALLATION_MAX_BYTES) {
+    throw catalogError('INSTALLATION_ARTIFACT_SIZE_LIMIT', 'upgraded installation artifact exceeds the 4 MiB safety limit');
+  }
+  const directory = openPinnedInstallationDirectory(dirname(path));
+  const name = basename(path);
+  const current = readSafeInstallationEntry(directory, name);
+  if (!sameIdentity(current.stat, source.stat) || current.content !== source.content) {
+    closeSync(directory.descriptor);
+    throw catalogError('INSTALLATION_STORAGE_CONFLICT', 'installation artifact changed before atomic upgrade');
+  }
+  const temporaryName = `${name}.${process.pid}.${randomUUID()}.tmp`;
+  const temporary = installationEntryPath(directory, temporaryName);
+  const destination = installationEntryPath(directory, name);
+  let temporaryDescriptor;
+  try {
+    temporaryDescriptor = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), 0o600);
+    writeAll(temporaryDescriptor, bytes);
+    fsyncSync(temporaryDescriptor);
+    closeSync(temporaryDescriptor);
+    temporaryDescriptor = undefined;
+    runInstallationStorageSecurityTestHook('beforeReplacementCommit', { path, directory: directory.absolute });
+    assertPinnedInstallationDirectory(directory);
+    const currentArtifact = readSafeInstallationEntry(directory, name);
+    if (!sameIdentity(currentArtifact.stat, source.stat) || currentArtifact.content !== source.content) {
+      throw catalogError('INSTALLATION_STORAGE_CONFLICT', 'installation storage changed during atomic upgrade');
+    }
+    renameSync(temporary, destination);
+    fsyncSync(directory.descriptor);
+  } finally {
+    if (temporaryDescriptor !== undefined) closeSync(temporaryDescriptor);
+    try { unlinkSync(temporary); } catch { /* preserve the primary result */ }
+    closeSync(directory.descriptor);
+  }
+}
+
+export function readSafeInstallationStorageFile(path, options = {}) {
+  return readSafeInstallationFile(path, options);
+}
+
+export function persistImmutableInstallationFile(path, content, options = {}) {
+  return persistImmutableInstallationBackup(path, content, options);
+}
+
+export function replaceInstallationStorageFile(path, content, source) {
+  return replaceInstallationArtifact(path, content, source);
+}
+
+export function readInstallationArtifactFile(projectDir, { allowMissing = true } = {}) {
+  const directory = resolve(projectDir, '.chati/v2');
+  return readSafeInstallationFile(join(directory, 'installation.json'), { allowMissing });
+}
+
+function readCatalogCacheFile(projectDir, { allowMissing = true } = {}) {
+  const directory = resolve(projectDir, '.chati/v2/cache');
+  return readSafeInstallationFile(join(directory, 'model-catalog.json'), {
+    allowMissing,
+    unsafeCode: 'UNSAFE_CATALOG_CACHE_FILE',
+    sizeCode: 'CATALOG_CACHE_SIZE_LIMIT',
+    label: 'catalog cache',
+    maxBytes: CATALOG_CACHE_MAX_BYTES,
+  });
+}
+
+function persistCatalogCache(projectDir, payload) {
+  const content = `${JSON.stringify(payload, null, 2)}\n`;
+  const bytes = Buffer.from(content);
+  if (bytes.length > CATALOG_CACHE_MAX_BYTES) {
+    throw catalogError('CATALOG_CACHE_SIZE_LIMIT', 'catalog cache exceeds the 4 MiB safety limit');
+  }
+  const path = resolve(projectDir, CATALOG_CACHE_PATH);
+  const directory = openPinnedInstallationDirectory(dirname(path), { create: true });
+  const name = basename(path);
+  const existing = readSafeInstallationEntry(directory, name, {
+    allowMissing: true,
+    unsafeCode: 'UNSAFE_CATALOG_CACHE_FILE',
+    sizeCode: 'CATALOG_CACHE_SIZE_LIMIT',
+    label: 'catalog cache',
+    maxBytes: CATALOG_CACHE_MAX_BYTES,
+  });
+  const temporaryName = `${name}.${process.pid}.${randomUUID()}.tmp`;
+  const temporary = installationEntryPath(directory, temporaryName);
+  const destination = installationEntryPath(directory, name);
+  let temporaryDescriptor;
+  try {
+    temporaryDescriptor = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), 0o600);
+    writeAll(temporaryDescriptor, bytes);
+    fsyncSync(temporaryDescriptor);
+    closeSync(temporaryDescriptor);
+    temporaryDescriptor = undefined;
+    runInstallationStorageSecurityTestHook('beforeCatalogCacheCommit', { path, directory: directory.absolute });
+    assertPinnedInstallationDirectory(directory);
+    if (existing !== null) {
+      const current = readSafeInstallationEntry(directory, name, {
+        unsafeCode: 'UNSAFE_CATALOG_CACHE_FILE', sizeCode: 'CATALOG_CACHE_SIZE_LIMIT',
+        label: 'catalog cache', maxBytes: CATALOG_CACHE_MAX_BYTES,
+      });
+      if (!sameSnapshot(current.stat, existing.stat) || current.content !== existing.content) {
+        throw catalogError('CATALOG_CACHE_STORAGE_CONFLICT', 'catalog cache changed during atomic replacement');
+      }
+    } else {
+      try {
+        readSafeInstallationEntry(directory, name, {
+          unsafeCode: 'UNSAFE_CATALOG_CACHE_FILE', sizeCode: 'CATALOG_CACHE_SIZE_LIMIT',
+          label: 'catalog cache', maxBytes: CATALOG_CACHE_MAX_BYTES,
+        });
+        throw catalogError('CATALOG_CACHE_STORAGE_CONFLICT', 'catalog cache appeared during atomic creation');
+      } catch (error) {
+        if (error?.code !== 'ENOENT') throw error;
+      }
+    }
+    renameSync(temporary, destination);
+    fsyncSync(directory.descriptor);
+  } finally {
+    if (temporaryDescriptor !== undefined) closeSync(temporaryDescriptor);
+    try { unlinkSync(temporary); } catch { /* preserve the primary result */ }
+    closeSync(directory.descriptor);
+  }
+  return CATALOG_CACHE_PATH;
+}
+
 function parseSignedPayload(value) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
     throw catalogError('INVALID_SIGNED_CATALOG', 'signed catalog payload must be an object');
@@ -39,12 +437,22 @@ export function assertCatalogUrl(value) {
   if (url.protocol !== 'https:' || url.username || url.password) throw catalogError('CATALOG_URL_INVALID', 'catalog URL must use HTTPS without embedded credentials');
   const hostname = url.hostname.toLowerCase().replace(/^\[|\]$/g, '');
   const ipKind = isIP(hostname);
-  const blockedIpv4 = ipKind === 4 && (/^10\./.test(hostname)
-    || /^127\./.test(hostname)
-    || /^169\.254\./.test(hostname)
-    || /^192\.168\./.test(hostname)
-    || /^172\.(1[6-9]|2\d|3[01])\./.test(hostname)
-    || /^0\./.test(hostname));
+  const mappedIpv4 = (() => {
+    const dotted = hostname.match(/^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/);
+    if (dotted) return dotted[1];
+    const hexadecimal = hostname.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+    if (!hexadecimal) return null;
+    const high = Number.parseInt(hexadecimal[1], 16);
+    const low = Number.parseInt(hexadecimal[2], 16);
+    return [high >>> 8, high & 0xff, low >>> 8, low & 0xff].join('.');
+  })();
+  const effectiveIpv4 = ipKind === 4 ? hostname : mappedIpv4;
+  const blockedIpv4 = effectiveIpv4 !== null && (/^10\./.test(effectiveIpv4)
+    || /^127\./.test(effectiveIpv4)
+    || /^169\.254\./.test(effectiveIpv4)
+    || /^192\.168\./.test(effectiveIpv4)
+    || /^172\.(1[6-9]|2\d|3[01])\./.test(effectiveIpv4)
+    || /^0\./.test(effectiveIpv4));
   const blockedIpv6 = ipKind === 6 && (hostname === '::1' || hostname === '::' || /^(fc|fd|fe8|fe9|fea|feb)/.test(hostname));
   if (hostname === 'localhost' || hostname.endsWith('.localhost') || blockedIpv4 || blockedIpv6) {
     throw catalogError('CATALOG_URL_FORBIDDEN', 'catalog URL may not target a loopback, link-local, or private host');
@@ -64,17 +472,117 @@ export function verifySignedCapabilityCatalog(payload, { clock = () => new Date(
   return validateCapabilitySnapshot(catalog, { clock });
 }
 
-function readSignedCatalogFile(path) {
-  return parseSignedPayload(JSON.parse(readFileSync(path, 'utf8')));
+const PROJECTED_MODEL_FIELDS = Object.freeze([
+  'provider_id', 'model_id', 'actions', 'adjudication_priority',
+  'highest_reasoning_configuration', 'routing_priority', 'tier', 'natural_role',
+]);
+
+function projectCatalogModel(model) {
+  return Object.fromEntries(PROJECTED_MODEL_FIELDS
+    .filter((field) => model[field] !== undefined)
+    .map((field) => [field, model[field]]));
 }
 
-function writeCache(projectDir, payload) {
-  const path = join(projectDir, CATALOG_CACHE_PATH);
-  mkdirSync(dirname(path), { recursive: true });
-  const temporary = `${path}.tmp-${process.pid}`;
-  writeFileSync(temporary, `${JSON.stringify(payload, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' });
-  renameSync(temporary, path);
-  return CATALOG_CACHE_PATH;
+/**
+ * Proves that a wizard projection still matches a catalog signed by CHATI.
+ * Runtime never trusts a locally recomputed installation digest as catalog
+ * authority. The signed source may be the project cache or bundled release.
+ */
+export function verifyInstallationCatalogProvenance(projectDir, snapshot, { clock = () => new Date(), publicKeyPem } = {}) {
+  if (!snapshot?.source_catalog_ref) {
+    throw catalogError('CATALOG_PROVENANCE_REQUIRED', 'installation model projection requires a signed source catalog reference');
+  }
+  const payloads = [];
+  const cache = projectDir ? readCatalogCacheFile(projectDir) : null;
+  if (cache !== null) {
+    try { payloads.push(parseSignedPayload(JSON.parse(cache.content))); } catch { /* invalid cache cannot establish provenance */ }
+  }
+  try { payloads.push(readBundledPayload()); } catch { /* invalid bundle cannot establish provenance */ }
+  for (const payload of payloads) {
+    let catalog;
+    try { catalog = verifySignedCapabilityCatalog(payload, { clock, publicKeyPem }); } catch { continue; }
+    if (catalog.snapshot_id !== snapshot.source_catalog_ref
+      || Date.parse(catalog.expires_at) !== Date.parse(snapshot.expires_at)) continue;
+    const valid = snapshot.models.every((selected) => {
+      const source = catalog.models.find((candidate) =>
+        candidate.provider_id === selected.provider_id && candidate.model_id === selected.model_id);
+      return source && canonicalSerialize(projectCatalogModel(source)) === canonicalSerialize(projectCatalogModel(selected));
+    });
+    if (valid) return true;
+  }
+  throw catalogError('CATALOG_PROVENANCE_INVALID', 'installation model projection does not match an available signed source catalog');
+}
+
+function availableSignedPayloads(projectDir) {
+  const payloads = [];
+  const cache = projectDir ? readCatalogCacheFile(projectDir) : null;
+  if (cache !== null) {
+    try { payloads.push(parseSignedPayload(JSON.parse(cache.content))); } catch { /* invalid cache is never authority */ }
+  }
+  try { payloads.push(readBundledPayload()); } catch { /* invalid bundle is never authority */ }
+  return payloads;
+}
+
+function projectionMatchesCatalog(snapshot, catalog) {
+  if (Date.parse(catalog.expires_at) !== Date.parse(snapshot.expires_at)) return false;
+  return snapshot.models.every((selected) => {
+    const source = catalog.models.find((candidate) =>
+      candidate.provider_id === selected.provider_id && candidate.model_id === selected.model_id);
+    if (!source) return false;
+    return Object.entries(projectCatalogModel(selected)).every(([field, value]) =>
+      canonicalSerialize(source[field]) === canonicalSerialize(value));
+  });
+}
+
+/**
+ * One-time compatibility repair for early v2 wizard artifacts that projected
+ * a signed catalog but omitted source_catalog_ref. It never infers models from
+ * vendor APIs: the exact projection must match an available signed CHATI
+ * catalog. Original bytes are preserved before the atomic replacement.
+ */
+export function backfillInstallationCatalogProvenance(projectDir, artifact, {
+  clock = () => new Date(), publicKeyPem, source = null,
+} = {}) {
+  if (artifact?.capability_snapshot?.source_catalog_ref) return Object.freeze(artifact);
+  if (!artifact || typeof artifact !== 'object' || Array.isArray(artifact)) {
+    throw catalogError('INVALID_INSTALLATION_ARTIFACT', 'legacy installation artifact must be an object');
+  }
+  const { digest: legacyDigest, installation_artifact_id, ...legacyCore } = artifact;
+  if (typeof legacyDigest !== 'string' || !/^[a-f0-9]{64}$/.test(legacyDigest)
+    || sha256(legacyCore) !== legacyDigest) {
+    throw catalogError('INSTALLATION_ARTIFACT_DRIFT', 'legacy installation artifact digest does not match its content');
+  }
+  const catalog = availableSignedPayloads(projectDir).map((payload) => {
+    try { return verifySignedCapabilityCatalog(payload, { clock, publicKeyPem }); } catch { return null; }
+  }).filter(Boolean).find((candidate) => projectionMatchesCatalog(artifact?.capability_snapshot ?? {}, candidate));
+  if (!catalog) {
+    throw catalogError(
+      'CATALOG_PROVENANCE_UPGRADE_REQUIRED',
+      'legacy v2 installation cannot be matched to a signed catalog; run the installer with --reconfigure',
+    );
+  }
+  const upgradedCore = canonicalize({
+    ...legacyCore,
+    capability_snapshot: { ...legacyCore.capability_snapshot, source_catalog_ref: catalog.snapshot_id },
+  });
+  const upgraded = canonicalize({
+    ...upgradedCore,
+    installation_artifact_id,
+    digest: sha256(upgradedCore),
+  });
+  const artifactPath = join(projectDir, '.chati/v2/installation.json');
+  const original = source ?? readInstallationArtifactFile(projectDir, { allowMissing: false });
+  let originalArtifact;
+  try { originalArtifact = JSON.parse(original.content); }
+  catch { throw catalogError('INVALID_INSTALLATION_ARTIFACT', 'legacy installation backup source is not valid JSON'); }
+  if (sha256(originalArtifact) !== sha256(artifact)) {
+    throw catalogError('INSTALLATION_STORAGE_CONFLICT', 'legacy installation changed before catalog provenance upgrade');
+  }
+  const backupDir = join(projectDir, '.chati/v2/backups', `catalog-provenance-${legacyDigest}`);
+  const backupPath = join(backupDir, 'installation.json');
+  persistImmutableInstallationBackup(backupPath, original.content);
+  replaceInstallationArtifact(artifactPath, `${canonicalSerialize(upgraded)}\n`, original);
+  return Object.freeze(upgraded);
 }
 
 function readBundledPayload() {
@@ -124,10 +632,10 @@ export async function resolveCapabilityCatalog({
   }
 
   if (projectDir) {
-    const cachePath = join(projectDir, CATALOG_CACHE_PATH);
-    if (existsSync(cachePath)) {
+    const cache = readCatalogCacheFile(projectDir);
+    if (cache !== null) {
       try {
-        const payload = readSignedCatalogFile(cachePath);
+        const payload = parseSignedPayload(JSON.parse(cache.content));
         const catalog = verifySignedCapabilityCatalog(payload, { clock, publicKeyPem });
         candidates.push({ source: 'cache', cache_path: CATALOG_CACHE_PATH, payload, catalog });
       } catch (error) {
@@ -154,7 +662,7 @@ export async function resolveCapabilityCatalog({
   );
   const selected = candidates[0];
   const cache_path = selected.source === 'remote' && projectDir
-    ? writeCache(projectDir, selected.payload)
+    ? persistCatalogCache(projectDir, selected.payload)
     : (selected.cache_path ?? null);
   return Object.freeze({
     source: selected.source,