@forgezero/agent 0.1.34 → 0.1.36

package/README.md

@@ -36,6 +36,56 @@ Install the service explicitly:
 fz agent install --apply         # writes a hardened systemd unit
 ```
 
+## Host bootstrap
+
+The package is also the host installer. There is no separate shell setup
+script and no second implementation for tenant or platform machines:
+
+```bash
+fz bootstrap platform                         # interactive plan, no mutation
+sudo fz bootstrap platform --apply            # initial DB+API or API-only host
+sudo fz bootstrap tenant --bootstrap-config ./tenant.json --apply
+sudo fz bootstrap metal --bootstrap-config ./metal.json --apply
+sudo fz bootstrap status
+sudo fz bootstrap repair --bootstrap-config ./original.json --apply
+```
+
+Platform bootstrap supports an elastic Community ArangoDB 3.11.14 fleet. The
+first three database-capable computes establish the writable cluster; later
+database joiners and API-only computes use the same command with their typed
+profile and an API-issued one-time enrolment file. Nothing treats three as a
+maximum.
+
+After genesis, a tenant can designate an enrolled compute as a bootstrap
+runner. The API creates a project-bound, expiring job containing only public
+SSH coordinates and a pinned Ed25519 host-key fingerprint. The runner claims it
+with its hybrid node identity, reads its SSH key only from a local systemd
+credential, pins one vetted DNS answer, transfers this packaged CLI, and runs
+the same `fz bootstrap tenant` flow on the target. Claim renewal, completion,
+retry and cancellation are fenced in the compute aggregate; the API never
+stores the SSH private key or a plaintext enrolment token.
+
+The attended Cloudflare resource phase is part of the same published command,
+but remains separate from the root host install so its management token never
+enters the API or Agent service environment:
+
+```bash
+chmod 600 cloudflare-bootstrap.json cloudflare-management.token
+fz bootstrap platform cloudflare --bootstrap-config ./cloudflare-bootstrap.json
+fz bootstrap platform cloudflare --bootstrap-config ./cloudflare-bootstrap.json --apply
+```
+
+The reviewed JSON has `format: 1`, kind
+`forgezero-cloudflare-bootstrap-request`, a `checkpointPath`, the typed
+`coordinates`, and `tokenFiles` containing file paths only. `coordinates.nodes`
+explicitly lists each node name, origin hostname, loopback service, Tunnel name
+and Access application name. Relative token, checkpoint and Worker project
+paths resolve beside the config file. Plan is offline. Apply creates/reuses one
+shared KV namespace, Worker and Access service token plus one Tunnel, Access
+application, ingress rule and DNS record per node. The command prints only
+resource IDs; connector, Access and requested runtime-token values stay in the
+atomically updated owner-only checkpoint for direct systemd-credential handoff.
+
 ## What changes for an application
 
 Nothing.

package/dist/agent-heartbeat.js

@@ -744,7 +744,7 @@ async function postSignedNode(options, path, body) {
 }
 
 // src/version.ts
-var VERSION3 = "0.1.34";
+var VERSION3 = "0.1.36";
 
 // src/agent-heartbeat.ts
 var unquote = (value) => value.replace(/^['"]|['"]$/g, "");

package/dist/bootstrap.d.ts

@@ -0,0 +1,133 @@
+import { type ProvisionPlan } from './cli/agent-install';
+import { type SoftwareCommandResult, type SoftwareRequirement } from './software';
+import { type PlatformSharedEnvironment } from './platform-bootstrap-runtime';
+export declare const PLATFORM_BOOTSTRAP_PROFILES: readonly ["platform-db-api", "platform-api"];
+export type PlatformBootstrapProfile = (typeof PLATFORM_BOOTSTRAP_PROFILES)[number];
+export type DatabaseBootstrapRole = 'master' | 'joiner' | 'none';
+export type BootstrapEnvironment = 'production' | 'development';
+export interface PlatformBootstrapConfig {
+    kind: 'platform';
+    environment: BootstrapEnvironment;
+    profile: PlatformBootstrapProfile;
+    /** API-owned compute reference. Initial seed references are fz-n1..3/dev-fz-n1..3. */
+    computeReference: string;
+    nodeHostname: string;
+    apiUrl: string;
+    repository: string;
+    branch: string;
+    deployRoot?: string;
+    telemetryEndpoint: string;
+    database: {
+        role: DatabaseBootstrapRole;
+        /** Cluster mode must remain default. Bootstrap verifies it and never mutates it. */
+        serverMode: 'default';
+        address?: string;
+        master?: string;
+        coordinators: string[];
+        /** Owner/root-only file containing the shared 64-hex bootstrap code. */
+        bootstrapSecretFile: string;
+    };
+    /** Required for every post-genesis compute; initial n1..n3 derive their one-use capability. */
+    platformEnrolTokenFile?: string;
+    runtime: {
+        environment: PlatformSharedEnvironment;
+        serviceUser: string;
+        slotsDirectory: string;
+        bluePort: number;
+        greenPort: number;
+        healthPath: string;
+        keepReleases: number;
+        credentialFiles?: {
+            smtpPassword?: string;
+            backupS3Secret?: string;
+        };
+    };
+    firewall: {
+        enabled: boolean;
+        sshPort: number;
+        privateCidrs: string[];
+    };
+    /** Install the connector binary only. Resource creation belongs to attended Cloudflare bootstrap. */
+    installCloudflared?: boolean;
+    /** Completed attended resource checkpoint; root seals only this node's runtime capabilities. */
+    cloudflareHandoff?: {
+        checkpointFile: string;
+        nodeName: string;
+    };
+}
+export interface TenantBootstrapConfig {
+    kind: 'tenant';
+    apiUrl: string;
+    realm: string;
+    nodeHostname: string;
+    telemetryEndpoint: string;
+    enrolTokenFile: string;
+    repository?: string;
+    branch?: string;
+    profile?: string;
+    deployRoot?: string;
+    software?: SoftwareRequirement[];
+    installCloudflared?: boolean;
+    /** Local-only runner authority. The API receives only the resulting node scope. */
+    bootstrapRunner?: {
+        sshPrivateKeyFile: string;
+        targetTelemetryEndpoint: string;
+    };
+}
+export type BootstrapConfig = PlatformBootstrapConfig | TenantBootstrapConfig;
+export interface BootstrapStep {
+    id: string;
+    label: string;
+    mutation: boolean;
+}
+export interface BootstrapPlan {
+    kind: BootstrapConfig['kind'];
+    mode: 'install' | 'repair';
+    profile: string;
+    steps: readonly BootstrapStep[];
+    software: readonly SoftwareRequirement[];
+    statePath: string;
+}
+export interface BootstrapResult {
+    plan: BootstrapPlan;
+    applied: boolean;
+    status: BootstrapStatus;
+    launch?: {
+        command: string;
+        inviteUrl: string;
+    };
+}
+export interface BootstrapStatus {
+    initialized: boolean;
+    kind?: BootstrapConfig['kind'];
+    profile?: string;
+    services: Record<string, boolean>;
+    problems: string[];
+}
+export interface BootstrapHost {
+    uid(): number;
+    exists(path: string): boolean;
+    read(path: string): string;
+    write(path: string, content: string, mode: number): void;
+    mkdir(path: string, mode: number): void;
+    remove(path: string): void;
+    inspect?(path: string): {
+        regular: boolean;
+        symbolic: boolean;
+        uid: number;
+        mode: number;
+        links: number;
+        size: number;
+    };
+    exec(argv: readonly string[], options?: {
+        stdin?: string;
+    }): Promise<SoftwareCommandResult>;
+    ensureSoftware(requirements: readonly SoftwareRequirement[]): Promise<unknown>;
+    installAgent(config: BootstrapConfig, enrolTokenSourcePath?: string): Promise<ProvisionPlan>;
+}
+export declare function validateBootstrapConfig(value: BootstrapConfig): BootstrapConfig;
+export declare function planBootstrap(input: BootstrapConfig, initialized?: boolean): BootstrapPlan;
+export declare function bootstrapStatus(host?: BootstrapHost): Promise<BootstrapStatus>;
+export declare function applyBootstrap(input: BootstrapConfig, host?: BootstrapHost): Promise<BootstrapResult>;
+export declare function readBootstrapConfig(path: string): BootstrapConfig;
+export declare function localBootstrapHost(): BootstrapHost;