@consiliency/agent-board-cli 1.24.0 → 1.25.0

package/dist/doctor.js

@@ -9,13 +9,17 @@
 // only with a live `wake_producer` at its expected tier, so 0 is never returned without runtime
 // evidence. Output is names and codes only: no identity value, key or path content is printed,
 // and an error's `code` is printed only when this repository authored it (`authoredCode`).
+import { execFile } from "node:child_process";
 import { randomBytes } from "node:crypto";
+import { existsSync, readdirSync } from "node:fs";
 import { homedir, userInfo } from "node:os";
-import { resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { AUTHORED_CAUSE_CODES, AgentSocketSelectionError, GENERIC_SUPABASE_FIELDS, IDENTITY_FILE_KEYS, IDENTITY_TRIGGER_FIELDS, KeystoreUnavailableError, assertIdentityHarness, codeProvenance, createAgentBoardClient, createOsKeychainBackend, expectedWakeTier, normalizeKeyReference, readIdentityFile, readSessionRecords, resolveCredentials, selectAgentSocketIdentity, } from "@consiliency/agent-board-client";
 import { judgeRegistration, nodeRegistrationFs, } from "./doctor_scopes.js";
+import { resolveKeyslotDir } from "./assets.js";
+import { SLOT_RE, externalDeclarationProblems, fileIdentity, keyslotSocketDir, machineIdOf, resolveAgentSocketPath, unsealedOptinProblems, } from "./setup_storage.js";
 export const DOCTOR_CHECKS = Object.freeze([
-    "identity_file", "keystore_key", "whoami", "board_membership", "registration", "runtime",
+    "identity_file", "keystore_key", "key_storage", "whoami", "board_membership", "registration", "runtime",
 ]);
 export const REPORTABLE_TOKEN = /^[A-Za-z0-9._/-]{1,64}$/;
 const reportable = (value) => value === null ? null : REPORTABLE_TOKEN.test(value) ? value : "unrecognised";
@@ -228,6 +232,142 @@ async function keystoreCheck(values, env, probe) {
         ? check("pass", "fingerprint_matches")
         : check("fail", "fingerprint_mismatch");
 }
+/**
+ * IF-0-SETUP-3 / IF-0-KEYSEAL-6 — which storage holds the identity's key, MEASURED: from the file's
+ * key reference plus the packaged `status.sh --json`, never from anything setup recorded.
+ *
+ *  - an `os_keychain` reference → pass `os_keychain` (keystore_key proves the key is there);
+ *  - an `agent_socket` reference: the socket keystore_key signs through (same resolution, including
+ *    `MESSAGE_BOARD_AGENT_SOCKET_PATH`) is matched by DEVICE AND INODE, never spelling, against
+ *    each `$XDG_RUNTIME_DIR/agent-board/<slot>.sock`;
+ *    - a keyslot → `status.sh --harness <h> --slot <slot> --json`. Its measurement fields
+ *      (machine_id, uid, slot, seam, mode) are compared with doctor's own values FIRST: a report
+ *      that is not about this host, user and slot says nothing, so a mismatch or a missing field is
+ *      2 even beside a status exit 1 (both are non-pass). Then exit 1 → 1, exit 2 → 2, and exit 0
+ *      passes as `sealed`, or as `unsealed` only when doctor's own field-by-field read of the opt-in
+ *      is valid (an invalid opt-in is 1, as A1-S2 requires of status.sh);
+ *    - any other socket → `external`, which passes only with a valid declaration
+ *      (`<configRoot>/agent-board/external-agent`); undeclared or mismatched → 2.
+ *  - status.sh absent, unrunnable, timed out or unparseable → 2.
+ */
+const STATUS_MODES = new Set(["sealed", "unsealed", "contradiction", "undetermined"]);
+const STATUS_EXIT2_REASON = /^(nothing_committed|undeterminable|linger_off|upgrade_available|loader_outdated|loader_unrecorded|legacy_loader_present|capability_(error|incapable|incapable-for-keyslot))$/;
+const STATUS_TIMEOUT_MS = 180_000;
+function runStatus(file, args, env) {
+    return new Promise((done) => {
+        execFile(file, args, { env, timeout: STATUS_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024, encoding: "utf8" }, (error, stdout) => {
+            const failure = error;
+            const code = !failure ? 0 : typeof failure.code === "number" && !failure.killed ? failure.code : null;
+            done({ code, stdout: String(stdout ?? "") });
+        });
+    });
+}
+/** The keyslot whose socket is the same file as `socket`, or null. */
+function matchKeyslot(socket, env) {
+    const dir = keyslotSocketDir(env);
+    const target = fileIdentity(socket);
+    if (!dir || !target)
+        return null;
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return null;
+    }
+    for (const name of names.sort()) {
+        if (!name.endsWith(".sock"))
+            continue;
+        const slot = name.slice(0, -".sock".length);
+        if (!SLOT_RE.test(slot))
+            continue;
+        const candidate = fileIdentity(join(dir, name));
+        if (candidate && candidate.dev === target.dev && candidate.ino === target.ino)
+            return slot;
+    }
+    return null;
+}
+async function keyStorageCheck(harness, values, fileEnv, env, options) {
+    let reference;
+    try {
+        reference = normalizeKeyReference(values[KEY_REFERENCE_KEY]);
+    }
+    catch {
+        return check("undetermined", "key_reference_invalid");
+    }
+    if (reference.resolver === "os_keychain")
+        return check("pass", "os_keychain");
+    if (reference.resolver !== "agent_socket")
+        return check("undetermined", "resolver_unsupported");
+    const socket = resolveAgentSocketPath(String(reference.handle), fileEnv);
+    if (socket === null)
+        return check("undetermined", "agent_socket_unresolved");
+    if (fileIdentity(socket) === null)
+        return check("undetermined", "agent_socket_absent");
+    const uid = options.uid ?? (typeof process.getuid === "function" ? process.getuid() : -1);
+    const machineId = machineIdOf(options.machineIdFile);
+    const slot = matchKeyslot(socket, env);
+    if (slot === null) {
+        const problems = externalDeclarationProblems(env, socket, uid, machineId);
+        if (problems.length === 0)
+            return check("pass", "external");
+        return check("undetermined", problems.includes("missing") ? "external_undeclared" : "external_declaration_mismatch");
+    }
+    let dir;
+    try {
+        dir = options.keyslotDir ?? resolveKeyslotDir();
+    }
+    catch {
+        return check("undetermined", "status_absent");
+    }
+    if (!existsSync(join(dir, "status.sh")))
+        return check("undetermined", "status_absent");
+    const run = await runStatus(join(dir, "status.sh"), ["--harness", harness, "--slot", slot, "--json"], env);
+    if (run.code === null)
+        return check("undetermined", "status_did_not_complete");
+    let report;
+    try {
+        const parsed = JSON.parse(run.stdout);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            throw new Error("not an object");
+        report = parsed;
+    }
+    catch {
+        return check("undetermined", "status_unreadable");
+    }
+    const seam = typeof env.KEYSEAL_TEST_ROOT === "string" && env.KEYSEAL_TEST_ROOT !== "";
+    const own = {
+        machine_id: (value) => machineId !== null && value === machineId,
+        uid: (value) => value === uid,
+        slot: (value) => value === slot,
+        seam: (value) => value === seam,
+        mode: (value) => typeof value === "string" && STATUS_MODES.has(value),
+    };
+    for (const [field, matches] of Object.entries(own)) {
+        if (!(field in report) || report[field] === null)
+            return check("undetermined", `status_field_missing:${field}`);
+        if (!matches(report[field]))
+            return check("undetermined", `status_field_mismatch:${field}`);
+    }
+    if (run.code === 1)
+        return check("fail", "keyslot_status_failed");
+    if (run.code === 2) {
+        const reasons = Array.isArray(report.exit2_reasons) ? report.exit2_reasons : [];
+        const named = reasons.length > 0 && reasons.every((reason) => typeof reason === "string" && STATUS_EXIT2_REASON.test(reason));
+        return check("undetermined", named ? `keyslot_status_undetermined:${reasons.join(",")}` : "keyslot_status_undetermined");
+    }
+    if (run.code !== 0)
+        return check("undetermined", "status_unexpected_exit");
+    if (report.mode === "sealed")
+        return check("pass", "sealed");
+    if (report.mode === "unsealed") {
+        const optin = report.optin;
+        if (optin?.ok !== true)
+            return check("fail", "unsealed_optin_invalid");
+        return unsealedOptinProblems(env, slot, uid, machineId).length === 0 ? check("pass", "unsealed") : check("fail", "unsealed_optin_invalid");
+    }
+    return check("undetermined", "status_mode_unexpected");
+}
 async function whoamiCheck(client, expectedHandle) {
     let rows;
     try {
@@ -342,12 +482,14 @@ export async function runDoctor(options) {
     }
     if (values === null) {
         checks.keystore_key = check("undetermined", "no_identity_file");
+        checks.key_storage = check("undetermined", "no_identity_file");
         checks.whoami = check("undetermined", "no_identity_file");
         checks.board_membership = check("undetermined", "no_identity_file");
     }
     else {
         const fileEnv = fileIdentityEnv(env, values);
         checks.keystore_key = await keystoreCheck(values, fileEnv, options.probeKeystore ?? defaultKeystoreProbe);
+        checks.key_storage = await keyStorageCheck(harness, values, fileEnv, env, options);
         let client = null;
         try {
             client = (options.createClient ?? defaultClient)(fileEnv);

package/dist/identity_writer.d.ts

@@ -16,16 +16,18 @@ export interface IdentityDeployment {
     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.
+ * Where each deployment value is read, in precedence order: the client's one alias table
+ * (`DEPLOYMENT_ENV_ALIASES`), which puts the enrollment's own names first (so the file records
+ * the deployment the enrollment used) and then the identity names. The enrollment resolvers read
+ * the same table, so the two cannot disagree. The generic Supabase names are in no list: 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 →
+ * The deployment half of an identity, read and shape-checked before enrollment commits. Each
+ * value is the shipped default, or env under the board group's all-or-nothing rule (the
+ * client's `resolveDeploymentField`). Absent from an env-set group → `identity_incomplete`,
+ * naming the variable that switched the group off; 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;

package/dist/identity_writer.js

@@ -11,7 +11,7 @@ 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";
+import { CredentialResolutionError, DEPLOYMENT_ENV_ALIASES, describeMissingDeploymentFields, identityConfigRoot, resolveDeploymentField, identityFilePath, serializeIdentityFile, walkTrustedDirectory, } from "@consiliency/agent-board-client";
 async function syncDirectory(path) {
     const handle = await fs.open(path, "r");
     try {
@@ -50,24 +50,17 @@ export async function writeOwnerOnlyFileAtomic(path, content, options = {}) {
     }
     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.
+ * Where each deployment value is read, in precedence order: the client's one alias table
+ * (`DEPLOYMENT_ENV_ALIASES`), which puts the enrollment's own names first (so the file records
+ * the deployment the enrollment used) and then the identity names. The enrollment resolvers read
+ * the same table, so the two cannot disagree. The generic Supabase names are in no list: 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")]),
+    boardUrl: DEPLOYMENT_ENV_ALIASES.boardUrl,
+    sessionUrl: DEPLOYMENT_ENV_ALIASES.sessionUrl,
+    publishableKey: DEPLOYMENT_ENV_ALIASES.publishableKey,
 });
 const DEPLOYMENT_FILE_KEYS = {
     boardUrl: "AGENT_BOARD_URL",
@@ -89,27 +82,22 @@ const PREFLIGHT_STAND_INS = {
     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 →
+ * The deployment half of an identity, read and shape-checked before enrollment commits. Each
+ * value is the shipped default, or env under the board group's all-or-nothing rule (the
+ * client's `resolveDeploymentField`). Absent from an env-set group → `identity_incomplete`,
+ * naming the variable that switched the group off; 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(", ")})`);
+        const resolved = resolveDeploymentField(env, field);
+        if (resolved.value === undefined) {
+            throw new CredentialResolutionError("identity_incomplete", `cannot write an identity file: no ${DEPLOYMENT_FILE_KEYS[field]} for it ${describeMissingDeploymentFields([field], resolved.switchedBy)}`);
         }
+        // A default is named by the file key it fills: it came from no variable.
+        const found = { name: resolved.name ?? `the default ${DEPLOYMENT_FILE_KEYS[field]}`, value: resolved.value };
         try {
             serializeIdentityFile({ ...PREFLIGHT_STAND_INS, [DEPLOYMENT_FILE_KEYS[field]]: found.value });
         }

package/dist/setup.d.ts

@@ -0,0 +1,116 @@
+import type { Command } from "commander";
+import { type DeviceAuthorizationPrompt, type EnrollmentIntent, type EnrollmentOutcome } from "@consiliency/agent-board-client";
+import { type BakedAssets } from "./assets.js";
+import { type DoctorOptions, type DoctorReport } from "./doctor.js";
+import { type DepsOutcome, type KeyStorageContext, type KeyStorageSelection } from "./setup_storage.js";
+import { type ChildRunner, type WriterContext } from "./setup_writers.js";
+export declare const SETUP_STEPS: readonly ["preflight", "deps", "key", "enroll", "identity", "board", "harness", "doctor"];
+export type SetupStepName = (typeof SETUP_STEPS)[number];
+export type SetupStatus = "done" | "already" | "skipped" | "failed" | "undetermined";
+export interface SetupStep {
+    step: SetupStepName | "clear_pending";
+    status: SetupStatus;
+    reason: string;
+}
+export interface SetupReport {
+    steps: SetupStep[];
+    exit: 0 | 1 | 2;
+    /** Human text: per-step fixes and the next steps. Never part of `--json`'s stdout. */
+    notes: string[];
+}
+export interface SetupOptions {
+    harness: string;
+    slug?: string;
+    invite?: boolean;
+    allowUnsealedKey?: boolean;
+    agentSocket?: string;
+    scope?: string;
+    installDeps?: boolean;
+    clearPending?: boolean;
+    /** Default true; `--no-follow-symlinks` refuses to write through a symlinked config. */
+    followSymlinks?: boolean;
+}
+/** The enrollment setup runs: the device flow, the key reference injected, intent always `none`. */
+export type SetupEnroller = (input: {
+    slug: string;
+    intent: EnrollmentIntent;
+    keyReference: string;
+    env: NodeJS.ProcessEnv;
+    onDeviceAuthorization: (prompt: DeviceAuthorizationPrompt) => void | Promise<void>;
+}) => Promise<EnrollmentOutcome>;
+export interface BoardClient {
+    redeemInviteLink(input: {
+        p_code: string;
+    }): Promise<unknown>;
+}
+export interface SetupDeps {
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    platform?: NodeJS.Platform;
+    /** stdin is a terminal. Default `process.stdin.isTTY === true`. */
+    interactive?: boolean;
+    /** One line from the terminal; `secret` hides the echo. */
+    prompt?: (question: string, options: {
+        secret: boolean;
+    }) => Promise<string>;
+    /** All of stdin (non-interactive). */
+    readStdin?: () => Promise<string>;
+    /** Every child (busctl, sudo, the harness CLIs) runs through this, with no stdin. */
+    run?: ChildRunner;
+    /** Default `/usr/bin/sudo`: never a PATH lookup. */
+    sudoPath?: string;
+    hostname?: () => string;
+    bakedAssets?: () => BakedAssets;
+    selectKeyStorage?: (ctx: KeyStorageContext) => Promise<KeyStorageSelection>;
+    /** Seams passed through to the storage selector (probeKeychain, run, keyslotDir, …). */
+    storage?: Partial<KeyStorageContext>;
+    enroll?: SetupEnroller;
+    createBoardClient?: (fileEnv: NodeJS.ProcessEnv) => BoardClient;
+    doctor?: (options: DoctorOptions) => Promise<DoctorReport>;
+    /** Seams passed through to doctor (createClient, probeKeystore, isAlive, …). */
+    doctorOptions?: Partial<DoctorOptions>;
+    /** Seams passed through to the harness writer (fs, claudeManagedDir). */
+    writer?: Partial<Pick<WriterContext, "fs" | "claudeManagedDir">>;
+}
+export declare const DEFAULT_SUDO = "/usr/bin/sudo";
+export declare const SECRET_SERVICE_NAME = "org.freedesktop.secrets";
+/** `busctl --user call … NameHasOwner`: asks the BUS whether the name is owned; never calls the service. */
+export declare const NAME_HAS_OWNER_ARGS: readonly string[];
+/**
+ * The keychain tool's install, one complete argv per package manager, first found wins. Each
+ * package name was re-checked against the distro's own index (throwaway containers, 2026-09-27):
+ * ubuntu 24.04 `libsecret-tools` ships ./usr/bin/secret-tool; fedora 44 `dnf repoquery
+ * --whatprovides /usr/bin/secret-tool` → libsecret; arch `pacman -F usr/bin/secret-tool` →
+ * core/libsecret; opensuse tumbleweed `zypper se --provides /usr/bin/secret-tool` → secret-tool
+ * (NOT libsecret-tools, which the plan text named).
+ */
+export declare const KEYCHAIN_INSTALL_ARGV: ReadonlyArray<{
+    manager: string;
+    argv: readonly string[];
+}>;
+/** `<short hostname>-<harness>`, lowercased to `[a-z0-9-]`. */
+export declare function defaultSlug(host: string, harness: string): string;
+export declare function pendingMarkerPath(harness: string, env: NodeJS.ProcessEnv): string;
+interface DepsContext {
+    env: NodeJS.ProcessEnv;
+    platform: NodeJS.Platform;
+    interactive: boolean;
+    installDeps: boolean;
+    run: ChildRunner;
+    sudo: string;
+    prompt: (question: string, options: {
+        secret: boolean;
+    }) => Promise<string>;
+}
+export declare function depsStep(ctx: DepsContext): Promise<DepsOutcome & {
+    fix?: string;
+}>;
+export declare function runSetup(options: SetupOptions, deps?: SetupDeps): Promise<SetupReport>;
+export type SetupRunner = (options: SetupOptions) => Promise<SetupReport>;
+interface SetupIo {
+    writeStdout(message: string): void;
+    writeStderr(message: string): void;
+}
+export declare function formatSetupReport(report: SetupReport): string;
+export declare function addSetupCommand(program: Command, io: SetupIo, setup: SetupRunner): void;
+export {};