failproofai 1.0.0-beta.2 → 1.0.0-beta.4

package/src/hooks/cloud-connection.ts

@@ -0,0 +1,205 @@
+/**
+ * One connection to Failproof Cloud, with two capabilities.
+ *
+ * # Why this exists
+ *
+ * Enrolment (#632) and collection (#640) were built independently and each
+ * arrived with its own credential file, its own URL and its own setup step:
+ *
+ *   pull policy   ->  ~/.failproofai/cloud.json    <base>/enforcement/v1/...
+ *   push events   ->  ~/.failproofai/ingest.json   <base>/events
+ *
+ * Same server, same organisation, usually the same key. Asked twice, a user
+ * who connects for policy sees an empty dashboard and reasonably concludes the
+ * product is broken — the second setup step is invisible until someone goes
+ * looking for it.
+ *
+ * So the URL and token are asked for ONCE and both capabilities are configured
+ * from them. The two files stay separate on disk — that is a real security
+ * boundary, since `cloud.json` and `ingest.json` can hold different keys with
+ * different permissions, and the daemon reads them independently — but nothing
+ * above this module has to know that.
+ *
+ * # Capabilities are verified and reported INDEPENDENTLY
+ *
+ * A key may carry `policies:pull` and not `events:add`, or the reverse. The
+ * honest outcome is then a partial connection with a precise reason, not an
+ * all-or-nothing failure: refusing to enrol for policy because the dashboard
+ * would be empty protects nothing, and silently skipping ingest reproduces the
+ * exact confusion this module removes.
+ */
+import {
+  cloudCredentialPath,
+  verifyCloudCredentials,
+  writeCloudCredentials,
+  type CloudCredentials,
+} from "./cloud-enrollment";
+import {
+  ingestPath,
+  validateIngestKey,
+  writeCollectorSettings,
+  writeIngestCredential,
+  type CollectorSettings,
+} from "./collector-config";
+
+/** The path ingest is served on, appended to the cloud base URL. */
+export const INGEST_PATH = "/events";
+
+/**
+ * The ingest endpoint for a cloud base URL.
+ *
+ * Ingest wants a COMPLETE endpoint while enrolment wants a base, which is the
+ * whole reason two URLs were being asked for. One is derivable from the other,
+ * so only the base is ever asked for.
+ */
+export function ingestUrlFor(baseUrl: string): string {
+  return `${baseUrl.replace(/\/$/, "")}${INGEST_PATH}`;
+}
+
+/**
+ * The cloud base for whatever URL someone actually typed.
+ *
+ * Accepts either form. People paste the ingest endpoint — it is what the older
+ * prompt asked for, and what any existing runbook or `ingest.json` contains —
+ * and rejecting it as "not a base URL" would be pedantry about a URL we can
+ * read perfectly well.
+ */
+export function cloudBaseFor(url: string): string {
+  const trimmed = url.replace(/\/$/, "");
+  return trimmed.endsWith(INGEST_PATH) ? trimmed.slice(0, -INGEST_PATH.length) : trimmed;
+}
+
+export interface ConnectInput {
+  /** Cloud base URL, already validated by `validateCloudUrl`. */
+  url: string;
+  token: string;
+  machineId: string;
+  /** Transcripts are a separate, explicit opt-in. Never defaulted on. */
+  sessions?: boolean;
+  environment?: string;
+  /** Injected by tests so nothing reaches the network. */
+  verifyPolicy?: typeof verifyCloudCredentials;
+  verifyIngest?: typeof validateIngestKey;
+}
+
+export interface CapabilityOutcome {
+  ok: boolean;
+  reason?: string;
+}
+
+export interface ConnectOutcome {
+  policy: CapabilityOutcome & { policyCount?: number; generation?: number };
+  ingest: CapabilityOutcome;
+  /** True when at least one capability was configured. */
+  anyConfigured: boolean;
+}
+
+/**
+ * Verify both capabilities, then write only what actually works.
+ *
+ * Verification happens BEFORE any write, per capability. A credential file that
+ * does not work is worse than none, because `--status` then reports a
+ * connection the machine does not have.
+ */
+export async function connectToCloud(input: ConnectInput): Promise<ConnectOutcome> {
+  const creds: CloudCredentials = {
+    url: input.url,
+    machineId: input.machineId,
+    token: input.token,
+  };
+
+  const verifyPolicy = input.verifyPolicy ?? verifyCloudCredentials;
+  const verifyIngest = input.verifyIngest ?? validateIngestKey;
+  const ingestUrl = ingestUrlFor(input.url);
+
+  // Both checks run regardless of the other's result: reporting "cannot pull
+  // policy" while staying silent about ingest would send someone to fix one
+  // permission and hit the next one afterwards.
+  const [policyResult, ingestResult] = await Promise.all([
+    verifyPolicy(creds),
+    verifyIngest({ url: ingestUrl, key: input.token }),
+  ]);
+
+  const outcome: ConnectOutcome = {
+    policy: policyResult.ok
+      ? { ok: true, policyCount: policyResult.policyCount, generation: policyResult.generation }
+      : { ok: false, reason: policyResult.reason },
+    ingest: ingestResult.ok ? { ok: true } : { ok: false, reason: ingestResult.reason },
+    anyConfigured: false,
+  };
+
+  if (policyResult.ok) {
+    writeCloudCredentials(creds);
+    outcome.anyConfigured = true;
+  }
+
+  if (ingestResult.ok) {
+    writeIngestCredential({ url: ingestUrl, key: input.token });
+    const settings: CollectorSettings = {
+      // Hook activity is what makes the dashboard show anything at all, and it
+      // carries decisions and tool names — never file contents.
+      hooks: true,
+      // Transcripts carry prompts, file contents and whatever was pasted into
+      // a terminal, so they stay off unless explicitly asked for.
+      sessions: input.sessions === true,
+      environment: input.environment,
+    };
+    writeCollectorSettings(settings);
+    outcome.anyConfigured = true;
+  }
+
+  return outcome;
+}
+
+/**
+ * How to describe the outcome to someone at a terminal.
+ *
+ * The partial cases are the ones worth wording carefully: each names the
+ * missing permission, because "connected, but the dashboard will stay empty"
+ * without a cause is the message that sends people to support.
+ */
+export function describeOutcome(outcome: ConnectOutcome, machineId: string, url: string): string[] {
+  const lines: string[] = [];
+
+  if (outcome.policy.ok && outcome.ingest.ok) {
+    lines.push(`Connected to ${url} as ${machineId}.`);
+    const n = outcome.policy.policyCount ?? 0;
+    lines.push(`  Policy    ${n} polic${n === 1 ? "y" : "ies"} assigned (generation ${outcome.policy.generation ?? 0}).`);
+    lines.push(`  Dashboard hook activity will be sent to ${ingestUrlFor(url)}.`);
+    return lines;
+  }
+
+  if (outcome.policy.ok && !outcome.ingest.ok) {
+    const n = outcome.policy.policyCount ?? 0;
+    lines.push(`Connected to ${url} as ${machineId} for policy only.`);
+    lines.push(`  Policy    ${n} polic${n === 1 ? "y" : "ies"} assigned (generation ${outcome.policy.generation ?? 0}).`);
+    lines.push(`  Dashboard NOT configured: ${outcome.ingest.reason}`);
+    lines.push("");
+    lines.push("  Enforcement works. Nothing will appear in the dashboard until this");
+    lines.push("  key also carries `events:add`, or you re-run --connect with one that does.");
+    return lines;
+  }
+
+  if (!outcome.policy.ok && outcome.ingest.ok) {
+    lines.push(`Connected to ${url} as ${machineId} for dashboard reporting only.`);
+    lines.push(`  Dashboard hook activity will be sent to ${ingestUrlFor(url)}.`);
+    lines.push(`  Cloud policy NOT configured: ${outcome.policy.reason}`);
+    lines.push("");
+    lines.push("  This machine keeps enforcing its LOCAL policies and will report what");
+    lines.push("  they decide, but will not receive centrally-managed ones.");
+    return lines;
+  }
+
+  lines.push(`Could not connect to ${url}.`);
+  lines.push(`  Policy:    ${outcome.policy.reason}`);
+  lines.push(`  Dashboard: ${outcome.ingest.reason}`);
+  return lines;
+}
+
+/** Paths written, for a closing note. Only those that exist. */
+export function configuredPaths(outcome: ConnectOutcome): string[] {
+  const paths: string[] = [];
+  if (outcome.policy.ok) paths.push(cloudCredentialPath());
+  if (outcome.ingest.ok) paths.push(ingestPath());
+  return paths;
+}

package/src/hooks/cloud-enrollment-cli.ts

@@ -0,0 +1,227 @@
+/**
+ * `failproofai config --connect | --disconnect`, and the connection half of
+ * `--status`.
+ */
+import {
+  clearCloudCredentials,
+  maskToken,
+  readCloudCredentials,
+  validateCloudUrl,
+  verifyCloudCredentials,
+  writeCloudCredentials,
+  cloudCredentialPath,
+} from "./cloud-enrollment";
+import { daemonServiceStatus } from "./daemon-service";
+import { daemonSocketPresent } from "./daemon-client";
+import {
+  cloudBaseFor,
+  configuredPaths,
+  connectToCloud,
+  describeOutcome,
+  ingestUrlFor,
+} from "./cloud-connection";
+import {
+  clearIngestCredential,
+  hasIngestCredential,
+  readIngestCredential,
+  validateIngestKey,
+} from "./collector-config";
+
+export interface ConnectOptions {
+  url?: string;
+  token?: string;
+  machineId?: string;
+  /** Defaults to the hostname; injected for tests. */
+  defaultMachineId?: string;
+  /**
+   * Send full session transcripts as well as hook decisions. Off unless asked
+   * for: a transcript carries prompts, file contents and whatever was pasted
+   * into a terminal, so it can never be a side effect of connecting.
+   */
+  sessions?: boolean;
+  environment?: string;
+  /** Injected for tests so nothing reaches the network. */
+  verify?: typeof verifyCloudCredentials;
+  verifyIngest?: typeof validateIngestKey;
+  daemonStatus?: () => ReturnType<typeof daemonServiceStatus>;
+}
+
+export interface CommandResult {
+  exitCode: number;
+  lines: string[];
+}
+
+/**
+ * Warn rather than refuse when there is no daemon.
+ *
+ * Cloud policy is evaluated by failproofaid, so credentials alone pull
+ * nothing — but refusing would break baking a machine image where the daemon
+ * is installed later, and enrolment is genuinely independent of it. Say so
+ * loudly instead of failing.
+ */
+function daemonWarning(status: ReturnType<typeof daemonServiceStatus>): string[] {
+  if (status === "running") return [];
+  // A daemon started by hand is invisible to the service manager but is
+  // running and pulling. Telling someone whose machine is actively enforcing
+  // that "nothing will be pulled" is false, and it is exactly the state a
+  // developer testing locally is in.
+  if (daemonSocketPresent()) {
+    return [
+      "",
+      "  A daemon is running outside the service manager, so policy is being pulled.",
+      "  Install it as a service to survive reboot and logout: failproofai config",
+    ];
+  }
+  if (status === "unsupported-platform") {
+    return [
+      "",
+      "! failproofaid does not run on this platform yet, so nothing will be pulled.",
+      "  The credentials are stored and will work on a supported machine.",
+    ];
+  }
+  if (status === "not-installed") {
+    // "as a service", not "at all": this reads the service manager, so a daemon
+    // someone is running by hand during development is reported as absent. The
+    // wording has to be true in both cases.
+    return [
+      "",
+      "! failproofaid is not installed as a service, so nothing will be pulled yet.",
+      "  Install it with: failproofai config",
+    ];
+  }
+  return [
+    "",
+    "! failproofaid is installed but not running, so nothing will be pulled yet.",
+    "  Check it with: failproofai config --status",
+  ];
+}
+
+export async function runConnectCommand(opts: ConnectOptions): Promise<CommandResult> {
+  if (!opts.url) return { exitCode: 1, lines: ["--connect needs a URL, e.g. --connect https://be.failproof.ai"] };
+  if (!opts.token) {
+    return {
+      exitCode: 1,
+      lines: [
+        "--connect needs a machine token: --token <key>",
+        "",
+        "Create an API key carrying only the `policies:pull` permission for this",
+        "machine. Do not use an admin key.",
+      ],
+    };
+  }
+
+  // Accepts the ingest endpoint too. People paste what the older setup asked
+  // for, or what is already in their `ingest.json`, and refusing a URL we can
+  // read perfectly well is pedantry.
+  const validated = validateCloudUrl(cloudBaseFor(opts.url));
+  if (!validated.ok) return { exitCode: 1, lines: [validated.reason] };
+
+  const machineId = (opts.machineId ?? opts.defaultMachineId ?? "").trim();
+  if (!machineId) {
+    return { exitCode: 1, lines: ["Could not determine a machine id — pass one with --machine-id <id>."] };
+  }
+
+  // ONE connection, both capabilities. Each is verified before anything is
+  // written and reported on its own, because a key can carry `policies:pull`
+  // without `events:add` and the useful message names which one is missing.
+  const outcome = await connectToCloud({
+    url: validated.url,
+    token: opts.token,
+    machineId,
+    sessions: opts.sessions,
+    environment: opts.environment,
+    verifyPolicy: opts.verify,
+    verifyIngest: opts.verifyIngest,
+  });
+
+  if (!outcome.anyConfigured) {
+    return { exitCode: 1, lines: describeOutcome(outcome, machineId, validated.url) };
+  }
+
+  // The exit code tracks the PRIMARY purpose — enrolling this machine for
+  // cloud-managed policy. Configuring the dashboard is worth doing and worth
+  // reporting, but it must not turn a failed enrolment into a success: a fleet
+  // provisioning script running `--connect … && …` has to stop when the machine
+  // will not receive policy. The ingest credential still gets written, because
+  // it works and discarding it helps nobody.
+  const exitCode = outcome.policy.ok ? 0 : 1;
+
+  const status = (opts.daemonStatus ?? daemonServiceStatus)();
+  const paths = configuredPaths(outcome);
+  const lines = [
+    ...describeOutcome(outcome, machineId, validated.url),
+    `  Token ${maskToken(opts.token)} stored in ${paths.join(" and ")} (owner-only).`,
+  ];
+  if (outcome.ingest.ok && opts.sessions !== true) {
+    // Said out loud rather than left as a default: someone who wanted
+    // transcripts should not discover months later that none were sent.
+    lines.push("  Session transcripts are NOT being sent. Add --send-transcripts to include them.");
+  }
+  lines.push(...daemonWarning(status));
+
+  return { exitCode, lines };
+}
+
+export function runDisconnectCommand(): CommandResult {
+  const existing = readCloudCredentials();
+  const hadIngest = hasIngestCredential();
+  const removed = clearCloudCredentials();
+  // Disconnect means disconnect. Clearing only the policy credential would
+  // leave the machine still shipping activity to a cloud the user believes
+  // they have left — the one outcome nobody expects from this command.
+  const removedIngest = clearIngestCredential();
+
+  if (!removed && !existing && !hadIngest) {
+    return { exitCode: 0, lines: ["This machine is not connected to Failproof Cloud."] };
+  }
+
+  const lines = [
+    "Disconnected from Failproof Cloud.",
+    "",
+    "  Cloud-managed policies already on disk stop being refreshed. Local",
+    "  builtin, custom and convention policies are unaffected.",
+  ];
+  if (removedIngest) {
+    lines.push("  Hook activity and transcripts stop being sent.");
+  }
+  return { exitCode: 0, lines };
+}
+
+/** The connection half of `--status`. Never prints the token. */
+export function connectionStatusLines(daemonStatus = daemonServiceStatus): string[] {
+  const envUrl = process.env.FAILPROOFAI_CLOUD_URL;
+  if (envUrl) {
+    // Env wins over the file in the daemon, so reporting the file here would
+    // describe a configuration that is not in effect.
+    return [
+      `Cloud: configured by environment (${envUrl}), which takes precedence over ${cloudCredentialPath()}.`,
+    ];
+  }
+  const creds = readCloudCredentials();
+  const ingest = readIngestCredential();
+
+  // Reported as ONE connection with two capabilities. A machine sending
+  // activity but pulling no policy, or the reverse, is a state worth seeing at
+  // a glance — it is exactly the half-configured case this command exists to
+  // catch, and two unrelated lines made it easy to miss.
+  if (!creds && !ingest) return ["Cloud: not connected."];
+
+  const lines: string[] = [];
+  if (creds) {
+    lines.push(`Cloud: connected to ${creds.url} as ${creds.machineId} (token ${maskToken(creds.token)}).`);
+    lines.push(`  Policy    pulling centrally-managed policies.`);
+  } else {
+    lines.push(`Cloud: connected to ${cloudBaseFor(ingest!.url)} for reporting only.`);
+    lines.push(`  Policy    NOT pulling — this machine enforces only its local policies.`);
+  }
+
+  if (ingest) {
+    lines.push(`  Dashboard sending hook activity to ${ingest.url}.`);
+  } else {
+    lines.push(`  Dashboard NOT sending — nothing from this machine appears in the dashboard.`);
+    lines.push(`            Re-run: failproofai config --connect ${creds!.url} --token <key>`);
+  }
+
+  lines.push(...daemonWarning(daemonStatus()).map((l) => (l === "" ? "" : `  ${l.trim()}`)));
+  return lines;
+}

package/src/hooks/cloud-enrollment.ts

@@ -0,0 +1,173 @@
+/**
+ * Connecting a machine to Failproof Cloud.
+ *
+ * The credential lives in a file the daemon reads, NOT in the service unit.
+ * `daemon-service.ts` installs that unit at mode 0644 into
+ * /etc/systemd/system (and the launchd plist likewise), both root-owned and
+ * world-readable — so an `Environment="FAILPROOFAI_CLOUD_TOKEN=…"` line would
+ * hand an organization-scoped bearer key to every local user, and
+ * `systemctl show` would print it back without any privilege at all.
+ *
+ * Keeping it out of the unit also means enrolment, re-enrolment, token
+ * rotation and disconnect need no root — none of them touch a privileged
+ * path — and enrolment stops being welded to service installation, so an
+ * already-running daemon can be connected without reinstalling anything.
+ *
+ * Environment variables still win over this file, so CI, containers and the
+ * existing tests are unaffected.
+ */
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { writeJsonAtomically } from "../../lib/atomic-write";
+import { fetchWithTimeout, isAbortError } from "../../lib/fetch-with-timeout";
+
+const SCHEMA_VERSION = 1;
+const VERIFY_TIMEOUT_MS = 10_000;
+
+export interface CloudCredentials {
+  url: string;
+  machineId: string;
+  token: string;
+}
+
+interface StoredCredentials extends CloudCredentials {
+  schemaVersion: number;
+}
+
+/** `~/.failproofai/cloud.json`. The override is honoured by the daemon too. */
+export function cloudCredentialPath(): string {
+  const override = process.env.FAILPROOFAI_CLOUD_CREDENTIALS;
+  if (override) return override;
+  return join(homedir(), ".failproofai", "cloud.json");
+}
+
+/**
+ * Rejects a URL that would put a bearer token on the wire in clear.
+ *
+ * Loopback stays allowed over http, because that is exactly what the
+ * enterprise doc's local walkthrough does (`http://localhost:8080`) and there
+ * is no network to intercept.
+ */
+export function validateCloudUrl(raw: string): { ok: true; url: string } | { ok: false; reason: string } {
+  let parsed: URL;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    return { ok: false, reason: `"${raw}" is not a valid URL. Expected something like https://be.failproof.ai` };
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    return { ok: false, reason: `Unsupported scheme "${parsed.protocol}" — use https (or http for localhost).` };
+  }
+  if (parsed.protocol === "http:") {
+    const host = parsed.hostname;
+    const loopback = host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]";
+    if (!loopback) {
+      return {
+        ok: false,
+        reason:
+          `Refusing to send the machine token to ${parsed.origin} over plain http. ` +
+          `Use https, or http only for localhost during development.`,
+      };
+    }
+  }
+  return { ok: true, url: parsed.origin + (parsed.pathname === "/" ? "" : parsed.pathname.replace(/\/$/, "")) };
+}
+
+/** Last four characters only — enough to tell two keys apart, useless if leaked. */
+export function maskToken(token: string): string {
+  if (token.length <= 4) return "****";
+  return `****${token.slice(-4)}`;
+}
+
+export function readCloudCredentials(): CloudCredentials | null {
+  const path = cloudCredentialPath();
+  if (!existsSync(path)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf8")) as Partial<StoredCredentials>;
+    if (raw.schemaVersion !== SCHEMA_VERSION) return null;
+    if (typeof raw.url !== "string" || typeof raw.machineId !== "string" || typeof raw.token !== "string") {
+      return null;
+    }
+    if (!raw.url || !raw.machineId || !raw.token) return null;
+    return { url: raw.url, machineId: raw.machineId, token: raw.token };
+  } catch {
+    // Unreadable or malformed reads as "not connected" rather than throwing:
+    // this is consulted by `--status`, and a corrupt file should be reported
+    // as disconnected, not crash the command.
+    return null;
+  }
+}
+
+export function writeCloudCredentials(creds: CloudCredentials): void {
+  // 0600 inside a 0700 dir — the default for writeJsonAtomically, and the
+  // whole reason this is a file of ours rather than a line in the unit.
+  writeJsonAtomically(cloudCredentialPath(), { schemaVersion: SCHEMA_VERSION, ...creds });
+}
+
+/** True if there was something to remove. */
+export function clearCloudCredentials(): boolean {
+  const path = cloudCredentialPath();
+  if (!existsSync(path)) return false;
+  try {
+    rmSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export type VerifyResult =
+  | { ok: true; policyCount: number; generation: number }
+  | { ok: false; reason: string };
+
+/**
+ * Prove the credentials work before reporting success.
+ *
+ * Writing a credential file and saying nothing means a typo, a revoked key or
+ * a key missing `policies:pull` surfaces much later — as a policy that
+ * mysteriously never arrives, which is the worst moment to discover it. So
+ * enrolment makes exactly the request the daemon will make and reports what
+ * came back.
+ */
+export async function verifyCloudCredentials(creds: CloudCredentials): Promise<VerifyResult> {
+  const url = `${creds.url}/enforcement/v1/desired-state?machineId=${encodeURIComponent(creds.machineId)}`;
+  let response: Response;
+  try {
+    response = await fetchWithTimeout(
+      url,
+      { headers: { Authorization: `Bearer ${creds.token}` } },
+      VERIFY_TIMEOUT_MS,
+    );
+  } catch (err) {
+    if (isAbortError(err)) return { ok: false, reason: `No response from ${creds.url} within ${VERIFY_TIMEOUT_MS / 1000}s.` };
+    return { ok: false, reason: `Could not reach ${creds.url}: ${err instanceof Error ? err.message : String(err)}` };
+  }
+
+  if (response.status === 401) {
+    return { ok: false, reason: "The server rejected this token (401). Check the key was copied whole." };
+  }
+  if (response.status === 403) {
+    return {
+      ok: false,
+      reason: "This key is valid but lacks the `policies:pull` permission (403). Create a machine key with that permission.",
+    };
+  }
+  if (!response.ok) {
+    return { ok: false, reason: `The server answered ${response.status} ${response.statusText}.` };
+  }
+
+  try {
+    const body = (await response.json()) as { policies?: unknown[]; generation?: number };
+    return {
+      ok: true,
+      policyCount: Array.isArray(body.policies) ? body.policies.length : 0,
+      generation: typeof body.generation === "number" ? body.generation : 0,
+    };
+  } catch {
+    return {
+      ok: false,
+      reason: `${creds.url} answered, but not with a desired-state document. Is this a Failproof Cloud URL?`,
+    };
+  }
+}