@intentius/chant 0.124.51 → 0.124.54

package/src/cloud-lister/credentials.ts

@@ -0,0 +1,110 @@
+/**
+ * behold#1029: where the lister's credentials come from.
+ *
+ * The goal's hard rule: against an emulator the lister takes explicit
+ * endpoints and static credentials only, and never the AWS SDK's default
+ * provider chain, Azure's DefaultAzureCredential or google-auth's
+ * application-default credentials. So:
+ *
+ *  - a target that names an `endpoint` must carry its credentials (a static
+ *    AWS key pair, an Azure bearer token, a GCP token or an explicit `null`
+ *    for an anonymous emulator). Without them the run is refused with
+ *    {@link ListerConfigError}, and no chain is loaded;
+ *  - only a target with no endpoint (a real cloud, which the maintainer runs)
+ *    may fall back to a cloud SDK's chain. Those SDKs are optional peers,
+ *    imported lazily by name, so chant's install and bundle do not grow for
+ *    people who never index; their absence is a clear error naming the
+ *    package.
+ *
+ * The lister itself reads no environment variable. `chant index` (chant#4532)
+ * turns its flags into these targets.
+ */
+
+export class ListerConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ListerConfigError";
+  }
+}
+
+export interface AwsStaticCredentials {
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken?: string;
+}
+
+/** The SDK chains a real-cloud run may use; replaced in tests so a test can prove none was touched. */
+export interface CredentialChains {
+  aws(): Promise<AwsStaticCredentials>;
+  azure(): Promise<string>;
+  gcp(): Promise<string>;
+}
+
+/** Imports a module by a name the bundler and the type checker do not follow. */
+async function optionalPeer(name: string): Promise<Record<string, unknown>> {
+  const specifier = name;
+  try {
+    return (await import(specifier)) as Record<string, unknown>;
+  } catch {
+    throw new ListerConfigError(`listing a real cloud without explicit credentials needs the optional package ${name}; install it beside chant, or pass credentials`);
+  }
+}
+
+type AnyFn = (...args: unknown[]) => unknown;
+
+export const sdkCredentialChains: CredentialChains = {
+  async aws() {
+    const mod = await optionalPeer("@aws-sdk/credential-providers");
+    const chain = (mod.fromNodeProviderChain as AnyFn)() as () => Promise<AwsStaticCredentials>;
+    const c = await chain();
+    return { accessKeyId: c.accessKeyId, secretAccessKey: c.secretAccessKey, ...(c.sessionToken ? { sessionToken: c.sessionToken } : {}) };
+  },
+  async azure() {
+    const mod = await optionalPeer("@azure/identity");
+    const Ctor = mod.DefaultAzureCredential as new () => { getToken(scope: string): Promise<{ token: string } | null> };
+    const t = await new Ctor().getToken("https://management.azure.com/.default");
+    if (!t) throw new ListerConfigError("DefaultAzureCredential returned no token");
+    return t.token;
+  },
+  async gcp() {
+    const mod = await optionalPeer("google-auth-library");
+    const Ctor = mod.GoogleAuth as new (o: { scopes: string[] }) => { getAccessToken(): Promise<string | null | undefined> };
+    const t = await new Ctor({ scopes: ["https://www.googleapis.com/auth/cloud-platform.read-only"] }).getAccessToken();
+    if (!t) throw new ListerConfigError("google-auth returned no access token");
+    return t;
+  },
+};
+
+export async function resolveAwsCredentials(
+  target: { endpoint?: string; credentials?: AwsStaticCredentials },
+  chains: CredentialChains,
+): Promise<AwsStaticCredentials> {
+  if (target.credentials) return target.credentials;
+  if (target.endpoint !== undefined) {
+    throw new ListerConfigError(`aws endpoint ${target.endpoint} needs static credentials (accessKeyId and secretAccessKey); the default provider chain is never used with an endpoint`);
+  }
+  return chains.aws();
+}
+
+export async function resolveAzureToken(
+  target: { endpoint?: string; token?: string },
+  chains: CredentialChains,
+): Promise<string> {
+  if (target.token !== undefined) return target.token;
+  if (target.endpoint !== undefined) {
+    throw new ListerConfigError(`azure endpoint ${target.endpoint} needs a static bearer token; DefaultAzureCredential is never used with an endpoint`);
+  }
+  return chains.azure();
+}
+
+/** `null` is an explicit anonymous call (floci-gcp with IAM enforcement off). */
+export async function resolveGcpToken(
+  target: { endpoint?: string; token?: string | null },
+  chains: CredentialChains,
+): Promise<string | null> {
+  if (target.token !== undefined) return target.token;
+  if (target.endpoint !== undefined) {
+    throw new ListerConfigError(`gcp endpoint ${target.endpoint} needs a static token, or token: null for an anonymous emulator; application-default credentials are never used with an endpoint`);
+  }
+  return chains.gcp();
+}

package/src/cloud-lister/fakes.ts

@@ -0,0 +1,66 @@
+/**
+ * behold#1029: test doubles for the lister. Nothing here opens a socket: a
+ * fake fetcher answers from a route function and throws on any call it was
+ * not given an answer for, and fake credential chains count their calls so a
+ * test can show none was touched.
+ */
+
+import type { WireCall } from "./guard";
+import type { CredentialChains } from "./credentials";
+import type { Fetcher, WireResponse } from "./transport";
+
+export function json(status: number, body: unknown, headers: Record<string, string> = {}): WireResponse {
+  return { status, headers: { "content-type": "application/json", ...headers }, body: JSON.stringify(body) };
+}
+
+export interface FakeFetcher {
+  fetcher: Fetcher;
+  calls: WireCall[];
+}
+
+export function fakeFetcher(route: (call: WireCall) => WireResponse | undefined): FakeFetcher {
+  const calls: WireCall[] = [];
+  return {
+    calls,
+    fetcher: async (call) => {
+      calls.push(call);
+      const res = route(call);
+      if (!res) throw new Error(`fake fetcher has no answer for ${call.method} ${call.url}`);
+      return res;
+    },
+  };
+}
+
+export interface CountingChains extends CredentialChains {
+  count: { aws: number; azure: number; gcp: number };
+}
+
+/** Chains that fail if used; `count` says how often each was asked. */
+export function refusingChains(): CountingChains {
+  const count = { aws: 0, azure: 0, gcp: 0 };
+  return {
+    count,
+    async aws() {
+      count.aws++;
+      throw new Error("the AWS default provider chain was asked for credentials");
+    },
+    async azure() {
+      count.azure++;
+      throw new Error("DefaultAzureCredential was asked for a token");
+    },
+    async gcp() {
+      count.gcp++;
+      throw new Error("application-default credentials were asked for a token");
+    },
+  };
+}
+
+/** A fixed clock that advances one second per reading, so timestamps are predictable. */
+export function steppingClock(start = "2026-10-26T12:00:00Z"): () => Date {
+  let t = Date.parse(start);
+  return () => {
+    const d = new Date(t);
+    t += 1000;
+    return d;
+  };
+}

package/src/cloud-lister/gcp.test.ts

@@ -0,0 +1,121 @@
+/**
+ * behold#1029: the GCP lister against a fake Cloud Asset Inventory. Shapes
+ * follow the pinned floci-gcp (source 641e6e8): `GET
+ * /cloudasset/v1/projects/{p}:searchAllResources`, `{ results, nextPageToken }`,
+ * and SERVICE_DISABLED as ServiceUsageGate writes it.
+ */
+import { describe, expect, it } from "vitest";
+import { listCloud } from "./index";
+import { enableCommand, labelQuery } from "./gcp";
+import { fakeFetcher, json, refusingChains, steppingClock } from "./fakes";
+
+const PROJECT = "plc-corpus";
+const ENDPOINT = "http://localhost:4588/cloudasset";
+const BUCKET = "//storage.googleapis.com/projects/_/buckets/plc-assets";
+const TOPIC = `//pubsub.googleapis.com/projects/${PROJECT}/topics/events`;
+
+const serviceDisabled = json(403, {
+  error: {
+    code: 403,
+    message: `Cloud Asset API has not been used in project ${PROJECT} before or it is disabled. Enable it by visiting https://console.developers.google.com/apis/api/cloudasset.googleapis.com/overview?project=${PROJECT} then retry.`,
+    status: "PERMISSION_DENIED",
+    errors: [{ message: "x", domain: "usageLimits", reason: "accessNotConfigured" }],
+    details: [{ "@type": "type.googleapis.com/google.rpc.ErrorInfo", reason: "SERVICE_DISABLED", domain: "googleapis.com", metadata: { service: "cloudasset.googleapis.com", consumer: `projects/${PROJECT}` } }],
+  },
+});
+
+describe("listing gcp", () => {
+  it("searches the project, pages, and fills the listing-result shape", async () => {
+    const fake = fakeFetcher((call) => {
+      const url = new URL(call.url);
+      if (!url.searchParams.get("pageToken")) {
+        return json(200, {
+          results: [
+            { name: BUCKET, assetType: "storage.googleapis.com/Bucket", project: "projects/123", location: "US", labels: { "plunge-stack": "0123456789abcdef", "plunge-urn": "fedcba9876543210fedcba9876543210" } },
+          ],
+          nextPageToken: "t2",
+        });
+      }
+      return json(200, { results: [{ name: TOPIC, assetType: "pubsub.googleapis.com/Topic", project: "projects/123", additionalAttributes: { secretValue: "s" } }] });
+    });
+    const result = await listCloud(
+      { substrate: "gcp", scopeId: PROJECT, types: "*", locations: "*" },
+      { substrate: "gcp", gcp: { endpoint: ENDPOINT, token: null } },
+      { fetcher: fake.fetcher, chains: refusingChains(), now: steppingClock(), retryDelays: [] },
+    );
+    expect(fake.calls.length).toBe(2);
+    const first = new URL(fake.calls[0].url);
+    expect(first.origin + first.pathname).toBe(`${ENDPOINT}/v1/projects/${PROJECT}:searchAllResources`);
+    expect(first.searchParams.get("pageSize")).toBe("500");
+    expect(fake.calls[0].headers.authorization).toBeUndefined();
+    expect(new URL(fake.calls[1].url).searchParams.get("pageToken")).toBe("t2");
+
+    const bucket = result.resources.find((r) => r.nativeId === BUCKET)!;
+    expect(bucket.id).toBe(`gcp/${PROJECT}/us/storage.googleapis.com%2FBucket/${BUCKET}`);
+    expect(bucket.location).toBe("us");
+    expect(bucket.cloudIds).toEqual([{ kind: "provider-id", value: BUCKET }]);
+    expect(bucket.facts.markers).toEqual({ owner: "0123456789abcdef", address: "fedcba9876543210fedcba9876543210", encoding: "digest", source: "live" });
+
+    const topic = result.resources.find((r) => r.nativeId === TOPIC)!;
+    expect(topic.location).toBe("global");
+    expect((topic.properties.additionalAttributes as Record<string, unknown>).secretValue).toBe("<masked>");
+    expect(result.coverage).toEqual([{ listedType: "*", location: "*", verdict: "listed" }]);
+  });
+
+  it("filters locations after the search and puts types and labels in the request", async () => {
+    const fake = fakeFetcher(() =>
+      json(200, {
+        results: [
+          { name: "//compute.googleapis.com/projects/p/zones/us-central1-a/instances/a", assetType: "compute.googleapis.com/Instance", location: "us-central1-a" },
+          { name: "//compute.googleapis.com/projects/p/zones/europe-west1-b/instances/b", assetType: "compute.googleapis.com/Instance", location: "europe-west1-b" },
+        ],
+      }),
+    );
+    const result = await listCloud(
+      { substrate: "gcp", scopeId: PROJECT, types: ["compute.googleapis.com/Instance"], locations: ["us-central1-a"], tagFilter: { env: "prod" } },
+      { substrate: "gcp", gcp: { endpoint: ENDPOINT, token: "static" } },
+      { fetcher: fake.fetcher, chains: refusingChains(), now: steppingClock(), retryDelays: [] },
+    );
+    const url = new URL(fake.calls[0].url);
+    expect(url.searchParams.getAll("assetTypes")).toEqual(["compute.googleapis.com/Instance"]);
+    expect(url.searchParams.get("query")).toBe("labels.env=prod");
+    expect(fake.calls[0].headers.authorization).toBe("Bearer static");
+    expect(result.resources.map((r) => r.location)).toEqual(["us-central1-a"]);
+    expect(result.coverage).toEqual([{ listedType: "compute.googleapis.com/Instance", location: "us-central1-a", verdict: "filtered", detail: 'tag filter {"env":"prod"}' }]);
+  });
+
+  it("never enables the Cloud Asset API: says so, prints the command, lists nothing", async () => {
+    const fake = fakeFetcher(() => serviceDisabled);
+    const result = await listCloud(
+      { substrate: "gcp", scopeId: PROJECT, types: ["storage.googleapis.com/Bucket"], locations: "*" },
+      { substrate: "gcp", gcp: { endpoint: ENDPOINT, token: null } },
+      { fetcher: fake.fetcher, chains: refusingChains(), now: steppingClock(), retryDelays: [] },
+    );
+    expect(result.resources).toEqual([]);
+    expect(result.coverage).toEqual([{ listedType: "storage.googleapis.com/Bucket", location: "*", verdict: "read-failed", detail: `Cloud Asset API is disabled on project ${PROJECT}` }]);
+    expect(result.notes).toHaveLength(1);
+    expect(result.notes[0].code).toBe("api-disabled");
+    expect(result.notes[0].command).toBe(enableCommand(PROJECT));
+    expect(result.notes[0].command).toBe("gcloud services enable cloudasset.googleapis.com --project=plc-corpus");
+    // One call, the search; nothing went to Service Usage.
+    expect(fake.calls).toHaveLength(1);
+    expect(fake.calls[0].method).toBe("GET");
+    expect(fake.calls[0].url).toContain(":searchAllResources");
+    expect(fake.calls.some((c) => /serviceusage|:enable|batchEnable/.test(c.url))).toBe(false);
+  });
+
+  it("never asks application-default credentials when an endpoint is given", async () => {
+    const chains = refusingChains();
+    const fake = fakeFetcher(() => undefined);
+    await expect(
+      listCloud({ substrate: "gcp", scopeId: PROJECT, types: "*", locations: "*" }, { substrate: "gcp", gcp: { endpoint: ENDPOINT } }, { fetcher: fake.fetcher, chains }),
+    ).rejects.toThrow(/application-default credentials are never used/);
+    expect(chains.count.gcp).toBe(0);
+    expect(fake.calls).toEqual([]);
+  });
+
+  it("joins label terms with AND and refuses anything else", () => {
+    expect(labelQuery({ a: "1", b: "2" })).toBe("labels.a=1 AND labels.b=2");
+    expect(() => labelQuery({ "a OR x": "1" })).toThrow();
+  });
+});

package/src/cloud-lister/gcp.ts

@@ -0,0 +1,159 @@
+/**
+ * behold#1029: GCP, through Cloud Asset Inventory's `searchAllResources` on
+ * one project, paged.
+ *
+ * Nothing is enabled for the person. The Cloud Asset API has to be on before
+ * a project can be searched, and turning it on changes the project. When the
+ * search answers SERVICE_DISABLED, the lister lists nothing for the project,
+ * marks every coverage entry `read-failed`, and puts the enable command in a
+ * note for the person to run. The guard (packages/core/src/cloud-lister/guard.ts) admits no
+ * Service Usage call at all, so the lister could not enable it if it tried.
+ *
+ * Types go in `assetTypes`, a tag filter in the query as `labels.KEY=VALUE`
+ * terms. Locations are filtered here, after the search, because floci-gcp's
+ * query subset has no location term.
+ *
+ * The pinned floci-gcp (ghcr.io/lex00/floci-gcp, source 641e6e8) serves this
+ * call under the path prefix `/cloudasset` (pass `http://localhost:4588/cloudasset`
+ * as the endpoint), for project scopes only, over the assets of four
+ * services (Compute, Cloud Storage, IAM, Pub/Sub), with SERVICE_DISABLED
+ * answered as GCP answers it when its Service Usage enforcement is on.
+ */
+
+import { buildResource, describeFailure, listedVerdict, noteTagFilter, withThrottleRetry, type ListerContext } from "./common";
+import { resolveGcpToken, ListerConfigError, type CredentialChains } from "./credentials";
+import { jsonBody, type TlsOptions, type WireResponse } from "./transport";
+import type { CloudId } from "./types";
+
+export interface GcpTarget {
+  /** An emulator's Cloud Asset base, e.g. `http://localhost:4588/cloudasset`. Absent means `https://cloudasset.googleapis.com`. */
+  endpoint?: string;
+  /** An OAuth access token; `null` sends none (an emulator with IAM enforcement off). Required with an endpoint. */
+  token?: string | null;
+  tls?: TlsOptions;
+}
+
+const PAGE_SIZE = 500;
+const MAX_PAGES = 10_000;
+const PROJECT = /^[A-Za-z0-9._:-]+$/;
+const LABEL_PART = /^[A-Za-z0-9_\-]+$/;
+
+export function enableCommand(project: string): string {
+  return `gcloud services enable cloudasset.googleapis.com --project=${project}`;
+}
+
+export function searchUrl(target: GcpTarget, project: string, params: { assetTypes?: readonly string[]; query?: string; pageToken?: string }): string {
+  const base = (target.endpoint ?? "https://cloudasset.googleapis.com").replace(/\/+$/, "");
+  const url = new URL(`${base}/v1/projects/${encodeURIComponent(project)}:searchAllResources`);
+  for (const t of params.assetTypes ?? []) url.searchParams.append("assetTypes", t);
+  if (params.query) url.searchParams.set("query", params.query);
+  url.searchParams.set("pageSize", String(PAGE_SIZE));
+  if (params.pageToken) url.searchParams.set("pageToken", params.pageToken);
+  return url.toString();
+}
+
+/** The `query` for a tag filter, or undefined. Exported for tests. */
+export function labelQuery(filter: Readonly<Record<string, string>> | undefined): string | undefined {
+  const entries = Object.entries(filter ?? {});
+  if (entries.length === 0) return undefined;
+  return entries
+    .map(([k, v]) => {
+      if (!LABEL_PART.test(k) || !LABEL_PART.test(v)) throw new ListerConfigError(`gcp label filter ${k}=${v} is not a plain label key and value`);
+      return `labels.${k}=${v}`;
+    })
+    .join(" AND ");
+}
+
+interface GcpError {
+  status: string;
+  message: string;
+  reasons: string[];
+}
+
+function gcpError(res: WireResponse): GcpError {
+  const body = jsonBody(res) as
+    | { error?: { status?: string; message?: string; details?: Array<{ reason?: string }>; errors?: Array<{ reason?: string }> } }
+    | Array<{ error?: { status?: string; message?: string; details?: Array<{ reason?: string }> } }>
+    | undefined;
+  const e = Array.isArray(body) ? body[0]?.error : body?.error;
+  const reasons = [...(e?.details ?? []), ...((e as { errors?: Array<{ reason?: string }> } | undefined)?.errors ?? [])]
+    .map((d) => d.reason ?? "")
+    .filter(Boolean);
+  return { status: e?.status ?? "", message: e?.message ?? "", reasons };
+}
+
+export function isServiceDisabled(res: WireResponse): boolean {
+  if (res.status !== 403) return false;
+  const err = gcpError(res);
+  return err.reasons.includes("SERVICE_DISABLED") || err.reasons.includes("accessNotConfigured") || /has not been used in project|is disabled/i.test(err.message);
+}
+
+export async function listGcp(
+  ctx: ListerContext,
+  target: GcpTarget,
+  chains: CredentialChains,
+  retryDelays?: readonly number[],
+): Promise<void> {
+  const { scope } = ctx;
+  if (!PROJECT.test(scope.scopeId)) throw new ListerConfigError(`gcp project ${JSON.stringify(scope.scopeId)} is not a project id`);
+  const token = await resolveGcpToken(target, chains);
+  const query = labelQuery(scope.tagFilter);
+  const assetTypes = scope.types === "*" ? undefined : scope.types;
+  const wantLocations = scope.locations === "*" ? undefined : new Set(scope.locations.map((l) => l.toLowerCase()));
+  const typesCovered = scope.types === "*" ? ["*"] : [...scope.types];
+  const locationsCovered = scope.locations === "*" ? ["*"] : [...scope.locations].map((l) => l.toLowerCase());
+  noteTagFilter(ctx, "as labels terms in the Cloud Asset query");
+
+  const found: Parameters<typeof buildResource>[1][] = [];
+  let pageToken: string | undefined;
+  for (let page = 0; page < MAX_PAGES; page++) {
+    const url = searchUrl(target, scope.scopeId, { assetTypes, query, pageToken });
+    const headers: Record<string, string> = { accept: "application/json" };
+    if (token !== null) headers.authorization = `Bearer ${token}`;
+    const res = await withThrottleRetry(
+      () => ctx.transport.send({ substrate: "gcp", method: "GET", url, headers }),
+      (r) => r.status === 429,
+      retryDelays,
+    );
+    const observedAt = ctx.now().toISOString();
+    if (res.status >= 400) {
+      const err = gcpError(res);
+      const detail = describeFailure(res, err.status, err.message);
+      if (isServiceDisabled(res)) {
+        const why = `Cloud Asset API is disabled on project ${scope.scopeId}`;
+        for (const t of typesCovered) for (const l of locationsCovered) ctx.coverage.push({ listedType: t, location: l, verdict: "read-failed", detail: why });
+        ctx.notes.push({
+          code: "api-disabled",
+          message: `${why}, so nothing was listed for it. chant never enables an API; enabling it changes the project. To list it, run the command yourself and index again.`,
+          command: enableCommand(scope.scopeId),
+        });
+        return;
+      }
+      const verdict = res.status === 401 || res.status === 403 ? "no-credentials" : "read-failed";
+      for (const t of typesCovered) for (const l of locationsCovered) ctx.coverage.push({ listedType: t, location: l, verdict, detail });
+      ctx.notes.push({ code: verdict === "no-credentials" ? "no-credentials" : "read-failed", message: `searchAllResources on project ${scope.scopeId} failed: ${detail}` });
+      return;
+    }
+    const parsed = jsonBody(res) as { results?: Array<Record<string, unknown>>; nextPageToken?: string } | undefined;
+    for (const r of parsed?.results ?? []) {
+      const name = typeof r.name === "string" ? r.name : undefined;
+      const assetType = typeof r.assetType === "string" ? r.assetType : undefined;
+      if (!name || !assetType) continue;
+      const location = (typeof r.location === "string" && r.location ? r.location : "global").toLowerCase();
+      if (wantLocations && !wantLocations.has(location)) continue;
+      const tags: Record<string, string> = {};
+      if (r.labels && typeof r.labels === "object") {
+        for (const [k, v] of Object.entries(r.labels as Record<string, unknown>)) tags[k] = String(v ?? "");
+      }
+      const cloudIds: CloudId[] = [{ kind: "provider-id", value: name }];
+      const attrs = r.additionalAttributes as Record<string, unknown> | undefined;
+      if (attrs && typeof attrs.selfLink === "string") cloudIds.push({ kind: "self-link", value: attrs.selfLink });
+      const { labels: _labels, ...properties } = r;
+      found.push({ listedType: assetType, location, nativeId: name, cloudIds, tags, properties, observedAt, labels: true });
+    }
+    pageToken = parsed?.nextPageToken || undefined;
+    if (!pageToken) break;
+  }
+  for (const r of found) ctx.resources.push(buildResource(ctx, r));
+  for (const t of typesCovered) for (const l of locationsCovered) ctx.coverage.push({ listedType: t, location: l, ...listedVerdict(scope) });
+}

package/src/cloud-lister/guard.test.ts

@@ -0,0 +1,198 @@
+/**
+ * behold#1029 done-when: "A test fails if any mutating API is reachable from
+ * the lister."
+ *
+ * Three layers, each of which goes red when a mutating call is added:
+ *  1. the allowlist is pinned to exactly the five read operations, and no
+ *     entry may name a write;
+ *  2. a mutating call of every kind each substrate has is refused by the
+ *     guard, and never reaches the fetcher;
+ *  3. every call each lister makes while listing (against fakes) classifies
+ *     into the allowlist, and the lister sources name no mutating operation.
+ *
+ * Red first: add `"cloudcontrol:CreateResource"` to READ_OPERATIONS.aws, or a
+ * `method: "PUT"` call to any lister, and layer 1 or 3 fails.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { assertReadCall, classifyCall, MutatingCallRefused, READ_OPERATIONS, type WireCall } from "./guard";
+import { Transport, OriginRefused } from "./transport";
+import { listCloud } from "./index";
+import { fakeFetcher, json, refusingChains, steppingClock } from "./fakes";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+describe("the read allowlist", () => {
+  it("is exactly the five read operations", () => {
+    expect(READ_OPERATIONS).toEqual({
+      aws: ["cloudcontrol:ListResources"],
+      azure: ["resourcegraph:resources"],
+      gcp: ["cloudasset:searchAllResources"],
+      kubernetes: ["k8s:discovery", "k8s:list"],
+    });
+  });
+
+  it("names no write", () => {
+    for (const ops of Object.values(READ_OPERATIONS)) {
+      for (const op of ops) expect(op).not.toMatch(/create|update|delete|put|patch|enable|disable|cancel|watch|tag|apply|import|export/i);
+    }
+  });
+});
+
+const aws = (target: string, method: WireCall["method"] = "POST"): WireCall => ({
+  substrate: "aws",
+  method,
+  url: "http://localhost:4566/",
+  headers: { "x-amz-target": `CloudApiService.${target}` },
+  body: "{}",
+});
+
+const MUTATING: Array<[string, WireCall]> = [
+  ["aws CreateResource", aws("CreateResource")],
+  ["aws UpdateResource", aws("UpdateResource")],
+  ["aws DeleteResource", aws("DeleteResource")],
+  ["aws CancelResourceRequest", aws("CancelResourceRequest")],
+  ["aws GetResource (not on the list either)", aws("GetResource")],
+  ["aws a call with no target", { substrate: "aws", method: "POST", url: "http://localhost:4566/", headers: {}, body: "Action=CreateBucket" }],
+  ["aws a PUT", { substrate: "aws", method: "PUT", url: "http://localhost:4566/bucket", headers: {} }],
+  ["azure PUT on an ARM resource", { substrate: "azure", method: "PUT", url: "https://localhost:4577/subscriptions/s/resourceGroups/rg?api-version=2021-04-01", headers: {} }],
+  ["azure DELETE on an ARM resource", { substrate: "azure", method: "DELETE", url: "https://localhost:4577/subscriptions/s/resourceGroups/rg?api-version=2021-04-01", headers: {} }],
+  ["azure POST to another provider action", { substrate: "azure", method: "POST", url: "https://localhost:4577/subscriptions/s/providers/Microsoft.Storage/register?api-version=2021-04-01", headers: {} }],
+  ["azure GET on Resource Graph's path", { substrate: "azure", method: "GET", url: "https://localhost:4577/providers/Microsoft.ResourceGraph/resources", headers: {} }],
+  ["gcp enabling the Cloud Asset API", { substrate: "gcp", method: "POST", url: "https://serviceusage.googleapis.com/v1/projects/p/services/cloudasset.googleapis.com:enable", headers: {} }],
+  ["gcp batchEnable", { substrate: "gcp", method: "POST", url: "https://serviceusage.googleapis.com/v1/projects/p/services:batchEnable", headers: {} }],
+  ["gcp a searchAllResources on the serviceusage host", { substrate: "gcp", method: "GET", url: "https://serviceusage.googleapis.com/v1/projects/p:searchAllResources", headers: {} }],
+  ["gcp POST searchAllResources", { substrate: "gcp", method: "POST", url: "http://localhost:4588/cloudasset/v1/projects/p:searchAllResources", headers: {} }],
+  ["gcp creating a feed", { substrate: "gcp", method: "POST", url: "https://cloudasset.googleapis.com/v1/projects/p/feeds", headers: {} }],
+  ["gcp exportAssets", { substrate: "gcp", method: "GET", url: "https://cloudasset.googleapis.com/v1/projects/p:exportAssets", headers: {} }],
+  ["k8s POST", { substrate: "kubernetes", method: "POST", url: "https://127.0.0.1:6443/api/v1/namespaces/default/pods", headers: {} }],
+  ["k8s PUT", { substrate: "kubernetes", method: "PUT", url: "https://127.0.0.1:6443/api/v1/namespaces/default/configmaps/x", headers: {} }],
+  ["k8s PATCH", { substrate: "kubernetes", method: "PATCH", url: "https://127.0.0.1:6443/apis/apps/v1/namespaces/default/deployments/x", headers: {} }],
+  ["k8s DELETE", { substrate: "kubernetes", method: "DELETE", url: "https://127.0.0.1:6443/api/v1/namespaces/default/pods/x", headers: {} }],
+  ["k8s a watch", { substrate: "kubernetes", method: "GET", url: "https://127.0.0.1:6443/api/v1/pods?watch=1", headers: {} }],
+  ["k8s a pod's exec", { substrate: "kubernetes", method: "GET", url: "https://127.0.0.1:6443/api/v1/namespaces/default/pods/x/exec?command=sh", headers: {} }],
+  ["k8s a service proxy", { substrate: "kubernetes", method: "GET", url: "https://127.0.0.1:6443/api/v1/namespaces/default/services/x/proxy/", headers: {} }],
+];
+
+describe("the guard refuses every mutating call", () => {
+  for (const [name, call] of MUTATING) {
+    it(name, async () => {
+      expect(() => assertReadCall(call)).toThrow(MutatingCallRefused);
+      const fake = fakeFetcher(() => json(200, {}));
+      const transport = new Transport({ fetcher: fake.fetcher });
+      await expect(transport.send(call)).rejects.toThrow(MutatingCallRefused);
+      expect(fake.calls).toEqual([]);
+    });
+  }
+
+  it("admits the four reads", () => {
+    expect(classifyCall(aws("ListResources"))).toBe("cloudcontrol:ListResources");
+    expect(classifyCall({ substrate: "azure", method: "POST", url: "https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2022-10-01", headers: {} })).toBe("resourcegraph:resources");
+    expect(classifyCall({ substrate: "gcp", method: "GET", url: "http://localhost:4588/cloudasset/v1/projects/p:searchAllResources?pageSize=500", headers: {} })).toBe("cloudasset:searchAllResources");
+    expect(classifyCall({ substrate: "kubernetes", method: "GET", url: "https://h/apis/apps/v1", headers: {} })).toBe("k8s:discovery");
+    expect(classifyCall({ substrate: "kubernetes", method: "GET", url: "https://h/apis/apps/v1/deployments?limit=500", headers: {} })).toBe("k8s:list");
+  });
+});
+
+describe("the origin pin", () => {
+  it("refuses a call to any host but the run's endpoint", async () => {
+    const fake = fakeFetcher(() => json(200, {}));
+    const transport = new Transport({ fetcher: fake.fetcher, pinnedOrigin: "http://localhost:4566" });
+    await expect(transport.send({ ...aws("ListResources"), url: "https://cloudcontrolapi.us-east-1.amazonaws.com/" })).rejects.toThrow(OriginRefused);
+    expect(fake.calls).toEqual([]);
+  });
+});
+
+describe("every call a lister makes is on the allowlist", () => {
+  const seen: Array<{ substrate: string; operation: string }> = [];
+  const onSend = (call: WireCall, operation: string) => seen.push({ substrate: call.substrate, operation });
+
+  it("aws", async () => {
+    const fake = fakeFetcher(() => json(200, { TypeName: "AWS::S3::Bucket", ResourceDescriptions: [] }));
+    await listCloud(
+      { substrate: "aws", scopeId: "000000000000", locations: ["us-east-1"], types: ["AWS::S3::Bucket", "AWS::IAM::Role"] },
+      { substrate: "aws", aws: { endpoint: "http://localhost:4566", credentials: { accessKeyId: "test", secretAccessKey: "test" } } },
+      { fetcher: fake.fetcher, chains: refusingChains(), now: steppingClock(), retryDelays: [], onSend },
+    );
+    expect(fake.calls.length).toBe(2);
+  });
+
+  it("azure", async () => {
+    const fake = fakeFetcher(() => json(200, { data: [], totalRecords: 0, count: 0 }));
+    await listCloud(
+      { substrate: "azure", scopeId: "00000000-0000-0000-0000-000000000000", locations: "*", types: "*" },
+      { substrate: "azure", azure: { endpoint: "https://localhost:4577", token: "static" } },
+      { fetcher: fake.fetcher, chains: refusingChains(), now: steppingClock(), retryDelays: [], onSend },
+    );
+    expect(fake.calls.length).toBe(1);
+  });
+
+  it("gcp", async () => {
+    const fake = fakeFetcher(() => json(200, {}));
+    await listCloud(
+      { substrate: "gcp", scopeId: "plc-corpus", locations: "*", types: "*" },
+      { substrate: "gcp", gcp: { endpoint: "http://localhost:4588/cloudasset", token: null } },
+      { fetcher: fake.fetcher, chains: refusingChains(), now: steppingClock(), retryDelays: [], onSend },
+    );
+    expect(fake.calls.length).toBe(1);
+  });
+
+  it("kubernetes", async () => {
+    const fake = fakeFetcher((call) => {
+      const path = new URL(call.url).pathname;
+      if (path === "/api/v1") return json(200, { resources: [{ name: "configmaps", kind: "ConfigMap", namespaced: true, verbs: ["get", "list", "create"] }] });
+      if (path === "/apis") return json(200, { groups: [] });
+      if (path === "/api/v1/configmaps") return json(200, { items: [] });
+      return undefined;
+    });
+    await listCloud(
+      { substrate: "kubernetes", scopeId: "kind-floci", locations: "*", types: "*" },
+      { substrate: "kubernetes", kubernetes: { server: "https://127.0.0.1:6443", token: "static" } },
+      { fetcher: fake.fetcher, chains: refusingChains(), now: steppingClock(), retryDelays: [], onSend },
+    );
+    expect(fake.calls.length).toBe(3);
+  });
+
+  it("and nothing else", () => {
+    for (const { substrate, operation } of seen) {
+      expect(READ_OPERATIONS[substrate as keyof typeof READ_OPERATIONS]).toContain(operation);
+    }
+    expect(new Set(seen.map((s) => s.operation))).toEqual(
+      new Set(["cloudcontrol:ListResources", "resourcegraph:resources", "cloudasset:searchAllResources", "k8s:discovery", "k8s:list"]),
+    );
+  });
+});
+
+describe("the lister sources", () => {
+  const sources = readdirSync(here).filter((f) => f.endsWith(".ts") && !f.endsWith(".test.ts") && f !== "guard.ts" && f !== "fakes.ts");
+
+  it("include every substrate's lister", () => {
+    expect(sources).toEqual(expect.arrayContaining(["aws.ts", "azure.ts", "gcp.ts", "kubernetes.ts", "transport.ts"]));
+  });
+
+  it("send only GET and POST", () => {
+    for (const f of sources) {
+      const text = readFileSync(join(here, f), "utf8");
+      expect(text, f).not.toMatch(/method:\s*"(PUT|PATCH|DELETE)"/);
+    }
+  });
+
+  it("name no mutating Cloud Control, Service Usage or Cloud Asset operation", () => {
+    for (const f of sources) {
+      const text = readFileSync(join(here, f), "utf8");
+      const targets = [...text.matchAll(/CloudApiService\.([A-Za-z]+)/g)].map((m) => m[1]);
+      for (const t of targets) expect(t, f).toBe("ListResources");
+      expect(text, f).not.toMatch(/:(enable|disable|batchEnable|exportAssets)\b|\/feeds\b/);
+      expect(text, f).not.toMatch(/serviceusage\.googleapis\.com/);
+    }
+  });
+
+  it("import no cloud SDK client", () => {
+    for (const f of sources) {
+      const text = readFileSync(join(here, f), "utf8");
+      expect(text, f).not.toMatch(/from\s+"@aws-sdk\/client-|from\s+"@azure\/arm-|from\s+"@google-cloud\/|from\s+"@kubernetes\/client-node"|from\s+"@intentius\/chant-k8s-client"/);
+    }
+  });
+});