failproofai 1.0.0-beta.2 → 1.0.0-beta.21

package/src/hooks/cloud-enrollment.ts

@@ -0,0 +1,284 @@
+/**
+ * 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 { randomUUID } from "node:crypto";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { hostname } from "node:os";
+import { writeJsonAtomically } from "../../lib/atomic-write";
+import { fetchWithTimeout, isAbortError } from "../../lib/fetch-with-timeout";
+import { credentialsFile } from "./fp-home";
+import { readConfig, readCredentials, writeCredentials } from "./fp-config";
+
+const SCHEMA_VERSION = 1;
+const VERIFY_TIMEOUT_MS = 10_000;
+
+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;
+}
+
+/**
+ * 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 {
+  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);
+}
+
+/**
+ * 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 {
+  if (!usingJsonOverride()) return readCredentials().cloud ?? 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;
+    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
+    // as disconnected, not crash the command.
+    return null;
+  }
+}
+
+export function writeCloudCredentials(creds: CloudCredentials): void {
+  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 recorded 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.
+ *
+ * ## Why this looks in TWO places before minting
+ *
+ * `connectToCloud` writes the id to two files under two INDEPENDENT conditions:
+ * `credentials.json`'s `cloud` table only when `policies:pull` verified, and
+ * `config.json`'s `collector.machine_id` only when `events:add` did. A key
+ * carrying one grant and not the other is not a broken setup — it is a
+ * first-class state the key-creation drawer offers as two separate presets
+ * (`policies` and `collector`), so half-written is a shape this function must
+ * expect rather than an anomaly.
+ *
+ * Consulting only the cloud credential therefore missed the id whenever the
+ * FIRST connection was ingest-only, and the consequences all landed on the
+ * server, where nothing could undo them:
+ *
+ *   1. a telemetry-only connect stamps `collector.machine_id = A` on every
+ *      event and writes no cloud credential;
+ *   2. a later connect with a policies-capable key finds no cloud credential,
+ *      mints B, and overwrites the collector block with it;
+ *   3. the fleet list — a union of enrolment rows and event-derived ids — now
+ *      shows ONE host as TWO machines: A reporting with no label and nothing
+ *      deployed, B enrolled and empty. A's history is stranded, and A counts
+ *      toward `unguarded` on the policy page, which is the exact false reading
+ *      that page exists to surface.
+ *
+ * Order is most-explicit to least, and the cloud credential stays ABOVE the
+ * collector block deliberately: if the two ever disagree, the cloud one is what
+ * the server has keyed this machine's enrolment, deployment and history on, and
+ * that is the association that must not break. Minting drops to last, where it
+ * now means what it says — nothing on this machine has ever carried an id.
+ *
+ * The collector value is returned VERBATIM rather than trimmed, because the
+ * daemon stamps it on events verbatim too (`spool.rs`, which filters only the
+ * empty string); normalising it here would hand the cloud a different id than
+ * the one the events carry and reintroduce the split this exists to close. A
+ * blank or whitespace-only value is not adopted — it identifies nothing, and
+ * the server would refuse it.
+ */
+export function resolveMachineId(explicit?: string): string {
+  const trimmed = explicit?.trim();
+  if (trimmed) return trimmed;
+  const existing = readCloudCredentials();
+  if (existing?.machineId) return existing.machineId;
+  // `readConfig` swallows a missing or corrupt file and answers with defaults,
+  // so an unreadable config degrades to minting rather than throwing on a path
+  // whose whole job is to keep enrolment working.
+  const collectorId = readConfig().collector.machineId;
+  if (collectorId?.trim()) return collectorId;
+  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 {
+  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 =
+  | { ok: true; policyCount: number; deployment: 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> {
+  // 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(
+      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[]; deployment?: number };
+    return {
+      ok: true,
+      policyCount: Array.isArray(body.policies) ? body.policies.length : 0,
+      deployment: typeof body.deployment === "number" ? body.deployment : 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-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

@@ -0,0 +1,206 @@
+/**
+ * Reads the daemon-owned active cloud policy deployment 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, rmSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+import { cloudPoliciesDir } from "./fp-home";
+
+/**
+ * Active-manifest schema versions this reader accepts.
+ *
+ * MUST stay in step with `SUPPORTED_SCHEMA_VERSIONS` in `cloud_policies.rs`,
+ * which is what WRITES the file this parses. They are two hand-maintained
+ * copies of one contract in two languages, and the failure is silent in the
+ * worst direction: the daemon reconciles happily, `active.json` is correct on
+ * disk, and only the hook path refuses it — so cloud policy stops being
+ * enforced while every other signal says the machine is healthy. Reproduced
+ * exactly that way while syncing this with AgentEye#559.
+ *
+ * 1 is accepted for files a pre-rename beta daemon left behind; 2 is what is
+ * written now.
+ */
+const ACCEPTED_ACTIVE_SCHEMA_VERSIONS: readonly number[] = [1, 2];
+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;
+  version: 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;
+  deployment: number;
+}
+
+interface ActiveManifest {
+  schemaVersion: number;
+  deployment: number;
+  policies: Array<{
+    id: string;
+    version: number;
+    effect?: string;
+    sha256: string;
+    path: string;
+  }>;
+}
+
+export function cloudManagedPolicyRoot(): string {
+  return (
+    process.env.FAILPROOFAI_CLOUD_POLICY_DIR ??
+    cloudPoliciesDir()
+  );
+}
+
+/**
+ * A version-1 manifest, in the spelling a pre-rename daemon actually wrote.
+ *
+ * Accepting schema 1 while reading only the version-2 FIELD NAMES made the
+ * acceptance unreachable: every genuine v1 file threw "active manifest
+ * deployment is invalid". The Rust reader of this same file handles it with
+ * `#[serde(alias = "generation")]` / `#[serde(alias = "revision")]`; this is the
+ * TypeScript half of that pair, and it was missing.
+ */
+interface LegacyActiveManifest {
+  generation?: number;
+  policies?: Array<{ revision?: number }>;
+}
+
+function parseManifest(value: unknown): ActiveManifest {
+  if (!value || typeof value !== "object") throw new Error("active manifest is not an object");
+  const raw = value as Partial<ActiveManifest> & LegacyActiveManifest;
+  if (!ACCEPTED_ACTIVE_SCHEMA_VERSIONS.includes(raw.schemaVersion as number)) {
+    throw new Error(
+      `unsupported active manifest schema ${String(raw.schemaVersion)} ` +
+        `(supported: ${ACCEPTED_ACTIVE_SCHEMA_VERSIONS.join(", ")})`,
+    );
+  }
+  // New name wins; the old one is a fallback, not an equal. A file carrying both
+  // (written by a mixed-version machine) must resolve to the current field.
+  const deployment = raw.deployment ?? raw.generation;
+  if (!Number.isSafeInteger(deployment) || (deployment ?? -1) < 0) {
+    throw new Error("active manifest deployment is invalid");
+  }
+  if (!Array.isArray(raw.policies)) throw new Error("active manifest policies is not an array");
+  const policies = raw.policies.map((p) => {
+    const entry = p as ActiveManifest["policies"][number] & { revision?: number };
+    return { ...entry, version: entry.version ?? entry.revision } as ActiveManifest["policies"][number];
+  });
+  return { schemaVersion: raw.schemaVersion as number, deployment: deployment as number, policies };
+}
+
+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 deployment 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;
+}
+
+/**
+ * Stop enforcing cloud-managed policies on this machine.
+ *
+ * Removes `active.json` only — the manifest that says which deployment is
+ * live. The deployment 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 deployment 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");
+  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.version) || policy.version < 0) {
+      throw new Error(`invalid version 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 deployment.
+      throw new Error(`unknown effect ${JSON.stringify(policy.effect)} for cloud-managed policy ${policy.id}`);
+    }
+    return {
+      id: policy.id,
+      version: policy.version,
+      effect: (policy.effect as PolicyEffect | undefined) ?? "enforce",
+      sha256: policy.sha256,
+      path,
+      deployment: manifest.deployment,
+    };
+  });
+}