failproofai 1.0.0-beta.2 → 1.0.0-beta.3

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?`,
+    };
+  }
+}

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

@@ -0,0 +1,138 @@
+/**
+ * Reads the daemon-owned active cloud policy generation for the TypeScript
+ * evaluator. The Rust reconciler is responsible for downloading and repairing
+ * artifacts; this boundary independently verifies the digest immediately
+ * before import so the worker never knowingly executes modified bytes.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, relative, resolve } from "node:path";
+
+const ACTIVE_SCHEMA_VERSION = 1;
+const SHA256_RE = /^[a-f0-9]{64}$/;
+const POLICY_ID_RE = /^[A-Za-z0-9._-]{1,128}$/;
+
+/** What an assignment may do. See PolicyEffect in cloud_policies.rs. */
+export type PolicyEffect = "enforce" | "observe";
+
+export interface CloudManagedPolicyArtifact {
+  id: string;
+  revision: number;
+  /**
+   * `observe` policies are evaluated exactly like any other and then have their
+   * verdict discarded, so a rollout can be measured against real traffic before
+   * it can break anyone's work. Absent means `enforce`: the default has to be
+   * the one that keeps enforcing, or a manifest written before observe mode
+   * would silently downgrade a machine to observation.
+   */
+  effect: PolicyEffect;
+  sha256: string;
+  path: string;
+  generation: number;
+}
+
+interface ActiveManifest {
+  schemaVersion: number;
+  generation: number;
+  policies: Array<{
+    id: string;
+    revision: number;
+    effect?: string;
+    sha256: string;
+    path: string;
+  }>;
+}
+
+export function cloudManagedPolicyRoot(): string {
+  return (
+    process.env.FAILPROOFAI_CLOUD_POLICY_DIR ??
+    resolve(homedir(), ".failproofai", "policies", "cloud-managed")
+  );
+}
+
+function parseManifest(value: unknown): ActiveManifest {
+  if (!value || typeof value !== "object") throw new Error("active manifest is not an object");
+  const manifest = value as Partial<ActiveManifest>;
+  if (manifest.schemaVersion !== ACTIVE_SCHEMA_VERSION) {
+    throw new Error(`unsupported active manifest schema ${String(manifest.schemaVersion)}`);
+  }
+  if (!Number.isSafeInteger(manifest.generation) || (manifest.generation ?? -1) < 0) {
+    throw new Error("active manifest generation is invalid");
+  }
+  if (!Array.isArray(manifest.policies)) throw new Error("active manifest policies is not an array");
+  return manifest as ActiveManifest;
+}
+
+function resolveManagedPath(root: string, candidate: string): string {
+  if (!candidate || isAbsolute(candidate)) throw new Error(`unsafe managed policy path ${JSON.stringify(candidate)}`);
+  const absolute = resolve(root, candidate);
+  const lexicalRelative = relative(root, absolute);
+  if (lexicalRelative.startsWith("..") || isAbsolute(lexicalRelative)) {
+    throw new Error(`managed policy path escapes its root: ${JSON.stringify(candidate)}`);
+  }
+
+  // Reject a symlinked artifact or generation directory escaping the managed
+  // root. The current daemon is same-user, but following an arbitrary path is
+  // still unnecessary ambient authority and becomes dangerous if its service
+  // identity is hardened later.
+  const realRoot = realpathSync(root);
+  const realFile = realpathSync(absolute);
+  const physicalRelative = relative(realRoot, realFile);
+  if (physicalRelative.startsWith("..") || isAbsolute(physicalRelative)) {
+    throw new Error(`managed policy symlink escapes its root: ${JSON.stringify(candidate)}`);
+  }
+  return realFile;
+}
+
+export function readActiveCloudManagedPolicies(): CloudManagedPolicyArtifact[] {
+  const root = cloudManagedPolicyRoot();
+  const activePath = resolve(root, "active.json");
+  if (!existsSync(activePath)) return [];
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(activePath, "utf8"));
+  } catch (err) {
+    throw new Error(`failed to read cloud-managed active manifest: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const manifest = parseManifest(raw);
+  const seen = new Set<string>();
+
+  return manifest.policies.map((policy) => {
+    if (!POLICY_ID_RE.test(policy.id) || policy.id === "." || policy.id === "..") {
+      throw new Error(`unsafe cloud-managed policy id ${JSON.stringify(policy.id)}`);
+    }
+    if (!Number.isSafeInteger(policy.revision) || policy.revision < 0) {
+      throw new Error(`invalid revision for cloud-managed policy ${policy.id}`);
+    }
+    if (!SHA256_RE.test(policy.sha256)) {
+      throw new Error(`invalid SHA-256 for cloud-managed policy ${policy.id}`);
+    }
+    if (seen.has(policy.id)) throw new Error(`duplicate cloud-managed policy id ${policy.id}`);
+    seen.add(policy.id);
+
+    const path = resolveManagedPath(root, policy.path);
+    const bytes = readFileSync(path);
+    const actual = createHash("sha256").update(bytes).digest("hex");
+    if (actual !== policy.sha256) {
+      throw new Error(
+        `cloud-managed policy ${policy.id} failed integrity verification: expected ${policy.sha256}, got ${actual}`,
+      );
+    }
+    if (policy.effect !== undefined && policy.effect !== "enforce" && policy.effect !== "observe") {
+      // Guessing would mean either enforcing something cloud did not ask to
+      // enforce, or observing something it wanted enforced. Both are worse than
+      // refusing the generation.
+      throw new Error(`unknown effect ${JSON.stringify(policy.effect)} for cloud-managed policy ${policy.id}`);
+    }
+    return {
+      id: policy.id,
+      revision: policy.revision,
+      effect: (policy.effect as PolicyEffect | undefined) ?? "enforce",
+      sha256: policy.sha256,
+      path,
+      generation: manifest.generation,
+    };
+  });
+}

package/src/hooks/collector-config.ts

@@ -0,0 +1,226 @@
+/**
+ * Writing the collector's configuration from the setup wizard.
+ *
+ * Two files, deliberately:
+ *
+ *   ~/.failproofai/ingest.json           mode 0600, the credential ONLY
+ *   ~/.failproofai/policies-config.json  the non-secret settings
+ *
+ * The split is not tidiness. `policies-config.json` is written with a bare
+ * `writeFileSync`, so it inherits the umask and lands at 0664 on a normal
+ * machine — inside a `~/.failproofai/` that is itself 0775. An API key there
+ * would be readable by every local user on the box. `~/.agenteye/cli.json`
+ * already stores its session token at 0600, so the correct precedent existed.
+ *
+ * The Rust daemon reads both (see `crates/fpai-collect/src/config.rs`); this is
+ * the only thing that writes them.
+ */
+import {
+  writeFileSync,
+  mkdirSync,
+  existsSync,
+  chmodSync,
+  statSync,
+  readFileSync,
+  rmSync,
+} from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+import { readHooksConfig, writeHooksConfig } from "./hooks-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 interface IngestCredential {
+  url: string;
+  key: string;
+}
+
+export interface CollectorSettings {
+  /** Ship agent session transcripts. Separate opt-in from having a key. */
+  sessions: boolean;
+  /** Ship hook activity. */
+  hooks: boolean;
+  hooksVerbosity?: "all" | "decisions" | "off";
+  redact?: "minimal" | "off";
+  environment?: string;
+}
+
+export function failproofaiHome(): string {
+  return process.env.FAILPROOFAI_HOME || join(homedir(), ".failproofai");
+}
+
+export function ingestPath(): string {
+  return join(failproofaiHome(), "ingest.json");
+}
+
+/** Whether an ingest credential is already configured on this machine. */
+export function hasIngestCredential(): boolean {
+  return existsSync(ingestPath());
+}
+
+/**
+ * The stored ingest credential, or null.
+ *
+ * Malformed JSON reads as absent rather than throwing: this is called from
+ * `--status`, and a status command that crashes on a corrupt file is worse
+ * than one reporting the capability as unconfigured — which, given the daemon
+ * 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;
+  }
+}
+
+/** Remove the ingest credential. Returns whether a file was actually removed. */
+export function clearIngestCredential(): boolean {
+  try {
+    rmSync(ingestPath());
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Write the credential at owner-only permissions, and tighten the home that
+ * holds it.
+ *
+ * A 0600 file inside a 0775 directory is still reachable by every local user,
+ * so the directory is tightened too. Both are best-effort on a filesystem
+ * 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 the collector block into the shared (non-secret) config. */
+export function writeCollectorSettings(settings: CollectorSettings): void {
+  const config = readHooksConfig();
+  writeHooksConfig({
+    ...config,
+    collector: {
+      sessions: settings.sessions,
+      hooks: settings.hooks,
+      hooksVerbosity: settings.hooksVerbosity ?? "decisions",
+      redact: settings.redact ?? "minimal",
+      environment: settings.environment ?? "local",
+    },
+  });
+}
+
+export type KeyCheck =
+  | { ok: true }
+  | { ok: false; reason: string };
+
+/**
+ * Verify a key against the endpoint before writing it anywhere.
+ *
+ * Sends an EMPTY body: ingest answers `{"accepted":0,"skipped":0}` for it, so
+ * the round-trip proves the URL resolves and the key authenticates without
+ * creating a spurious event in the user's dashboard.
+ *
+ * Failing here at setup is the whole point — otherwise a typo'd key is only
+ * discovered later as a silent pile of 401s in `failed/`, which reads like a
+ * server problem rather than a typo.
+ */
+export async function validateIngestKey(
+  cred: IngestCredential,
+  fetchImpl: typeof fetch = fetch,
+  timeoutMs = 10_000,
+): Promise<KeyCheck> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(cred.url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${cred.key}`,
+        "Content-Type": "application/x-ndjson",
+      },
+      body: "",
+      // Never follow a redirect. `fetch` follows by default, and the dashboard
+      // (which sits on a different port of the same host, and is printed during
+      // setup right beside the API) answers POST /events with a 307 to its
+      // login page — which then returns 200. So `res.ok` was true for an
+      // endpoint that authenticates nothing and stores nothing: the credential
+      // was written, setup reported success, and every batch afterwards was
+      // POSTed into a login form and lost. Confusing the two URLs is the most
+      // likely mistake available here.
+      redirect: "manual",
+      signal: controller.signal,
+    });
+    if (res.status >= 300 && res.status < 400) {
+      return {
+        ok: false,
+        reason:
+          "that URL redirects rather than accepting events — it looks like the dashboard, not the ingest API",
+      };
+    }
+    if (res.status === 401 || res.status === 403) {
+      return { ok: false, reason: `the server rejected that key (${res.status})` };
+    }
+    if (res.status === 404) {
+      return { ok: false, reason: `no ingest endpoint at that URL (404)` };
+    }
+    if (!res.ok) {
+      return { ok: false, reason: `the server answered ${res.status}` };
+    }
+    // A 2xx is not enough either. Ingest answers `{"accepted":N,"skipped":M}`;
+    // anything else returning 200 (a proxy, a static host, a catch-all router)
+    // would otherwise pass. Requiring the shape is what actually proves this is
+    // the endpoint the uploader will be talking to.
+    let body: unknown;
+    try {
+      body = await res.json();
+    } catch {
+      return {
+        ok: false,
+        reason: "that URL answered without an ingest response — it is not the events endpoint",
+      };
+    }
+    const shaped =
+      typeof body === "object" &&
+      body !== null &&
+      typeof (body as { accepted?: unknown }).accepted === "number";
+    if (!shaped) {
+      return {
+        ok: false,
+        reason: "that URL answered, but not with an ingest response — it is not the events endpoint",
+      };
+    }
+    return { ok: true };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    // Deliberately does not echo the URL back: it may contain a hostname the
+    // user would rather not see in a shared terminal recording.
+    return { ok: false, reason: `could not reach the server (${msg})` };
+  } finally {
+    clearTimeout(timer);
+  }
+}