@aipt/idp-deploy 0.1.2

package/src/render.mjs

@@ -0,0 +1,330 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { doctorConfig, referencedFiles, registryPrivateScopes } from './config.mjs';
+import { invariant } from './errors.mjs';
+import { inventoryDirectory, sha256, stableJson } from './hash.mjs';
+import { resolveProfile } from './profiles.mjs';
+import { atomicWrite, resolveContained } from './security.mjs';
+
+function makeDirectory(candidate, mode = 0o755) {
+  fs.mkdirSync(candidate, { recursive: true, mode });
+  const current = fs.lstatSync(candidate).mode & 0o777;
+  fs.chmodSync(candidate, current & mode);
+}
+
+function writeReadonly(candidate, content) {
+  makeDirectory(path.dirname(candidate));
+  atomicWrite(candidate, content, 0o444);
+}
+
+function copyReadonly(source, target) {
+  writeReadonly(target, fs.readFileSync(source));
+}
+
+function copySecret(source, target) {
+  makeDirectory(path.dirname(target), 0o700);
+  atomicWrite(target, fs.readFileSync(source), 0o400);
+}
+
+function caddyHandlers(active) {
+  const handlers = [
+    '  header {',
+    '    -Server',
+    '    X-Content-Type-Options nosniff',
+    '    X-Frame-Options DENY',
+    '    Referrer-Policy no-referrer',
+    '  }',
+    '  handle /live {',
+    '    respond "IDP edge ok" 200',
+    '  }',
+  ];
+  if (active.has('flow')) handlers.push(
+    '  handle /flow {',
+    '    redir /flow/ 308',
+    '  }',
+    '  handle_path /flow/* {',
+    '    reverse_proxy flow:3710',
+    '  }',
+  );
+  if (active.has('tech')) handlers.push(
+    '  handle /knowledge-workbench {',
+    '    redir /knowledge-workbench/ 308',
+    '  }',
+    '  handle /knowledge-workbench/* {',
+    '    reverse_proxy tech-workbench:3011',
+    '  }',
+    '  handle /knowledge {',
+    '    redir /knowledge/ 308',
+    '  }',
+    '  handle_path /knowledge/* {',
+    '    reverse_proxy tech:3698',
+    '  }',
+  );
+  if (active.has('smartgo')) handlers.push(
+    '  handle /smartgo/api {',
+    '    redir /smartgo/api/ 308',
+    '  }',
+    '  handle_path /smartgo/api/* {',
+    '    reverse_proxy smartgo-api:3200',
+    '  }',
+    '  handle /smartgo-artifacts/* {',
+    '    reverse_proxy smartgo-object-store:9000',
+    '  }',
+  );
+  if (active.has('portal')) handlers.push(
+    '  handle {',
+    '    reverse_proxy portal:7007',
+    '  }',
+  );
+  else if (active.has('tech')) handlers.push(
+    '  handle {',
+    '    reverse_proxy tech:3698',
+    '  }',
+  );
+  else handlers.push(
+    '  handle {',
+    '    respond "当前部署 Profile 没有 Web 门户" 404',
+    '  }',
+  );
+  return handlers;
+}
+
+function smartGoApplicationSite(address, upstream) {
+  return `${address} {
+  header {
+    -Server
+    X-Content-Type-Options nosniff
+    X-Frame-Options DENY
+    Referrer-Policy no-referrer
+  }
+  reverse_proxy ${upstream}
+}`;
+}
+
+function siteBlock({ address, active, tls = false, redirectTo }) {
+  const lines = [`${address} {`];
+  if (redirectTo) lines.push(`  redir ${redirectTo}{uri} permanent`);
+  else {
+    if (tls) lines.push('  tls /run/secrets/tls-certificate.pem /run/secrets/tls-private-key.pem');
+    lines.push(...caddyHandlers(active));
+  }
+  lines.push('}');
+  return lines.join('\n');
+}
+
+export function renderCaddyfile(env, active) {
+  const httpAddress = `http://${env.IDP_PUBLIC_HOST}:${env.IDP_HTTP_PORT}`;
+  const httpsAddress = `https://${env.IDP_PUBLIC_HOST}:${env.IDP_HTTPS_PORT}`;
+  const blocks = [
+    '{', '  admin off', '  auto_https off', '}',
+    'http://127.0.0.1:2019 {',
+    '  handle /live {',
+    '    respond "IDP edge ok" 200',
+    '  }',
+    '  handle {',
+    '    respond "Not Found" 404',
+    '  }',
+    '}',
+  ];
+  if (env.IDP_TLS_ENABLED === 'true') {
+    if (env.IDP_HTTP_ENABLED === 'true') blocks.push(siteBlock({ address: httpAddress, active, redirectTo: httpsAddress }));
+    blocks.push(siteBlock({ address: httpsAddress, active, tls: true }));
+  } else {
+    blocks.push(siteBlock({ address: httpAddress, active }));
+  }
+  if (active.has('smartgo')) {
+    blocks.push(
+      smartGoApplicationSite(`http://:${env.IDP_SMARTGO_GOTOLOGY_PORT}`, 'smartgo-gotology:3000'),
+      smartGoApplicationSite(`http://:${env.IDP_SMARTGO_OPERATIONS_PORT}`, 'smartgo-operations:3101'),
+      smartGoApplicationSite(`http://:${env.IDP_SMARTGO_STUDIO_PORT}`, 'smartgo-studio:3002'),
+    );
+  }
+  return `${blocks.join('\n\n')}\n`;
+}
+
+export function renderVerdaccioConfig(privateScopes = ['@aipt', '@bench']) {
+  const scopes = privateScopes.map((scope) => {
+    invariant(/^@[a-z0-9][a-z0-9._-]{0,63}$/u.test(scope), 'IDP_REGISTRY_SCOPE_INVALID', `Registry私有Scope格式无效：${scope}`);
+    return `  '${scope}/*':\n    access: $all\n    publish: $authenticated\n    unpublish: $authenticated`;
+  }).join('\n');
+  return `storage: /verdaccio/storage/packages
+plugins: /verdaccio/plugins
+auth:
+  htpasswd:
+    file: /verdaccio/storage/auth/htpasswd
+    max_users: 100
+uplinks:
+  npmjs:
+    url: https://registry.npmjs.org/
+packages:
+${scopes}
+  '@*/*':
+    access: $all
+    publish: $authenticated
+    unpublish: $authenticated
+    proxy: npmjs
+  '**':
+    access: $all
+    publish: $authenticated
+    unpublish: $authenticated
+    proxy: npmjs
+web:
+  enable: true
+log:
+  type: stdout
+  format: pretty
+  level: http
+`;
+}
+
+function renderComponentBundle({ staging, root, component, componentEnvText, refs, additionalSensitiveRefs = [] }) {
+  // Flow 的已批准组件合同以 IDP_CONFIG_DIR 为部署配置根，并固定从
+  // $IDP_CONFIG_DIR/components/flow 读取；其单服务挂载仍只包含 Flow，
+  // 不能为了路径兼容而把整个运行时投影暴露给容器。
+  const target = component === 'flow'
+    ? path.join(staging, component, 'components', component)
+    : path.join(staging, component);
+  makeDirectory(target, 0o700);
+  const runtimeExcludedKeys = component === 'smartgo' ? new Set(['SMARTGO_NPMRC_FILE']) : new Set();
+  const runtimeEnvText = componentEnvText.split(/(?<=\n)/u).filter((line) => {
+    const key = line.match(/^([A-Z][A-Z0-9_]*)=/u)?.[1];
+    return !key || !runtimeExcludedKeys.has(key);
+  }).join('');
+  atomicWrite(path.join(target, '.env'), runtimeEnvText, 0o400);
+  const componentRefs = [
+    ...refs.filter((entry) => entry.scope === component && !runtimeExcludedKeys.has(entry.key)),
+    ...additionalSensitiveRefs,
+  ];
+  const projectedReferences = new Set();
+  for (const ref of componentRefs) {
+    if (!fs.existsSync(ref.absolute)) continue;
+    invariant(!projectedReferences.has(ref.reference), 'IDP_RUNTIME_PROJECTION_COLLISION', `${component}运行时投影路径重复：${ref.reference}`);
+    projectedReferences.add(ref.reference);
+    const sensitive = ref.sensitive === true || ref.key?.endsWith('_FILE');
+    const targetFile = path.join(target, ref.reference);
+    makeDirectory(path.dirname(targetFile), 0o700);
+    atomicWrite(targetFile, fs.readFileSync(ref.absolute), sensitive ? 0o400 : 0o444);
+  }
+  const componentConfig = path.join(root, 'components', component, 'config');
+  if (fs.existsSync(componentConfig)) {
+    for (const entry of fs.readdirSync(componentConfig, { withFileTypes: true })) {
+      if (!entry.isFile()) continue;
+      const reference = `config/${entry.name}`;
+      if (projectedReferences.has(reference)) continue;
+      copyReadonly(path.join(componentConfig, entry.name), path.join(target, reference));
+    }
+  }
+}
+
+function readGeneratedManifest(target) {
+  const candidate = path.join(target, 'manifest.json');
+  invariant(fs.existsSync(candidate), 'IDP_RENDER_GENERATION_INVALID', `运行时生成代次缺少manifest.json：${target}`);
+  let manifest;
+  try { manifest = JSON.parse(fs.readFileSync(candidate, 'utf8')); }
+  catch { invariant(false, 'IDP_RENDER_GENERATION_INVALID', `运行时生成代次manifest不是有效JSON：${target}`); }
+  const exactKeys = ['schemaVersion', 'profile', 'configDigest', 'generatedAt', 'files', 'digest'];
+  invariant(
+    manifest && typeof manifest === 'object' && !Array.isArray(manifest) &&
+    stableJson(Object.keys(manifest).sort()) === stableJson(exactKeys.sort()),
+    'IDP_RENDER_GENERATION_INVALID', `运行时生成代次manifest字段无效：${target}`,
+  );
+  const generatedAt = typeof manifest.generatedAt === 'string' ? new Date(manifest.generatedAt) : new Date(Number.NaN);
+  const { generatedAt: _generatedAt, digest, ...facts } = manifest;
+  invariant(
+    manifest.schemaVersion === 1 && typeof manifest.profile === 'string' &&
+    /^sha256:[0-9a-f]{64}$/u.test(manifest.configDigest ?? '') &&
+    !Number.isNaN(generatedAt.getTime()) && generatedAt.toISOString() === manifest.generatedAt &&
+    Array.isArray(manifest.files) && /^sha256:[0-9a-f]{64}$/u.test(digest ?? '') &&
+    sha256(stableJson(facts)) === digest,
+    'IDP_RENDER_GENERATION_INVALID', `运行时生成代次manifest事实摘要无效：${target}`,
+  );
+  const actualFiles = inventoryDirectory(target)
+    .filter(({ path: filePath }) => filePath !== 'manifest.json')
+    .map(({ path: filePath, mode, size, digest: fileDigest }) => ({ path: filePath, mode, size, digest: fileDigest }));
+  invariant(stableJson(actualFiles) === stableJson(manifest.files), 'IDP_RENDER_GENERATION_INVALID', `运行时生成代次文件与manifest不一致：${target}`);
+  return manifest;
+}
+
+export function readRuntimeGenerationManifest(runtimeRoot, profile, digest) {
+  invariant(/^sha256:[0-9a-f]{64}$/u.test(digest ?? ''), 'IDP_RENDER_GENERATION_INVALID', '运行时生成代次digest无效');
+  const target = resolveContained(
+    runtimeRoot,
+    `rendered/${profile}/generations/${digest.slice('sha256:'.length)}`,
+    '运行时生成代次',
+  );
+  return readGeneratedManifest(target);
+}
+
+function publishGeneratedDirectory(runtimeRoot, staging, target, expectedManifest) {
+  const relative = path.relative(runtimeRoot, target);
+  invariant(relative.startsWith('rendered/') && !relative.includes('..'), 'IDP_RENDER_TARGET_INVALID', '生成目录必须位于Runtime Root的rendered目录');
+  makeDirectory(path.dirname(target), 0o700);
+  if (fs.existsSync(target)) {
+    const existing = readGeneratedManifest(target);
+    invariant(existing.digest === expectedManifest.digest, 'IDP_RENDER_GENERATION_CONFLICT', '相同运行时生成代次路径包含不同事实');
+    fs.rmSync(staging, { recursive: true, force: true });
+    return existing;
+  }
+  fs.renameSync(staging, target);
+  return expectedManifest;
+}
+
+export function renderRuntimeBundles(configRoot, profile) {
+  const { root, env, components, report, techSourceCredentials } = doctorConfig(configRoot, { requireConfigured: false, profile });
+  const active = new Set(resolveProfile(profile));
+  const runtimeRoot = env.IDP_RUNTIME_DIR;
+  makeDirectory(runtimeRoot, 0o700);
+  makeDirectory(path.join(runtimeRoot, 'tmp'), 0o700);
+  const staging = resolveContained(runtimeRoot, `tmp/render-${profile}-${process.pid}-${Date.now()}`, '生成暂存目录');
+  makeDirectory(staging, 0o700);
+  try {
+    const refs = referencedFiles(root);
+    if (active.has('postgresql')) {
+      const bootstrapRefs = [
+        ['IDP_POSTGRES_SUPERUSER_PASSWORD_FILE', 'superuser-password'],
+        ['IDP_POSTGRES_TECH_PASSWORD_FILE', 'tech-password'],
+        ['IDP_POSTGRES_PORTAL_PASSWORD_FILE', 'portal-password'],
+        ...(active.has('smartgo') ? [['IDP_POSTGRES_SMARTGO_PASSWORD_FILE', 'smartgo-password']] : []),
+      ];
+      for (const [key, filename] of bootstrapRefs) {
+        const ref = refs.find((entry) => entry.scope === 'root' && entry.key === key);
+        invariant(ref && fs.existsSync(ref.absolute), 'IDP_RUNTIME_PROJECTION_SOURCE_MISSING', `PostgreSQL Bootstrap缺少${key}`);
+        copySecret(ref.absolute, path.join(staging, 'postgresql-bootstrap', filename));
+      }
+    }
+    for (const component of ['tech', 'flow', 'portal', 'smartgo']) {
+      if (!active.has(component)) continue;
+      renderComponentBundle({
+        staging,
+        root,
+        component,
+        componentEnvText: fs.readFileSync(path.join(root, 'components', component, '.env'), 'utf8'),
+        refs,
+        additionalSensitiveRefs: component === 'tech'
+          ? techSourceCredentials.files.map((entry) => ({ ...entry, sensitive: true }))
+          : [],
+      });
+    }
+    if (active.has('edge')) {
+      writeReadonly(path.join(staging, 'edge', 'Caddyfile'), renderCaddyfile(env, active));
+    }
+    if (active.has('registry')) {
+      writeReadonly(path.join(staging, 'registry', 'config.yaml'), renderVerdaccioConfig(registryPrivateScopes(env)));
+    }
+    const inventory = inventoryDirectory(staging);
+    const facts = {
+      schemaVersion: 1,
+      profile,
+      configDigest: report.digest,
+      files: inventory.map(({ path: filePath, mode, size, digest }) => ({ path: filePath, mode, size, digest })),
+    };
+    const manifest = { ...facts, generatedAt: new Date().toISOString(), digest: sha256(stableJson(facts)) };
+    writeReadonly(path.join(staging, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+    const target = resolveContained(runtimeRoot, `rendered/${profile}/generations/${manifest.digest.slice('sha256:'.length)}`, '生成目标代次');
+    const publishedManifest = publishGeneratedDirectory(runtimeRoot, staging, target, manifest);
+    return { target, manifest: publishedManifest };
+  } catch (error) {
+    if (fs.existsSync(staging)) fs.rmSync(staging, { recursive: true, force: true });
+    throw error;
+  }
+}

package/src/security.mjs

@@ -0,0 +1,156 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { IdpError, invariant } from './errors.mjs';
+
+export function parseEnv(text, source = '.env') {
+  const result = Object.create(null);
+  for (const [index, raw] of text.split(/\r?\n/u).entries()) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    invariant(!line.startsWith('export '), 'IDP_ENV_EXPORT_FORBIDDEN', `${source}:${index + 1} 不允许使用 export`);
+    const match = /^([A-Z][A-Z0-9_]*)=(.*)$/u.exec(line);
+    invariant(match, 'IDP_ENV_INVALID', `${source}:${index + 1} 不是严格 KEY=VALUE 格式`);
+    const [, key, rawValue] = match;
+    invariant(!(key in result), 'IDP_ENV_DUPLICATE', `${source}:${index + 1} 重复变量 ${key}`);
+    let value = rawValue.trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    invariant(!/[`$][({]?/u.test(value), 'IDP_ENV_EXPANSION_FORBIDDEN', `${source}:${index + 1} 不允许命令或变量展开`);
+    result[key] = value;
+  }
+  return result;
+}
+
+export function findGitAncestor(candidate) {
+  let cursor = path.resolve(candidate);
+  for (;;) {
+    if (fs.existsSync(path.join(cursor, '.git'))) return cursor;
+    const parent = path.dirname(cursor);
+    if (parent === cursor) return undefined;
+    cursor = parent;
+  }
+}
+
+export function canonicalExisting(candidate, role = '路径') {
+  invariant(path.isAbsolute(candidate), 'IDP_PATH_NOT_ABSOLUTE', `${role}必须是绝对路径`);
+  const stat = fs.lstatSync(candidate);
+  invariant(!stat.isSymbolicLink(), 'IDP_PATH_SYMLINK', `${role}不能是符号链接`);
+  return fs.realpathSync.native(candidate);
+}
+
+export function canonicalPlannedDirectory(candidate, role = '目录') {
+  invariant(path.isAbsolute(candidate), 'IDP_PATH_NOT_ABSOLUTE', `${role}必须是绝对路径`);
+  let cursor = path.resolve(candidate);
+  const suffix = [];
+  while (!fs.existsSync(cursor)) {
+    const parent = path.dirname(cursor);
+    invariant(parent !== cursor, 'IDP_DIRECTORY_ANCESTOR_MISSING', `${role}找不到已存在的父目录`);
+    suffix.unshift(path.basename(cursor));
+    cursor = parent;
+  }
+  const stat = fs.lstatSync(cursor);
+  invariant(!stat.isSymbolicLink(), 'IDP_PATH_SYMLINK', `${role}的最近已存在路径不能是符号链接：${cursor}`);
+  invariant(stat.isDirectory(), 'IDP_DIRECTORY_INVALID', `${role}的父路径必须是目录：${cursor}`);
+  return path.join(fs.realpathSync.native(cursor), ...suffix);
+}
+
+export function secureDirectoryRoot(candidate, role = '目录', { create = false, allowForeignOwner = false } = {}) {
+  const planned = canonicalPlannedDirectory(candidate, role);
+  if (create && !fs.existsSync(planned)) fs.mkdirSync(planned, { recursive: true, mode: 0o700 });
+  if (!fs.existsSync(planned)) return planned;
+  const stat = fs.lstatSync(planned);
+  invariant(stat.isDirectory() && !stat.isSymbolicLink(), 'IDP_DIRECTORY_INVALID', `${role}必须是普通目录：${planned}`);
+  if (!allowForeignOwner && typeof process.getuid === 'function') invariant(stat.uid === process.getuid(), 'IDP_DIRECTORY_OWNER_INVALID', `${role}必须由当前部署用户拥有：${planned}`);
+  if (create) fs.chmodSync(planned, 0o700);
+  assertMode(planned, 0o700, role);
+  return fs.realpathSync.native(planned);
+}
+
+export function assertOutsideRepositories(candidate, role = '路径') {
+  const gitRoot = findGitAncestor(candidate);
+  invariant(!gitRoot, 'IDP_PATH_INSIDE_REPOSITORY', `${role}不能位于Git仓库内：${gitRoot}`);
+}
+
+export function assertMode(candidate, maximumMode, role = '文件') {
+  const stat = fs.lstatSync(candidate);
+  const actual = stat.mode & 0o777;
+  invariant((actual & ~maximumMode) === 0, 'IDP_MODE_TOO_OPEN', `${role}权限过宽：${actual.toString(8)}，最大允许${maximumMode.toString(8)}`);
+}
+
+export function assertSafeDirectory(candidate, maximumMode = 0o700, { role = '目录' } = {}) {
+  const stat = fs.lstatSync(candidate);
+  invariant(stat.isDirectory() && !stat.isSymbolicLink(), 'IDP_DIRECTORY_INVALID', `${role}必须是普通目录：${candidate}`);
+  assertMode(candidate, maximumMode, role);
+  return stat;
+}
+
+export function assertSafeRegularFile(candidate, maximumMode = 0o600, { allowEmpty = true, role = '文件' } = {}) {
+  const stat = fs.lstatSync(candidate);
+  invariant(stat.isFile(), 'IDP_FILE_NOT_REGULAR', `${role}必须是普通文件：${candidate}`);
+  invariant(!stat.isSymbolicLink(), 'IDP_FILE_SYMLINK', `${role}不能是符号链接：${candidate}`);
+  invariant(stat.nlink === 1, 'IDP_FILE_HARDLINK', `${role}必须只有一个硬链接：${candidate}`);
+  assertMode(candidate, maximumMode, role);
+  if (!allowEmpty) invariant(stat.size > 0, 'IDP_FILE_EMPTY', `${role}尚未配置：${candidate}`);
+  return stat;
+}
+
+export function resolveContained(root, reference, role = '文件引用') {
+  invariant(reference && !path.isAbsolute(reference), 'IDP_REF_NOT_RELATIVE', `${role}必须是相对路径`);
+  invariant(!reference.includes('\0'), 'IDP_REF_NUL', `${role}包含非法NUL`);
+  invariant(!/[*?{}[\]]/u.test(reference), 'IDP_REF_GLOB', `${role}不允许glob`);
+  const resolved = path.resolve(root, reference);
+  const relative = path.relative(root, resolved);
+  invariant(relative && !relative.startsWith('..') && !path.isAbsolute(relative), 'IDP_REF_ESCAPE', `${role}逃逸Config Root：${reference}`);
+  let cursor = root;
+  for (const segment of relative.split(path.sep)) {
+    cursor = path.join(cursor, segment);
+    if (!fs.existsSync(cursor)) break;
+    invariant(!fs.lstatSync(cursor).isSymbolicLink(), 'IDP_REF_SYMLINK', `${role}的路径中不允许符号链接：${reference}`);
+  }
+  return resolved;
+}
+
+export function assertDisjointRoots(entries) {
+  for (let left = 0; left < entries.length; left += 1) {
+    for (let right = left + 1; right < entries.length; right += 1) {
+      const [leftRole, leftPath] = entries[left];
+      const [rightRole, rightPath] = entries[right];
+      const relLR = path.relative(leftPath, rightPath);
+      const relRL = path.relative(rightPath, leftPath);
+      const nested = relLR === '' || (!relLR.startsWith('..') && !path.isAbsolute(relLR)) || (!relRL.startsWith('..') && !path.isAbsolute(relRL));
+      invariant(!nested, 'IDP_ROOTS_OVERLAP', `${leftRole}与${rightRole}不能相同或互相嵌套`);
+    }
+  }
+}
+
+export function createExclusiveFile(candidate, content = '', mode = 0o600) {
+  const handle = fs.openSync(candidate, 'wx', mode);
+  let succeeded = false;
+  try {
+    fs.writeFileSync(handle, content, { encoding: 'utf8' });
+    fs.fsyncSync(handle);
+    succeeded = true;
+  } finally {
+    fs.closeSync(handle);
+    if (!succeeded) {
+      try { fs.unlinkSync(candidate); } catch {}
+    }
+  }
+}
+
+export function atomicWrite(candidate, content, mode = 0o600) {
+  const parent = path.dirname(candidate);
+  invariant(fs.existsSync(parent) && fs.lstatSync(parent).isDirectory() && !fs.lstatSync(parent).isSymbolicLink(), 'IDP_ATOMIC_PARENT_INVALID', `原子写入父目录无效：${parent}`);
+  const temp = path.join(parent, `.${path.basename(candidate)}.${process.pid}.${Date.now()}.tmp`);
+  createExclusiveFile(temp, content, mode);
+  try {
+    fs.renameSync(temp, candidate);
+    fs.chmodSync(candidate, mode);
+    const parentHandle = fs.openSync(parent, 'r');
+    try { fs.fsyncSync(parentHandle); } finally { fs.closeSync(parentHandle); }
+  } catch (error) {
+    try { fs.unlinkSync(temp); } catch {}
+    throw new IdpError('IDP_ATOMIC_WRITE_FAILED', `原子写入失败：${candidate}`, { cause: error.message });
+  }
+}

package/src/source-contracts.mjs

@@ -0,0 +1,106 @@
+import { invariant } from './errors.mjs';
+import { sha256, stableJson } from './hash.mjs';
+
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const VERSION = /^(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)(?:-[0-9A-Za-z.-]+)?$/u;
+const PACKAGE = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/u;
+const CAPABILITY_REF = /^capability:[a-z0-9][a-z0-9.-]*@[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$/u;
+
+function record(value) { return typeof value === 'object' && value !== null && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype; }
+function exactKeys(value, expected, role) {
+  invariant(record(value), 'IDP_SOURCE_SCHEMA_INVALID', `${role}必须是对象`);
+  const actual = Object.keys(value).sort(); const wanted = [...expected].sort();
+  invariant(actual.length === wanted.length && actual.every((key, index) => key === wanted[index]), 'IDP_SOURCE_SCHEMA_INVALID', `${role}字段不符合严格合同`);
+}
+function sortedUniqueStrings(value, predicate = () => true) {
+  return Array.isArray(value) && value.every((entry) => typeof entry === 'string' && predicate(entry)) && value.every((entry, index) => index === 0 || value[index - 1] < entry);
+}
+function canonicalTimestamp(value, role) {
+  const date = new Date(value);
+  invariant(typeof value === 'string' && !Number.isNaN(date.getTime()) && date.toISOString() === value, 'IDP_SOURCE_SCHEMA_INVALID', `${role}必须是规范ISO-8601 UTC时间`);
+}
+
+export function validateDyytoSnapshot(document) {
+  exactKeys(document, ['schemaVersion', 'generatedAt', 'sourceDigest', 'items'], 'Dyyto Snapshot');
+  invariant(document.schemaVersion === 1 && DIGEST.test(document.sourceDigest ?? '') && Array.isArray(document.items) && document.items.length <= 20_000, 'IDP_SOURCE_SCHEMA_INVALID', 'Dyyto Snapshot顶层字段无效');
+  canonicalTimestamp(document.generatedAt, 'generatedAt');
+  const refs = new Set(); let previous = '';
+  for (const [index, item] of document.items.entries()) {
+    exactKeys(item, ['kind', 'ref', 'packageName', 'version', 'releaseDigest', 'capabilities'], `Dyyto items[${index}]`);
+    invariant(item.kind === 'package' && PACKAGE.test(item.packageName ?? '') && VERSION.test(item.version ?? '') && DIGEST.test(item.releaseDigest ?? ''), 'IDP_SOURCE_SCHEMA_INVALID', `Dyyto items[${index}]字段无效`);
+    invariant(item.ref === `package:${item.packageName}@${item.version}` && item.ref > previous && !refs.has(item.ref), 'IDP_SOURCE_DUPLICATE', `Dyyto Package ref必须唯一且按字典序排列：${item.ref}`);
+    invariant(sortedUniqueStrings(item.capabilities, (value) => CAPABILITY_REF.test(value)), 'IDP_SOURCE_SCHEMA_INVALID', `Dyyto ${item.ref} capabilities必须是排序唯一的精确ref`);
+    previous = item.ref; refs.add(item.ref);
+  }
+  const { sourceDigest, ...body } = document;
+  invariant(sha256(stableJson(body)) === sourceDigest, 'IDP_SOURCE_DIGEST_MISMATCH', 'Dyyto Snapshot sourceDigest不匹配');
+  return document;
+}
+
+const FILE_URI = /(?:^|[^a-zA-Z0-9])file:\/{2,3}[^\s"'<>]+/iu;
+const HOME_PATH = /(?:^|[^a-zA-Z0-9])~[\\/][^\s"'<>]*/u;
+const POSIX_ABSOLUTE = /(?:^|[^a-zA-Z0-9:/])\/(?!\/)[^\s"'<>]*/u;
+const UNC_PATH = /(?:^|[^a-zA-Z0-9:/])(?:\\\\|\/\/)[^\\/\s"'<>]+[\\/][^\s"'<>]+/u;
+const WINDOWS_ABSOLUTE = /(?:^|[^a-zA-Z0-9])[a-zA-Z]:[\\/][^\s"'<>]*/u;
+
+function assertNoHostPaths(value) {
+  let scannedStringCount = 0;
+  const visit = (current) => {
+    if (typeof current === 'string') {
+      scannedStringCount += 1;
+      invariant(![FILE_URI, HOME_PATH, POSIX_ABSOLUTE, UNC_PATH, WINDOWS_ABSOLUTE].some((pattern) => pattern.test(current)), 'IDP_SOURCE_HOST_PATH', 'Bench Snapshot包含宿主机绝对路径');
+    }
+    else if (Array.isArray(current)) current.forEach(visit);
+    else if (record(current)) Object.entries(current).forEach(([key, child]) => { visit(key); visit(child); });
+  };
+  visit(value);
+  return scannedStringCount;
+}
+
+function assertNoInlineSecrets(configuration) {
+  const visit = (current) => {
+    if (Array.isArray(current)) return current.forEach(visit);
+    if (!record(current)) return;
+    for (const [key, value] of Object.entries(current)) {
+      invariant(!/(password|secret|token|api[-_]?key|access[-_]?key|private[-_]?key)/iu.test(key), 'IDP_SOURCE_INLINE_SECRET', `Bench configuration禁止内联敏感字段：${key}`);
+      visit(value);
+    }
+  };
+  visit(configuration);
+}
+
+export function validateBenchSnapshot(document) {
+  exactKeys(document, ['schemaVersion', 'environment', 'catalogDigest', 'policy', 'availableCapabilities', 'bindings', 'snapshotDigest'], 'Bench Snapshot');
+  invariant(document.schemaVersion === 'bench.environment-snapshot/v1' && /^[a-z][a-z0-9-]*(?:\.[a-z0-9-]+)*$/u.test(document.environment ?? '') && DIGEST.test(document.catalogDigest ?? '') && DIGEST.test(document.snapshotDigest ?? ''), 'IDP_SOURCE_SCHEMA_INVALID', 'Bench Snapshot顶层字段无效');
+  exactKeys(document.policy, ['configurationRootVariable', 'fileReferencesVerified', 'secretValuesExposed', 'hostPathsExposed', 'hostPathScan', 'provisioningAuthority'], 'Bench policy');
+  exactKeys(document.policy.hostPathScan, ['detector', 'scannedStringCount', 'matchCount'], 'Bench hostPathScan');
+  invariant(document.policy.configurationRootVariable === 'IDP_CONFIG_DIR' && document.policy.fileReferencesVerified === true && document.policy.secretValuesExposed === false && document.policy.hostPathsExposed === false && document.policy.provisioningAuthority === 'idp-deploy', 'IDP_SOURCE_POLICY_INVALID', 'Bench Snapshot安全策略证据无效');
+  invariant(document.policy.hostPathScan.detector === 'bench.host-path/v1' && Number.isSafeInteger(document.policy.hostPathScan.scannedStringCount) && document.policy.hostPathScan.scannedStringCount >= 0 && document.policy.hostPathScan.matchCount === 0, 'IDP_SOURCE_POLICY_INVALID', 'Bench hostPathScan证据无效');
+  invariant(sortedUniqueStrings(document.availableCapabilities), 'IDP_SOURCE_SCHEMA_INVALID', 'Bench availableCapabilities必须排序且唯一');
+  invariant(Array.isArray(document.bindings) && document.bindings.length <= 20_000, 'IDP_SOURCE_SCHEMA_INVALID', 'Bench bindings必须是有界数组');
+  const bindingIds = new Set(); let previous = '';
+  for (const [index, binding] of document.bindings.entries()) {
+    exactKeys(binding, ['id', 'consumer', 'capability', 'offering', 'profile', 'configuration', 'secretRefNames', 'certificateRefNames', 'trustRefNames'], `Bench bindings[${index}]`);
+    invariant([binding.id, binding.consumer, binding.capability, binding.offering, binding.profile].every((value) => typeof value === 'string' && value.length > 0 && value.length <= 256), 'IDP_SOURCE_SCHEMA_INVALID', `Bench bindings[${index}]标识无效`);
+    invariant(binding.id > previous && !bindingIds.has(binding.id), 'IDP_SOURCE_DUPLICATE', `Bench Binding id必须唯一且按字典序排列：${binding.id}`);
+    invariant(record(binding.configuration) && sortedUniqueStrings(binding.secretRefNames) && sortedUniqueStrings(binding.certificateRefNames) && sortedUniqueStrings(binding.trustRefNames), 'IDP_SOURCE_SCHEMA_INVALID', `Bench Binding ${binding.id}配置无效`);
+    invariant(document.availableCapabilities.includes(binding.capability), 'IDP_SOURCE_SCHEMA_INVALID', `Bench Binding ${binding.id}引用未声明的Capability`);
+    assertNoInlineSecrets(binding.configuration);
+    previous = binding.id; bindingIds.add(binding.id);
+  }
+  const { hostPathsExposed: _hostPathsExposed, hostPathScan: _hostPathScan, ...policyScanSubject } = document.policy;
+  const scanSubject = {
+    schemaVersion: document.schemaVersion,
+    environment: document.environment,
+    catalogDigest: document.catalogDigest,
+    policy: policyScanSubject,
+    availableCapabilities: document.availableCapabilities,
+    bindings: document.bindings,
+  };
+  const scannedStringCount = assertNoHostPaths(scanSubject);
+  invariant(document.policy.hostPathScan.scannedStringCount === scannedStringCount, 'IDP_SOURCE_POLICY_INVALID', 'Bench hostPathScan扫描计数与内容不一致');
+  assertNoHostPaths(document);
+  const { snapshotDigest, ...body } = document;
+  invariant(sha256(stableJson(body)) === snapshotDigest, 'IDP_SOURCE_DIGEST_MISMATCH', 'Bench Snapshot snapshotDigest不匹配');
+  return document;
+}