@consiliency/agent-board-cli 1.9.0 → 1.10.0

package/dist/enroll_runtime.d.ts

@@ -1,8 +1,74 @@
-import { type PendingEnrollment, type PendingEnrollmentStore } from "@consiliency/agent-board-client";
+import type { EnrollmentOutcome, FinalizedFleetHarnessTemplate, PendingFleetHarnessTemplate } from "@consiliency/agent-board-client";
+import { type EnrollmentIntent, type PendingEnrollment, type PendingEnrollmentStore } from "@consiliency/agent-board-client";
 export declare class EnrollRuntimeError extends Error {
     code: string;
     constructor(code: string, message: string);
 }
+/** Versioned, non-secret continuation for an interrupted fleet device flow. */
+export interface FleetDeviceContinuation {
+    version: "fleet_device_continuation.v1";
+    enrollmentId: string;
+    runtimeOutput: string;
+    publishableKeyFieldReference: string;
+    keyReference: string;
+    pendingTemplate: PendingFleetHarnessTemplate;
+    /** Persisted after the server transaction so local publication can retry without polling again. */
+    outcome?: EnrollmentOutcome;
+}
+/** Secret-bearing RFC 8628 state. This is never rendered by the CLI. */
+export interface DevicePendingEnrollment {
+    flow: "device_code";
+    enrollmentId: string;
+    deviceCode: string;
+    interval: number;
+    expiresAt?: number;
+    expiresIn?: number;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete?: string;
+    intent: EnrollmentIntent;
+    slug: string;
+    agentKind?: string;
+    requestedScopes?: string[];
+    requestedBoardScopes?: string[];
+}
+export declare class FleetDeviceContinuationStore {
+    private readonly dir;
+    constructor(dir: string);
+    private path;
+    private guardDir;
+    put(value: FleetDeviceContinuation): Promise<void>;
+    get(id: string): Promise<FleetDeviceContinuation | undefined>;
+    delete(id: string): Promise<void>;
+}
+export declare class DevicePendingEnrollmentStore {
+    private readonly dir;
+    constructor(dir: string);
+    private path;
+    private guardDir;
+    put(value: DevicePendingEnrollment): Promise<void>;
+    get(id: string): Promise<DevicePendingEnrollment | undefined>;
+    delete(id: string): Promise<void>;
+}
+export interface FleetRuntimeFilesystemOptions {
+    syncDirectory?: (path: string) => Promise<void>;
+}
+/** Prepare and durably validate the local destination before bounded enrollment. */
+export declare function prepareFleetRuntimeOutput(root: string, options?: FleetRuntimeFilesystemOptions): Promise<void>;
+/**
+ * Publish a completed fleet template as one generation. The stable `current`
+ * link is replaced only after both owner-only files have been fsync'd and the
+ * generation directory has been renamed into place.
+ */
+export declare function publishFinalizedFleetTemplate(root: string, template: FinalizedFleetHarnessTemplate, options?: FleetRuntimeFilesystemOptions): Promise<{
+    generation: string;
+    digest: string;
+}>;
+/** Validate the complete batch before the first filesystem mutation. */
+export declare function publishFinalizedFleetTemplates(root: string, templates: readonly FinalizedFleetHarnessTemplate[]): Promise<readonly {
+    generation: string;
+    digest: string;
+}[]>;
 export interface FilePendingEnrollmentStoreOptions {
     /** Override the state directory (default: $XDG_STATE_HOME/agent-board/pending-enroll). */
     dir?: string;

package/dist/enroll_runtime.js

@@ -7,7 +7,8 @@ import { spawn } from "node:child_process";
 import { constants as FS } from "node:fs";
 import * as fs from "node:fs/promises";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { validateFinalizedFleetHarnessTemplate } from "@consiliency/agent-board-client";
 import { resolveEnrollmentDescriptor, } from "@consiliency/agent-board-client";
 export class EnrollRuntimeError extends Error {
     code;
@@ -17,6 +18,261 @@ export class EnrollRuntimeError extends Error {
         this.code = code;
     }
 }
+export class FleetDeviceContinuationStore {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    path(id) {
+        if (!/^enr-[A-Za-z0-9-]+$/.test(id))
+            throw new EnrollRuntimeError("invalid_fleet_continuation_id", "fleet continuation id is invalid");
+        return join(this.dir, `${id}.fleet.json`);
+    }
+    async guardDir() {
+        const st = await fs.lstat(this.dir);
+        if (!st.isDirectory() || st.isSymbolicLink() || (st.mode & 0o077) !== 0 || (typeof process.getuid === "function" && st.uid !== process.getuid()))
+            throw new EnrollRuntimeError("insecure_fleet_continuation", "fleet continuation directory is unsafe");
+    }
+    async put(value) {
+        if (value.version !== "fleet_device_continuation.v1" || !value.enrollmentId || !value.runtimeOutput || !value.keyReference)
+            throw new EnrollRuntimeError("invalid_fleet_continuation", "fleet continuation is incomplete");
+        await fs.mkdir(this.dir, { recursive: true, mode: 0o700 });
+        await this.guardDir();
+        const target = this.path(value.enrollmentId);
+        const temp = `${target}.tmp-${process.pid}-${Date.now()}`;
+        const handle = await fs.open(temp, FS.O_CREAT | FS.O_EXCL | FS.O_WRONLY | FS.O_NOFOLLOW, 0o600);
+        try {
+            await handle.writeFile(JSON.stringify(value), "utf8");
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await fs.rename(temp, target);
+    }
+    async get(id) {
+        try {
+            await this.guardDir();
+            const path = this.path(id);
+            const handle = await fs.open(path, FS.O_RDONLY | FS.O_NOFOLLOW);
+            let raw;
+            try {
+                const stat = await handle.stat();
+                if (!stat.isFile() || stat.nlink !== 1 || (stat.mode & 0o077) !== 0 || (typeof process.getuid === "function" && stat.uid !== process.getuid()))
+                    throw new EnrollRuntimeError("insecure_fleet_continuation", "fleet continuation must be owner-only regular file");
+                raw = await handle.readFile("utf8");
+            }
+            finally {
+                await handle.close();
+            }
+            let value;
+            try {
+                value = JSON.parse(raw);
+            }
+            catch {
+                throw new EnrollRuntimeError("invalid_fleet_continuation", "fleet continuation is corrupt");
+            }
+            if (value.version !== "fleet_device_continuation.v1" || value.enrollmentId !== id || !value.runtimeOutput || !value.keyReference || value.pendingTemplate?.templateContractVersion !== "fleet_harness_template.pending.v1")
+                throw new EnrollRuntimeError("invalid_fleet_continuation", "fleet continuation is corrupt");
+            return value;
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw error;
+        }
+    }
+    async delete(id) { await fs.unlink(this.path(id)).catch((error) => { if (error.code !== "ENOENT")
+        throw error; }); }
+}
+export class DevicePendingEnrollmentStore {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    path(id) {
+        if (!/^enr-[A-Za-z0-9-]+$/.test(id))
+            throw new EnrollRuntimeError("invalid_device_enrollment_id", "device enrollment id is invalid");
+        return join(this.dir, `${id}.device.json`);
+    }
+    async guardDir() {
+        const stat = await fs.lstat(this.dir);
+        if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0 || (typeof process.getuid === "function" && stat.uid !== process.getuid())) {
+            throw new EnrollRuntimeError("insecure_device_pending", "device pending directory must be owner-only");
+        }
+    }
+    async put(value) {
+        const target = this.path(value.enrollmentId);
+        if (value.flow !== "device_code" || !value.deviceCode || /[\r\n\0]/.test(value.deviceCode) || !Number.isFinite(value.interval) || value.interval <= 0 || !value.slug || !value.intent)
+            throw new EnrollRuntimeError("invalid_device_pending", "device pending record is invalid");
+        await fs.mkdir(this.dir, { recursive: true, mode: 0o700 });
+        await this.guardDir();
+        const tmp = `${target}.tmp-${process.pid}-${Date.now()}`;
+        const handle = await fs.open(tmp, FS.O_CREAT | FS.O_EXCL | FS.O_WRONLY | FS.O_NOFOLLOW, 0o600);
+        try {
+            await handle.writeFile(JSON.stringify(value), "utf8");
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await fs.rename(tmp, target);
+    }
+    async get(id) {
+        const path = this.path(id);
+        try {
+            await this.guardDir();
+            const handle = await fs.open(path, FS.O_RDONLY | FS.O_NOFOLLOW);
+            let raw;
+            try {
+                const stat = await handle.stat();
+                if (!stat.isFile() || stat.nlink !== 1 || (stat.mode & 0o077) !== 0 || (typeof process.getuid === "function" && stat.uid !== process.getuid()))
+                    throw new EnrollRuntimeError("insecure_device_pending", "device pending record is unsafe");
+                raw = await handle.readFile("utf8");
+            }
+            finally {
+                await handle.close();
+            }
+            let value;
+            try {
+                value = JSON.parse(raw);
+            }
+            catch {
+                throw new EnrollRuntimeError("invalid_device_pending", "device pending record is corrupt or expired");
+            }
+            if (value.flow !== "device_code" || value.enrollmentId !== id || !value.deviceCode || !value.slug || !value.intent || (value.expiresAt !== undefined && value.expiresAt <= Math.floor(Date.now() / 1000)))
+                throw new EnrollRuntimeError("invalid_device_pending", "device pending record is corrupt or expired");
+            return value;
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw error;
+        }
+    }
+    async delete(id) { await fs.unlink(this.path(id)).catch((error) => { if (error.code !== "ENOENT")
+        throw error; }); }
+}
+async function syncDirectory(path) {
+    const handle = await fs.open(path, "r");
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function requireOwnerOnlyDirectory(path) {
+    const stat = await fs.lstat(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0
+        || (typeof process.getuid === "function" && stat.uid !== process.getuid())) {
+        throw new EnrollRuntimeError("invalid_runtime_output", "runtime output must be an owner-only directory");
+    }
+}
+/** Prepare and durably validate the local destination before bounded enrollment. */
+export async function prepareFleetRuntimeOutput(root, options = {}) {
+    if (!root || root.includes("\0"))
+        throw new EnrollRuntimeError("invalid_runtime_output", "runtime output path is invalid");
+    const sync = options.syncDirectory ?? syncDirectory;
+    await fs.mkdir(root, { recursive: true, mode: 0o700 }).catch((error) => {
+        if (error.code !== "EEXIST")
+            throw error;
+    });
+    await requireOwnerOnlyDirectory(root);
+    await sync(dirname(root));
+    await sync(root);
+    const generationRoot = join(root, "generations");
+    await fs.mkdir(generationRoot, { mode: 0o700 }).catch((error) => {
+        if (error.code !== "EEXIST")
+            throw error;
+    });
+    await requireOwnerOnlyDirectory(generationRoot);
+    await sync(root);
+    await sync(generationRoot);
+}
+/**
+ * Publish a completed fleet template as one generation. The stable `current`
+ * link is replaced only after both owner-only files have been fsync'd and the
+ * generation directory has been renamed into place.
+ */
+export async function publishFinalizedFleetTemplate(root, template, options = {}) {
+    validateFinalizedFleetHarnessTemplate(template);
+    const sync = options.syncDirectory ?? syncDirectory;
+    await prepareFleetRuntimeOutput(root, { syncDirectory: sync });
+    const generationRoot = join(root, "generations");
+    const generation = join(generationRoot, template.receiptDigest);
+    const runtimeEnv = Object.entries(template.runtimeEnv).map(([key, value]) => `${key}=${JSON.stringify(value)}`).join("\n") + "\n";
+    const pmcp = JSON.stringify(template.pmcpStanza) + "\n";
+    const switchCurrent = async () => {
+        const next = join(root, `.current-${process.pid}-${Date.now()}`);
+        await fs.symlink(join("generations", template.receiptDigest), next);
+        try {
+            await sync(root);
+            await fs.rename(next, join(root, "current"));
+            await sync(root);
+        }
+        catch (error) {
+            await fs.unlink(next).catch(() => { });
+            throw error;
+        }
+    };
+    try {
+        const stat = await fs.lstat(generation);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new EnrollRuntimeError("runtime_generation_exists", "runtime generation is unsafe");
+        if (await fs.readFile(join(generation, "runtime.env"), "utf8") !== runtimeEnv || await fs.readFile(join(generation, "pmcp.json"), "utf8") !== pmcp)
+            throw new EnrollRuntimeError("runtime_generation_exists", "runtime generation already exists with different content");
+        await switchCurrent();
+        return { generation, digest: template.receiptDigest };
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const staged = join(generationRoot, `.${template.receiptDigest}.staged-${process.pid}-${Date.now()}`);
+    await fs.mkdir(staged, { mode: 0o700 });
+    try {
+        const write = async (name, content) => {
+            const path = join(staged, name);
+            const handle = await fs.open(path, FS.O_CREAT | FS.O_EXCL | FS.O_WRONLY | FS.O_NOFOLLOW, 0o600);
+            try {
+                await handle.writeFile(content, "utf8");
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+        };
+        await write("runtime.env", runtimeEnv);
+        await write("pmcp.json", pmcp);
+        await sync(staged);
+        await fs.rename(staged, generation);
+        await sync(generationRoot);
+        await switchCurrent();
+        return { generation, digest: template.receiptDigest };
+    }
+    catch (error) {
+        await fs.rm(staged, { recursive: true, force: true }).catch(() => { });
+        throw error;
+    }
+}
+/** Validate the complete batch before the first filesystem mutation. */
+export async function publishFinalizedFleetTemplates(root, templates) {
+    if (templates.length === 0)
+        throw new EnrollRuntimeError("invalid_runtime_batch", "runtime template batch is empty");
+    for (const template of templates)
+        validateFinalizedFleetHarnessTemplate(template);
+    const stanzaNames = templates.map((template) => template.stanzaName);
+    if (new Set(stanzaNames).size !== stanzaNames.length)
+        throw new EnrollRuntimeError("runtime_batch_collision", "runtime template batch has duplicate stanza names");
+    const environments = templates.map((template) => JSON.stringify(template.runtimeEnv));
+    if (new Set(environments).size !== environments.length)
+        throw new EnrollRuntimeError("runtime_batch_collision", "runtime template batch has duplicate environments");
+    const results = [];
+    for (const template of templates)
+        results.push(await publishFinalizedFleetTemplate(root, template));
+    return results;
+}
 function nowSeconds(now) {
     return now ? now() : Math.floor(Date.now() / 1000);
 }
@@ -86,6 +342,7 @@ export class FilePendingEnrollmentStore {
             redirectMode: pending.redirectMode,
             clientId: pending.clientId,
             expiresAt: pending.expiresAt,
+            deviceCode: pending.deviceCode,
         };
         const finalPath = this.fileFor(pending.enrollmentId);
         const tempPath = `${finalPath}.tmp-${process.pid}-${Date.now()}`;
@@ -165,6 +422,7 @@ export class FilePendingEnrollmentStore {
             redirectMode: parsed.redirectMode ?? "oob",
             clientId: parsed.clientId,
             expiresAt: parsed.expiresAt,
+            deviceCode: parsed.deviceCode,
         };
     }
     async delete(enrollmentId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@consiliency/agent-board-cli",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "repository": "https://github.com/Consiliency/message-board.git",
   "type": "module",
   "main": "./dist/index.js",
@@ -31,7 +31,7 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@consiliency/agent-board-client": "1.15.0",
+    "@consiliency/agent-board-client": "1.16.0",
     "commander": "^14.0.1"
   },
   "license": "Apache-2.0"