@consiliency/agent-board-cli 1.22.5 → 1.23.0

package/dist/enroll_runtime.js

@@ -10,6 +10,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { validateFinalizedFleetHarnessTemplate, markAuthoredCode } from "@consiliency/agent-board-client";
 import { resolveEnrollmentDescriptor, } from "@consiliency/agent-board-client";
+import { writeOwnerOnlyFile } from "./identity_writer.js";
 export class EnrollRuntimeError extends Error {
     code;
     constructor(code, message) {
@@ -233,19 +234,10 @@ export async function publishFinalizedFleetTemplate(root, template, options = {}
     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);
+        // Straight into the staged directory, not temp+rename: the generation becomes visible
+        // only when the whole directory is renamed below.
+        await writeOwnerOnlyFile(join(staged, "runtime.env"), runtimeEnv);
+        await writeOwnerOnlyFile(join(staged, "pmcp.json"), pmcp);
         await sync(staged);
         await fs.rename(staged, generation);
         await sync(generationRoot);

package/dist/identity_writer.d.ts

@@ -0,0 +1,44 @@
+import { type EnrollmentOutcome } from "@consiliency/agent-board-client";
+export interface OwnerOnlyWriteOptions {
+    syncDirectory?: (path: string) => Promise<void>;
+}
+/** Create `path` exclusively (never following a planted link) at 0600, write, fsync. */
+export declare function writeOwnerOnlyFile(path: string, content: string): Promise<void>;
+/**
+ * Write `content` to `path` so a reader sees the old file or the whole new one, never a
+ * part: an exclusive 0600 temp beside it, fsync'd, renamed over it, then the directory
+ * fsync'd. On any throw before the rename the temp is removed.
+ */
+export declare function writeOwnerOnlyFileAtomic(path: string, content: string, options?: OwnerOnlyWriteOptions): Promise<void>;
+export interface IdentityDeployment {
+    boardUrl: string;
+    sessionUrl: string;
+    publishableKey: string;
+}
+/**
+ * Where each deployment value is read, in precedence order: the enrollment's own names first
+ * (so the file records the deployment the enrollment used — pinned against the client's
+ * enrollment resolvers in the test), then the identity names. The generic Supabase names the
+ * enrollment also accepts for the publishable key are NOT read: a generic key never fills an
+ * identity field, here or in the loader.
+ */
+export declare const DEPLOYMENT_ENV_NAMES: Readonly<Record<keyof IdentityDeployment, readonly string[]>>;
+/**
+ * The deployment half of an identity, read and shape-checked before enrollment commits.
+ * Absent → `identity_incomplete`; not the non-secret shape its key requires →
+ * `identity_secret_value`. Both name the variable, never the value.
+ */
+export declare function resolveIdentityDeployment(env: NodeJS.ProcessEnv): IdentityDeployment;
+/**
+ * The identity file's values for an enrolled agent. The URLs and publishable key come only
+ * from `deployment`; everything else from the outcome. Validated by the client's serializer
+ * before it is returned.
+ */
+export declare function identityValuesFromEnrollment(outcome: EnrollmentOutcome, deployment: IdentityDeployment): Record<string, string>;
+/**
+ * Write `harness`'s identity file for this host. Every refusal (bad harness, relative root,
+ * invalid host, bad value) fires before the first filesystem change. The directory is then
+ * put through the reader's own trusted walk, so the writer never produces a file the loader
+ * would refuse to open. Returns the path written.
+ */
+export declare function writeIdentityFile(harness: string, values: Readonly<Record<string, string>>, env: NodeJS.ProcessEnv, options?: OwnerOnlyWriteOptions): Promise<string>;

package/dist/identity_writer.js

@@ -0,0 +1,186 @@
+// CREDPATH SL-2 — the identity file WRITER. The contract (key set, value shapes, path, trusted
+// walk) is the client's `identity_file.ts`; nothing here restates it. This module only decides
+// which VALUES go in, and writes them the way the reader will accept.
+//
+// Order matters, because the Portal enrollment token is single-use
+// (Consiliency/message-board#521): `resolveIdentityDeployment` runs BEFORE enrollment commits,
+// so a missing or secret-shaped deployment value is refused while the token is still unspent.
+// Only then does enrollment run, and `identityValuesFromEnrollment` + `writeIdentityFile` turn
+// its outcome into the file.
+import { createHash } from "node:crypto";
+import { constants as FS } from "node:fs";
+import * as fs from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { CredentialResolutionError, ENV_ALIAS_FAMILIES, identityConfigRoot, identityFilePath, serializeIdentityFile, walkTrustedDirectory, } from "@consiliency/agent-board-client";
+async function syncDirectory(path) {
+    const handle = await fs.open(path, "r");
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Create `path` exclusively (never following a planted link) at 0600, write, fsync. */
+export async function writeOwnerOnlyFile(path, content) {
+    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();
+    }
+}
+/**
+ * Write `content` to `path` so a reader sees the old file or the whole new one, never a
+ * part: an exclusive 0600 temp beside it, fsync'd, renamed over it, then the directory
+ * fsync'd. On any throw before the rename the temp is removed.
+ */
+export async function writeOwnerOnlyFileAtomic(path, content, options = {}) {
+    const sync = options.syncDirectory ?? syncDirectory;
+    const temp = `${path}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+    try {
+        await writeOwnerOnlyFile(temp, content);
+        await fs.rename(temp, path);
+    }
+    catch (error) {
+        await fs.unlink(temp).catch(() => { });
+        throw error;
+    }
+    await sync(dirname(path));
+}
+/** The identity-name alias family containing `canonical`, from the client's one declaration. */
+function identityFamily(canonical) {
+    const family = ENV_ALIAS_FAMILIES.find((members) => members.includes(canonical));
+    if (!family)
+        throw new Error(`identity_writer: no alias family declares ${canonical}`);
+    return family;
+}
+/**
+ * Where each deployment value is read, in precedence order: the enrollment's own names first
+ * (so the file records the deployment the enrollment used — pinned against the client's
+ * enrollment resolvers in the test), then the identity names. The generic Supabase names the
+ * enrollment also accepts for the publishable key are NOT read: a generic key never fills an
+ * identity field, here or in the loader.
+ */
+export const DEPLOYMENT_ENV_NAMES = Object.freeze({
+    boardUrl: Object.freeze(["MESSAGE_BOARD_ENROLL_BOARD_URL", ...identityFamily("AGENT_BOARD_URL")]),
+    sessionUrl: Object.freeze(["MESSAGE_BOARD_ENROLL_SESSION_URL", "AGENT_BOARD_ENROLL_SESSION_URL", ...identityFamily("AGENT_BOARD_SESSION_URL")]),
+    publishableKey: Object.freeze(["MESSAGE_BOARD_ENROLL_PUBLISHABLE_KEY", "AGENT_BOARD_ENROLL_PUBLISHABLE_KEY", ...identityFamily("AGENT_BOARD_PUBLISHABLE_KEY")]),
+});
+const DEPLOYMENT_FILE_KEYS = {
+    boardUrl: "AGENT_BOARD_URL",
+    sessionUrl: "AGENT_BOARD_SESSION_URL",
+    publishableKey: "AGENT_BOARD_PUBLISHABLE_KEY",
+};
+// Well-shaped stand-ins for the values only the enrollment outcome supplies. The preflight
+// substitutes ONE deployment value into this map and lets `serializeIdentityFile` judge it, so
+// the shape rule applied here is the parser's own, never a second copy.
+const PREFLIGHT_STAND_INS = {
+    AGENT_BOARD_URL: "https://preflight.invalid",
+    AGENT_BOARD_SESSION_URL: "https://preflight.invalid/session",
+    AGENT_BOARD_PUBLISHABLE_KEY: "sb_publishable_preflight",
+    AGENT_BOARD_AGENT_SLUG: "preflight",
+    AGENT_BOARD_EXPECTED_AGENT_HANDLE: "preflight",
+    AGENT_BOARD_AGENT_KEY_REFERENCE: "os_keychain:preflight",
+    AGENT_BOARD_SIGNING_KEY_ID: "preflight",
+    AGENT_BOARD_SIGNING_KEY_VERSION: "1",
+    AGENT_BOARD_SIGNING_PUBLIC_KEY_FINGERPRINT: `sha256:${"A".repeat(43)}`,
+    MESSAGE_BOARD_AGENT_AUTH_MODE: "keystore_session",
+};
+function firstPresent(env, names) {
+    for (const name of names) {
+        const value = env[name];
+        if (value !== undefined && value.trim() !== "")
+            return { name, value: value.trim() };
+    }
+    return undefined;
+}
+/**
+ * The deployment half of an identity, read and shape-checked before enrollment commits.
+ * Absent → `identity_incomplete`; not the non-secret shape its key requires →
+ * `identity_secret_value`. Both name the variable, never the value.
+ */
+export function resolveIdentityDeployment(env) {
+    const deployment = {};
+    for (const field of Object.keys(DEPLOYMENT_ENV_NAMES)) {
+        const names = DEPLOYMENT_ENV_NAMES[field];
+        const found = firstPresent(env, names);
+        if (!found) {
+            throw new CredentialResolutionError("identity_incomplete", `cannot write an identity file: no ${DEPLOYMENT_FILE_KEYS[field]} for it (set one of: ${names.join(", ")})`);
+        }
+        try {
+            serializeIdentityFile({ ...PREFLIGHT_STAND_INS, [DEPLOYMENT_FILE_KEYS[field]]: found.value });
+        }
+        catch (error) {
+            if (error.code !== "identity_secret_value")
+                throw error;
+            throw new CredentialResolutionError("identity_secret_value", `${found.name} is not the non-secret shape ${DEPLOYMENT_FILE_KEYS[field]} requires; an identity file carries public values only`);
+        }
+        deployment[field] = found.value;
+    }
+    return deployment;
+}
+// ---------------------------------------------------------------------------------------------
+// Outcome → values → file
+// ---------------------------------------------------------------------------------------------
+/** `sha256:` + base64url, over the DECODED public key — exactly what fleet finalize recomputes. */
+function publicKeyFingerprint(agentPublicKey) {
+    const publicKey = Buffer.from(agentPublicKey, "base64url");
+    // The same refusal finalize makes: a value that is not canonical base64url of 32 bytes would
+    // still hash to a plausible fingerprint, of a key that is not the enrolled one. The
+    // re-encode comparison is also the charset and padding check.
+    if (publicKey.length !== 32 || publicKey.toString("base64url") !== agentPublicKey) {
+        throw new CredentialResolutionError("identity_public_key_invalid", "the enrollment outcome's public key is not a 32-byte base64url key");
+    }
+    return `sha256:${createHash("sha256").update(publicKey).digest("base64url")}`;
+}
+/**
+ * The identity file's values for an enrolled agent. The URLs and publishable key come only
+ * from `deployment`; everything else from the outcome. Validated by the client's serializer
+ * before it is returned.
+ */
+export function identityValuesFromEnrollment(outcome, deployment) {
+    const values = {
+        AGENT_BOARD_URL: deployment.boardUrl,
+        AGENT_BOARD_SESSION_URL: deployment.sessionUrl,
+        AGENT_BOARD_PUBLISHABLE_KEY: deployment.publishableKey,
+        AGENT_BOARD_AGENT_SLUG: outcome.agentHandle,
+        AGENT_BOARD_EXPECTED_AGENT_HANDLE: outcome.agentHandle,
+        // The form `fleet_onboarding.ts` checks: `${resolver}:${handle}`.
+        AGENT_BOARD_AGENT_KEY_REFERENCE: `${outcome.keyReference.resolver}:${outcome.keyReference.handle}`,
+        // `keyId`, the server's key identity /session mints against — NOT `signingKeyId`, the row.
+        AGENT_BOARD_SIGNING_KEY_ID: outcome.keyId,
+        AGENT_BOARD_SIGNING_KEY_VERSION: String(outcome.keyVersion),
+        AGENT_BOARD_SIGNING_PUBLIC_KEY_FINGERPRINT: publicKeyFingerprint(outcome.agentPublicKey),
+        MESSAGE_BOARD_AGENT_AUTH_MODE: "keystore_session",
+    };
+    serializeIdentityFile(values);
+    return values;
+}
+async function mkdirPrivate(path) {
+    await fs.mkdir(path, { mode: 0o700 }).catch((error) => {
+        if (error.code !== "EEXIST")
+            throw error;
+    });
+}
+/**
+ * Write `harness`'s identity file for this host. Every refusal (bad harness, relative root,
+ * invalid host, bad value) fires before the first filesystem change. The directory is then
+ * put through the reader's own trusted walk, so the writer never produces a file the loader
+ * would refuse to open. Returns the path written.
+ */
+export async function writeIdentityFile(harness, values, env, options = {}) {
+    const path = identityFilePath(harness, env);
+    const content = serializeIdentityFile(values);
+    const configRoot = identityConfigRoot(env);
+    const strictFrom = join(configRoot, "agent-board");
+    await fs.mkdir(configRoot, { recursive: true, mode: 0o700 });
+    await mkdirPrivate(strictFrom);
+    await mkdirPrivate(join(strictFrom, "identities"));
+    await mkdirPrivate(dirname(path));
+    walkTrustedDirectory(dirname(path), strictFrom);
+    await writeOwnerOnlyFileAtomic(path, content, options);
+    return path;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@consiliency/agent-board-cli",
-  "version": "1.22.5",
+  "version": "1.23.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.38.0",
+    "@consiliency/agent-board-client": "1.39.0",
     "commander": "^14.0.1"
   },
   "license": "Apache-2.0"