@forgezero/agent 0.1.34 → 0.1.36

package/dist/platform-bootstrap-runtime.d.ts

@@ -0,0 +1,161 @@
+/** Typed, side-effect-free host runtime plans used by `fz bootstrap platform`. */
+export type PlatformSoftwareProfile = 'platform-db-api' | 'platform-api';
+export type PlatformDatabaseRole = 'master' | 'joiner' | 'none';
+export type ApiSlot = 'blue' | 'green';
+export interface PlatformSharedEnvironment {
+    softwareProfile: PlatformSoftwareProfile;
+    databaseRole: PlatformDatabaseRole;
+    databaseCoordinators: string[];
+    databaseAddress?: string;
+    databaseMaster?: string;
+    databaseNetworkMode: 'private-lan' | 'cloudflare-warp';
+    databaseReplicationFactor: number;
+    databaseWriteConcern: number;
+    databaseUser: string;
+    nodeHostname: string;
+    nodeRegion: string;
+    nodeRole: 'guest';
+    appOrigin: string;
+    apiOrigin: string;
+    publicApiPort: number;
+    sharedDirectory: string;
+    seedSyncPeers: string[];
+    seedSyncMembers: number;
+    seedSyncEpoch: string;
+    concurrencyLimit: number;
+    drainDeadlineMs: number;
+    otlpEndpoint: 'http://127.0.0.1:4318';
+    otlpCollectorUnit: string;
+    agentOtlpEndpoint: string;
+    otlpFlushIntervalMs: number;
+    otlpTraceSampleRatio: number;
+    custodianEmail?: string;
+    smtp?: {
+        host: string;
+        port: number;
+        user?: string;
+        from: string;
+    };
+    backup?: {
+        endpoint: string;
+        region: string;
+        bucket: string;
+        accessKeyId: string;
+    };
+    cloudflare?: {
+        accountId: string;
+        zoneId: string;
+        kvNamespaceId: string;
+        tunnelId: string;
+        tunnelService: string;
+        warp?: {
+            organization: string;
+            virtualNetworkId: string;
+            deviceProfileId: string;
+        };
+    };
+    repository: string;
+    branch: string;
+    deployProfile: string;
+}
+export declare function validatePlatformSharedEnvironment(input: PlatformSharedEnvironment, options?: {
+    allowPendingCloudflareHandoff?: boolean;
+}): PlatformSharedEnvironment;
+/** Render only non-secret runtime coordinates. Passwords/tokens have no field in this contract. */
+export declare function renderPlatformSharedEnvironment(input: PlatformSharedEnvironment): string;
+export interface SystemdCredentialSpec {
+    name: 'arangodb-jwt' | 'seed-sync-root' | 'bootstrap-smtp-password' | 'cloudflare-kv-token' | 'cloudflare-network-token';
+    encryptedPath: string;
+    required: boolean;
+}
+export declare function platformApiCredentialSpecs(options: {
+    smtp: boolean;
+    cloudflareKv: boolean;
+    cloudflareNetwork: boolean;
+}): SystemdCredentialSpec[];
+export interface ApiRuntimeRenderOptions {
+    serviceUser: string;
+    sharedDirectory: string;
+    sharedEnvironmentFile: string;
+    slotsDirectory: string;
+    bluePort: number;
+    greenPort: number;
+    collectorUnit: string;
+    credentials: SystemdCredentialSpec[];
+}
+export declare function renderPlatformApiUnits(input: ApiRuntimeRenderOptions): {
+    template: string;
+    dropIns: Record<ApiSlot, string>;
+};
+export declare function renderPlatformNginx(input: {
+    publicPort: number;
+    initialSlotPort: number;
+}): {
+    upstream: string;
+    site: string;
+};
+export interface ActivationBoundary {
+    command: '/usr/local/libexec/forgezero-activate';
+    argv: [string];
+    runAs: 'root';
+    invoker: 'forgezero-runner';
+}
+/** The caller passes an immutable release path, never a shell command. */
+export declare function planPlatformActivation(releasesDirectory: string, releasePath: string): ActivationBoundary;
+export interface PlatformActivationConfig {
+    root: string;
+    serviceUser: string;
+    bluePort: number;
+    greenPort: number;
+    healthPath: string;
+    keepReleases: number;
+}
+/**
+ * Render the fixed privilege boundary used by the credential-free deployment
+ * runner. Repository data supplies one release path; it never supplies shell.
+ */
+export declare function renderPlatformActivationFiles(input: PlatformActivationConfig): {
+    environment: string;
+    helper: string;
+    sudoers: string;
+};
+export interface LocalOtlpProofPlan {
+    unitCheck: {
+        command: 'systemctl';
+        argv: ['is-active', '--quiet', string];
+    };
+    receiverCheck: {
+        command: 'curl';
+        argv: string[];
+        acceptedStatus: '2xx';
+    };
+}
+export declare function planLocalOtlpProof(endpoint: string, collectorUnit: string): LocalOtlpProofPlan;
+export type BringupStage = 'runtime-ready' | 'invite-prepared' | 'deploy-requested' | 'deploy-healthy' | 'invite-presented' | 'complete' | 'failed';
+export interface PlatformBringupState {
+    requiresFirstInvite: boolean;
+    stage: BringupStage;
+    inviteTokenFilePresent: boolean;
+    lastError?: string;
+}
+export type PlatformBringupEvent = {
+    type: 'invite-prepared';
+    tokenFilePresent: boolean;
+} | {
+    type: 'deploy-requested';
+} | {
+    type: 'deploy-healthy';
+} | {
+    type: 'invite-presented';
+} | {
+    type: 'complete';
+} | {
+    type: 'failed';
+    error: string;
+};
+export declare function initialPlatformBringupState(requiresFirstInvite: boolean): PlatformBringupState;
+/** Strict persisted sequencing: genesis invite before deploy, presentation only after health. */
+export declare function advancePlatformBringup(state: PlatformBringupState, event: PlatformBringupEvent): PlatformBringupState;
+export type PlatformBringupAction = 'prepare-invite' | 'request-deploy' | 'await-deploy-health' | 'present-invite' | 'mark-complete' | 'none';
+export declare function nextPlatformBringupAction(state: PlatformBringupState): PlatformBringupAction;
+export declare function repairPlatformBringup(state: PlatformBringupState): PlatformBringupState;

package/dist/platform-bootstrap-runtime.js

@@ -0,0 +1,462 @@
+// src/platform-bootstrap-runtime.ts
+var safeAtom = (name, value) => {
+  if (!value || /[\0\r\n]/.test(value))
+    throw new Error(`${name} must be non-empty and single-line.`);
+  return value;
+};
+var boundedInteger = (name, value, minimum, maximum) => {
+  if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+    throw new Error(`${name} must be an integer from ${minimum} through ${maximum}.`);
+  }
+  return value;
+};
+var privateCoordinator = (raw) => {
+  const url = new URL(raw);
+  if (url.protocol !== "http:" || url.username || url.password || url.search || url.hash || url.pathname !== "/") {
+    throw new Error("ArangoDB coordinator URLs must be credential-free private HTTP origins.");
+  }
+  const host = url.hostname.replace(/^\[|\]$/g, "");
+  const privateHost = host === "localhost" || host === "::1" || host.startsWith("fd") || host.startsWith("fc") || /^127\./.test(host) || /^10\./.test(host) || /^192\.168\./.test(host) || /^172\.(1[6-9]|2\d|3[01])\./.test(host);
+  if (!privateHost || url.port && url.port !== "8529") {
+    throw new Error("ArangoDB coordinators must use private addresses and port 8529.");
+  }
+  return url.origin;
+};
+var httpsOrigin = (name, raw) => {
+  const value = new URL(raw);
+  if (value.protocol !== "https:" || value.username || value.password || value.search || value.hash || value.pathname !== "/") {
+    throw new Error(`${name} must be a credential-free HTTPS origin.`);
+  }
+  return value.origin;
+};
+var systemdValue = (name, raw) => {
+  if (/[\0\r\n]/.test(raw))
+    throw new Error(`${name} must be single-line.`);
+  const value = raw;
+  return `"${value.replaceAll("\\", "\\\\").replaceAll('"', "\\\"").replaceAll("$", "\\$")}"`;
+};
+function validatePlatformSharedEnvironment(input, options = {}) {
+  if (input.softwareProfile === "platform-api" !== (input.databaseRole === "none")) {
+    throw new Error("platform-api requires database role none; platform-db-api requires master or joiner.");
+  }
+  if (input.databaseCoordinators.length < 1 || input.databaseCoordinators.length > 16) {
+    throw new Error("databaseCoordinators must contain 1 through 16 endpoints.");
+  }
+  const coordinators = input.databaseCoordinators.map(privateCoordinator);
+  if (new Set(coordinators).size !== coordinators.length)
+    throw new Error("databaseCoordinators must be unique.");
+  if (!["private-lan", "cloudflare-warp"].includes(input.databaseNetworkMode)) {
+    throw new Error("Database networking must be private-lan or cloudflare-warp.");
+  }
+  boundedInteger("databaseReplicationFactor", input.databaseReplicationFactor, 1, 16);
+  boundedInteger("databaseWriteConcern", input.databaseWriteConcern, 1, 16);
+  if (input.databaseWriteConcern > input.databaseReplicationFactor) {
+    throw new Error("databaseWriteConcern cannot exceed databaseReplicationFactor.");
+  }
+  boundedInteger("publicApiPort", input.publicApiPort, 1024, 65533);
+  boundedInteger("seedSyncMembers", input.seedSyncMembers, 1, 64);
+  boundedInteger("concurrencyLimit", input.concurrencyLimit, 1, 1e6);
+  boundedInteger("drainDeadlineMs", input.drainDeadlineMs, 1000, 300000);
+  boundedInteger("otlpFlushIntervalMs", input.otlpFlushIntervalMs, 1000, 300000);
+  if (!Number.isFinite(input.otlpTraceSampleRatio) || input.otlpTraceSampleRatio < 0 || input.otlpTraceSampleRatio > 1) {
+    throw new Error("otlpTraceSampleRatio must be from 0 through 1.");
+  }
+  if (input.otlpEndpoint !== "http://127.0.0.1:4318")
+    throw new Error("OTLP must use the exact local collector endpoint.");
+  validateCollectorUnit(input.otlpCollectorUnit);
+  httpsOrigin("agentOtlpEndpoint", input.agentOtlpEndpoint);
+  for (const [name, value] of Object.entries({
+    nodeHostname: input.nodeHostname,
+    nodeRegion: input.nodeRegion,
+    databaseUser: input.databaseUser,
+    sharedDirectory: input.sharedDirectory,
+    seedSyncEpoch: input.seedSyncEpoch,
+    repository: input.repository,
+    branch: input.branch,
+    deployProfile: input.deployProfile
+  }))
+    safeAtom(name, value);
+  if (!input.sharedDirectory.startsWith("/"))
+    throw new Error("sharedDirectory must be absolute.");
+  for (const peer of input.seedSyncPeers) {
+    const url = new URL(peer);
+    if (url.protocol !== "ws:" && url.protocol !== "wss:")
+      throw new Error("Seed peers must be WebSocket URLs.");
+    if (url.username || url.password || url.hash)
+      throw new Error("Seed peers cannot contain credentials or fragments.");
+  }
+  if (input.smtp) {
+    safeAtom("smtp.host", input.smtp.host);
+    boundedInteger("smtp.port", input.smtp.port, 1, 65535);
+    safeAtom("smtp.from", input.smtp.from);
+    if (input.smtp.user)
+      safeAtom("smtp.user", input.smtp.user);
+  }
+  if (input.backup) {
+    httpsOrigin("backup.endpoint", input.backup.endpoint);
+    for (const [name, value] of Object.entries(input.backup))
+      safeAtom(`backup.${name}`, value);
+  }
+  if (input.cloudflare) {
+    if (![input.cloudflare.accountId, input.cloudflare.zoneId, input.cloudflare.kvNamespaceId].every((item) => /^[a-f0-9]{32}$/i.test(item)) || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(input.cloudflare.tunnelId)) {
+      throw new Error("Cloudflare account, zone, KV and Tunnel ids are malformed.");
+    }
+    const service = new URL(input.cloudflare.tunnelService);
+    if (service.protocol !== "http:" || !["127.0.0.1", "localhost", "::1"].includes(service.hostname) || service.username || service.password || service.search || service.hash)
+      throw new Error("Cloudflare Tunnel service must be loopback HTTP.");
+    if (input.cloudflare.warp) {
+      if (!/^[A-Za-z0-9][A-Za-z0-9-]{0,62}$/.test(input.cloudflare.warp.organization) || !/^[0-9a-f-]{36}$/i.test(input.cloudflare.warp.virtualNetworkId) || !/^[A-Za-z0-9_-]{1,128}$/.test(input.cloudflare.warp.deviceProfileId)) {
+        throw new Error("Cloudflare WARP organization, VNET or device profile is malformed.");
+      }
+    }
+  }
+  if (!options.allowPendingCloudflareHandoff && input.databaseNetworkMode === "cloudflare-warp" !== Boolean(input.cloudflare?.warp)) {
+    throw new Error("cloudflare-warp networking requires its exact enrolled Cloudflare coordinates.");
+  }
+  return {
+    ...input,
+    databaseCoordinators: coordinators,
+    appOrigin: httpsOrigin("appOrigin", input.appOrigin),
+    apiOrigin: httpsOrigin("apiOrigin", input.apiOrigin),
+    agentOtlpEndpoint: httpsOrigin("agentOtlpEndpoint", input.agentOtlpEndpoint)
+  };
+}
+function renderPlatformSharedEnvironment(input) {
+  const value = validatePlatformSharedEnvironment(input);
+  const appHost = new URL(value.appOrigin).hostname.split(".").slice(-2).join(".");
+  const apiHost = new URL(value.apiOrigin).hostname.split(".").slice(-2).join(".");
+  const entries = {
+    ARANGO_URL: value.databaseCoordinators[0],
+    ARANGO_URLS: value.databaseCoordinators.join(","),
+    ARANGO_DB: "fz",
+    FZ_DATABASE_MODE: "platform",
+    ARANGO_USER: value.databaseUser,
+    ARANGO_REPLICATION_FACTOR: String(value.databaseReplicationFactor),
+    ARANGO_WRITE_CONCERN: String(value.databaseWriteConcern),
+    FZ_DB_ROLE: value.databaseRole,
+    FZ_SOFTWARE_PROFILE: value.softwareProfile,
+    FZ_ROLE: value.nodeRole,
+    FZ_DB_ADDRESS: value.databaseAddress ?? "",
+    FZ_DB_MASTER: value.databaseMaster ?? "",
+    FZ_DB_NETWORK_MODE: value.databaseNetworkMode,
+    FZ_SEED_SYNC_PEERS: value.seedSyncPeers.join(","),
+    FZ_SEED_SYNC_MEMBERS: String(value.seedSyncMembers),
+    FZ_SEED_SYNC_EPOCH: value.seedSyncEpoch,
+    FZ_SEED_SYNC_CREDENTIAL: "seed-sync-root",
+    FZ_SHARED_DIR: value.sharedDirectory,
+    FZ_PUBLIC_API_PORT: String(value.publicApiPort),
+    ORIGIN: value.appOrigin,
+    API_ORIGIN: value.apiOrigin,
+    HOST: "127.0.0.1",
+    APP_ORIGINS: value.appOrigin,
+    TRUST_CLOUDFLARE_IP: "1",
+    SESSION_COOKIE_SAMESITE: appHost === apiHost ? "lax" : "none",
+    SESSION_COOKIE_DOMAIN: "",
+    FZ_NODE_HOSTNAME: value.nodeHostname,
+    FZ_NODE_REGION: value.nodeRegion,
+    FZ_CONCURRENCY_LIMIT: String(value.concurrencyLimit),
+    FZ_DRAIN_DEADLINE_MS: String(value.drainDeadlineMs),
+    OTEL_EXPORTER_OTLP_ENDPOINT: value.otlpEndpoint,
+    FZ_OTLP_COLLECTOR_UNIT: value.otlpCollectorUnit,
+    OTEL_SERVICE_NAME: "forgezero-api",
+    FZ_OTLP_FLUSH_INTERVAL_MS: String(value.otlpFlushIntervalMs),
+    FZ_OTLP_TRACE_SAMPLE_RATIO: String(value.otlpTraceSampleRatio),
+    FZ_AGENT_OTLP_ENDPOINT: value.agentOtlpEndpoint,
+    FZ_CUSTODIAN_EMAIL: value.custodianEmail ?? "",
+    FZ_PROFILE: value.deployProfile,
+    FZ_REPO: value.repository,
+    FZ_BRANCH: value.branch,
+    FZ_SMTP_HOST: value.smtp?.host ?? "",
+    FZ_SMTP_PORT: value.smtp ? String(value.smtp.port) : "",
+    FZ_SMTP_USER: value.smtp?.user ?? "",
+    FZ_SMTP_FROM: value.smtp?.from ?? "",
+    BACKUP_S3_ENDPOINT: value.backup?.endpoint ?? "",
+    BACKUP_S3_REGION: value.backup?.region ?? "",
+    BACKUP_S3_BUCKET: value.backup?.bucket ?? "",
+    BACKUP_S3_ACCESS_KEY_ID: value.backup?.accessKeyId ?? "",
+    FZ_CF_ACCOUNT_ID: value.cloudflare?.accountId ?? "",
+    FZ_CF_ZONE_ID: value.cloudflare?.zoneId ?? "",
+    FZ_CF_KV_NAMESPACE_ID: value.cloudflare?.kvNamespaceId ?? "",
+    FZ_CF_TUNNEL_ID: value.cloudflare?.tunnelId ?? "",
+    FZ_CF_TUNNEL_SERVICE: value.cloudflare?.tunnelService ?? "",
+    FZ_WARP_ORGANIZATION: value.cloudflare?.warp?.organization ?? "",
+    FZ_CF_VIRTUAL_NETWORK_ID: value.cloudflare?.warp?.virtualNetworkId ?? "",
+    FZ_CF_WARP_POLICY_ID: value.cloudflare?.warp?.deviceProfileId ?? ""
+  };
+  return `# Generated by fz bootstrap platform. Non-secret coordinates only.
+` + Object.entries(entries).map(([key, entry]) => `${key}=${systemdValue(key, entry)}`).join(`
+`) + `
+`;
+}
+function platformApiCredentialSpecs(options) {
+  const optional = [
+    ["bootstrap-smtp-password", options.smtp],
+    ["cloudflare-kv-token", options.cloudflareKv],
+    ["cloudflare-network-token", options.cloudflareNetwork]
+  ];
+  return [
+    { name: "arangodb-jwt", encryptedPath: "/etc/forgezero/creds/arangodb-jwt.cred", required: true },
+    { name: "seed-sync-root", encryptedPath: "/etc/forgezero/creds/seed-sync-root.cred", required: true },
+    ...optional.filter(([, present]) => present).map(([name]) => ({
+      name,
+      encryptedPath: `/etc/forgezero/creds/${name}.cred`,
+      required: false
+    }))
+  ];
+}
+function renderPlatformApiUnits(input) {
+  for (const path of [input.sharedDirectory, input.sharedEnvironmentFile, input.slotsDirectory]) {
+    if (!path.startsWith("/") || /[\r\n]/.test(path))
+      throw new Error("Runtime paths must be absolute and single-line.");
+  }
+  if (!/^[a-z_][a-z0-9_-]{0,31}$/.test(input.serviceUser))
+    throw new Error("Invalid service user.");
+  validateCollectorUnit(input.collectorUnit);
+  boundedInteger("bluePort", input.bluePort, 1024, 65535);
+  boundedInteger("greenPort", input.greenPort, 1024, 65535);
+  if (input.bluePort === input.greenPort)
+    throw new Error("Blue and green ports must differ.");
+  const credentials = input.credentials.map((credential) => `LoadCredentialEncrypted=${credential.name}:${credential.encryptedPath}`).join(`
+`);
+  const template = `[Unit]
+Description=ForgeZero (%i slot)
+After=network-online.target ${input.collectorUnit}
+Wants=network-online.target ${input.collectorUnit}
+
+[Service]
+Type=simple
+User=${input.serviceUser}
+WorkingDirectory=${input.slotsDirectory}/%i
+Environment=NODE_ENV=production
+Environment=FZ_SLOT=%i
+EnvironmentFile=${input.sharedEnvironmentFile}
+${credentials}
+ExecStart=/usr/local/bin/bun run ${input.slotsDirectory}/%i/src/index.ts
+Restart=always
+RestartSec=2
+TimeoutStopSec=35s
+LimitCORE=0
+UMask=0077
+NoNewPrivileges=yes
+PrivateTmp=yes
+PrivateDevices=yes
+ProtectSystem=strict
+ProtectHome=yes
+ReadOnlyPaths=${input.sharedDirectory}
+ProtectKernelTunables=yes
+ProtectKernelModules=yes
+ProtectControlGroups=yes
+RestrictSUIDSGID=yes
+RestrictRealtime=yes
+LockPersonality=yes
+RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6
+
+[Install]
+WantedBy=multi-user.target
+`;
+  return { template, dropIns: {
+    blue: `[Service]
+Environment=PORT=${input.bluePort}
+`,
+    green: `[Service]
+Environment=PORT=${input.greenPort}
+`
+  } };
+}
+function renderPlatformNginx(input) {
+  boundedInteger("publicPort", input.publicPort, 1024, 65535);
+  boundedInteger("initialSlotPort", input.initialSlotPort, 1024, 65535);
+  if (input.publicPort === input.initialSlotPort)
+    throw new Error("Edge and slot ports must differ.");
+  return {
+    upstream: `upstream forgezero { server 127.0.0.1:${input.initialSlotPort}; }
+`,
+    site: `server {
+  listen 127.0.0.1:${input.publicPort};
+  server_name _;
+  location ^~ /api/ { proxy_pass http://forgezero; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto https; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; }
+  location ^~ /v1/ { proxy_pass http://forgezero; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto https; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; }
+  location / { return 404; }
+}
+`
+  };
+}
+function planPlatformActivation(releasesDirectory, releasePath) {
+  if (!releasesDirectory.startsWith("/") || !releasePath.startsWith("/") || /[\0\r\n]/.test(releasePath)) {
+    throw new Error("Activation paths must be absolute and single-line.");
+  }
+  const root = releasesDirectory.replace(/\/+$/, "");
+  if (!releasePath.startsWith(`${root}/`) || releasePath === root || releasePath.includes("/../")) {
+    throw new Error("Release must be an immutable child of the releases directory.");
+  }
+  return { command: "/usr/local/libexec/forgezero-activate", argv: [releasePath], runAs: "root", invoker: "forgezero-runner" };
+}
+function renderPlatformActivationFiles(input) {
+  if (!input.root.startsWith("/") || /[\0\r\n]/.test(input.root))
+    throw new Error("Activation root must be absolute and single-line.");
+  if (!/^[a-z_][a-z0-9_-]{0,31}$/.test(input.serviceUser))
+    throw new Error("Invalid activation service user.");
+  boundedInteger("bluePort", input.bluePort, 1024, 65535);
+  boundedInteger("greenPort", input.greenPort, 1024, 65535);
+  if (input.bluePort === input.greenPort)
+    throw new Error("Activation slot ports must differ.");
+  boundedInteger("keepReleases", input.keepReleases, 2, 100);
+  if (!/^\/[A-Za-z0-9/_-]{1,128}$/.test(input.healthPath) || input.healthPath.includes("..")) {
+    throw new Error("Activation health path is malformed.");
+  }
+  const environment = [
+    `FZ_DIR=${input.root}`,
+    `FZ_USER=${input.serviceUser}`,
+    `FZ_BLUE_PORT=${input.bluePort}`,
+    `FZ_GREEN_PORT=${input.greenPort}`,
+    `FZ_HEALTH_PATH=${input.healthPath}`,
+    `FZ_KEEP_RELEASES=${input.keepReleases}`
+  ].join(`
+`) + `
+`;
+  const helper = `#!/usr/bin/env bash
+set -Eeuo pipefail
+source /etc/forgezero/deploy.env
+[[ $# == 1 ]] || { echo "usage: forgezero-activate <release>" >&2; exit 2; }
+release="$(realpath -e "$1")"; releases="$(realpath -e "$FZ_DIR/releases")"; slots="$FZ_DIR/slots"
+install -d -o root -g root -m 0755 "$slots"
+case "$release/" in "$releases"/*/) ;; *) echo "release is outside $releases" >&2; exit 2 ;; esac
+[[ -f "$release/.fz/deploy.json" && -s "$release/src/index.ts" && -s "$release/bun.lock" ]] || { echo "release is incomplete" >&2; exit 2; }
+slot_file="$FZ_DIR/.forge-slot"; previous_slot="$(cat "$slot_file" 2>/dev/null || true)"
+if [[ "$previous_slot" == blue ]]; then target=green; port="$FZ_GREEN_PORT"; else target=blue; port="$FZ_BLUE_PORT"; fi
+target_link="$slots/$target"; previous_target_link="$(readlink -f "$target_link" 2>/dev/null || true)"
+chown -R root:"$FZ_USER" "$release"; chmod -R a-w "$release"; find "$release" -type d -exec chmod a+rx {} +; find "$release" -type f -exec chmod a+r {} +
+ln -sfn "$release" "$target_link"; systemctl restart "forgezero@\${target}.service"
+healthy=0; for _ in $(seq 1 30); do curl -fsS --max-time 2 "http://127.0.0.1:\${port}\${FZ_HEALTH_PATH}" >/dev/null 2>&1 && { healthy=1; break; }; sleep 1; done
+if (( ! healthy )); then systemctl stop "forgezero@\${target}.service" || true; [[ -n "$previous_target_link" && -d "$previous_target_link" ]] && ln -sfn "$previous_target_link" "$target_link" || rm -f "$target_link"; exit 1; fi
+upstream=/etc/nginx/conf.d/forgezero-upstream.conf; backup="$(mktemp -p /run forgezero-upstream.XXXXXX)"; [[ -f "$upstream" ]] && cp "$upstream" "$backup" || : >"$backup"
+printf 'upstream forgezero { server 127.0.0.1:%s; }\\n' "$port" >"$upstream"
+if ! nginx -t || ! nginx -s reload; then [[ -s "$backup" ]] && cp "$backup" "$upstream" || rm -f "$upstream"; rm -f "$backup"; systemctl stop "forgezero@\${target}.service" || true; [[ -n "$previous_target_link" && -d "$previous_target_link" ]] && ln -sfn "$previous_target_link" "$target_link" || rm -f "$target_link"; nginx -t >/dev/null 2>&1 && nginx -s reload || true; exit 1; fi
+rm -f "$backup"; printf '%s\\n' "$target" >"$slot_file"; [[ -n "$previous_slot" && "$previous_slot" != "$target" ]] && systemctl stop "forgezero@\${previous_slot}.service" || true
+mapfile -t old < <(find "$releases" -mindepth 1 -maxdepth 1 -type d -printf '%T@ %p\\n' | sort -rn | tail -n "+$((FZ_KEEP_RELEASES + 1))" | cut -d' ' -f2-)
+for path in "\${old[@]}"; do [[ "$path" == "$release" ]] || rm -rf -- "$path"; done
+printf 'promoted %s on %s\\n' "$release" "$target"
+`;
+  return {
+    environment,
+    helper,
+    sudoers: `forgezero-runner ALL=(root) NOPASSWD: /usr/local/libexec/forgezero-activate *
+`
+  };
+}
+function validateCollectorUnit(unit) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.@-]{0,127}\.service$/.test(unit))
+    throw new Error("Invalid OTLP collector service unit.");
+  if (/^(forgezero@.*|forgezero-agent|forgezero-metal-agent|forgezero-db)\.service$/.test(unit)) {
+    throw new Error("OTLP collector must be independently supervised.");
+  }
+}
+function planLocalOtlpProof(endpoint, collectorUnit) {
+  if (endpoint !== "http://127.0.0.1:4318")
+    throw new Error("OTLP proof requires exact loopback endpoint http://127.0.0.1:4318.");
+  validateCollectorUnit(collectorUnit);
+  return {
+    unitCheck: { command: "systemctl", argv: ["is-active", "--quiet", collectorUnit] },
+    receiverCheck: {
+      command: "curl",
+      acceptedStatus: "2xx",
+      argv: [
+        "--silent",
+        "--show-error",
+        "--max-time",
+        "5",
+        "--output",
+        "/dev/null",
+        "--write-out",
+        "%{http_code}",
+        "--request",
+        "POST",
+        "--header",
+        "Content-Type: application/json",
+        "--data-binary",
+        "{}",
+        `${endpoint}/v1/metrics`
+      ]
+    }
+  };
+}
+function initialPlatformBringupState(requiresFirstInvite) {
+  return { requiresFirstInvite, stage: "runtime-ready", inviteTokenFilePresent: false };
+}
+function advancePlatformBringup(state, event) {
+  if (state.stage === "failed")
+    throw new Error("A failed bring-up must be explicitly repaired before resuming.");
+  if (event.type === "failed")
+    return { ...state, stage: "failed", lastError: safeAtom("error", event.error) };
+  if (event.type === state.stage)
+    return state;
+  if (event.type === "invite-prepared") {
+    if (!state.requiresFirstInvite || state.stage !== "runtime-ready" || !event.tokenFilePresent) {
+      throw new Error("The first invite must be durably present before it is recorded.");
+    }
+    return { ...state, stage: "invite-prepared", inviteTokenFilePresent: true };
+  }
+  if (event.type === "deploy-requested") {
+    const expected = state.requiresFirstInvite ? "invite-prepared" : "runtime-ready";
+    if (state.stage !== expected || state.requiresFirstInvite && !state.inviteTokenFilePresent) {
+      throw new Error("Deployment cannot start before required invite preparation.");
+    }
+    return { ...state, stage: "deploy-requested" };
+  }
+  if (event.type === "deploy-healthy") {
+    if (state.stage !== "deploy-requested")
+      throw new Error("Deployment health requires a requested deployment.");
+    return { ...state, stage: "deploy-healthy" };
+  }
+  if (event.type === "invite-presented") {
+    if (!state.requiresFirstInvite || state.stage !== "deploy-healthy" || !state.inviteTokenFilePresent) {
+      throw new Error("Invite presentation requires a healthy deployment and the original token file.");
+    }
+    return { ...state, stage: "invite-presented" };
+  }
+  if (event.type === "complete") {
+    const expected = state.requiresFirstInvite ? "invite-presented" : "deploy-healthy";
+    if (state.stage !== expected)
+      throw new Error("Bring-up cannot complete before its ordered ceremony.");
+    return { ...state, stage: "complete" };
+  }
+  throw new Error("Unsupported bring-up transition.");
+}
+function nextPlatformBringupAction(state) {
+  if (state.stage === "failed" || state.stage === "complete")
+    return "none";
+  if (state.stage === "runtime-ready")
+    return state.requiresFirstInvite ? "prepare-invite" : "request-deploy";
+  if (state.stage === "invite-prepared") {
+    if (!state.inviteTokenFilePresent)
+      throw new Error("Recorded invite is missing; refusing implicit rotation.");
+    return "request-deploy";
+  }
+  if (state.stage === "deploy-requested")
+    return "await-deploy-health";
+  if (state.stage === "deploy-healthy")
+    return state.requiresFirstInvite ? "present-invite" : "mark-complete";
+  return "mark-complete";
+}
+function repairPlatformBringup(state) {
+  if (state.stage !== "failed")
+    return state;
+  if (state.requiresFirstInvite && !state.inviteTokenFilePresent) {
+    throw new Error("Missing issued invite cannot be repaired by implicit rotation.");
+  }
+  return { ...state, stage: state.inviteTokenFilePresent ? "invite-prepared" : "runtime-ready", lastError: undefined };
+}
+export {
+  validatePlatformSharedEnvironment,
+  repairPlatformBringup,
+  renderPlatformSharedEnvironment,
+  renderPlatformNginx,
+  renderPlatformApiUnits,
+  renderPlatformActivationFiles,
+  platformApiCredentialSpecs,
+  planPlatformActivation,
+  planLocalOtlpProof,
+  nextPlatformBringupAction,
+  initialPlatformBringupState,
+  advancePlatformBringup
+};

package/dist/provision.d.ts

@@ -100,6 +100,10 @@ export interface UnitOptions {
     runnerPublicTcpPorts?: readonly number[];
     /** Enable PQ-authenticated lifecycle claims through a constrained root helper. */
     pullMigrations?: boolean;
+    /** Claim API-owned SSH bootstrap jobs; the private key stays a systemd credential on this runner. */
+    pullBootstrap?: boolean;
+    bootstrapSshCredentialPath?: string;
+    bootstrapTargetTelemetryEndpoint?: string;
     /** Root-owned declarative lifecycle profile; never supplied by a migration claim. */
     lifecycleProfilePath?: string;
     lifecycleHelperSocketPath?: string;