@intentius/chant 0.124.52 → 0.124.54

package/src/cloud-lister/guard.ts

@@ -0,0 +1,111 @@
+/**
+ * behold#1029: read-only by construction.
+ *
+ * Every request the lister makes is a {@link WireCall}, and every WireCall
+ * goes through {@link assertReadCall} before anything reaches the network
+ * (packages/core/src/cloud-lister/transport.ts is the only sender). The check classifies the
+ * call from what would go on the wire (method, path, `X-Amz-Target`), never
+ * from a label the caller attaches, and admits only the operations in
+ * {@link READ_OPERATIONS}:
+ *
+ *  - aws: Cloud Control `ListResources` (a POST, but the JSON protocol's only
+ *    verb; the target header names the operation);
+ *  - azure: Resource Graph's query, `POST /providers/Microsoft.ResourceGraph/resources`
+ *    (a read that takes its KQL in the body);
+ *  - gcp: Cloud Asset `searchAllResources`, a GET. Nothing under
+ *    `serviceusage` is admitted, so the lister cannot enable the Cloud Asset
+ *    API on a project (#1029: "nothing is enabled for the person");
+ *  - kubernetes: GET discovery (`/api`, `/apis`, `/api/v1`, `/apis/<g>/<v>`)
+ *    and GET collection lists, never `watch`.
+ *
+ * packages/core/src/cloud-lister/guard.test.ts holds the allowlist to exactly this set and
+ * shows a mutating call of each substrate refused.
+ */
+
+import type { Substrate } from "./types";
+
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+
+/** One HTTP request as it would be sent. */
+export interface WireCall {
+  substrate: Substrate;
+  method: HttpMethod;
+  url: string;
+  headers: Record<string, string>;
+  body?: string;
+}
+
+/** The only operations the lister may send, by substrate. */
+export const READ_OPERATIONS: Readonly<Record<Substrate, readonly string[]>> = {
+  aws: ["cloudcontrol:ListResources"],
+  azure: ["resourcegraph:resources"],
+  gcp: ["cloudasset:searchAllResources"],
+  kubernetes: ["k8s:discovery", "k8s:list"],
+};
+
+export class MutatingCallRefused extends Error {
+  constructor(
+    readonly call: Pick<WireCall, "substrate" | "method" | "url">,
+    readonly operation: string,
+  ) {
+    super(`chant's cloud lister refused ${call.method} ${call.url} (${operation}): only ${READ_OPERATIONS[call.substrate].join(", ")} may be sent`);
+    this.name = "MutatingCallRefused";
+  }
+}
+
+function header(headers: Record<string, string>, name: string): string | undefined {
+  const lower = name.toLowerCase();
+  for (const [k, v] of Object.entries(headers)) if (k.toLowerCase() === lower) return v;
+  return undefined;
+}
+
+/**
+ * The operation a call performs, read off the wire. Anything this cannot
+ * name precisely comes back as `<substrate>:unknown:<detail>`, which no
+ * allowlist entry matches.
+ */
+export function classifyCall(call: WireCall): string {
+  const url = new URL(call.url);
+  const path = url.pathname;
+  switch (call.substrate) {
+    case "aws": {
+      const target = header(call.headers, "x-amz-target") ?? "";
+      const m = /^CloudApiService\.([A-Za-z]+)$/.exec(target);
+      if (call.method === "POST" && m) return `cloudcontrol:${m[1]}`;
+      return `aws:unknown:${call.method} ${target || path}`;
+    }
+    case "azure": {
+      if (call.method === "POST" && /\/providers\/microsoft\.resourcegraph\/resources$/i.test(path)) {
+        return "resourcegraph:resources";
+      }
+      return `azure:unknown:${call.method} ${path}`;
+    }
+    case "gcp": {
+      const m = /\/v1\/(projects|folders|organizations)\/[^/:]+:([A-Za-z]+)$/.exec(path);
+      if (call.method === "GET" && m && m[2] === "searchAllResources" && !/serviceusage/i.test(url.hostname + path)) {
+        return "cloudasset:searchAllResources";
+      }
+      return `gcp:unknown:${call.method} ${path}`;
+    }
+    case "kubernetes": {
+      if (call.method !== "GET") return `k8s:unknown:${call.method} ${path}`;
+      const watch = url.searchParams.get("watch");
+      if (watch !== null && watch !== "false" && watch !== "0") return `k8s:watch:${path}`;
+      if (/^\/(api|apis)\/?$/.test(path)) return "k8s:discovery";
+      if (/^\/api\/v1\/?$/.test(path)) return "k8s:discovery";
+      if (/^\/apis\/[^/]+\/[^/]+\/?$/.test(path)) return "k8s:discovery";
+      // A collection: /api/v1/<plural> or /apis/<g>/<v>/<plural>. A named
+      // object, a subresource (logs, exec, proxy) or a namespaced path is not.
+      if (/^\/api\/v1\/[a-z0-9.-]+$/.test(path)) return "k8s:list";
+      if (/^\/apis\/[^/]+\/[^/]+\/[a-z0-9.-]+$/.test(path)) return "k8s:list";
+      return `k8s:unknown:${call.method} ${path}`;
+    }
+  }
+}
+
+/** Throws {@link MutatingCallRefused} unless the call is one of {@link READ_OPERATIONS}. */
+export function assertReadCall(call: WireCall): string {
+  const operation = classifyCall(call);
+  if (!READ_OPERATIONS[call.substrate].includes(operation)) throw new MutatingCallRefused(call, operation);
+  return operation;
+}

package/src/cloud-lister/ids.ts

@@ -0,0 +1,54 @@
+/**
+ * behold#1029: a listed node's id, ruled on behold#1025 (Q2):
+ * `<substrate>/<scopeId>/<location>/<listedType>/<nativeId>`.
+ *
+ * Several of those parts carry `/` of their own: a Kubernetes type
+ * (`apps/v1/Deployment`), an ARM type (`microsoft.storage/storageaccounts`),
+ * and most native ids (an ARM id, `namespace/name`). The id stays readable and
+ * parses back by escaping `%` and `/` in the first four parts only. The native
+ * id is last, so everything after the fourth separator is it, unescaped: the
+ * exact string the aws matcher (chant#4523) compares with `declaredIdentifier`.
+ */
+
+import type { Substrate } from "./types";
+
+function escapeSegment(s: string): string {
+  return s.replace(/%/g, "%25").replace(/\//g, "%2F");
+}
+
+function unescapeSegment(s: string): string {
+  return s.replace(/%2F/gi, "/").replace(/%25/g, "%");
+}
+
+export interface ListedNodeIdParts {
+  substrate: Substrate;
+  scopeId: string;
+  location: string;
+  listedType: string;
+  nativeId: string;
+}
+
+export function listedNodeId(parts: ListedNodeIdParts): string {
+  return [
+    escapeSegment(parts.substrate),
+    escapeSegment(parts.scopeId),
+    escapeSegment(parts.location),
+    escapeSegment(parts.listedType),
+    parts.nativeId,
+  ].join("/");
+}
+
+/** The parts back from an id {@link listedNodeId} wrote; `undefined` for anything else. */
+export function parseListedNodeId(id: string): ListedNodeIdParts | undefined {
+  const parts: string[] = [];
+  let rest = id;
+  for (let i = 0; i < 4; i++) {
+    const at = rest.indexOf("/");
+    if (at < 0) return undefined;
+    parts.push(unescapeSegment(rest.slice(0, at)));
+    rest = rest.slice(at + 1);
+  }
+  const [substrate, scopeId, location, listedType] = parts;
+  if (substrate !== "aws" && substrate !== "azure" && substrate !== "gcp" && substrate !== "kubernetes") return undefined;
+  return { substrate, scopeId, location, listedType, nativeId: rest };
+}

package/src/cloud-lister/index.ts

@@ -0,0 +1,134 @@
+/**
+ * The read-only cloud lister `chant index` runs (chant#4532; built as
+ * behold#1029 and moved here on the ruling that every model lives in chant,
+ * https://github.com/INTENTIUS/behold/issues/1024#issuecomment-6433236820).
+ *
+ * One call lists one substrate and one account, subscription, project or
+ * cluster (behold#1025 ruling Q6) and returns a {@link ListingResult}: the
+ * design's listing-result source shape, which chant's `typeListing`
+ * (chant#4521) types into an `IndexDocument`. It has no command of its own
+ * (`chant index` and `behold index` both reach it through
+ * ../lifecycle/cloud-index.ts), reads no project or configuration, and works
+ * in an empty directory.
+ *
+ * Read-only by construction: no cloud SDK client is built. Every request is
+ * a plain HTTP call through one {@link Transport}, which refuses anything
+ * outside the read allowlist (packages/core/src/cloud-lister/guard.ts) and, when the run
+ * names an endpoint, anything not sent to that endpoint's origin. There is
+ * no estate, no record store and no write call.
+ */
+
+import { sortResult, type ListerContext } from "./common";
+import { listAws, type AwsTarget } from "./aws";
+import { listAzure, type AzureTarget } from "./azure";
+import { listGcp, type GcpTarget } from "./gcp";
+import { listKubernetes, type KubernetesTarget } from "./kubernetes";
+import { sdkCredentialChains, type CredentialChains } from "./credentials";
+import { Transport, type Fetcher, type TlsOptions, type TransportOptions } from "./transport";
+import type { CloudScope, ListingResult } from "./types";
+
+export type { CloudScope, ListingResult, ListedResource, CoverageEntry, IndexNote, CloudId, ListedFacts, MarkerFact, Substrate, TagFilter } from "./types";
+export type { AwsTarget } from "./aws";
+export type { AzureTarget } from "./azure";
+export type { GcpTarget } from "./gcp";
+export type { KubernetesTarget } from "./kubernetes";
+export { kubeTargetFromKubeconfig } from "./kubernetes";
+export { ListerConfigError } from "./credentials";
+export { MutatingCallRefused, READ_OPERATIONS } from "./guard";
+export { OriginRefused } from "./transport";
+export { listedNodeId, parseListedNodeId } from "./ids";
+
+/** Where and how to reach the scope's substrate. The variant must match `scope.substrate`. */
+export type SubstrateTarget =
+  | { substrate: "aws"; aws: AwsTarget }
+  | { substrate: "azure"; azure: AzureTarget }
+  | { substrate: "gcp"; gcp: GcpTarget }
+  | { substrate: "kubernetes"; kubernetes: KubernetesTarget };
+
+export interface ListOptions {
+  /** Replaces the network (tests). */
+  fetcher?: Fetcher;
+  /** Replaces the real-cloud SDK credential chains (tests prove none is touched with an endpoint). */
+  chains?: CredentialChains;
+  now?: () => Date;
+  /** Throttle backoff, in ms; tests pass `[]`. */
+  retryDelays?: readonly number[];
+  /** The caller's version (chant's, or behold's when behold calls in), for `source.version`. */
+  version?: string;
+  /** Sees every call that passed the guard (tests record with it). */
+  onSend?: TransportOptions["onSend"];
+}
+
+function sortedUnique(values: readonly string[] | "*"): readonly string[] | "*" {
+  if (values === "*") return "*";
+  return [...new Set(values)].sort();
+}
+
+/** The scope as the stamp records it: lists sorted and deduplicated (#1025 "Stamp"). */
+export function canonicalScope(scope: CloudScope): CloudScope {
+  return {
+    substrate: scope.substrate,
+    scopeId: scope.scopeId,
+    locations: sortedUnique(scope.locations),
+    types: sortedUnique(scope.types),
+    ...(scope.tagFilter && Object.keys(scope.tagFilter).length > 0
+      ? { tagFilter: Object.fromEntries(Object.entries(scope.tagFilter).sort(([a], [b]) => (a < b ? -1 : 1))) }
+      : {}),
+  };
+}
+
+function endpointAndTls(target: SubstrateTarget): { endpoint?: string; tls?: TlsOptions } {
+  switch (target.substrate) {
+    case "aws":
+      return { endpoint: target.aws.endpoint, tls: target.aws.tls };
+    case "azure":
+      return { endpoint: target.azure.endpoint, tls: target.azure.tls };
+    case "gcp":
+      return { endpoint: target.gcp.endpoint, tls: target.gcp.tls };
+    case "kubernetes":
+      return { endpoint: target.kubernetes.server, tls: target.kubernetes.tls };
+  }
+}
+
+export async function listCloud(scope: CloudScope, target: SubstrateTarget, options: ListOptions = {}): Promise<ListingResult> {
+  if (scope.substrate !== target.substrate) {
+    throw new Error(`scope is ${scope.substrate} but the target is ${target.substrate}`);
+  }
+  const canonical = canonicalScope(scope);
+  const now = options.now ?? (() => new Date());
+  const { endpoint, tls } = endpointAndTls(target);
+  const transport = new Transport({
+    fetcher: options.fetcher,
+    tls,
+    ...(endpoint !== undefined ? { pinnedOrigin: endpoint } : {}),
+    ...(options.onSend ? { onSend: options.onSend } : {}),
+  });
+  const chains = options.chains ?? sdkCredentialChains;
+  const ctx: ListerContext = { scope: canonical, transport, now, resources: [], coverage: [], notes: [] };
+  const startedAt = now().toISOString();
+  switch (target.substrate) {
+    case "aws":
+      await listAws(ctx, target.aws, chains, options.retryDelays);
+      break;
+    case "azure":
+      await listAzure(ctx, target.azure, chains, options.retryDelays);
+      break;
+    case "gcp":
+      await listGcp(ctx, target.gcp, chains, options.retryDelays);
+      break;
+    case "kubernetes":
+      await listKubernetes(ctx, target.kubernetes, options.retryDelays);
+      break;
+  }
+  sortResult(ctx);
+  return {
+    listing: "v1",
+    source: { name: "chant-lister", version: options.version ?? "unknown" },
+    scope: canonical,
+    startedAt,
+    completedAt: now().toISOString(),
+    resources: ctx.resources,
+    coverage: ctx.coverage,
+    notes: ctx.notes,
+  };
+}

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

@@ -0,0 +1,160 @@
+/**
+ * behold#1029: the Kubernetes lister against a fake API server: discovery
+ * (`/api/v1`, `/apis`, `/apis/<g>/<v>`), then LIST per served kind.
+ */
+import { describe, expect, it } from "vitest";
+import { listCloud } from "./index";
+import { kubeTargetFromKubeconfig } from "./kubernetes";
+import { ListerConfigError } from "./credentials";
+import { MASKED } from "./mask";
+import { fakeFetcher, json, refusingChains, steppingClock } from "./fakes";
+import type { WireCall } from "./guard";
+
+const SERVER = "https://127.0.0.1:6443";
+
+function cluster(call: WireCall) {
+  const url = new URL(call.url);
+  switch (url.pathname) {
+    case "/api/v1":
+      return json(200, {
+        resources: [
+          { name: "secrets", kind: "Secret", namespaced: true, verbs: ["get", "list", "create", "delete"] },
+          { name: "namespaces", kind: "Namespace", namespaced: false, verbs: ["get", "list"] },
+          { name: "pods", kind: "Pod", namespaced: true, verbs: ["get", "list"] },
+          { name: "pods/log", kind: "Pod", namespaced: true, verbs: ["get"] },
+          { name: "events", kind: "Event", namespaced: true, verbs: ["list"] },
+          { name: "bindings", kind: "Binding", namespaced: true, verbs: ["create"] },
+        ],
+      });
+    case "/apis":
+      return json(200, { groups: [{ name: "apps", preferredVersion: { groupVersion: "apps/v1", version: "v1" }, versions: [{ groupVersion: "apps/v1", version: "v1" }] }] });
+    case "/apis/apps/v1":
+      return json(200, { resources: [{ name: "deployments", kind: "Deployment", namespaced: true, verbs: ["get", "list", "patch"] }] });
+    case "/api/v1/secrets":
+      return json(200, {
+        items: [
+          {
+            metadata: {
+              name: "db",
+              namespace: "app",
+              uid: "uid-secret",
+              labels: { "app.kubernetes.io/managed-by": "chant", "chant.intentius.io/stack": "app" },
+              annotations: { "kubectl.kubernetes.io/last-applied-configuration": '{"data":{"password":"aHVudGVyMg=="}}' },
+              managedFields: [{ manager: "kubectl" }],
+            },
+            type: "Opaque",
+            data: { password: "aHVudGVyMg==", user: "YWRtaW4=" },
+          },
+        ],
+      });
+    case "/api/v1/namespaces":
+      return json(200, { items: [{ metadata: { name: "app", uid: "uid-ns" } }] });
+    case "/api/v1/pods":
+      if (!url.searchParams.get("continue")) {
+        return json(200, { items: [{ metadata: { name: "web-1", namespace: "app", uid: "uid-p1" } }], metadata: { continue: "c2" } });
+      }
+      return json(200, { items: [{ metadata: { name: "other", namespace: "kube-system", uid: "uid-p2" } }] });
+    case "/apis/apps/v1/deployments":
+      return json(403, { kind: "Status", reason: "Forbidden", message: 'deployments.apps is forbidden: User "reader" cannot list resource "deployments"' });
+  }
+  return undefined;
+}
+
+describe("listing kubernetes", () => {
+  it("discovers, lists, pages and masks", async () => {
+    const fake = fakeFetcher(cluster);
+    const result = await listCloud(
+      { substrate: "kubernetes", scopeId: "kind-floci", types: "*", locations: "*" },
+      { substrate: "kubernetes", kubernetes: { server: SERVER, token: "static" } },
+      { fetcher: fake.fetcher, chains: refusingChains(), now: steppingClock(), retryDelays: [] },
+    );
+    const paths = fake.calls.map((c) => new URL(c.url).pathname);
+    expect(paths).not.toContain("/api/v1/events");
+    expect(paths).not.toContain("/api/v1/bindings");
+    expect(paths.filter((p) => p === "/api/v1/pods")).toHaveLength(2);
+    expect(fake.calls.every((c) => c.method === "GET" && c.headers.authorization === "Bearer static")).toBe(true);
+
+    const secret = result.resources.find((r) => r.listedType === "v1/Secret")!;
+    expect(secret.id).toBe("kubernetes/kind-floci/app/v1%2FSecret/app/db");
+    expect(secret.nativeId).toBe("app/db");
+    expect(secret.cloudIds).toEqual([{ kind: "k8s-uid", value: "uid-secret" }]);
+    expect(secret.properties.data).toEqual({ password: MASKED, user: MASKED });
+    expect(JSON.stringify(secret)).not.toContain("aHVudGVyMg==");
+    expect(JSON.stringify(secret)).not.toContain("YWRtaW4=");
+    expect((secret.properties.metadata as Record<string, unknown>).managedFields).toBeUndefined();
+    expect(secret.facts.markers).toEqual({ owner: "app", encoding: "plain", source: "live" });
+
+    const ns = result.resources.find((r) => r.listedType === "v1/Namespace")!;
+    expect(ns.location).toBe("cluster");
+    expect(ns.nativeId).toBe("app");
+
+    expect(result.resources.filter((r) => r.listedType === "v1/Pod").map((r) => r.nativeId)).toEqual(["app/web-1", "kube-system/other"]);
+
+    expect(result.coverage).toEqual([
+      { listedType: "apps/v1/Deployment", location: "*", verdict: "no-credentials", detail: expect.stringContaining("Forbidden") },
+      { listedType: "v1/Namespace", location: "cluster", verdict: "listed" },
+      { listedType: "v1/Pod", location: "*", verdict: "listed" },
+      { listedType: "v1/Secret", location: "*", verdict: "listed" },
+    ]);
+    expect(result.notes.map((n) => n.code).sort()).toEqual(["default-types", "no-credentials"]);
+  });
+
+  it("keeps to the named namespaces and types, and notes a type the cluster cannot list", async () => {
+    const fake = fakeFetcher(cluster);
+    const result = await listCloud(
+      { substrate: "kubernetes", scopeId: "kind-floci", types: ["v1/Pod", "example.com/v1/Widget"], locations: ["app"], tagFilter: { tier: "web" } },
+      { substrate: "kubernetes", kubernetes: { server: SERVER, token: "static" } },
+      { fetcher: fake.fetcher, chains: refusingChains(), now: steppingClock(), retryDelays: [] },
+    );
+    const podList = fake.calls.find((c) => new URL(c.url).pathname === "/api/v1/pods")!;
+    expect(new URL(podList.url).searchParams.get("labelSelector")).toBe("tier=web");
+    expect(result.resources.map((r) => r.nativeId)).toEqual(["app/web-1"]);
+    expect(result.coverage).toEqual([
+      { listedType: "example.com/v1/Widget", location: "*", verdict: "unsupported-kind", detail: expect.any(String) },
+      { listedType: "v1/Pod", location: "app", verdict: "filtered", detail: 'tag filter {"tier":"web"}' },
+    ]);
+    expect(result.notes.find((n) => n.code === "no-lister")?.listedType).toBe("example.com/v1/Widget");
+  });
+});
+
+describe("kubeTargetFromKubeconfig", () => {
+  const base = (user: string) => `apiVersion: v1
+kind: Config
+current-context: kind-floci
+clusters:
+- name: kind-floci
+  cluster:
+    server: https://127.0.0.1:6443
+    certificate-authority-data: ${Buffer.from("CA PEM").toString("base64")}
+contexts:
+- name: kind-floci
+  context:
+    cluster: kind-floci
+    user: reader
+users:
+- name: reader
+  user:
+${user}
+`;
+
+  it("reads a static token and the cluster CA", () => {
+    const t = kubeTargetFromKubeconfig(base("    token: abc"));
+    expect(t.server).toBe("https://127.0.0.1:6443");
+    expect(t.token).toBe("abc");
+    expect(t.tls?.ca).toBe("CA PEM");
+    expect(t.clusterName).toBe("kind-floci");
+  });
+
+  it("reads a client certificate and key", () => {
+    const t = kubeTargetFromKubeconfig(
+      base(`    client-certificate-data: ${Buffer.from("CERT").toString("base64")}\n    client-key-data: ${Buffer.from("KEY").toString("base64")}`),
+    );
+    expect(t.tls?.cert).toBe("CERT");
+    expect(t.tls?.key).toBe("KEY");
+    expect(t.token).toBeUndefined();
+  });
+
+  it("refuses an exec plugin", () => {
+    expect(() => kubeTargetFromKubeconfig(base("    exec:\n      apiVersion: client.authentication.k8s.io/v1\n      command: aws"))).toThrow(ListerConfigError);
+  });
+});