@twin3-ai/agent-id 0.1.0

package/installer.js

@@ -0,0 +1,722 @@
+"use strict";
+
+const fs = require("node:fs/promises");
+const path = require("node:path");
+const crypto = require("node:crypto");
+const { DEFAULT_ENDPOINT } = require("./runtime-config.js");
+
+const INSTALL_SCHEMA = "agentx-install-plan-v1";
+const STATE_SCHEMA = "agentx-site-agent-install-state-v1";
+const MANAGED_DIR = ".agent-id";
+const SECRET_IGNORE = "*\n!.gitignore\n";
+
+function installError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function normalizeProjectRoot(projectRoot = process.cwd()) {
+  const root = path.resolve(String(projectRoot));
+  if (!path.isAbsolute(root)) throw installError("INVALID_PROJECT_ROOT", "Project root must be an absolute path.");
+  return root;
+}
+
+function normalizeSiteUrl(value) {
+  let parsed;
+  try {
+    parsed = new URL(String(value || ""));
+  } catch (_err) {
+    throw installError("INVALID_SITE_URL", "Site URL must be a valid http or https URL.");
+  }
+  if (!["http:", "https:"].includes(parsed.protocol) || parsed.username || parsed.password || !parsed.hostname) {
+    throw installError("INVALID_SITE_URL", "Site URL must be a public http or https URL without credentials.");
+  }
+  if (parsed.search || parsed.hash) throw installError("INVALID_SITE_URL", "Site URL must not contain a query string or fragment.");
+  parsed.pathname = parsed.pathname.replace(/\/{2,}/g, "/").replace(/\/$/, "") || "/";
+  return parsed.toString().replace(/\/$/, "") || parsed.origin;
+}
+
+async function readJson(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+async function detectProject({ projectRoot = process.cwd(), fsImpl = fs } = {}) {
+  const root = normalizeProjectRoot(projectRoot);
+  const packageJson = await (async () => {
+    try { return JSON.parse(await fsImpl.readFile(path.join(root, "package.json"), "utf8")); }
+    catch (error) { return error.code === "ENOENT" ? null : (() => { throw error; })(); }
+  })();
+  const dependencies = {
+    ...(packageJson && packageJson.dependencies ? packageJson.dependencies : {}),
+    ...(packageJson && packageJson.devDependencies ? packageJson.devDependencies : {})
+  };
+  const exists = async (name) => {
+    try { await fsImpl.access(path.join(root, name)); return true; }
+    catch (_err) { return false; }
+  };
+  const dependencyNames = Object.keys(dependencies);
+  const hasStaticEntry = await exists("index.html") || await exists("public/index.html");
+  const cliOnlyStaticSite = Boolean(
+    packageJson
+    && hasStaticEntry
+    && dependencyNames.length > 0
+    && dependencyNames.every((name) => name === "@twin3-ai/agent-id")
+  );
+  const framework = dependencies.next ? "next"
+    : dependencies.nuxt ? "nuxt"
+      : dependencies.astro ? "astro"
+        : dependencies.gatsby ? "gatsby"
+          : dependencies.svelte || dependencies["@sveltejs/kit"] ? "svelte"
+            : dependencies.vite ? "vite"
+              : cliOnlyStaticSite ? "static"
+                : packageJson ? "node" : "static";
+  const packageManager = await exists("pnpm-lock.yaml") ? "pnpm"
+    : await exists("yarn.lock") ? "yarn"
+      : await exists("bun.lockb") || await exists("bun.lock") ? "bun"
+        : packageJson ? "npm" : "none";
+  const detectedFiles = [];
+  for (const name of ["package.json", "pnpm-lock.yaml", "yarn.lock", "bun.lock", "package-lock.json"]) {
+    if (await exists(name)) detectedFiles.push(name);
+  }
+  return {
+    project_root: root,
+    framework,
+    package_manager: packageManager,
+    package_name: packageJson && typeof packageJson.name === "string" ? packageJson.name : "",
+    detected_files: detectedFiles
+  };
+}
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stableValue(value[key])]));
+}
+
+function stableJson(value) {
+  return JSON.stringify(stableValue(value));
+}
+
+function hashText(value) {
+  return `sha256:${crypto.createHash("sha256").update(value).digest("hex")}`;
+}
+
+function runtimeTemplate() {
+  return `"use strict";
+
+// Server-side only helper. Keep SITE_AGENT_KEY in the host secret store.
+const { createSiteAgentClient } = require("@twin3-ai/agent-id");
+
+function createAgentIdRuntime(options = {}) {
+  return createSiteAgentClient({
+    endpoint: options.endpoint || process.env.AGENT_ID_ENDPOINT,
+    agentKey: options.agentKey || process.env.SITE_AGENT_KEY
+  });
+}
+
+module.exports = { createAgentIdRuntime };
+`;
+}
+
+function staticRunnerTemplate(siteUrl) {
+  return `"use strict";
+
+const fs = require("node:fs/promises");
+const path = require("node:path");
+
+const SITE_URL = process.env.SITE_URL || ${JSON.stringify(siteUrl)};
+const AGENT_ID_ENDPOINT = String(process.env.AGENT_ID_ENDPOINT || "").replace(/\\/+$/, "");
+const SITE_AGENT_KEY = process.env.SITE_AGENT_KEY || "";
+const SYNC_MODE = process.env.AGENT_ID_SYNC_MODE || "full";
+
+function redact(value) {
+  if (Array.isArray(value)) return value.map(redact);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+    key,
+    /key|token|secret|authorization/i.test(key) ? "[REDACTED]" : redact(item)
+  ]));
+}
+
+async function call(action, payload = {}) {
+  const response = await fetch(AGENT_ID_ENDPOINT + "/api/site_agents/call", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ ...payload, url: SITE_URL, action, agent_key: SITE_AGENT_KEY })
+  });
+  const text = await response.text();
+  let body;
+  try { body = JSON.parse(text || "{}"); } catch (_error) { body = { text }; }
+  if (!response.ok || body.ok === false) {
+    const error = new Error("Agent ID sync failed: " + response.status);
+    error.status = response.status;
+    error.body = redact(body);
+    throw error;
+  }
+  return body;
+}
+
+async function main() {
+  if (!AGENT_ID_ENDPOINT) throw new Error("AGENT_ID_ENDPOINT is required. Use the stable Agent ID API domain supplied by the service owner.");
+  if (!SITE_AGENT_KEY) throw new Error("SITE_AGENT_KEY is required in the customer-owned runner environment.");
+  if (!["heartbeat", "monthly", "full"].includes(SYNC_MODE)) throw new Error("AGENT_ID_SYNC_MODE must be heartbeat, monthly, or full.");
+  const observedAt = new Date().toISOString();
+  const heartbeat = SYNC_MODE === "monthly" ? { skipped: true, reason: "monthly_insights_run" } : await call("site_agent_events", {
+    source: "customer_owned_github_actions_runner",
+    events: [{ event: "heartbeat", url: SITE_URL, ts: Math.floor(Date.now() / 1000), data: { runtime: "github_actions", sdk_version: "0.1.0" } }]
+  });
+  const insights = SYNC_MODE === "heartbeat" ? { skipped: true, reason: "daily_heartbeat_only" } : await call("insights_feed", {
+    source: "customer_owned_github_actions_runner",
+    audit_url: true,
+    cadence: "monthly"
+  });
+  const report = redact({
+    schema: "agentx-customer-owned-sync-report-v1",
+    site_url: SITE_URL,
+    parent_endpoint: AGENT_ID_ENDPOINT,
+    observed_at: observedAt,
+    sync_mode: SYNC_MODE,
+    heartbeat,
+    insights,
+    authority: "advisory_only",
+    customer_approval_required_for_site_changes: true
+  });
+  const target = path.join(process.cwd(), ".agent-id/reports/latest.json");
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  await fs.writeFile(target, JSON.stringify(report, null, 2) + "\\n", "utf8");
+  process.stdout.write(JSON.stringify({ ok: true, report: ".agent-id/reports/latest.json", observed_at: observedAt }) + "\\n");
+}
+
+main().catch((error) => {
+  console.error(JSON.stringify({ ok: false, error: error.message, status: error.status || 0, details: error.body || null }));
+  process.exit(1);
+});
+`;
+}
+
+function staticWorkflowTemplate(siteUrl) {
+  return [
+    "name: Agent ID website sync",
+    "",
+    "on:",
+    "  workflow_dispatch:",
+    "  schedule:",
+    "    - cron: '17 2 * * *'",
+    "    - cron: '23 3 1 * *'",
+    "",
+    "permissions:",
+    "  contents: read",
+    "",
+    "jobs:",
+    "  sync:",
+    "    runs-on: ubuntu-latest",
+    "    timeout-minutes: 10",
+    "    steps:",
+    "      - uses: actions/checkout@v4",
+    "      - uses: actions/setup-node@v4",
+    "        with:",
+    "          node-version: '20'",
+    "      - name: Pull verified insights from Agent ID",
+    "        run: node .agent-id/runner.cjs",
+    "        env:",
+    `          SITE_URL: ${siteUrl}`,
+    "          AGENT_ID_ENDPOINT: ${{ vars.AGENT_ID_ENDPOINT }}",
+    "          AGENT_ID_SYNC_MODE: ${{ github.event_name == 'workflow_dispatch' && 'full' || github.event.schedule == '23 3 1 * *' && 'monthly' || 'heartbeat' }}",
+    "          SITE_AGENT_KEY: ${{ secrets.SITE_AGENT_KEY }}",
+    "      - name: Upload redacted sync report",
+    "        if: always()",
+    "        uses: actions/upload-artifact@v4",
+    "        with:",
+    "          name: agent-id-sync-report",
+    "          path: .agent-id/reports/latest.json",
+    "          if-no-files-found: error",
+    "          retention-days: 30",
+    ""
+  ].join("\n");
+}
+
+function readmeTemplate(siteUrl, framework, packageManager, endpoint) {
+  if (framework === "static") {
+    return `# Agent ID Site Agent installation
+
+- Site URL: ${siteUrl}
+- Parent service: ${endpoint}
+- Runtime: customer-owned GitHub Actions Runner
+
+## Required owner actions
+
+1. Publish the domain verification document returned by Agent ID.
+2. Verify domain ownership and obtain the Site Agent Key.
+3. Save the stable API origin as the repository variable \`AGENT_ID_ENDPOINT\`; do not use a Cloud Run revision URL.
+4. Save the key as the repository secret \`SITE_AGENT_KEY\`.
+5. Run the \`Agent ID website sync\` workflow once. Keep the daily heartbeat and monthly insights schedules enabled.
+6. Review the uploaded \`agent-id-sync-report\` artifact before approving website changes.
+
+The Runner sends a daily connection heartbeat. It pulls evidence-bound optimization insights on the first day of each month; a manual run performs both. It does not expose the key, commit code, deploy the site, or give Agent ID direct write access to this repository.
+`;
+  }
+  return `# Agent ID Site Agent installation
+
+- Site URL: ${siteUrl}
+- Detected framework: ${framework}
+- Detected package manager: ${packageManager}
+
+## Next steps
+
+1. Publish the domain verification file or DNS record returned by Agent ID.
+2. Run domain verification from the website owner environment.
+3. Install \`@twin3-ai/agent-id\` in the website server, Worker, CMS connector, or Agent runtime.
+4. Store the issued Site Agent Key as \`SITE_AGENT_KEY\` in the server secret store.
+5. Start \`agent-id-sync --url ${siteUrl} --once\` for a first evidence exchange.
+
+This directory contains only the local install state and a server-side helper template. It never contains a Site Agent Key, browser token, customer content, or deployment credentials. The Agent ID service does not receive direct write access to this website by installing this package.
+`;
+}
+
+function stateTemplate(plan) {
+  return {
+    schema: STATE_SCHEMA,
+    install_id: plan.install_id,
+    site_url: plan.site_url,
+    host: new URL(plan.site_url).hostname,
+    parent_endpoint: plan.parent_endpoint,
+    framework: plan.framework,
+    package_manager: plan.package_manager,
+    status: "installed",
+    verification_status: "pending_domain_verification",
+    requires_site_agent_key: true,
+    site_agent_key_storage: plan.framework === "static"
+      ? "github_actions_secret:SITE_AGENT_KEY"
+      : "server_secret_store:SITE_AGENT_KEY",
+    managed_paths: plan.files.map((file) => file.path),
+    no_direct_customer_site_mutation: true,
+    no_secret_in_state: true
+  };
+}
+
+function buildInstallPlan({ url, projectRoot = process.cwd(), endpoint = DEFAULT_ENDPOINT, framework, packageManager, detected } = {}) {
+  return Promise.resolve().then(async () => {
+    const siteUrl = normalizeSiteUrl(url);
+    const root = normalizeProjectRoot(projectRoot);
+    const detectedProject = detected || await detectProject({ projectRoot: root });
+    const selectedFramework = framework || detectedProject.framework;
+    const selectedPackageManager = packageManager || detectedProject.package_manager;
+    if (!/^[a-z][a-z0-9._-]{0,31}$/.test(String(selectedFramework))) throw installError("INVALID_FRAMEWORK", "Framework identifier is invalid.");
+    if (!/^[a-z][a-z0-9._-]{0,31}$/.test(String(selectedPackageManager))) throw installError("INVALID_PACKAGE_MANAGER", "Package manager identifier is invalid.");
+    const parentEndpoint = String(endpoint || DEFAULT_ENDPOINT).replace(/\/+$/, "");
+    const files = selectedFramework === "static" ? [
+      { path: `${MANAGED_DIR}/install-state.json`, mode: "private", content: "" },
+      { path: `${MANAGED_DIR}/runner.cjs`, mode: "customer_runner", content: staticRunnerTemplate(siteUrl, parentEndpoint) },
+      { path: `${MANAGED_DIR}/README.md`, mode: "documentation", content: readmeTemplate(siteUrl, selectedFramework, selectedPackageManager, parentEndpoint) },
+      { path: ".github/workflows/agent-id-sync.yml", mode: "customer_runner_workflow", content: staticWorkflowTemplate(siteUrl, parentEndpoint) }
+    ] : [
+      { path: `${MANAGED_DIR}/install-state.json`, mode: "private", content: "" },
+      { path: `${MANAGED_DIR}/site-agent.cjs`, mode: "server_helper", content: runtimeTemplate() },
+      { path: `${MANAGED_DIR}/README.md`, mode: "documentation", content: readmeTemplate(siteUrl, selectedFramework, selectedPackageManager, parentEndpoint) }
+    ];
+    const base = {
+      schema: INSTALL_SCHEMA,
+      version: 1,
+      site_url: siteUrl,
+      parent_endpoint: parentEndpoint,
+      project_root: root,
+      framework: selectedFramework,
+      package_manager: selectedPackageManager,
+      approval_required: true,
+      side_effects: selectedFramework === "static"
+        ? ["write_agent_id_namespace", "write_dedicated_github_actions_workflow"]
+        : ["write_only_agent_id_namespace"],
+      excluded_side_effects: ["package_install", "customer_content_change", "deployment", "secret_creation", "database_change", "default_branch_push"],
+      next_steps: selectedFramework === "static"
+        ? ["publish_domain_proof", "verify_domain_ownership", "store_SITE_AGENT_KEY_as_GitHub_Actions_secret", "run_customer_owned_sync_workflow"]
+        : ["verify_domain_ownership", "install_server_package", "store_SITE_AGENT_KEY_in_server_secret_store", "start_site_agent_sync"],
+      files: files.map(({ path: filePath, mode, content }) => ({ path: filePath, mode, sha256: hashText(content) }))
+    };
+    base.install_id = hashText(stableJson(base)).slice(0, 24);
+    base.files[0].sha256 = hashText(JSON.stringify(stateTemplate({ ...base, files: base.files }), null, 2) + "\n");
+    return Object.freeze({ ...base, files: files.map((file, index) => ({ ...base.files[index], content: file.content })) });
+  });
+}
+
+function validatePlan(plan) {
+  if (!plan || plan.schema !== INSTALL_SCHEMA || plan.approval_required !== true) throw installError("INVALID_INSTALL_PLAN", "The installation plan is invalid or missing approval metadata.");
+  const expectedCount = plan.framework === "static" ? 4 : 3;
+  if (!Array.isArray(plan.files) || plan.files.length !== expectedCount) throw installError("INVALID_INSTALL_PLAN", `The installation plan must contain exactly ${expectedCount} managed files.`);
+  const root = normalizeProjectRoot(plan.project_root);
+  for (const file of plan.files) {
+    const allowedWorkflow = plan.framework === "static" && file && file.path === ".github/workflows/agent-id-sync.yml";
+    if (!file || typeof file.path !== "string" || path.isAbsolute(file.path) || file.path.split(/[\\/]+/).includes("..") || (!file.path.startsWith(`${MANAGED_DIR}/`) && !allowedWorkflow)) {
+      throw installError("UNSAFE_INSTALL_PATH", "Installation can only write managed Agent ID files and its dedicated GitHub Actions workflow.");
+    }
+  }
+  return root;
+}
+
+async function writeAtomic(filePath, content, mode) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true, mode: mode === "private" ? 0o700 : 0o755 });
+  const temp = `${filePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  try {
+    await fs.writeFile(temp, content, { encoding: "utf8", mode: mode === "private" ? 0o600 : 0o644 });
+    await fs.rename(temp, filePath);
+    await fs.chmod(filePath, mode === "private" ? 0o600 : 0o644);
+  } finally {
+    await fs.rm(temp, { force: true }).catch(() => {});
+  }
+}
+
+async function prepareEnterpriseSecretDirectory(projectRoot = process.cwd()) {
+  const root = normalizeProjectRoot(projectRoot);
+  const realRoot = await fs.realpath(root);
+  const managedDirectory = path.join(root, MANAGED_DIR);
+  let managedStat;
+  try { managedStat = await fs.lstat(managedDirectory); }
+  catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    await fs.mkdir(managedDirectory, { mode: 0o700 });
+    managedStat = await fs.lstat(managedDirectory);
+  }
+  if (managedStat.isSymbolicLink() || !managedStat.isDirectory()) {
+    throw installError("UNSAFE_ENTERPRISE_SECRET_DIRECTORY", "The .agent-id path must be a real directory.");
+  }
+  const realManagedDirectory = await fs.realpath(managedDirectory);
+  if (realManagedDirectory !== realRoot && !realManagedDirectory.startsWith(realRoot + path.sep)) {
+    throw installError("UNSAFE_ENTERPRISE_SECRET_DIRECTORY", "The .agent-id path must remain in the customer project.");
+  }
+  await fs.chmod(managedDirectory, 0o700);
+  const secretDirectory = path.join(managedDirectory, "secrets");
+  let directoryStat;
+  try { directoryStat = await fs.lstat(secretDirectory); }
+  catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    await fs.mkdir(secretDirectory, { mode: 0o700 });
+    directoryStat = await fs.lstat(secretDirectory);
+  }
+  const realSecretDirectory = await fs.realpath(secretDirectory);
+  if (
+    directoryStat.isSymbolicLink()
+    || !directoryStat.isDirectory()
+    || (realSecretDirectory !== realRoot && !realSecretDirectory.startsWith(realRoot + path.sep))
+  ) {
+    throw installError("UNSAFE_ENTERPRISE_SECRET_DIRECTORY", "Enterprise secrets must remain in the customer project.");
+  }
+  await fs.chmod(secretDirectory, 0o700);
+  const ignorePath = path.join(secretDirectory, ".gitignore");
+  let existingIgnore = null;
+  try { existingIgnore = await fs.readFile(ignorePath, "utf8"); }
+  catch (error) { if (error.code !== "ENOENT") throw error; }
+  if (existingIgnore !== null && existingIgnore !== SECRET_IGNORE) {
+    throw installError("ENTERPRISE_SECRET_IGNORE_CONFLICT", "Refusing to replace a customer-managed secret ignore file.");
+  }
+  if (existingIgnore === null) await writeAtomic(ignorePath, SECRET_IGNORE, "documentation");
+  return {
+    secret_directory: secretDirectory,
+    key_path: path.join(secretDirectory, "enterprise-ed25519.pem"),
+    credential_path: path.join(secretDirectory, "enterprise-credential.json")
+  };
+}
+
+async function writeEnterpriseBootstrapCredential(projectRoot, credential, bootstrapSecret) {
+  const details = credential && typeof credential === "object" ? credential : {};
+  const secret = String(bootstrapSecret || "");
+  const required = ["credential_id", "tenant_id", "host", "environment", "agent_id"];
+  if (required.some((field) => typeof details[field] !== "string" || !details[field]) || !secret.startsWith("bsc_")) {
+    throw installError("INVALID_ENTERPRISE_CREDENTIAL", "A complete bootstrap credential is required.");
+  }
+  const paths = await prepareEnterpriseSecretDirectory(projectRoot);
+  try {
+    await fs.lstat(paths.credential_path);
+    throw installError("ENTERPRISE_CREDENTIAL_CONFLICT", "Refusing to overwrite an existing enterprise credential.");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  const stored = {
+    schema: "agentx-customer-bootstrap-credential-v1",
+    credential_id: details.credential_id,
+    client_id: String(details.client_id || ""),
+    key_id: String(details.key_id || ""),
+    tenant_id: details.tenant_id,
+    host: details.host,
+    environment: details.environment,
+    agent_id: details.agent_id,
+    public_key_thumbprint: String(details.public_key_thumbprint || ""),
+    maximum_scopes: Array.isArray(details.maximum_scopes) ? [...details.maximum_scopes] : [],
+    status: String(details.status || "active"),
+    issued_at: Number(details.issued_at || 0),
+    expires_at: Number(details.expires_at || 0),
+    bootstrap_secret: secret
+  };
+  const serialized = JSON.stringify(stored, null, 2) + "\n";
+  if (/access_token|PRIVATE KEY/.test(serialized)) {
+    throw installError("ENTERPRISE_CREDENTIAL_CONTENT_INVALID", "Credential storage cannot contain access tokens or private keys.");
+  }
+  await writeAtomic(paths.credential_path, serialized, "private");
+  return {
+    schema: "agentx-enterprise-credential-write-receipt-v1",
+    credential_id: stored.credential_id,
+    credential_path: paths.credential_path,
+    mode: "0600",
+    secret_persisted_locally: true
+  };
+}
+
+async function replaceEnterpriseBootstrapCredential(projectRoot, credential, bootstrapSecret, expectedCredentialId) {
+  const existing = await readEnterpriseBootstrapCredential(projectRoot);
+  if (!existing || existing.credential.credential_id !== String(expectedCredentialId || "")) {
+    throw installError("ENTERPRISE_CREDENTIAL_REPLACEMENT_MISMATCH", "The local credential changed before rotation could be committed.");
+  }
+  const details = credential && typeof credential === "object" ? credential : {};
+  const secret = String(bootstrapSecret || "");
+  const required = ["credential_id", "tenant_id", "host", "environment", "agent_id", "public_key_thumbprint"];
+  if (required.some((field) => typeof details[field] !== "string" || !details[field]) || !secret.startsWith("bsc_")) {
+    throw installError("INVALID_ENTERPRISE_CREDENTIAL", "A complete replacement credential is required.");
+  }
+  for (const field of ["tenant_id", "host", "environment", "agent_id", "public_key_thumbprint"]) {
+    if (details[field] !== existing.credential[field]) {
+      throw installError("ENTERPRISE_CREDENTIAL_REPLACEMENT_MISMATCH", `Replacement credential changed ${field}.`);
+    }
+  }
+  const stored = {
+    schema: "agentx-customer-bootstrap-credential-v1",
+    credential_id: details.credential_id,
+    client_id: String(details.client_id || ""),
+    key_id: String(details.key_id || ""),
+    tenant_id: details.tenant_id,
+    host: details.host,
+    environment: details.environment,
+    agent_id: details.agent_id,
+    public_key_thumbprint: details.public_key_thumbprint,
+    maximum_scopes: Array.isArray(details.maximum_scopes) ? [...details.maximum_scopes] : [],
+    status: String(details.status || "active"),
+    issued_at: Number(details.issued_at || 0),
+    expires_at: Number(details.expires_at || 0),
+    bootstrap_secret: secret
+  };
+  await writeAtomic(existing.credential_path, JSON.stringify(stored, null, 2) + "\n", "private");
+  return {
+    schema: "agentx-enterprise-credential-rotation-receipt-v1",
+    previous_credential_id: existing.credential.credential_id,
+    credential_id: stored.credential_id,
+    credential_path: existing.credential_path,
+    mode: "0600",
+    secret_replaced_atomically: true
+  };
+}
+
+async function removeEnterpriseBootstrapCredential(projectRoot, expectedCredentialId) {
+  const existing = await readEnterpriseBootstrapCredential(projectRoot);
+  if (!existing || existing.credential.credential_id !== String(expectedCredentialId || "")) {
+    throw installError("ENTERPRISE_CREDENTIAL_REVOKE_MISMATCH", "The local credential changed before revocation could be finalized.");
+  }
+  await fs.rm(existing.credential_path, { force: true });
+  return {
+    schema: "agentx-enterprise-credential-revocation-receipt-v1",
+    credential_id: existing.credential.credential_id,
+    credential_removed: true,
+    private_key_retained: true
+  };
+}
+
+async function readEnterpriseBootstrapCredential(projectRoot = process.cwd()) {
+  const paths = await prepareEnterpriseSecretDirectory(projectRoot);
+  const keyStat = await fs.lstat(paths.key_path).catch((error) => {
+    if (error.code === "ENOENT") throw installError("ENTERPRISE_PRIVATE_KEY_MISSING", "Enterprise private key is required before domain verification.");
+    throw error;
+  });
+  if (keyStat.isSymbolicLink() || !keyStat.isFile() || (keyStat.mode & 0o777) !== 0o600) {
+    throw installError("ENTERPRISE_PRIVATE_KEY_INVALID", "Enterprise private key must be a regular 0600 file.");
+  }
+  let stat;
+  try { stat = await fs.lstat(paths.credential_path); }
+  catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+  if (stat.isSymbolicLink() || !stat.isFile() || (stat.mode & 0o777) !== 0o600) {
+    throw installError("ENTERPRISE_CREDENTIAL_FILE_INVALID", "Enterprise credential must be a regular 0600 file.");
+  }
+  const credential = await readJson(paths.credential_path);
+  const required = ["credential_id", "tenant_id", "host", "environment", "agent_id", "public_key_thumbprint"];
+  if (
+    !credential
+    || credential.schema !== "agentx-customer-bootstrap-credential-v1"
+    || required.some((field) => typeof credential[field] !== "string" || !credential[field])
+    || !String(credential.bootstrap_secret || "").startsWith("bsc_")
+  ) {
+    throw installError("ENTERPRISE_CREDENTIAL_FILE_INVALID", "Enterprise credential is incomplete or invalid.");
+  }
+  return { credential, credential_path: paths.credential_path, key_path: paths.key_path };
+}
+
+function installContents(plan) {
+  const state = stateTemplate(plan);
+  return {
+    state,
+    contents: {
+      [`${MANAGED_DIR}/install-state.json`]: JSON.stringify(state, null, 2) + "\n",
+      [`${MANAGED_DIR}/site-agent.cjs`]: runtimeTemplate(),
+      [`${MANAGED_DIR}/runner.cjs`]: staticRunnerTemplate(plan.site_url),
+      [`${MANAGED_DIR}/README.md`]: readmeTemplate(plan.site_url, plan.framework, plan.package_manager, plan.parent_endpoint),
+      ".github/workflows/agent-id-sync.yml": staticWorkflowTemplate(plan.site_url)
+    }
+  };
+}
+
+async function inspectInstallPlan(plan) {
+  const root = validatePlan(plan);
+  const { state, contents } = installContents(plan);
+  const prepared = [];
+  for (const file of plan.files) {
+    const target = path.resolve(root, file.path);
+    if (target !== root && !target.startsWith(root + path.sep)) throw installError("UNSAFE_INSTALL_PATH", "Installation path escaped the project root.");
+    const content = contents[file.path];
+    if (typeof content !== "string" || hashText(content) !== file.sha256) throw installError("PLAN_CONTENT_MISMATCH", `Install plan content mismatch for ${file.path}.`);
+    let existing = null;
+    try { existing = await fs.readFile(target, "utf8"); } catch (error) { if (error.code !== "ENOENT") throw error; }
+    if (existing !== null && existing !== content) throw installError("INSTALL_CONFLICT", `Refusing to overwrite an existing file: ${file.path}`);
+    prepared.push({ file, target, content, existing });
+  }
+  return { root, state, prepared };
+}
+
+async function preflightInstallPlan(plan) {
+  const { prepared } = await inspectInstallPlan(plan);
+  return {
+    schema: "agentx-install-preflight-v1",
+    ok: true,
+    install_id: plan.install_id,
+    files: prepared.map(({ file, existing }) => ({ path: file.path, action: existing === null ? "create" : "unchanged" })),
+    side_effects: [],
+  };
+}
+
+async function applyInstallPlan(plan, { approved = false } = {}) {
+  if (approved !== true) throw installError("INSTALL_APPROVAL_REQUIRED", "Installation requires explicit approved=true.");
+  const { state, prepared } = await inspectInstallPlan(plan);
+  const result = { schema: "agentx-install-receipt-v1", install_id: plan.install_id, changed: false, files: [], state: state.status };
+  for (const { file, target, content, existing } of prepared) {
+    if (existing === null) {
+      await writeAtomic(target, content, file.mode);
+      result.changed = true;
+    }
+    result.files.push({ path: file.path, changed: existing === null, sha256: file.sha256 });
+  }
+  return result;
+}
+
+async function resumeInstall(projectRoot = process.cwd()) {
+  const root = normalizeProjectRoot(projectRoot);
+  const statePath = path.join(root, MANAGED_DIR, "install-state.json");
+  const state = await readJson(statePath);
+  if (!state || state.schema !== STATE_SCHEMA) return { schema: "agentx-install-status-v1", state: "not_installed", project_root: root, next_steps: ["build_install_plan"] };
+  return {
+    schema: "agentx-install-status-v1",
+    state: state.status || "unknown",
+    verification_status: state.verification_status || "pending_domain_verification",
+    site_url: state.site_url || "",
+    install_id: state.install_id || "",
+    project_root: root,
+    next_steps: state.framework === "static"
+      ? (state.verification_status === "verified"
+          ? ["store_SITE_AGENT_KEY_as_GitHub_Actions_secret", "run_customer_owned_sync_workflow"]
+          : ["publish_domain_proof", "verify_domain_ownership", "store_SITE_AGENT_KEY_as_GitHub_Actions_secret"])
+      : (state.verification_status === "verified" ? ["install_server_package", "start_site_agent_sync"] : ["verify_domain_ownership", "install_server_package", "store_SITE_AGENT_KEY_in_server_secret_store"])
+  };
+}
+
+async function enterpriseInstallStatus(projectRoot = process.cwd()) {
+  const root = normalizeProjectRoot(projectRoot);
+  const state = await readJson(path.join(root, MANAGED_DIR, "enterprise-state.json"));
+  const policy = await readJson(path.join(root, MANAGED_DIR, "enterprise-policy.json"));
+  return {
+    schema: "agentx-enterprise-install-status-v1",
+    state: state && state.status ? state.status : "not_enrolled",
+    site_url: state && state.site_url ? state.site_url : "",
+    environment: state && state.environment ? state.environment : "",
+    agent_id: state && state.agent_id ? state.agent_id : "",
+    credential_id: state && state.credential_id ? state.credential_id : "",
+    challenge_id: state && state.challenge_id ? state.challenge_id : "",
+    domain_proof_ready: Boolean(state && state.domain_proof && state.domain_proof.schema === "agentx-domain-proof-v1"),
+    public_key_thumbprint: state && state.public_key_thumbprint ? state.public_key_thumbprint : "",
+    policy_default: policy && policy.default === "deny" ? "deny" : "uninitialized",
+    policy_version: policy && Number.isInteger(policy.version) ? policy.version : 0,
+    policy_digest: policy && typeof policy.digest === "string" ? policy.digest : "",
+    short_lived_credential_storage: "memory_only",
+    mutation_authority: "local_policy_only"
+  };
+}
+
+async function writeEnterpriseEnrollmentState(projectRoot, state) {
+  const root = normalizeProjectRoot(projectRoot);
+  const proof = state && state.domain_proof && state.domain_proof.schema === "agentx-domain-proof-v1"
+    ? {
+        schema: "agentx-domain-proof-v1",
+        challenge_id: String(state.domain_proof.challenge_id || ""),
+        proof: String(state.domain_proof.proof || ""),
+        agent_id: String(state.domain_proof.agent_id || ""),
+        tenant_id: String(state.domain_proof.tenant_id || ""),
+        host: String(state.domain_proof.host || ""),
+        environment: String(state.domain_proof.environment || ""),
+        public_key_thumbprint: String(state.domain_proof.public_key_thumbprint || ""),
+        expires_at: Number(state.domain_proof.expires_at || 0)
+      }
+    : null;
+  const allowed = {
+    schema: "agentx-enterprise-enrollment-state-v1",
+    status: state.status || "challenge_pending",
+    site_url: normalizeSiteUrl(state.site_url),
+    environment: state.environment,
+    agent_id: state.agent_id || "",
+    credential_id: state.credential_id || "",
+    challenge_id: state.challenge_id || "",
+    public_key_thumbprint: state.public_key_thumbprint || ""
+  };
+  if (proof) allowed.domain_proof = proof;
+  const serialized = JSON.stringify(allowed, null, 2) + "\n";
+  if (/access_token|bootstrap_secret|PRIVATE KEY/.test(serialized)) throw installError("ENTERPRISE_SECRET_IN_STATE", "Enterprise secrets cannot be stored in installer state.");
+  await writeAtomic(path.join(root, MANAGED_DIR, "enterprise-state.json"), serialized, "private");
+  return allowed;
+}
+
+async function uninstallInstall(projectRoot = process.cwd(), { approved = false } = {}) {
+  if (approved !== true) throw installError("INSTALL_APPROVAL_REQUIRED", "Uninstall requires explicit approved=true.");
+  const root = normalizeProjectRoot(projectRoot);
+  const statePath = path.join(root, MANAGED_DIR, "install-state.json");
+  const state = await readJson(statePath);
+  if (!state || state.schema !== STATE_SCHEMA) return { schema: "agentx-uninstall-receipt-v1", removed: false, files: [] };
+  const files = Array.isArray(state.managed_paths) ? state.managed_paths : [];
+  const removed = [];
+  for (const relative of files) {
+    const allowedWorkflow = relative === ".github/workflows/agent-id-sync.yml";
+    if (typeof relative !== "string" || path.isAbsolute(relative) || (!relative.startsWith(`${MANAGED_DIR}/`) && !allowedWorkflow) || relative.split(/[\\/]+/).includes("..")) throw installError("UNSAFE_INSTALL_PATH", "Refusing to remove a file outside managed Agent ID paths.");
+    const target = path.resolve(root, relative);
+    await fs.rm(target, { force: true });
+    removed.push(relative);
+  }
+  await fs.rm(path.join(root, MANAGED_DIR), { recursive: false, force: true }).catch(() => {});
+  return { schema: "agentx-uninstall-receipt-v1", removed: true, files: removed, install_id: state.install_id || "" };
+}
+
+module.exports = {
+  INSTALL_SCHEMA,
+  STATE_SCHEMA,
+  buildInstallPlan,
+  preflightInstallPlan,
+  detectProject,
+  applyInstallPlan,
+  resumeInstall,
+  uninstallInstall,
+  enterpriseInstallStatus,
+  prepareEnterpriseSecretDirectory,
+  writeEnterpriseBootstrapCredential,
+  replaceEnterpriseBootstrapCredential,
+  removeEnterpriseBootstrapCredential,
+  readEnterpriseBootstrapCredential,
+  writeEnterpriseEnrollmentState,
+  normalizeSiteUrl
+};