@aipt/idp-deploy 0.1.2

package/src/bindings.mjs

@@ -0,0 +1,518 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { doctorConfig, registryPrivateScopes } from './config.mjs';
+import { IdpError, invariant } from './errors.mjs';
+import { inventoryDirectory, sha256, stableJson } from './hash.mjs';
+import { readActiveProfileState, readLatestVerifyEvidence, withInstanceLock } from './operations.mjs';
+import { resolveProfile, resolveProfileServices } from './profiles.mjs';
+import { assertSafeDirectory, assertSafeRegularFile, createExclusiveFile, resolveContained } from './security.mjs';
+
+const MANAGED_DIRECTORY = 'bindings/idp-deploy';
+const MANIFEST_FILE = '.idp-deploy-managed.json';
+const MANIFEST_KEYS = Object.freeze([
+  'activeProfileDigest', 'configDigest', 'digest', 'environment', 'files', 'instanceId',
+  'owner', 'planDigest', 'profile', 'schemaVersion', 'verifyReceiptDigest',
+]);
+const ROLLBACK_TOKEN_KEYS = Object.freeze([
+  'action', 'digest', 'expectedCurrentDigest', 'preimage', 'profile', 'schemaVersion', 'target',
+]);
+const DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/u;
+
+function assertOwnedDirectory(candidate, role) {
+  const stat = assertSafeDirectory(candidate, 0o700, { role });
+  invariant((stat.mode & 0o777) === 0o700, 'IDP_BINDING_DIRECTORY_MODE_INVALID', `${role}权限必须固定为0700：${candidate}`);
+  if (typeof process.getuid === 'function') {
+    invariant(stat.uid === process.getuid(), 'IDP_BINDING_DIRECTORY_OWNER_INVALID', `${role}必须由当前部署用户拥有：${candidate}`);
+  }
+  return stat;
+}
+
+function assertOwnedRegularFile(candidate, role) {
+  const stat = assertSafeRegularFile(candidate, 0o600, { allowEmpty: false, role });
+  invariant((stat.mode & 0o777) === 0o600, 'IDP_BINDING_FILE_MODE_INVALID', `${role}权限必须固定为0600：${candidate}`);
+  if (typeof process.getuid === 'function') {
+    invariant(stat.uid === process.getuid(), 'IDP_BINDING_FILE_OWNER_INVALID', `${role}必须由当前部署用户拥有：${candidate}`);
+  }
+  return stat;
+}
+
+function ensurePrivateDirectory(candidate, role) {
+  if (!fs.existsSync(candidate)) fs.mkdirSync(candidate, { recursive: true, mode: 0o700 });
+  assertOwnedDirectory(candidate, role);
+  fs.chmodSync(candidate, 0o700);
+}
+
+function fsyncDirectory(candidate) {
+  const handle = fs.openSync(candidate, 'r');
+  try { fs.fsyncSync(handle); } finally { fs.closeSync(handle); }
+}
+
+function exactKeys(value, expected, code, role) {
+  invariant(
+    value && typeof value === 'object' && !Array.isArray(value) &&
+    stableJson(Object.keys(value).sort()) === stableJson([...expected].sort()),
+    code,
+    `${role}字段集合无效`,
+  );
+}
+
+function urlAuthority(host) {
+  const unwrapped = String(host).replace(/^\[|\]$/gu, '');
+  return unwrapped.includes(':') ? `[${unwrapped}]` : unwrapped;
+}
+
+function bindingId(instanceId, suffix) {
+  const value = `${instanceId}-${suffix}`;
+  invariant(/^[a-z0-9][a-z0-9.-]{0,127}$/u.test(value), 'IDP_BINDING_ID_INVALID', `生成的Binding ID不符合v1合同：${value}`);
+  return value;
+}
+
+function assertFileReference(reference, prefix, role) {
+  invariant(
+    typeof reference === 'string' && reference.startsWith(`${prefix}/`) && !path.isAbsolute(reference) && !reference.split('/').includes('..'),
+    'IDP_BINDING_FILE_REFERENCE_INVALID',
+    `${role}必须是Config Dir内以${prefix}/开头的安全相对路径`,
+  );
+  return reference;
+}
+
+function makeBinding({ id, consumer, environment, capability, offering, profile, configuration, fileRefs = {} }) {
+  invariant(/^[a-z0-9][a-z0-9.-]{0,127}$/u.test(consumer), 'IDP_BINDING_CONSUMER_INVALID', `Binding consumer不符合v1合同：${consumer}`);
+  invariant(/^[a-z0-9][a-z0-9.-]{0,127}$/u.test(environment), 'IDP_BINDING_ENVIRONMENT_INVALID', `Binding environment不符合v1合同：${environment}`);
+  return {
+    apiVersion: 'infrastructure.bench.dev/v1',
+    kind: 'ServiceBinding',
+    metadata: { id, consumer, environment },
+    spec: { capability, offering, profile, configuration, fileRefs },
+  };
+}
+
+export function buildManagedBindings({ env, activeServices }) {
+  const active = new Set(activeServices);
+  const bindings = [];
+  if (active.has('tech') && active.has('edge')) {
+    const tlsEnabled = env.IDP_TLS_ENABLED === 'true';
+    const scheme = tlsEnabled ? 'https' : 'http';
+    const port = tlsEnabled ? env.IDP_HTTPS_PORT : env.IDP_HTTP_PORT;
+    const publicBaseUrl = `${scheme}://${urlAuthority(env.IDP_PUBLIC_HOST)}:${port}/knowledge`;
+    const parsed = new URL(publicBaseUrl);
+    invariant(!parsed.username && !parsed.password && !parsed.search && !parsed.hash, 'IDP_BINDING_EDGE_URL_INVALID', 'Tech Edge Binding URL不能包含凭据、查询参数或片段');
+    const fileRefs = tlsEnabled ? {
+      certs: { certificate: assertFileReference(env.IDP_TLS_CERT_FILE, 'certs', 'TLS证书Binding引用') },
+      secrets: { privateKey: assertFileReference(env.IDP_TLS_KEY_FILE, 'secrets', 'TLS私钥Binding引用') },
+    } : {};
+    bindings.push({
+      path: 'tech/edge.yaml',
+      document: makeBinding({
+        id: bindingId(env.IDP_INSTANCE_ID, 'tech-edge'), consumer: 'tech', environment: env.IDP_ENVIRONMENT,
+        capability: 'network.edge-http-tls', offering: 'edge.standard-http-tls', profile: 'edge.http-tls',
+        configuration: { publicBaseUrl, httpEnabled: env.IDP_HTTP_ENABLED === 'true', tlsEnabled }, fileRefs,
+      }),
+    });
+  }
+  if (active.has('tech') && active.has('postgresql')) {
+    bindings.push({
+      path: 'tech/postgresql.yaml',
+      document: makeBinding({
+        id: bindingId(env.IDP_INSTANCE_ID, 'tech-postgresql'), consumer: 'tech', environment: env.IDP_ENVIRONMENT,
+        capability: 'data.postgresql', offering: 'postgresql.standard', profile: 'postgresql.database',
+        configuration: { endpoint: 'postgresql', port: 5432, database: 'tech', username: 'tech', sslMode: 'disable', authMode: 'password' },
+        fileRefs: { secrets: { password: assertFileReference(env.IDP_POSTGRES_TECH_PASSWORD_FILE, 'secrets', 'Tech PostgreSQL密码Binding引用') } },
+      }),
+    });
+  }
+  if (active.has('registry')) {
+    const registryUrl = `http://${urlAuthority(env.IDP_REGISTRY_BIND)}:${env.IDP_REGISTRY_PORT}`;
+    const parsed = new URL(registryUrl);
+    invariant(!parsed.username && !parsed.password && !parsed.search && !parsed.hash, 'IDP_BINDING_REGISTRY_URL_INVALID', 'Registry Binding URL不能包含凭据、查询参数或片段');
+    bindings.push({
+      path: 'bench/npm.yaml',
+      document: makeBinding({
+        id: bindingId(env.IDP_INSTANCE_ID, 'bench-npm'), consumer: 'bench', environment: env.IDP_ENVIRONMENT,
+        capability: 'artifact.npm-registry', offering: 'npm.standard-registry', profile: 'npm.registry',
+        configuration: { registryUrl, scopes: registryPrivateScopes(env), authMode: 'anonymous-read', alwaysAuth: false },
+      }),
+    });
+  }
+  return bindings.sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+}
+
+function yamlScalar(value) {
+  if (typeof value === 'string') return JSON.stringify(value);
+  if (typeof value === 'boolean' || typeof value === 'number') return String(value);
+  if (Array.isArray(value)) return JSON.stringify(value);
+  throw new IdpError('IDP_BINDING_YAML_VALUE_INVALID', '生成Binding时遇到不支持的YAML值');
+}
+
+function yamlObject(value, depth = 0) {
+  const lines = [];
+  const prefix = '  '.repeat(depth);
+  for (const [key, child] of Object.entries(value)) {
+    invariant(/^[A-Za-z][A-Za-z0-9]*$/u.test(key), 'IDP_BINDING_YAML_KEY_INVALID', `生成Binding时遇到不安全的YAML键：${key}`);
+    if (child && typeof child === 'object' && !Array.isArray(child)) {
+      const keys = Object.keys(child);
+      if (keys.length === 0) lines.push(`${prefix}${key}: {}`);
+      else lines.push(`${prefix}${key}:`, ...yamlObject(child, depth + 1));
+    } else lines.push(`${prefix}${key}: ${yamlScalar(child)}`);
+  }
+  return lines;
+}
+
+export function renderServiceBinding(document) {
+  return `${yamlObject(document).join('\n')}\n`;
+}
+
+function validateManagedDirectory(target) {
+  try {
+    assertOwnedDirectory(target, 'idp-deploy受管Binding目录');
+    const manifestPath = path.join(target, MANIFEST_FILE);
+    assertOwnedRegularFile(manifestPath, 'idp-deploy受管Binding Manifest');
+    let manifest;
+    try { manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); }
+    catch { throw new IdpError('IDP_BINDING_MANAGED_DRIFT', '受管Binding Manifest不是有效JSON，拒绝覆盖'); }
+    invariant(
+      manifest && typeof manifest === 'object' && !Array.isArray(manifest) && stableJson(Object.keys(manifest).sort()) === stableJson([...MANIFEST_KEYS].sort()),
+      'IDP_BINDING_MANAGED_DRIFT', '受管Binding Manifest字段已变化，拒绝覆盖',
+    );
+    const { digest, ...body } = manifest;
+    const { planDigest, ...planState } = body;
+    invariant(
+      manifest.schemaVersion === 1 && manifest.owner === 'idp-deploy' && /^sha256:[0-9a-f]{64}$/u.test(manifest.planDigest ?? '') &&
+      /^sha256:[0-9a-f]{64}$/u.test(digest ?? '') && sha256(stableJson(body)) === digest &&
+      sha256(stableJson({ ...planState, target: MANAGED_DIRECTORY })) === planDigest && Array.isArray(manifest.files),
+      'IDP_BINDING_MANAGED_DRIFT', '受管Binding Manifest合同或摘要无效，拒绝覆盖',
+    );
+    const actual = inventoryDirectory(target).filter((entry) => entry.path !== MANIFEST_FILE);
+    for (const entry of actual) {
+      invariant(!entry.unsupported, 'IDP_BINDING_MANAGED_DRIFT', '受管Binding目录包含链接或特殊文件，拒绝覆盖');
+      assertOwnedRegularFile(path.join(target, entry.path), `受管Binding ${entry.path}`);
+    }
+    const visitDirectories = (directory) => {
+      assertOwnedDirectory(directory, 'idp-deploy受管Binding子目录');
+      for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+        if (entry.isDirectory()) visitDirectories(path.join(directory, entry.name));
+      }
+    };
+    visitDirectories(target);
+    invariant(stableJson(actual) === stableJson(manifest.files), 'IDP_BINDING_MANAGED_DRIFT', '受管Binding文件被新增、删除或修改，拒绝覆盖');
+    return manifest;
+  } catch (error) {
+    if (error?.code === 'IDP_BINDING_MANAGED_DRIFT') throw error;
+    throw new IdpError('IDP_BINDING_MANAGED_DRIFT', `受管Binding目录不再符合上次发布状态，拒绝覆盖：${error.message}`);
+  }
+}
+
+function buildRollbackToken({ profile, currentManifest, previousManifest, preimage }) {
+  const action = previousManifest ? 'restore' : 'remove';
+  const body = {
+    schemaVersion: 1,
+    target: MANAGED_DIRECTORY,
+    profile,
+    action,
+    expectedCurrentDigest: currentManifest.digest,
+    preimage: previousManifest ? { path: preimage, digest: previousManifest.digest } : null,
+  };
+  return { ...body, digest: sha256(stableJson(body)) };
+}
+
+function validateRollbackToken(token) {
+  exactKeys(token, ROLLBACK_TOKEN_KEYS, 'IDP_BINDING_ROLLBACK_TOKEN_INVALID', 'Binding回滚令牌');
+  const { digest, ...body } = token;
+  invariant(
+    token.schemaVersion === 1 && token.target === MANAGED_DIRECTORY &&
+    ['remove', 'restore'].includes(token.action) && DIGEST_PATTERN.test(token.expectedCurrentDigest ?? '') &&
+    DIGEST_PATTERN.test(digest ?? '') && sha256(stableJson(body)) === digest,
+    'IDP_BINDING_ROLLBACK_TOKEN_INVALID',
+    'Binding回滚令牌合同或摘要无效',
+  );
+  resolveProfile(token.profile);
+  if (token.action === 'remove') {
+    invariant(token.preimage === null, 'IDP_BINDING_ROLLBACK_TOKEN_INVALID', '首次创建Binding的回滚令牌不能声明Preimage');
+  } else {
+    exactKeys(token.preimage, ['digest', 'path'], 'IDP_BINDING_ROLLBACK_TOKEN_INVALID', 'Binding回滚Preimage');
+    invariant(
+      DIGEST_PATTERN.test(token.preimage.digest ?? '') &&
+      /^snapshots\/binding-preimages\/[A-Za-z0-9-]+$/u.test(token.preimage.path ?? ''),
+      'IDP_BINDING_ROLLBACK_TOKEN_INVALID',
+      'Binding回滚Preimage引用或摘要无效',
+    );
+  }
+  return token;
+}
+
+function cloneManagedDirectory(source, target, expectedDigest) {
+  const before = validateManagedDirectory(source);
+  invariant(before.digest === expectedDigest, 'IDP_BINDING_ROLLBACK_PREIMAGE_INVALID', 'Binding Preimage摘要与回滚令牌不一致');
+  invariant(!fs.existsSync(target), 'IDP_BINDING_ROLLBACK_STAGING_COLLISION', 'Binding回滚暂存目录已存在');
+  fs.mkdirSync(target, { mode: 0o700 });
+  const copyDirectory = (sourceDirectory, targetDirectory) => {
+    for (const entry of fs.readdirSync(sourceDirectory, { withFileTypes: true })) {
+      const sourceEntry = path.join(sourceDirectory, entry.name);
+      const targetEntry = path.join(targetDirectory, entry.name);
+      if (entry.isDirectory()) {
+        assertOwnedDirectory(sourceEntry, 'Binding Preimage子目录');
+        fs.mkdirSync(targetEntry, { mode: 0o700 });
+        copyDirectory(sourceEntry, targetEntry);
+      } else {
+        assertOwnedRegularFile(sourceEntry, 'Binding Preimage文件');
+        createExclusiveFile(targetEntry, fs.readFileSync(sourceEntry), 0o600);
+      }
+    }
+    fsyncDirectory(targetDirectory);
+  };
+  try {
+    copyDirectory(source, target);
+    const sourceAfter = validateManagedDirectory(source);
+    const copied = validateManagedDirectory(target);
+    invariant(
+      sourceAfter.digest === expectedDigest && copied.digest === expectedDigest,
+      'IDP_BINDING_ROLLBACK_PREIMAGE_INVALID',
+      'Binding Preimage在回滚候选创建期间发生变化',
+    );
+    return copied;
+  } catch (error) {
+    if (fs.existsSync(target)) fs.rmSync(target, { recursive: true, force: true });
+    if (error?.code?.startsWith('IDP_BINDING_ROLLBACK_')) throw error;
+    throw new IdpError('IDP_BINDING_ROLLBACK_PREIMAGE_INVALID', `Binding Preimage不安全或无法复制：${error.message}`);
+  }
+}
+
+function materializePlan({ staging, bindings, profile, env, report, activeState, verifyReceipt }) {
+  ensurePrivateDirectory(staging, 'Binding暂存目录');
+  for (const binding of bindings) {
+    const target = path.join(staging, binding.path);
+    ensurePrivateDirectory(path.dirname(target), 'Binding暂存子目录');
+    createExclusiveFile(target, renderServiceBinding(binding.document), 0o600);
+  }
+  const files = inventoryDirectory(staging);
+  const planFacts = {
+    schemaVersion: 1, owner: 'idp-deploy', target: MANAGED_DIRECTORY, profile,
+    environment: env.IDP_ENVIRONMENT, instanceId: env.IDP_INSTANCE_ID, configDigest: report.digest,
+    activeProfileDigest: activeState.digest, verifyReceiptDigest: verifyReceipt.digest, files,
+  };
+  const planDigest = sha256(stableJson(planFacts));
+  const stateBody = { ...planFacts, planDigest };
+  delete stateBody.target;
+  const manifest = { ...stateBody, digest: sha256(stableJson(stateBody)) };
+  createExclusiveFile(path.join(staging, MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`, 0o600);
+  fsyncDirectory(staging);
+  return { planDigest, manifest };
+}
+
+function publishPlan({ root, target, staging, expectedCurrent }) {
+  const preimages = resolveContained(root, 'snapshots/binding-preimages', 'Binding Preimage目录');
+  ensurePrivateDirectory(preimages, 'Binding Preimage目录');
+  let preimage = null;
+  let previousMoved = false;
+  let published = false;
+  try {
+    if (expectedCurrent) {
+      const current = validateManagedDirectory(target);
+      invariant(current.digest === expectedCurrent.digest, 'IDP_BINDING_MANAGED_DRIFT', '受管Binding在Plan创建后发生变化，拒绝覆盖');
+      const stamp = new Date().toISOString().replace(/[:.]/gu, '-');
+      preimage = path.join(preimages, `${stamp}-${expectedCurrent.planDigest.slice(7, 19)}-${crypto.randomUUID()}`);
+      fs.renameSync(target, preimage);
+      previousMoved = true;
+      fsyncDirectory(preimages);
+    } else {
+      invariant(!fs.existsSync(target), 'IDP_BINDING_MANAGED_DRIFT', '受管Binding目录在Plan创建后被其他进程创建，拒绝覆盖');
+    }
+    fs.renameSync(staging, target);
+    published = true;
+    fsyncDirectory(path.dirname(target));
+  } catch (error) {
+    let rollbackError;
+    try {
+      if (published && fs.existsSync(target)) {
+        invariant(!fs.existsSync(staging), 'IDP_BINDING_ROLLBACK_COLLISION', 'Binding回滚暂存路径已被占用');
+        fs.renameSync(target, staging);
+        published = false;
+      }
+      if (previousMoved && preimage && fs.existsSync(preimage)) fs.renameSync(preimage, target);
+      fsyncDirectory(path.dirname(target));
+    } catch (failure) { rollbackError = failure; }
+    if (rollbackError) {
+      throw new IdpError('IDP_BINDING_ROLLBACK_FAILED', `Binding发布失败且Preimage回滚未完成：${rollbackError.message}`, { originalError: error.message });
+    }
+    if (error?.code === 'IDP_BINDING_MANAGED_DRIFT') throw error;
+    throw new IdpError('IDP_BINDING_PUBLISH_FAILED', `Binding发布失败，原配置已恢复：${error.message}`);
+  } finally {
+    if (fs.existsSync(staging)) fs.rmSync(staging, { recursive: true, force: true });
+  }
+  return preimage ? path.relative(root, preimage) : null;
+}
+
+function rollbackCurrent(target, expectedDigest) {
+  try {
+    invariant(fs.existsSync(target), 'IDP_BINDING_ROLLBACK_CAS_CONFLICT', '待回滚的受管Binding目录已不存在');
+    const current = validateManagedDirectory(target);
+    invariant(
+      current.digest === expectedDigest,
+      'IDP_BINDING_ROLLBACK_CAS_CONFLICT',
+      '受管Binding在同步完成后被用户或其他进程修改，拒绝回滚覆盖',
+    );
+    return current;
+  } catch (error) {
+    if (error?.code === 'IDP_BINDING_ROLLBACK_CAS_CONFLICT') throw error;
+    throw new IdpError(
+      'IDP_BINDING_ROLLBACK_CAS_CONFLICT',
+      `受管Binding在同步完成后不再符合CAS前置状态，拒绝回滚覆盖：${error.message}`,
+    );
+  }
+}
+
+function rollbackPreimage(target, expectedDigest) {
+  try {
+    const preimage = validateManagedDirectory(target);
+    invariant(preimage.digest === expectedDigest, 'IDP_BINDING_ROLLBACK_PREIMAGE_INVALID', 'Binding Preimage摘要与回滚令牌不一致');
+    return preimage;
+  } catch (error) {
+    if (error?.code === 'IDP_BINDING_ROLLBACK_PREIMAGE_INVALID') throw error;
+    throw new IdpError('IDP_BINDING_ROLLBACK_PREIMAGE_INVALID', `Binding Preimage不安全或已漂移，拒绝回滚：${error.message}`);
+  }
+}
+
+/**
+ * 使用syncManagedBindings返回的rollback令牌恢复受管Binding。
+ * Preimage只会被验证与复制，不会被移动、覆盖或删除。
+ */
+export function rollbackManagedBindingsCas({ configRoot, rollback, instanceLease }) {
+  const token = validateRollbackToken(rollback);
+  const preliminary = doctorConfig(configRoot, { requireConfigured: false, profile: token.profile });
+  return withInstanceLock(preliminary.root, preliminary.env, `bindings:rollback:${token.profile}`, () => {
+    const root = preliminary.root;
+    const bindingsRoot = resolveContained(root, 'bindings', 'Binding根目录');
+    assertOwnedDirectory(bindingsRoot, 'Binding根目录');
+    let target;
+    try { target = resolveContained(root, MANAGED_DIRECTORY, 'idp-deploy受管Binding目录'); }
+    catch (error) {
+      throw new IdpError('IDP_BINDING_ROLLBACK_CAS_CONFLICT', `待回滚的受管Binding路径不安全，拒绝覆盖：${error.message}`);
+    }
+    rollbackCurrent(target, token.expectedCurrentDigest);
+
+    let preimagePath = null;
+    let staging = null;
+    if (token.action === 'restore') {
+      try {
+        preimagePath = resolveContained(root, token.preimage.path, 'Binding回滚Preimage');
+        rollbackPreimage(preimagePath, token.preimage.digest);
+      } catch (error) {
+        if (error?.code === 'IDP_BINDING_ROLLBACK_PREIMAGE_INVALID') throw error;
+        throw new IdpError('IDP_BINDING_ROLLBACK_PREIMAGE_INVALID', `Binding Preimage不安全或已漂移，拒绝回滚：${error.message}`);
+      }
+      staging = resolveContained(root, `imports/.idp-deploy-binding-rollback-${process.pid}-${crypto.randomUUID()}`, 'Binding回滚暂存目录');
+      cloneManagedDirectory(preimagePath, staging, token.preimage.digest);
+    }
+
+    const forwardRoot = resolveContained(root, 'snapshots/binding-rollback-forwards', 'Binding回滚前向快照目录');
+    ensurePrivateDirectory(forwardRoot, 'Binding回滚前向快照目录');
+    const stamp = new Date().toISOString().replace(/[:.]/gu, '-');
+    const forward = path.join(forwardRoot, `${stamp}-${token.expectedCurrentDigest.slice(7, 19)}-${crypto.randomUUID()}`);
+    let currentMoved = false;
+    let restoredPublished = false;
+    try {
+      fs.renameSync(target, forward);
+      currentMoved = true;
+      fsyncDirectory(bindingsRoot);
+      const moved = rollbackCurrent(forward, token.expectedCurrentDigest);
+      if (token.action === 'restore') {
+        rollbackPreimage(preimagePath, token.preimage.digest);
+        invariant(!fs.existsSync(target), 'IDP_BINDING_ROLLBACK_TARGET_COLLISION', 'Binding回滚目标被其他进程重新创建');
+        fs.renameSync(staging, target);
+        restoredPublished = true;
+        fsyncDirectory(bindingsRoot);
+        const restored = validateManagedDirectory(target);
+        invariant(restored.digest === token.preimage.digest, 'IDP_BINDING_ROLLBACK_RESTORE_INVALID', '恢复后的Binding摘要与Preimage不一致');
+        rollbackPreimage(preimagePath, token.preimage.digest);
+      }
+      fsyncDirectory(forwardRoot);
+      return {
+        schemaVersion: 1,
+        status: token.action === 'restore' ? 'restored' : 'removed',
+        profile: token.profile,
+        target: MANAGED_DIRECTORY,
+        restoredDigest: token.action === 'restore' ? token.preimage.digest : null,
+        preimage: token.preimage?.path ?? null,
+        forwardImage: path.relative(root, forward),
+        rolledBackDigest: moved.digest,
+      };
+    } catch (error) {
+      let recoveryError;
+      try {
+        if (restoredPublished && fs.existsSync(target)) {
+          const restored = validateManagedDirectory(target);
+          invariant(
+            restored.digest === token.preimage.digest,
+            'IDP_BINDING_ROLLBACK_RECOVERY_CONFLICT',
+            '回滚恢复目录已被并发修改，拒绝覆盖；前向快照仍被保留',
+          );
+          invariant(!fs.existsSync(staging), 'IDP_BINDING_ROLLBACK_STAGING_COLLISION', 'Binding回滚暂存路径被并发占用');
+          fs.renameSync(target, staging);
+          restoredPublished = false;
+        }
+        if (currentMoved && fs.existsSync(forward)) {
+          invariant(!fs.existsSync(target), 'IDP_BINDING_ROLLBACK_RECOVERY_CONFLICT', 'Binding目标被并发创建，拒绝覆盖；前向快照仍被保留');
+          fs.renameSync(forward, target);
+          currentMoved = false;
+        }
+        fsyncDirectory(bindingsRoot);
+      } catch (failure) { recoveryError = failure; }
+      if (recoveryError) {
+        throw new IdpError(
+          'IDP_BINDING_ROLLBACK_FAILED',
+          `Binding CAS回滚失败且无法安全恢复回滚前状态：${recoveryError.message}`,
+          { originalError: error.message, forwardImage: path.relative(root, forward) },
+        );
+      }
+      if (error?.code?.startsWith('IDP_BINDING_ROLLBACK_')) throw error;
+      throw new IdpError('IDP_BINDING_ROLLBACK_FAILED', `Binding CAS回滚失败，已恢复回滚前状态：${error.message}`);
+    } finally {
+      if (staging && fs.existsSync(staging)) fs.rmSync(staging, { recursive: true, force: true });
+    }
+  }, { lease: instanceLease });
+}
+
+export function syncManagedBindings({ configRoot, profile, instanceLease }) {
+  const preliminary = doctorConfig(configRoot, { requireConfigured: true, profile });
+  const { root } = preliminary;
+  const activeServices = resolveProfile(profile);
+  return withInstanceLock(root, preliminary.env, `bindings:sync:${profile}`, () => {
+    const { env, report } = doctorConfig(root, { requireConfigured: true, profile });
+    invariant(report.digest === preliminary.report.digest, 'IDP_BINDING_CONFIG_CHANGED_DURING_PLAN', 'Config Dir在Binding Plan创建期间发生变化，拒绝写入');
+    const activeState = readActiveProfileState(env);
+    invariant(activeState, 'IDP_BINDING_ACTIVE_PROFILE_MISSING', '尚无活动Profile运行事实；请先执行idpctl switch或up');
+    invariant(activeState.status === 'active' && activeState.profile === profile, 'IDP_BINDING_ACTIVE_PROFILE_MISMATCH', `活动Profile为${activeState.status}/${activeState.profile}，不能生成${profile} Binding`);
+    invariant(activeState.configDigest === report.digest, 'IDP_BINDING_DEPLOYED_CONFIG_DRIFT', '当前Config Dir已变化但尚未重新部署，拒绝生成过期或虚假的Binding');
+    invariant(stableJson(activeState.services) === stableJson(resolveProfileServices(profile)), 'IDP_BINDING_ACTIVE_SERVICES_MISMATCH', '活动Profile服务集合与目标Profile不一致');
+    const verifyReceipt = readLatestVerifyEvidence(env, {
+      profile, configDigest: report.digest, renderDigest: activeState.renderDigest, activeUpdatedAt: activeState.updatedAt,
+    });
+    const bindings = buildManagedBindings({ env, activeServices });
+    invariant(bindings.length > 0, 'IDP_BINDING_NO_MANAGED_CAPABILITY', `${profile}没有当前部署控制面可以真实声明的Bench Binding`);
+
+    const bindingsRoot = resolveContained(root, 'bindings', 'Binding根目录');
+    assertOwnedDirectory(bindingsRoot, 'Binding根目录');
+    const target = resolveContained(root, MANAGED_DIRECTORY, 'idp-deploy受管Binding目录');
+    const expectedCurrent = fs.existsSync(target) ? validateManagedDirectory(target) : null;
+    const staging = resolveContained(root, `imports/.idp-deploy-bindings-${process.pid}-${crypto.randomUUID()}`, 'Binding暂存目录');
+    const { planDigest, manifest } = materializePlan({ staging, bindings, profile, env, report, activeState, verifyReceipt });
+    if (expectedCurrent?.planDigest === planDigest) {
+      const current = validateManagedDirectory(target);
+      invariant(current.digest === expectedCurrent.digest, 'IDP_BINDING_MANAGED_DRIFT', '受管Binding在Plan创建后发生变化，拒绝返回未变更状态');
+      fs.rmSync(staging, { recursive: true, force: true });
+      return {
+        schemaVersion: 1, status: 'unchanged', profile, environment: env.IDP_ENVIRONMENT,
+        target: MANAGED_DIRECTORY, planDigest, preimage: null, rollback: null,
+        bindings: bindings.map(({ path: filePath, document }) => ({ path: filePath, id: document.metadata.id, profile: document.spec.profile })),
+      };
+    }
+    const preimage = publishPlan({ root, target, staging, expectedCurrent });
+    const rollback = buildRollbackToken({ profile, currentManifest: manifest, previousManifest: expectedCurrent, preimage });
+    return {
+      schemaVersion: 1, status: expectedCurrent ? 'updated' : 'created', profile, environment: env.IDP_ENVIRONMENT,
+      target: MANAGED_DIRECTORY, planDigest: manifest.planDigest, preimage, rollback,
+      bindings: bindings.map(({ path: filePath, document }) => ({ path: filePath, id: document.metadata.id, profile: document.spec.profile })),
+    };
+  }, { lease: instanceLease });
+}