failproofai 1.0.0-beta.5 → 1.0.0-beta.7

package/src/hooks/cloud-enrollment.ts

@@ -16,11 +16,14 @@
  * Environment variables still win over this file, so CI, containers and the
  * existing tests are unaffected.
  */
+import { randomUUID } from "node:crypto";
 import { existsSync, readFileSync, rmSync } from "node:fs";
-import { homedir } from "node:os";
+import { homedir, hostname } from "node:os";
 import { join } from "node:path";
 import { writeJsonAtomically } from "../../lib/atomic-write";
 import { fetchWithTimeout, isAbortError } from "../../lib/fetch-with-timeout";
+import { credentialsFile } from "./fp-home";
+import { readCredentials, writeCredentials } from "./fp-config";
 
 const SCHEMA_VERSION = 1;
 const VERIFY_TIMEOUT_MS = 10_000;
@@ -29,17 +32,34 @@ export interface CloudCredentials {
   url: string;
   machineId: string;
   token: string;
+  /**
+   * A human-facing name for this machine (e.g. the hostname, or "Chetan's
+   * laptop"). Display only — the identity is `machineId`. Optional: absent on
+   * credentials written before labels existed, and never required to connect.
+   */
+  machineLabel?: string;
 }
 
 interface StoredCredentials extends CloudCredentials {
   schemaVersion: number;
 }
 
-/** `~/.failproofai/cloud.json`. The override is honoured by the daemon too. */
+/**
+ * Where the cloud credential lives.
+ *
+ * Layout 2 moved it out of `cloud.json` and into the `[cloud]` table of
+ * `credentials.toml`, alongside every other token, so there is exactly one
+ * owner-only file to protect rather than three. The env override still names a
+ * standalone JSON file, because the daemon and CI both use it that way and it
+ * predates the consolidation.
+ */
 export function cloudCredentialPath(): string {
-  const override = process.env.FAILPROOFAI_CLOUD_CREDENTIALS;
-  if (override) return override;
-  return join(homedir(), ".failproofai", "cloud.json");
+  return process.env.FAILPROOFAI_CLOUD_CREDENTIALS ?? credentialsFile();
+}
+
+/** True when the credential is coming from the JSON override, not the TOML. */
+function usingJsonOverride(): boolean {
+  return Boolean(process.env.FAILPROOFAI_CLOUD_CREDENTIALS);
 }
 
 /**
@@ -81,6 +101,7 @@ export function maskToken(token: string): string {
 }
 
 export function readCloudCredentials(): CloudCredentials | null {
+  if (!usingJsonOverride()) return readCredentials().cloud ?? null;
   const path = cloudCredentialPath();
   if (!existsSync(path)) return null;
   try {
@@ -90,7 +111,8 @@ export function readCloudCredentials(): CloudCredentials | null {
       return null;
     }
     if (!raw.url || !raw.machineId || !raw.token) return null;
-    return { url: raw.url, machineId: raw.machineId, token: raw.token };
+    const label = typeof raw.machineLabel === "string" && raw.machineLabel ? raw.machineLabel : undefined;
+    return { url: raw.url, machineId: raw.machineId, token: raw.token, machineLabel: label };
   } catch {
     // Unreadable or malformed reads as "not connected" rather than throwing:
     // this is consulted by `--status`, and a corrupt file should be reported
@@ -100,21 +122,63 @@ export function readCloudCredentials(): CloudCredentials | 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 });
+  if (usingJsonOverride()) {
+    // 0600 inside a 0700 dir — the default for writeJsonAtomically.
+    writeJsonAtomically(cloudCredentialPath(), { schemaVersion: SCHEMA_VERSION, ...creds });
+    return;
+  }
+  // Merge, never replace: credentials.toml also carries the ingest key and the
+  // auth session, and rewriting the file from one caller must not drop the
+  // others.
+  writeCredentials({ ...readCredentials(), cloud: creds });
+}
+
+/**
+ * The stable key that identifies this machine to the cloud.
+ *
+ * An explicit `--machine-id` always wins. Otherwise the id already enrolled on
+ * this machine is reused, so re-running `--connect` is idempotent and never
+ * "moves" the machine. Only a machine that has none mints a fresh one — and it
+ * mints a random id, NOT the hostname, because two hosts sharing a hostname
+ * (fresh cloud VMs, cloned images) would otherwise silently merge into one
+ * machine on the server. The hostname becomes the human label instead.
+ */
+export function resolveMachineId(explicit?: string): string {
+  const trimmed = explicit?.trim();
+  if (trimmed) return trimmed;
+  const existing = readCloudCredentials();
+  if (existing?.machineId) return existing.machineId;
+  return randomUUID();
+}
+
+/**
+ * The human-facing name for this machine. Defaults to the hostname as a
+ * *suggestion* — mutable, not the identity, and free to collide with another
+ * machine's label because `machineId` keeps them apart.
+ */
+export function resolveMachineLabel(explicit?: string): string {
+  return explicit?.trim() || hostname();
 }
 
 /** 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;
+  if (usingJsonOverride()) {
+    const path = cloudCredentialPath();
+    if (!existsSync(path)) return false;
+    try {
+      rmSync(path);
+      return true;
+    } catch {
+      return false;
+    }
   }
+  const current = readCredentials();
+  if (!current.cloud) return false;
+  // Drop only the cloud table — disconnecting policy must not also revoke the
+  // ingest key or the dashboard session.
+  const { cloud: _dropped, ...rest } = current;
+  writeCredentials(rest);
+  return true;
 }
 
 export type VerifyResult =
@@ -131,7 +195,13 @@ export type VerifyResult =
  * came back.
  */
 export async function verifyCloudCredentials(creds: CloudCredentials): Promise<VerifyResult> {
-  const url = `${creds.url}/enforcement/v1/desired-state?machineId=${encodeURIComponent(creds.machineId)}`;
+  // The label rides the enrolment request so the server can record a
+  // human-facing name alongside the id. An older server simply ignores the
+  // extra query param, so sending it is always safe.
+  const labelParam = creds.machineLabel
+    ? `&label=${encodeURIComponent(creds.machineLabel)}`
+    : "";
+  const url = `${creds.url}/enforcement/v1/desired-state?machineId=${encodeURIComponent(creds.machineId)}${labelParam}`;
   let response: Response;
   try {
     response = await fetchWithTimeout(

package/src/hooks/cloud-introspect.ts

@@ -0,0 +1,147 @@
+/**
+ * `GET /v1/auth/introspect` — asking the server what a key actually is.
+ *
+ * Before this endpoint existed a machine could not describe its own
+ * credential: every other `/keys*` route needs a `keys:*` permission that a
+ * machine credential must never hold. So a revoked key, a valid key missing
+ * one permission, and a valid key pointed at the WRONG ORG all failed
+ * identically — at the point of use, later, as an empty dashboard.
+ *
+ * Introspect answers all three at connect time, in one request:
+ *
+ *   is the key accepted at all?          401 vs 200
+ *   which org will this machine report into?   org_slug / org_name
+ *   can it do the job it was provisioned for?  permissions
+ *
+ * ## Effective, not granted — the subtle part
+ *
+ * Permissions imply other permissions, and the server widens a grant at
+ * authentication time (`expand_implied`): `alerts:read` also carries
+ * `issues:read`, and so on. Authorization is checked against the WIDENED set.
+ *
+ * The dashboard's key page and the CLI both display the *stored* grant, so both
+ * understate what a key can do. Introspect returns what the server actually
+ * enforces — which is precisely why a local permission check is only correct
+ * when it is built against this response and not against the displayed list.
+ *
+ * ## Do not poll this
+ *
+ * `/v1` has no rate limiting and failed auth is not negatively cached: one bad
+ * token is one database lookup per request. This runs ONCE, when a machine is
+ * provisioned. Revocation and expiry are cached server-side for up to a minute,
+ * so treat a positive answer as current to within a minute — never to the
+ * second.
+ */
+
+/** The path introspect is served on, appended to the cloud origin. */
+export const INTROSPECT_PATH = "/v1/auth/introspect";
+
+export interface KeyIdentity {
+  keyId?: string;
+  orgId?: string;
+  orgSlug?: string;
+  orgName?: string;
+  /** The EFFECTIVE permission set — what the server enforces. */
+  permissions: string[];
+  expiresAt?: string | null;
+}
+
+export type IntrospectResult =
+  | { kind: "ok"; identity: KeyIdentity }
+  /** The key was refused. Nothing more is knowable — the body carries no detail. */
+  | { kind: "rejected" }
+  /**
+   * This server has no introspect endpoint, i.e. it predates the endpoint.
+   * The caller must fall back to probing rather than treating it as a bad key:
+   * the CLI ships independently of whatever AgentEye a customer runs, so a
+   * perfectly good key on an older server must still connect.
+   */
+  | { kind: "unsupported" }
+  /** Network/DNS/TLS — indistinguishable from a typo'd host, so reported as-is. */
+  | { kind: "unreachable"; reason: string };
+
+export function introspectUrlFor(origin: string): string {
+  return `${origin.replace(/\/$/, "")}${INTROSPECT_PATH}`;
+}
+
+export async function introspectKey(
+  origin: string,
+  token: string,
+  fetchImpl: typeof fetch = fetch,
+  timeoutMs = 10_000,
+): Promise<IntrospectResult> {
+  // AbortController rather than the shared fetchWithTimeout helper: this needs
+  // an injectable `fetch` so tests never reach the network, and that helper
+  // closes over the global one.
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let res: Response;
+  try {
+    res = await fetchImpl(introspectUrlFor(origin), {
+      headers: { Authorization: `Bearer ${token}` },
+      // Never follow a redirect. The dashboard app answers unrouted paths and
+      // will happily 307 to a login page that then returns 200 — which would
+      // read as a valid key against an endpoint that authenticated nothing.
+      redirect: "manual",
+      signal: controller.signal,
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    // Deliberately does not echo the URL: setup is routinely run while
+    // screen-sharing, and the host may be one the user would rather not show.
+    return { kind: "unreachable", reason: message };
+  } finally {
+    clearTimeout(timer);
+  }
+
+  if (res.status === 401 || res.status === 403) return { kind: "rejected" };
+  // 404 is "this server has no such route"; a redirect means we reached the web
+  // app rather than the API, which on an older deployment means the same thing.
+  if (res.status === 404 || (res.status >= 300 && res.status < 400)) {
+    return { kind: "unsupported" };
+  }
+  if (!res.ok) return { kind: "unreachable", reason: `the server answered ${res.status}` };
+
+  let body: unknown;
+  try {
+    body = await res.json();
+  } catch {
+    // A 200 that is not JSON is a proxy or a static host, not introspect.
+    return { kind: "unsupported" };
+  }
+
+  const b = body as Record<string, unknown>;
+  // `valid: false` is not documented as a 200 shape, but treating a negative
+  // assertion as success would be the worst possible reading of it.
+  if (b.valid === false) return { kind: "rejected" };
+  if (!Array.isArray(b.permissions)) {
+    // Shaped like something else entirely — an unrelated 200 from a proxy.
+    return { kind: "unsupported" };
+  }
+
+  return {
+    kind: "ok",
+    identity: {
+      keyId: typeof b.key_id === "string" ? b.key_id : undefined,
+      orgId: typeof b.org_id === "string" ? b.org_id : undefined,
+      orgSlug: typeof b.org_slug === "string" ? b.org_slug : undefined,
+      orgName: typeof b.org_name === "string" ? b.org_name : undefined,
+      permissions: b.permissions.filter((p): p is string => typeof p === "string"),
+      expiresAt: typeof b.expires_at === "string" ? b.expires_at : null,
+    },
+  };
+}
+
+/** The permission each capability needs. Named so the messages can quote them. */
+export const PERMISSION_EVENTS = "events:add";
+export const PERMISSION_POLICIES = "policies:pull";
+
+export function hasPermission(identity: KeyIdentity, permission: string): boolean {
+  return identity.permissions.includes(permission);
+}
+
+/** "Acme Inc (acme)", or the slug/id alone when the server sent less. */
+export function describeOrg(identity: KeyIdentity): string {
+  if (identity.orgName && identity.orgSlug) return `${identity.orgName} (${identity.orgSlug})`;
+  return identity.orgName ?? identity.orgSlug ?? identity.orgId ?? "an unknown organisation";
+}

package/src/hooks/cloud-managed-policies.ts

@@ -5,9 +5,10 @@
  * before import so the worker never knowingly executes modified bytes.
  */
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync, rmSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, relative, resolve } from "node:path";
+import { cloudPoliciesDir } from "./fp-home";
 
 const ACTIVE_SCHEMA_VERSION = 1;
 const SHA256_RE = /^[a-f0-9]{64}$/;
@@ -47,7 +48,7 @@ interface ActiveManifest {
 export function cloudManagedPolicyRoot(): string {
   return (
     process.env.FAILPROOFAI_CLOUD_POLICY_DIR ??
-    resolve(homedir(), ".failproofai", "policies", "cloud-managed")
+    cloudPoliciesDir()
   );
 }
 
@@ -85,6 +86,36 @@ function resolveManagedPath(root: string, candidate: string): string {
   return realFile;
 }
 
+/**
+ * Stop enforcing cloud-managed policies on this machine.
+ *
+ * Removes `active.json` only — the manifest that says which generation is
+ * live. The generation directories and content-addressed artifacts are left
+ * alone: they are large, hash-verified on use, and inert once nothing points
+ * at them, so keeping them makes a reconnect cheap and offline-safe.
+ *
+ * Called by `--disconnect`, which without it did not disconnect. Clearing the
+ * credential stops the daemon REFRESHING policy; every artifact already on disk
+ * kept being loaded and enforced on every tool call, so a user who had
+ * deliberately left their organisation's cloud went on being governed by
+ * whatever generation happened to be current when they left — indefinitely,
+ * with `--status` reporting the machine as unconnected.
+ *
+ * Returns true when a manifest was actually removed.
+ */
+export function clearActiveCloudManagedPolicies(): boolean {
+  const activePath = resolve(cloudManagedPolicyRoot(), "active.json");
+  if (!existsSync(activePath)) return false;
+  try {
+    rmSync(activePath, { force: true });
+    return true;
+  } catch {
+    // Best-effort: `--disconnect` still clears the credentials, and reporting
+    // a failure to remove one file would obscure that the rest succeeded.
+    return false;
+  }
+}
+
 export function readActiveCloudManagedPolicies(): CloudManagedPolicyArtifact[] {
   const root = cloudManagedPolicyRoot();
   const activePath = resolve(root, "active.json");

package/src/hooks/collector-config.ts

@@ -28,9 +28,11 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 
 import { readHooksConfig, writeHooksConfig } from "./hooks-config";
+import { credentialsFile, failproofaiHome as layoutHome } from "./fp-home";
+import { readCredentials, writeCredentials, updateConfig } from "./fp-config";
 
 /** The hosted ingest endpoint — a COMPLETE endpoint, not a base to join onto. */
-export const DEFAULT_INGEST_URL = "https://server.befailproof.ai/events";
+export const DEFAULT_INGEST_URL = "https://server.befailproof.ai/v1/events";
 
 export interface IngestCredential {
   url: string;
@@ -55,16 +57,16 @@ export interface CollectorSettings {
 }
 
 export function failproofaiHome(): string {
-  return process.env.FAILPROOFAI_HOME || join(homedir(), ".failproofai");
+  return layoutHome();
 }
 
 export function ingestPath(): string {
-  return join(failproofaiHome(), "ingest.json");
+  return credentialsFile();
 }
 
 /** Whether an ingest credential is already configured on this machine. */
 export function hasIngestCredential(): boolean {
-  return existsSync(ingestPath());
+  return Boolean(readCredentials().ingest);
 }
 
 /**
@@ -76,24 +78,19 @@ export function hasIngestCredential(): boolean {
  * cannot read it either, is the truth.
  */
 export function readIngestCredential(): IngestCredential | null {
-  try {
-    const raw = JSON.parse(readFileSync(ingestPath(), "utf8")) as Partial<IngestCredential>;
-    if (typeof raw.url !== "string" || typeof raw.key !== "string") return null;
-    if (!raw.url || !raw.key) return null;
-    return { url: raw.url, key: raw.key };
-  } catch {
-    return null;
-  }
+  const ingest = readCredentials().ingest;
+  return ingest ? { url: ingest.url, key: ingest.key } : null;
 }
 
 /** Remove the ingest credential. Returns whether a file was actually removed. */
 export function clearIngestCredential(): boolean {
-  try {
-    rmSync(ingestPath());
-    return true;
-  } catch {
-    return false;
-  }
+  const current = readCredentials();
+  if (!current.ingest) return false;
+  // Drop only the ingest table: stopping event reporting must not also revoke
+  // the policy-pull credential or the dashboard session.
+  const { ingest: _dropped, ...rest } = current;
+  writeCredentials(rest);
+  return true;
 }
 
 /**
@@ -105,41 +102,26 @@ export function clearIngestCredential(): boolean {
  * without POSIX modes; the write itself is not.
  */
 export function writeIngestCredential(cred: IngestCredential): string {
-  const home = failproofaiHome();
-  mkdirSync(home, { recursive: true });
-  try {
-    const mode = statSync(home).mode & 0o777;
-    if (mode & 0o077) chmodSync(home, 0o700);
-  } catch {
-    // Not fatal: the file's own 0600 is the primary protection.
-  }
-
-  const path = ingestPath();
-  // `mode` on writeFileSync applies only when the file is CREATED, so an
-  // existing over-permissive file would keep its mode without the chmod.
-  writeFileSync(path, JSON.stringify(cred, null, 2) + "\n", { mode: 0o600 });
-  try {
-    chmodSync(path, 0o600);
-  } catch {
-    /* best effort */
-  }
-  return path;
+  // Merge, never replace — credentials.toml also holds the cloud token and the
+  // auth session, and one caller rewriting the file must not drop the others.
+  // writeCredentials owns the 0600 mode and tightens the home around it.
+  writeCredentials({ ...readCredentials(), ingest: cred });
+  return credentialsFile();
 }
 
 /** Merge the collector block into the shared (non-secret) config. */
 export function writeCollectorSettings(settings: CollectorSettings): void {
-  const config = readHooksConfig();
-  writeHooksConfig({
-    ...config,
+  // Collector preferences are NOT secret, so they live in config.toml. The key
+  // that makes them meaningful lives in credentials.toml; that split is the
+  // whole point of layout 2.
+  updateConfig({
     collector: {
       sessions: settings.sessions,
       hooks: settings.hooks,
       hooksVerbosity: settings.hooksVerbosity ?? "decisions",
       redact: settings.redact ?? "minimal",
       environment: settings.environment ?? "local",
-      // Omit when unknown rather than writing null: the Rust side treats an
-      // absent field as "no machine", which is the correct fallback.
-      ...(settings.machineId ? { machineId: settings.machineId } : {}),
+      machineId: settings.machineId,
     },
   });
 }