chati-dev 4.5.16 → 4.5.27

package/src/installer-v2/index.js

@@ -6,10 +6,16 @@
  * are explicit through installV2 or authorized migrateV2. It never invokes a
  * provider CLI or reads credentials.
  */
-import { existsSync, mkdirSync, writeFileSync, renameSync, readFileSync, copyFileSync } from 'node:fs';
-import { dirname, join, relative, resolve, sep } from 'node:path';
+import { existsSync } from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
 import { canonicalize, canonicalSerialize, sha256, ContractError } from '@chati/core';
 import { validateInstallation } from '@chati/provider-registry';
+import {
+  persistImmutableInstallationFile, readSafeInstallationStorageFile,
+  replaceInstallationStorageFile, verifyInstallationCatalogProvenance,
+} from './catalog-client.js';
+import { authorizeInstallationArtifact } from './installation-authority.js';
+import { validateProviderExecutableBinding } from './provider-executable.js';
 
 export const INSTALLATION_SCHEMA_VERSION = 2;
 export const INSTALLATION_ARTIFACT_PATH = '.chati/v2/installation.json';
@@ -56,8 +62,9 @@ const INSTALLATION_KEYS = new Set([
 ]);
 const BINDING_KEYS = new Set([
   'provider_id', 'harness_id', 'allowed_models', 'allowed_reasoning_configurations',
+  'executable_path', 'executable_sha256', 'supporting_executables',
 ]);
-const SNAPSHOT_KEYS = new Set(['snapshot_id', 'expires_at', 'models']);
+const SNAPSHOT_KEYS = new Set(['snapshot_id', 'source_catalog_ref', 'expires_at', 'models']);
 const MODEL_KEYS = new Set([
   'provider_id', 'model_id', 'actions', 'adjudication_priority',
   'highest_reasoning_configuration', 'routing_priority', 'tier', 'natural_role',
@@ -97,7 +104,8 @@ function ensureRelativePath(path) {
   assertString(path, 'INVALID_MANAGED_PATH', 'managed path');
   const normalized = path.replaceAll('\\', '/');
   const root = normalized.split('/')[0];
-  if (normalized.startsWith('/') || normalized.split('/').includes('..')) {
+  if (normalized === '.' || normalized.startsWith('/') || normalized.includes('\0') || normalized.includes(':')
+    || normalized.split('/').some((segment) => !segment || segment === '.' || segment === '..')) {
     throw new ContractError('INVALID_MANAGED_PATH', 'managed path must remain inside the project');
   }
   if (['.claude', '.codex', '.grok'].includes(root)) {
@@ -109,6 +117,21 @@ function ensureRelativePath(path) {
   return normalized;
 }
 
+function validateInstallationExecutableBindings(installation) {
+  if (!Array.isArray(installation?.enabled_providers)) return;
+  for (const binding of installation.enabled_providers) {
+    assertExactKeys(binding, BINDING_KEYS, 'enabled provider binding');
+    const hasBindingMaterial = binding?.executable_path !== undefined
+      || binding?.executable_sha256 !== undefined
+      || binding?.supporting_executables !== undefined;
+    if (!hasBindingMaterial) continue;
+    validateProviderExecutableBinding(binding, {
+      harnessId: binding.harness_id,
+      requireCodexSupportingExecutable: binding.harness_id === 'codex',
+    });
+  }
+}
+
 function normalizeBrainReadCapability(capability) {
   if (capability === undefined || capability === null || capability === false) return { status: 'not-configured' };
   assertObject(capability, 'INVALID_BRAIN_CAPABILITY', 'brain_read_capability');
@@ -123,6 +146,7 @@ function artifactCore(input, createdAt) {
   assertObject(input.installation, 'INVALID_INSTALLATION', 'installation');
   assertObject(input.capability_snapshot, 'INVALID_CATALOG', 'capability_snapshot');
   assertString(input.project_id, 'INVALID_INSTALLATION', 'project_id');
+  validateInstallationExecutableBindings(input.installation);
   const installation = validateInstallation(input.installation, input.capability_snapshot, { clock: () => createdAt });
   const brain_read_capability = normalizeBrainReadCapability(input.brain_read_capability);
   const managed_paths = (input.managed_paths ?? [INSTALLATION_ARTIFACT_PATH]).map(ensureRelativePath);
@@ -135,6 +159,9 @@ function artifactCore(input, createdAt) {
     // This is a projection, not a catalog copy. Keep only attributes needed by
     // the installation contract and only models explicitly selected by a binding.
     snapshot_id: input.capability_snapshot.snapshot_id,
+    ...(input.capability_snapshot.source_catalog_ref !== undefined
+      ? { source_catalog_ref: input.capability_snapshot.source_catalog_ref }
+      : {}),
     expires_at: input.capability_snapshot.expires_at,
     models: input.capability_snapshot.models
       .filter((model) => selectedModelKeys.has(`${model.provider_id}:${model.model_id}`))
@@ -185,6 +212,11 @@ export function doctorV2(artifact, { clock = () => new Date() } = {}) {
     assertString(installation_artifact_id, 'INVALID_ARTIFACT', 'installation_artifact_id');
     if (sha256(core) !== digest) throw new ContractError('INSTALLATION_ARTIFACT_DRIFT', 'installation artifact digest does not match its content');
     validateInstallation(artifact.installation, artifact.capability_snapshot, { clock: () => readClock(clock) });
+    validateInstallationExecutableBindings(artifact.installation);
+    if (artifact.capability_snapshot.snapshot_id.startsWith('wizard-catalog-')
+      && !artifact.capability_snapshot.source_catalog_ref) {
+      throw new ContractError('MISSING_CATALOG_PROVENANCE', 'wizard installation artifact must retain its signed source catalog reference');
+    }
     normalizeBrainReadCapability(artifact.brain_read_capability);
     if (!Array.isArray(artifact.managed_paths) || !artifact.managed_paths.every((path) => ensureRelativePath(path))) {
       throw new ContractError('INVALID_MANAGED_PATH', 'managed_paths must be valid project-relative paths');
@@ -251,6 +283,10 @@ export function dryRunV2(input, { projectDir, clock = () => new Date(), exists =
   assertString(projectDir, 'INVALID_PROJECT_DIR', 'projectDir');
   const artifact = createInstallationArtifact(input, { clock });
   const doctor = doctorV2(artifact, { clock });
+  if (!doctor.passed) {
+    const failure = doctor.checks.find((check) => check.status === 'fail') || {};
+    throw new ContractError(failure.code || 'INVALID_INSTALLATION_ARTIFACT', failure.message || 'installation artifact failed doctor');
+  }
   const detector = detectV1Installation(projectDir, { exists });
   const backup_plan = createBackupPlan(projectDir, detector, artifact);
   const rollback_plan = createRollbackPlan(artifact, backup_plan);
@@ -264,21 +300,34 @@ export function dryRunV2(input, { projectDir, clock = () => new Date(), exists =
 }
 
 /** Explicit v2 installation. It writes only the provider-neutral artifact path. */
-export function installV2(input, { projectDir, clock = () => new Date(), exists = existsSync } = {}) {
+export function installV2(input, {
+  projectDir, clock = () => new Date(), exists = existsSync, authorityDirectory,
+} = {}) {
   const report = dryRunV2(input, { projectDir, clock, exists });
+  verifyInstallationCatalogProvenance(projectDir, report.artifact.capability_snapshot, { clock });
   const artifactPath = join(projectDir, INSTALLATION_ARTIFACT_PATH);
-  const directory = join(projectDir, '.chati', 'v2');
-  mkdirSync(directory, { recursive: true });
   const serialized = `${canonicalSerialize(report.artifact)}\n`;
-  if (existsSync(artifactPath)) {
-    const existing = readFileSync(artifactPath, 'utf8');
-    if (existing === serialized) return Object.freeze(canonicalize({ ...report, mode: 'installed', writes_performed: false, artifact_path: INSTALLATION_ARTIFACT_PATH }));
+  const existing = readSafeInstallationStorageFile(artifactPath, { allowMissing: true });
+  if (existing !== null) {
+    if (existing.content === serialized) {
+      const authority = authorizeInstallationArtifact(projectDir, report.artifact, { authorityDirectory });
+      return Object.freeze(canonicalize({
+        ...report, mode: 'installed', writes_performed: false,
+        artifact_path: INSTALLATION_ARTIFACT_PATH,
+        authority_receipt_path: authority.receipt_path,
+      }));
+    }
     throw new ContractError('INSTALLATION_ARTIFACT_EXISTS', 'existing v2 artifact differs; use an explicit migration or rollback flow');
   }
-  const temporary = `${artifactPath}.tmp-${process.pid}`;
-  writeFileSync(temporary, serialized, { encoding: 'utf8', flag: 'wx' });
-  renameSync(temporary, artifactPath);
-  return Object.freeze(canonicalize({ ...report, mode: 'installed', writes_performed: true, artifact_path: INSTALLATION_ARTIFACT_PATH }));
+  const authority = authorizeInstallationArtifact(projectDir, report.artifact, { authorityDirectory });
+  persistImmutableInstallationFile(artifactPath, serialized, {
+    conflictCode: 'INSTALLATION_ARTIFACT_EXISTS', label: 'installation artifact',
+  });
+  return Object.freeze(canonicalize({
+    ...report, mode: 'installed', writes_performed: true,
+    artifact_path: INSTALLATION_ARTIFACT_PATH,
+    authority_receipt_path: authority.receipt_path,
+  }));
 }
 
 /**
@@ -286,13 +335,16 @@ export function installV2(input, { projectDir, clock = () => new Date(), exists
  * bytes in the project-local backup store. Provider-specific files are never
  * read or rewritten by this operation.
  */
-export function reconfigureV2(input, { projectDir, clock = () => new Date(), exists = existsSync } = {}) {
+export function reconfigureV2(input, {
+  projectDir, clock = () => new Date(), exists = existsSync, authorityDirectory,
+} = {}) {
   const report = dryRunV2(input, { projectDir, clock, exists });
+  verifyInstallationCatalogProvenance(projectDir, report.artifact.capability_snapshot, { clock });
   const artifactPath = join(projectDir, INSTALLATION_ARTIFACT_PATH);
-  if (!existsSync(artifactPath)) return installV2(input, { projectDir, clock, exists });
-  const existing = readFileSync(artifactPath, 'utf8');
+  const existing = readSafeInstallationStorageFile(artifactPath, { allowMissing: true });
+  if (existing === null) return installV2(input, { projectDir, clock, exists, authorityDirectory });
   let existingArtifact;
-  try { existingArtifact = JSON.parse(existing); } catch (error) {
+  try { existingArtifact = JSON.parse(existing.content); } catch (error) {
     throw new ContractError('EXISTING_INSTALLATION_CORRUPT', `existing v2 artifact is not valid JSON: ${error.message}`);
   }
   if (existingArtifact?.schema_version !== INSTALLATION_SCHEMA_VERSION || existingArtifact?.artifact_type !== 'chati-installation') {
@@ -300,20 +352,18 @@ export function reconfigureV2(input, { projectDir, clock = () => new Date(), exi
   }
   const backupId = `reconfigure-${sha256({ previous: existingArtifact.digest, next: report.artifact.digest }).slice(0, 20)}`;
   const backupPath = join(projectDir, '.chati', 'v2', 'backups', backupId, 'installation.json');
-  mkdirSync(dirname(backupPath), { recursive: true });
-  if (existsSync(backupPath) && readFileSync(backupPath, 'utf8') !== existing) {
-    throw new ContractError('RECONFIGURE_BACKUP_CONFLICT', 'reconfiguration backup path contains different material');
-  }
-  if (!existsSync(backupPath)) writeFileSync(backupPath, existing, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+  persistImmutableInstallationFile(backupPath, existing.content, {
+    conflictCode: 'RECONFIGURE_BACKUP_CONFLICT', label: 'reconfiguration backup',
+  });
+  const authority = authorizeInstallationArtifact(projectDir, report.artifact, { authorityDirectory });
   const serialized = `${canonicalSerialize(report.artifact)}\n`;
-  const temporary = `${artifactPath}.tmp-${process.pid}`;
-  writeFileSync(temporary, serialized, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
-  renameSync(temporary, artifactPath);
+  replaceInstallationStorageFile(artifactPath, serialized, existing);
   return Object.freeze(canonicalize({
     ...report,
     mode: 'reconfigured',
     writes_performed: true,
     artifact_path: INSTALLATION_ARTIFACT_PATH,
+    authority_receipt_path: authority.receipt_path,
     backup_path: relative(projectDir, backupPath).replaceAll('\\', '/'),
     provider_specific_files_rewritten: false,
   }));
@@ -324,16 +374,19 @@ export function reconfigureV2(input, { projectDir, clock = () => new Date(), exi
  * legacy markers, writes the provider-neutral artifact, and never rewrites a
  * provider-specific configuration file.
  */
-export function migrateV2(input, { projectDir, authorize = false, clock = () => new Date(), exists = existsSync } = {}) {
+export function migrateV2(input, {
+  projectDir, authorize = false, clock = () => new Date(), exists = existsSync, authorityDirectory,
+} = {}) {
   const preview = dryRunV2(input, { projectDir, clock, exists });
   if (authorize !== true) {
     return Object.freeze(canonicalize({ ...preview, mode: 'migration-preview', writes_performed: false, requires_explicit_authorization: true }));
   }
 
   const artifactPath = join(projectDir, INSTALLATION_ARTIFACT_PATH);
-  if (existsSync(artifactPath)) {
+  const existingArtifact = readSafeInstallationStorageFile(artifactPath, { allowMissing: true });
+  if (existingArtifact !== null) {
     const expected = `${canonicalSerialize(preview.artifact)}\n`;
-    if (readFileSync(artifactPath, 'utf8') !== expected) {
+    if (existingArtifact.content !== expected) {
       throw new ContractError('INSTALLATION_ARTIFACT_EXISTS', 'existing v2 artifact differs; use an explicit rollback flow');
     }
   }
@@ -342,18 +395,22 @@ export function migrateV2(input, { projectDir, authorize = false, clock = () =>
   for (const entry of preview.backup_plan.entries) {
     const source = join(projectDir, entry.source_path);
     const destination = join(projectDir, entry.backup_path);
-    if (!existsSync(source) || existsSync(destination)) continue;
-    mkdirSync(dirname(destination), { recursive: true });
-    copyFileSync(source, destination, 0);
-    backed_up.push(entry);
+    const sourceFile = readSafeInstallationStorageFile(source, {
+      allowMissing: true, encoding: null, label: 'legacy migration source',
+    });
+    if (sourceFile === null) continue;
+    if (persistImmutableInstallationFile(destination, sourceFile.content, {
+      conflictCode: 'MIGRATION_BACKUP_CONFLICT', label: 'legacy migration backup',
+    })) backed_up.push(entry);
   }
-  const installed = installV2(input, { projectDir, clock, exists });
+  const installed = installV2(input, { projectDir, clock, exists, authorityDirectory });
   return Object.freeze(canonicalize({
     ...preview,
     mode: 'migrated',
     writes_performed: installed.writes_performed || backed_up.length > 0,
     backed_up,
     artifact_path: installed.artifact_path,
+    authority_receipt_path: installed.authority_receipt_path,
     provider_specific_files_rewritten: false,
   }));
 }

package/src/installer-v2/installation-authority.js

@@ -0,0 +1,327 @@
+import {
+  createHash, createPrivateKey, createPublicKey, generateKeyPairSync,
+  sign as cryptoSign, verify as cryptoVerify,
+} from 'node:crypto';
+import { userInfo } from 'node:os';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { lstatSync, realpathSync } from 'node:fs';
+import { canonicalSerialize, ContractError } from '@chati/core';
+import {
+  persistImmutableInstallationFile, readSafeInstallationStorageFile,
+} from './catalog-client.js';
+
+export const INSTALLATION_AUTHORITY_RECEIPT_VERSION = 1;
+export const INSTALLATION_AUTHORITY_RECEIPT_TYPE = 'chati-installation-authority';
+export const INSTALLATION_AUTHORITY_DIRECTORY = '.chati/v2/authorities';
+
+const PRIVATE_KEY_FILENAME = 'installation-ed25519-private.pem';
+const PUBLIC_KEY_FILENAME = 'installation-ed25519-public.pem';
+const RECEIPT_KEYS = new Set([
+  'schema_version', 'receipt_type', 'authority_id', 'project_binding',
+  'installation_artifact_id', 'installation_digest', 'artifact_created_at',
+  'issued_at', 'signature',
+]);
+const PROJECT_BINDING_KEYS = new Set(['project_id', 'realpath_sha256', 'device', 'inode']);
+
+function fail(code, message, details = {}) {
+  throw new ContractError(code, message, details);
+}
+
+function exactKeys(value, expected, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    fail('INVALID_INSTALLATION_AUTHORITY_RECEIPT', `${label} must be an object`);
+  }
+  const actual = Object.keys(value);
+  if (actual.length !== expected.size || actual.some((key) => !expected.has(key))) {
+    fail('INVALID_INSTALLATION_AUTHORITY_RECEIPT', `${label} has an invalid closed schema`);
+  }
+}
+
+function authorityRoot(authorityDirectory) {
+  // Never derive a trust anchor from caller-controlled HOME. userInfo() is
+  // backed by the operating-system account database on supported hosts.
+  return resolve(authorityDirectory || join(userInfo().homedir, '.chati-dev', 'authority'));
+}
+
+export function installationAuthorityPublicKeyPath(authorityDirectory) {
+  const privateRoot = authorityRoot(authorityDirectory);
+  return join(dirname(privateRoot), `${basename(privateRoot)}-public`, PUBLIC_KEY_FILENAME);
+}
+
+function legacyInstallationAuthorityPublicKeyPath(authorityDirectory) {
+  return join(authorityRoot(authorityDirectory), PUBLIC_KEY_FILENAME);
+}
+
+function keyFingerprint(publicKey) {
+  const der = publicKey.export({ type: 'spki', format: 'der' });
+  return createHash('sha256').update(der).digest('hex');
+}
+
+function assertPrivateKeyPermissions(source) {
+  if (process.platform === 'win32') return;
+  const mode = Number(source.stat.mode & 0o777n);
+  if ((mode & 0o077) !== 0) fail('UNSAFE_INSTALLATION_AUTHORITY_KEY', 'installation authority private key must not be accessible by group or others');
+  if (typeof process.geteuid === 'function' && source.stat.uid !== BigInt(process.geteuid())) {
+    fail('UNSAFE_INSTALLATION_AUTHORITY_KEY', 'installation authority private key must be owned by the current user');
+  }
+}
+
+function readOrCreateAuthorityKeyPair(authorityDirectory) {
+  const root = authorityRoot(authorityDirectory);
+  const privatePath = join(root, PRIVATE_KEY_FILENAME);
+  const publicPath = installationAuthorityPublicKeyPath(authorityDirectory);
+  let privateSource = readSafeInstallationStorageFile(privatePath, {
+    allowMissing: true, label: 'installation authority private key', encoding: 'utf8', maxBytes: 64 * 1024,
+  });
+  if (privateSource === null) {
+    const generated = generateKeyPairSync('ed25519', {
+      privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+      publicKeyEncoding: { type: 'spki', format: 'pem' },
+    });
+    try {
+      persistImmutableInstallationFile(privatePath, generated.privateKey, {
+        conflictCode: 'INSTALLATION_AUTHORITY_KEY_CONFLICT',
+        label: 'installation authority private key', maxBytes: 64 * 1024,
+      });
+    } catch (error) {
+      if (error?.code !== 'INSTALLATION_AUTHORITY_KEY_CONFLICT') throw error;
+    }
+    privateSource = readSafeInstallationStorageFile(privatePath, {
+      label: 'installation authority private key', encoding: 'utf8', maxBytes: 64 * 1024,
+    });
+  }
+  assertPrivateKeyPermissions(privateSource);
+
+  let privateKey;
+  let publicKey;
+  try {
+    privateKey = createPrivateKey(privateSource.content);
+    publicKey = createPublicKey(privateKey);
+  } catch {
+    fail('INVALID_INSTALLATION_AUTHORITY_KEY', 'installation authority private key is invalid');
+  }
+  if (privateKey.asymmetricKeyType !== 'ed25519') {
+    fail('INVALID_INSTALLATION_AUTHORITY_KEY', 'installation authority key must be Ed25519');
+  }
+  const publicPem = publicKey.export({ type: 'spki', format: 'pem' });
+  const existingPublic = readSafeInstallationStorageFile(publicPath, {
+    allowMissing: true, label: 'installation authority public key', encoding: 'utf8', maxBytes: 64 * 1024,
+  });
+  if (existingPublic === null) {
+    persistImmutableInstallationFile(publicPath, publicPem, {
+      conflictCode: 'INSTALLATION_AUTHORITY_KEY_CONFLICT',
+      label: 'installation authority public key', maxBytes: 64 * 1024,
+    });
+  } else {
+    let storedPublic;
+    try { storedPublic = createPublicKey(existingPublic.content); }
+    catch { fail('INVALID_INSTALLATION_AUTHORITY_KEY', 'installation authority public key is invalid'); }
+    if (keyFingerprint(storedPublic) !== keyFingerprint(publicKey)) {
+      fail('INSTALLATION_AUTHORITY_KEY_CONFLICT', 'installation authority public key does not match its private key');
+    }
+  }
+  return Object.freeze({ privateKey, publicKey, authority_id: `host-ed25519-${keyFingerprint(publicKey)}` });
+}
+
+function readAuthorityPublicKey(authorityDirectory) {
+  const locations = [
+    {
+      path: installationAuthorityPublicKeyPath(authorityDirectory),
+      allowDirectDirectoryFallback: true,
+    },
+    // Installations created before the public-only authority directory keep
+    // their verification key beside the private key. This fallback is never
+    // granted the strict-runtime directory escape used by the public path.
+    {
+      path: legacyInstallationAuthorityPublicKeyPath(authorityDirectory),
+      allowDirectDirectoryFallback: false,
+    },
+  ];
+  let source = null;
+  for (const location of locations) {
+    try {
+      source = readSafeInstallationStorageFile(location.path, {
+        label: 'installation authority public key', encoding: 'utf8', maxBytes: 64 * 1024,
+        allowDirectDirectoryFallback: location.allowDirectDirectoryFallback,
+      });
+      break;
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+    }
+  }
+  if (source === null) fail('INSTALLATION_AUTHORITY_REQUIRED', 'installation authority public key is missing on this host');
+  let publicKey;
+  try { publicKey = createPublicKey(source.content); }
+  catch { fail('INVALID_INSTALLATION_AUTHORITY_KEY', 'installation authority public key is invalid'); }
+  if (publicKey.type !== 'public' || publicKey.asymmetricKeyType !== 'ed25519') {
+    fail('INVALID_INSTALLATION_AUTHORITY_KEY', 'installation authority public key must be Ed25519');
+  }
+  return Object.freeze({ publicKey, authority_id: `host-ed25519-${keyFingerprint(publicKey)}` });
+}
+
+function projectBinding(projectDir, projectId) {
+  const physical = realpathSync(resolve(projectDir));
+  const stat = lstatSync(physical, { bigint: true });
+  if (!stat.isDirectory()) fail('INVALID_INSTALLATION_PROJECT', 'installation authority requires a real project directory');
+  return Object.freeze({
+    project_id: projectId,
+    realpath_sha256: createHash('sha256').update(physical).digest('hex'),
+    device: String(stat.dev),
+    inode: String(stat.ino),
+  });
+}
+
+/**
+ * Return the host-stable, non-secret identity of a real project directory.
+ *
+ * This is intentionally narrower than an installation receipt binding: a
+ * short-lived runtime receipt has no installation artifact or project id to
+ * carry, but it must still be unusable if copied to a different project.
+ */
+export function installationAuthorityProjectScope(projectDir) {
+  const binding = projectBinding(projectDir, 'runtime-script-receipt');
+  return Object.freeze({
+    realpath_sha256: binding.realpath_sha256,
+    device: binding.device,
+    inode: binding.inode,
+  });
+}
+
+function receiptPath(projectDir, artifact) {
+  if (!/^[a-f0-9]{64}$/.test(artifact?.digest || '')) {
+    fail('INVALID_INSTALLATION_ARTIFACT', 'installation authority requires a valid artifact digest');
+  }
+  return join(resolve(projectDir), INSTALLATION_AUTHORITY_DIRECTORY, `${artifact.digest}.json`);
+}
+
+function unsignedReceipt(receipt) {
+  const payload = { ...receipt };
+  delete payload.signature;
+  return payload;
+}
+
+/** Mint a host-authority receipt after an explicit install/reconfigure action. */
+export function authorizeInstallationArtifact(projectDir, artifact, {
+  authorityDirectory,
+} = {}) {
+  const authority = readOrCreateAuthorityKeyPair(authorityDirectory);
+  const payload = {
+    schema_version: INSTALLATION_AUTHORITY_RECEIPT_VERSION,
+    receipt_type: INSTALLATION_AUTHORITY_RECEIPT_TYPE,
+    authority_id: authority.authority_id,
+    project_binding: projectBinding(projectDir, artifact.project_id),
+    installation_artifact_id: artifact.installation_artifact_id,
+    installation_digest: artifact.digest,
+    artifact_created_at: artifact.created_at,
+    issued_at: artifact.created_at,
+  };
+  const receipt = Object.freeze({
+    ...payload,
+    signature: cryptoSign(null, Buffer.from(canonicalSerialize(payload)), authority.privateKey).toString('base64'),
+  });
+  const path = receiptPath(projectDir, artifact);
+  persistImmutableInstallationFile(path, `${canonicalSerialize(receipt)}\n`, {
+    conflictCode: 'INSTALLATION_AUTHORITY_RECEIPT_CONFLICT',
+    label: 'installation authority receipt', maxBytes: 256 * 1024,
+  });
+  return Object.freeze({
+    receipt,
+    receipt_path: relative(resolve(projectDir), path).replaceAll('\\', '/'),
+  });
+}
+
+/** Verify runtime installation authority against the machine trust anchor. */
+export function verifyInstallationArtifactAuthority(projectDir, artifact, { authorityDirectory } = {}) {
+  let source;
+  try {
+    source = readSafeInstallationStorageFile(receiptPath(projectDir, artifact), {
+      label: 'installation authority receipt', encoding: 'utf8', maxBytes: 256 * 1024,
+    });
+  } catch (error) {
+    if (error?.code === 'ENOENT') fail('INSTALLATION_AUTHORITY_REQUIRED', 'installation artifact has no host-authority receipt');
+    throw error;
+  }
+  let receipt;
+  try { receipt = JSON.parse(source.content); }
+  catch { fail('INVALID_INSTALLATION_AUTHORITY_RECEIPT', 'installation authority receipt is not valid JSON'); }
+  exactKeys(receipt, RECEIPT_KEYS, 'installation authority receipt');
+  exactKeys(receipt.project_binding, PROJECT_BINDING_KEYS, 'installation authority project binding');
+  if (receipt.schema_version !== INSTALLATION_AUTHORITY_RECEIPT_VERSION
+    || receipt.receipt_type !== INSTALLATION_AUTHORITY_RECEIPT_TYPE
+    || !Number.isFinite(Date.parse(receipt.issued_at))
+    || !Number.isFinite(Date.parse(receipt.artifact_created_at))) {
+    fail('INVALID_INSTALLATION_AUTHORITY_RECEIPT', 'installation authority receipt metadata is invalid');
+  }
+  const authority = readAuthorityPublicKey(authorityDirectory);
+  if (receipt.authority_id !== authority.authority_id) {
+    fail('INSTALLATION_AUTHORITY_MISMATCH', 'installation authority receipt was minted by a different host authority');
+  }
+  const expectedBinding = projectBinding(projectDir, artifact.project_id);
+  if (canonicalSerialize(receipt.project_binding) !== canonicalSerialize(expectedBinding)
+    || receipt.installation_artifact_id !== artifact.installation_artifact_id
+    || receipt.installation_digest !== artifact.digest
+    || receipt.artifact_created_at !== artifact.created_at) {
+    fail('INSTALLATION_AUTHORITY_BINDING_MISMATCH', 'installation authority receipt does not bind this artifact and project root');
+  }
+  if (typeof receipt.signature !== 'string'
+    || !/^[A-Za-z0-9+/]+={0,2}$/.test(receipt.signature)
+    || Buffer.from(receipt.signature, 'base64').length !== 64) {
+    fail('INVALID_INSTALLATION_AUTHORITY_RECEIPT', 'installation authority receipt signature is malformed');
+  }
+  const verified = cryptoVerify(
+    null,
+    Buffer.from(canonicalSerialize(unsignedReceipt(receipt))),
+    authority.publicKey,
+    Buffer.from(receipt.signature, 'base64'),
+  );
+  if (!verified) fail('INSTALLATION_AUTHORITY_SIGNATURE_INVALID', 'installation authority receipt signature is invalid');
+  return Object.freeze({ valid: true, authority_id: authority.authority_id, receipt_path: relative(resolve(projectDir), receiptPath(projectDir, artifact)).replaceAll('\\', '/') });
+}
+
+export function installationAuthorityStateDirectory(authorityDirectory) {
+  return authorityRoot(authorityDirectory);
+}
+
+/** Sign a domain-separated payload with the persistent host authority. */
+export function signHostAuthorityPayload(payload, {
+  domain,
+  authorityDirectory,
+} = {}) {
+  if (typeof domain !== 'string' || !/^[a-z0-9._-]{1,128}$/.test(domain)) {
+    fail('INVALID_HOST_AUTHORITY_DOMAIN', 'host authority signature requires a path-inert domain');
+  }
+  const authority = readOrCreateAuthorityKeyPair(authorityDirectory);
+  const envelope = { domain, authority_id: authority.authority_id, payload };
+  return Object.freeze({
+    authority_id: authority.authority_id,
+    signature: cryptoSign(
+      null,
+      Buffer.from(canonicalSerialize(envelope)),
+      authority.privateKey,
+    ).toString('base64'),
+  });
+}
+
+/** Verify a domain-separated payload using this host's persistent authority. */
+export function verifyHostAuthorityPayload(payload, {
+  domain,
+  authorityId,
+  signature,
+  authorityDirectory,
+} = {}) {
+  if (typeof domain !== 'string' || !/^[a-z0-9._-]{1,128}$/.test(domain)
+    || typeof authorityId !== 'string'
+    || typeof signature !== 'string'
+    || !/^[A-Za-z0-9+/]+={0,2}$/.test(signature)
+    || Buffer.from(signature, 'base64').length !== 64) return false;
+  let authority;
+  try { authority = readAuthorityPublicKey(authorityDirectory); }
+  catch { return false; }
+  if (authority.authority_id !== authorityId) return false;
+  return cryptoVerify(
+    null,
+    Buffer.from(canonicalSerialize({ domain, authority_id: authorityId, payload })),
+    authority.publicKey,
+    Buffer.from(signature, 'base64'),
+  );
+}