@intentius/chant 0.124.51 → 0.124.54

package/src/cloud-lister/kubernetes.ts

@@ -0,0 +1,284 @@
+/**
+ * behold#1029: Kubernetes, through API discovery and then one LIST per
+ * served kind, paged with `continue`.
+ *
+ * The lister does not go through `@intentius/chant-k8s-client`. That client
+ * builds a full read and write client, and its only network seam
+ * (`requestLayer`) replaces the whole HTTP send, so the read-only guard could
+ * not sit in front of its real transport. Discovery and LIST are plain GETs,
+ * so they go through the lister's own guarded transport like every other
+ * substrate, with the cluster's server, token and certificates passed
+ * explicitly. {@link kubeTargetFromKubeconfig} reads those from a kubeconfig
+ * the caller names, and refuses an exec plugin or an auth provider: those
+ * are credential chains, and the lister takes static credentials only.
+ *
+ * Locations are namespaces. A cluster-scoped object's location is `cluster`;
+ * it is listed when the scope's locations are `*` or include `cluster`. With
+ * types `*`, events and leases are left out (they change on every read, so
+ * every version's digest would differ) and a note says so.
+ *
+ * kind (the pinned `kindest/node` in choudoufu's live/kind-node-image) runs a
+ * real API server, so discovery and LIST are served as on any cluster.
+ */
+
+import { readFileSync } from "node:fs";
+import { parseYAML } from "../yaml";
+import { buildResource, describeFailure, listedVerdict, noteTagFilter, withThrottleRetry, type ListerContext } from "./common";
+import { ListerConfigError } from "./credentials";
+import { maskKubernetesObject } from "./mask";
+import { jsonBody, type TlsOptions, type WireResponse } from "./transport";
+
+export interface KubernetesTarget {
+  /** The API server, e.g. `https://127.0.0.1:6443`. */
+  server: string;
+  /** A bearer token; absent when the client certificate in `tls` authenticates. */
+  token?: string;
+  tls?: TlsOptions;
+}
+
+/** A served, listable kind from discovery. */
+export interface ServedKind {
+  group: string;
+  version: string;
+  kind: string;
+  plural: string;
+  namespaced: boolean;
+  /** `v1/Pod`, `apps/v1/Deployment`: the lister's `listedType`. */
+  listedType: string;
+}
+
+const PAGE_SIZE = 500;
+const MAX_PAGES = 10_000;
+const LABEL_PART = /^[A-Za-z0-9_.\-\/]+$/;
+const CLUSTER_LOCATION = "cluster";
+/** Left out of `types: "*"`: they change on every read. */
+const CHURNING_TYPES = new Set(["v1/Event", "events.k8s.io/v1/Event", "coordination.k8s.io/v1/Lease"]);
+
+export function listedTypeOf(group: string, version: string, kind: string): string {
+  return group === "" ? `${version}/${kind}` : `${group}/${version}/${kind}`;
+}
+
+function apiUrl(target: KubernetesTarget, path: string, query?: Record<string, string>): string {
+  const base = target.server.replace(/\/+$/, "");
+  const url = new URL(base + path);
+  for (const [k, v] of Object.entries(query ?? {})) url.searchParams.set(k, v);
+  return url.toString();
+}
+
+function headersFor(target: KubernetesTarget): Record<string, string> {
+  return { accept: "application/json", ...(target.token ? { authorization: `Bearer ${target.token}` } : {}) };
+}
+
+async function get(ctx: ListerContext, target: KubernetesTarget, path: string, query: Record<string, string> | undefined, retryDelays?: readonly number[]): Promise<WireResponse> {
+  const url = apiUrl(target, path, query);
+  return withThrottleRetry(() => ctx.transport.send({ substrate: "kubernetes", method: "GET", url, headers: headersFor(target) }), (r) => r.status === 429, retryDelays);
+}
+
+function k8sMessage(res: WireResponse): string {
+  const body = jsonBody(res) as { message?: string; reason?: string } | undefined;
+  return describeFailure(res, body?.reason, body?.message);
+}
+
+function resourcesOf(body: unknown, group: string, version: string): ServedKind[] {
+  const list = (body as { resources?: Array<{ name?: string; kind?: string; namespaced?: boolean; verbs?: string[] }> } | undefined)?.resources ?? [];
+  const out: ServedKind[] = [];
+  for (const r of list) {
+    if (!r.name || !r.kind || r.name.includes("/")) continue;
+    if (!(r.verbs ?? []).includes("list")) continue;
+    out.push({ group, version, kind: r.kind, plural: r.name, namespaced: r.namespaced === true, listedType: listedTypeOf(group, version, r.kind) });
+  }
+  return out;
+}
+
+/**
+ * Every listable kind the cluster serves: the core group's `v1`, and for each
+ * other group its preferred version plus any version a requested type names.
+ */
+export async function discover(
+  ctx: ListerContext,
+  target: KubernetesTarget,
+  requested: ReadonlySet<string> | undefined,
+  retryDelays?: readonly number[],
+): Promise<ServedKind[]> {
+  const kinds: ServedKind[] = [];
+  const core = await get(ctx, target, "/api/v1", undefined, retryDelays);
+  if (core.status >= 400) {
+    ctx.notes.push({ code: core.status === 401 || core.status === 403 ? "no-credentials" : "read-failed", message: `discovery of the core group failed: ${k8sMessage(core)}` });
+  } else {
+    kinds.push(...resourcesOf(jsonBody(core), "", "v1"));
+  }
+  const groups = await get(ctx, target, "/apis", undefined, retryDelays);
+  if (groups.status >= 400) {
+    ctx.notes.push({ code: groups.status === 401 || groups.status === 403 ? "no-credentials" : "read-failed", message: `discovery of API groups failed: ${k8sMessage(groups)}` });
+    return kinds;
+  }
+  const list = (jsonBody(groups) as { groups?: Array<{ name?: string; preferredVersion?: { version?: string }; versions?: Array<{ version?: string }> }> } | undefined)?.groups ?? [];
+  for (const g of list) {
+    if (!g.name) continue;
+    const versions = new Set<string>();
+    if (g.preferredVersion?.version) versions.add(g.preferredVersion.version);
+    if (requested) {
+      for (const v of g.versions ?? []) {
+        if (v.version && [...requested].some((t) => t.startsWith(`${g.name}/${v.version}/`))) versions.add(v.version);
+      }
+    }
+    for (const version of versions) {
+      const res = await get(ctx, target, `/apis/${g.name}/${version}`, undefined, retryDelays);
+      if (res.status >= 400) {
+        ctx.notes.push({ code: "read-failed", message: `discovery of ${g.name}/${version} failed: ${k8sMessage(res)}` });
+        continue;
+      }
+      kinds.push(...resourcesOf(jsonBody(res), g.name, version));
+    }
+  }
+  return kinds;
+}
+
+/** `labelSelector` for a tag filter, or undefined. Exported for tests. */
+export function labelSelector(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(`kubernetes label filter ${k}=${v} is not a plain label key and value`);
+      return `${k}=${v}`;
+    })
+    .join(",");
+}
+
+export async function listKubernetes(ctx: ListerContext, target: KubernetesTarget, retryDelays?: readonly number[]): Promise<void> {
+  const { scope } = ctx;
+  const requested = scope.types === "*" ? undefined : new Set(scope.types);
+  const selector = labelSelector(scope.tagFilter);
+  noteTagFilter(ctx, "as a labelSelector on every LIST");
+  const served = await discover(ctx, target, requested, retryDelays);
+
+  let toList: ServedKind[];
+  if (requested) {
+    const byType = new Map(served.map((k) => [k.listedType, k]));
+    toList = [];
+    for (const t of requested) {
+      const k = byType.get(t);
+      if (k) {
+        toList.push(k);
+      } else {
+        ctx.coverage.push({ listedType: t, location: "*", verdict: "unsupported-kind", detail: "the cluster's discovery serves no listable resource of this type" });
+        ctx.notes.push({ code: "no-lister", listedType: t, message: `${t} is not a listable resource on this cluster (not served by discovery, or no list verb)` });
+      }
+    }
+  } else {
+    toList = served.filter((k) => !CHURNING_TYPES.has(k.listedType));
+    const skipped = served.filter((k) => CHURNING_TYPES.has(k.listedType)).map((k) => k.listedType);
+    if (skipped.length > 0) {
+      ctx.notes.push({ code: "default-types", message: `types "*" left out ${skipped.join(", ")}, which change on every read; name them to list them` });
+    }
+  }
+
+  const namespaces = scope.locations === "*" ? undefined : new Set(scope.locations);
+  const wantCluster = scope.locations === "*" || scope.locations.includes(CLUSTER_LOCATION);
+  const nsCoverage = scope.locations === "*" ? ["*"] : scope.locations.filter((l) => l !== CLUSTER_LOCATION);
+
+  for (const k of toList) {
+    if (!k.namespaced && !wantCluster) continue;
+    if (k.namespaced && nsCoverage.length === 0) continue;
+    const coverageLocations = k.namespaced ? nsCoverage : [CLUSTER_LOCATION];
+    const path = k.group === "" ? `/api/v1/${k.plural}` : `/apis/${k.group}/${k.version}/${k.plural}`;
+    const found: Parameters<typeof buildResource>[1][] = [];
+    let cont: string | undefined;
+    let failed: WireResponse | undefined;
+    for (let page = 0; page < MAX_PAGES; page++) {
+      const query: Record<string, string> = { limit: String(PAGE_SIZE) };
+      if (cont) query.continue = cont;
+      if (selector) query.labelSelector = selector;
+      const res = await get(ctx, target, path, query, retryDelays);
+      const observedAt = ctx.now().toISOString();
+      if (res.status >= 400) {
+        failed = res;
+        break;
+      }
+      const body = jsonBody(res) as { items?: Array<Record<string, unknown>>; metadata?: { continue?: string } } | undefined;
+      for (const item of body?.items ?? []) {
+        const meta = (item.metadata ?? {}) as { name?: string; namespace?: string; uid?: string; labels?: Record<string, string>; managedFields?: unknown };
+        if (!meta.name) continue;
+        const ns = meta.namespace;
+        if (k.namespaced && namespaces && (!ns || !namespaces.has(ns))) continue;
+        const location = k.namespaced ? ns ?? "" : CLUSTER_LOCATION;
+        const obj: Record<string, unknown> = { ...item, apiVersion: k.group === "" ? k.version : `${k.group}/${k.version}`, kind: k.kind };
+        const { managedFields: _mf, ...restMeta } = meta;
+        obj.metadata = restMeta;
+        const tags: Record<string, string> = {};
+        for (const [lk, lv] of Object.entries(meta.labels ?? {})) tags[lk] = String(lv);
+        found.push({
+          listedType: k.listedType,
+          location,
+          nativeId: k.namespaced ? `${ns}/${meta.name}` : meta.name,
+          cloudIds: meta.uid ? [{ kind: "k8s-uid", value: meta.uid }] : [],
+          tags,
+          properties: maskKubernetesObject(obj),
+          observedAt,
+          labels: true,
+        });
+      }
+      cont = body?.metadata?.continue || undefined;
+      if (!cont) break;
+    }
+    if (failed) {
+      const detail = k8sMessage(failed);
+      const verdict = failed.status === 401 || failed.status === 403 ? "no-credentials" : failed.status === 404 ? "unsupported-kind" : "read-failed";
+      for (const l of coverageLocations) ctx.coverage.push({ listedType: k.listedType, location: l, verdict, detail });
+      ctx.notes.push({
+        code: verdict === "no-credentials" ? "no-credentials" : verdict === "unsupported-kind" ? "no-lister" : "read-failed",
+        listedType: k.listedType,
+        message: `LIST ${k.listedType} failed: ${detail}`,
+      });
+      continue;
+    }
+    for (const r of found) ctx.resources.push(buildResource(ctx, r));
+    for (const l of coverageLocations) ctx.coverage.push({ listedType: k.listedType, location: l, ...listedVerdict(scope) });
+  }
+}
+
+/**
+ * A {@link KubernetesTarget} from a kubeconfig the caller names (its text,
+ * and the directory relative file paths resolve against). Static credentials
+ * only: a token, a token file, or a client certificate and key. An exec
+ * plugin or an auth provider is refused.
+ */
+export function kubeTargetFromKubeconfig(text: string, opts: { context?: string; baseDir?: string } = {}): KubernetesTarget & { contextName: string; clusterName: string } {
+  const doc = parseYAML(text) as Record<string, unknown>;
+  const named = <T>(list: unknown, name: string, field: string): T | undefined => {
+    for (const e of Array.isArray(list) ? list : []) {
+      const o = e as Record<string, unknown>;
+      if (o?.name === name) return o[field] as T;
+    }
+    return undefined;
+  };
+  const contextName = opts.context ?? (typeof doc["current-context"] === "string" ? (doc["current-context"] as string) : undefined);
+  if (!contextName) throw new ListerConfigError("the kubeconfig names no context and none was given");
+  const context = named<Record<string, unknown>>(doc.contexts, contextName, "context");
+  if (!context) throw new ListerConfigError(`the kubeconfig has no context ${contextName}`);
+  const clusterName = String(context.cluster ?? "");
+  const userName = String(context.user ?? "");
+  const cluster = named<Record<string, unknown>>(doc.clusters, clusterName, "cluster");
+  if (!cluster || typeof cluster.server !== "string") throw new ListerConfigError(`the kubeconfig's cluster ${clusterName} has no server`);
+  const user = named<Record<string, unknown>>(doc.users, userName, "user") ?? {};
+  if (user.exec || user["auth-provider"]) {
+    throw new ListerConfigError(`the kubeconfig user ${userName} authenticates through an exec plugin or auth provider; the lister takes static credentials only (a token, or a client certificate and key)`);
+  }
+  const file = (p: unknown): string | undefined => {
+    if (typeof p !== "string" || !p) return undefined;
+    const path = p.startsWith("/") || !opts.baseDir ? p : `${opts.baseDir}/${p}`;
+    return readFileSync(path, "utf8");
+  };
+  const b64 = (d: unknown): string | undefined => (typeof d === "string" && d ? Buffer.from(d, "base64").toString("utf8") : undefined);
+  const tls: TlsOptions = {};
+  const ca = b64(cluster["certificate-authority-data"]) ?? file(cluster["certificate-authority"]);
+  if (ca) tls.ca = ca;
+  const cert = b64(user["client-certificate-data"]) ?? file(user["client-certificate"]);
+  if (cert) tls.cert = cert;
+  const key = b64(user["client-key-data"]) ?? file(user["client-key"]);
+  if (key) tls.key = key;
+  if (cluster["insecure-skip-tls-verify"] === true) tls.insecureSkipVerify = true;
+  const token = typeof user.token === "string" && user.token ? (user.token as string) : file(user.tokenFile)?.trim();
+  return { server: cluster.server, ...(token ? { token } : {}), tls, contextName, clusterName };
+}

package/src/cloud-lister/markers.ts

@@ -0,0 +1,74 @@
+/**
+ * behold#1029: ownership markers read off a listed object's tags or labels,
+ * in chant#4520's `EngineFacts.markers` shape with `source: "live"`.
+ *
+ * The key sets the lister knows (#1025 "What a cloud source can and cannot
+ * say about engine facts"):
+ *  - choudoufu: `tofu-estate` and `tofu-address`, the address escaped
+ *    (choudoufu internal/live/markers/markers.go:40,43);
+ *  - plunge: `plunge-stack` and `plunge-urn` (continued in `plunge-urn-2`
+ *    to `-4`), plain on tags and digests on labels (chant#4520's
+ *    `markerScheme` for plunge);
+ *  - chant: the lexicons' `ChannelKeys` with managed-by `chant`
+ *    (packages/core/src/ownership.ts; aws `chant:*`, azure `chant-*`, gcp
+ *    `managed-by` and `chant-stack`, the shared label convention for
+ *    Kubernetes).
+ *
+ * `markers` is one object, so an object carrying several engines' markers
+ * reports the first found in that order. Every tag stays in `tags`, so
+ * nothing is lost. A marker key is matched case-insensitively, because Azure
+ * tag names are case-insensitive. The lister never derives ownership from a
+ * marker: that is relative to an estate or stack it does not read.
+ */
+
+import type { MarkerFact } from "./types";
+
+function lookup(tags: Record<string, string>, key: string): string | undefined {
+  if (key in tags) return tags[key];
+  const lower = key.toLowerCase();
+  for (const [k, v] of Object.entries(tags)) if (k.toLowerCase() === lower) return v;
+  return undefined;
+}
+
+const CHANT_KEY_SETS: ReadonlyArray<{ managedBy: string; stack: string }> = [
+  { managedBy: "chant:managed-by", stack: "chant:stack" },
+  { managedBy: "chant-managed-by", stack: "chant-stack" },
+  { managedBy: "managed-by", stack: "chant-stack" },
+  { managedBy: "app.kubernetes.io/managed-by", stack: "chant.intentius.io/stack" },
+];
+
+/**
+ * The marker fact for one object. `labels` says the values came from GCP or
+ * Kubernetes labels, where plunge writes digests rather than plain values.
+ */
+export function readMarkers(tags: Record<string, string>, opts: { labels: boolean }): MarkerFact | undefined {
+  const estate = lookup(tags, "tofu-estate");
+  if (estate !== undefined) {
+    const address = lookup(tags, "tofu-address");
+    return { owner: estate, ...(address !== undefined ? { address } : {}), encoding: "escaped", source: "live" };
+  }
+  const stack = lookup(tags, "plunge-stack");
+  if (stack !== undefined) {
+    let urn = lookup(tags, "plunge-urn");
+    if (urn !== undefined && !opts.labels) {
+      for (let i = 2; i <= 4; i++) {
+        const more = lookup(tags, `plunge-urn-${i}`);
+        if (more === undefined) break;
+        urn += more;
+      }
+    }
+    return {
+      owner: stack,
+      ...(urn !== undefined ? { address: urn } : {}),
+      encoding: opts.labels ? "digest" : "plain",
+      source: "live",
+    };
+  }
+  for (const keys of CHANT_KEY_SETS) {
+    if (lookup(tags, keys.managedBy) === "chant") {
+      const owner = lookup(tags, keys.stack);
+      return { ...(owner !== undefined ? { owner } : {}), encoding: "plain", source: "live" };
+    }
+  }
+  return undefined;
+}

package/src/cloud-lister/mask.ts

@@ -0,0 +1,77 @@
+/**
+ * behold#1029: secret-bearing values are masked in the lister, before a
+ * `ListingResult` exists, so no later stage (chant#4521's typing, the store,
+ * LadybugDB) ever holds one (#1025 "Source interface").
+ *
+ * The key list is chant's `SENSITIVE_KEY_PATTERNS` (../sensitive-key.ts), the
+ * one list chant's thin and deep observation paths share. behold carried a
+ * copy while the lister lived there; in chant it is the same list.
+ *
+ * Beyond key names, two things are masked whole because their values are
+ * secrets whatever their keys are called:
+ *  - a Kubernetes Secret's `data` and `stringData`, and its
+ *    `kubectl.kubernetes.io/last-applied-configuration` annotation, which
+ *    repeats them;
+ *  - any tag or label whose key matches the patterns.
+ */
+
+import { isSensitiveKey, SENSITIVE_KEY_PATTERNS } from "../sensitive-key";
+
+export { isSensitiveKey, SENSITIVE_KEY_PATTERNS };
+
+/** What a masked value becomes. A fixed string, so a masked value never diffs. */
+export const MASKED = "<masked>";
+
+/**
+ * A deep copy of `value` with every value under a sensitive key replaced by
+ * {@link MASKED}. Arrays of `{Key, Value}` / `{key, value}` pairs (AWS tags,
+ * some ARM shapes) are masked by the pair's key as well.
+ */
+export function maskValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map((v) => maskValue(v));
+  if (value === null || typeof value !== "object") return value;
+  const obj = value as Record<string, unknown>;
+  const pairKey = typeof obj.Key === "string" ? obj.Key : typeof obj.key === "string" ? obj.key : undefined;
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (isSensitiveKey(k)) {
+      out[k] = MASKED;
+    } else if (pairKey !== undefined && isSensitiveKey(pairKey) && (k === "Value" || k === "value")) {
+      out[k] = MASKED;
+    } else {
+      out[k] = maskValue(v);
+    }
+  }
+  return out;
+}
+
+export function maskProperties(props: Record<string, unknown>): Record<string, unknown> {
+  return maskValue(props) as Record<string, unknown>;
+}
+
+export function maskTags(tags: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(tags)) out[k] = isSensitiveKey(k) ? MASKED : v;
+  return out;
+}
+
+const LAST_APPLIED = "kubectl.kubernetes.io/last-applied-configuration";
+
+/** A Kubernetes object, masked: key names everywhere, and a Secret's payload whole. */
+export function maskKubernetesObject(obj: Record<string, unknown>): Record<string, unknown> {
+  const masked = maskProperties(obj);
+  if (obj.kind === "Secret") {
+    for (const field of ["data", "stringData"]) {
+      const payload = masked[field];
+      if (payload && typeof payload === "object") {
+        masked[field] = Object.fromEntries(Object.keys(payload as object).map((k) => [k, MASKED]));
+      }
+    }
+  }
+  const metadata = masked.metadata as Record<string, unknown> | undefined;
+  const annotations = metadata?.annotations as Record<string, unknown> | undefined;
+  if (annotations && LAST_APPLIED in annotations && obj.kind === "Secret") {
+    annotations[LAST_APPLIED] = MASKED;
+  }
+  return masked;
+}

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

@@ -0,0 +1,81 @@
+/**
+ * behold#1029: the pieces of the listing-result shape: node ids (ruling Q2),
+ * masking (chant's one key list), and markers (chant#4520's shape).
+ */
+import { describe, expect, it } from "vitest";
+import { listedNodeId, parseListedNodeId } from "./ids";
+import { isSensitiveKey, MASKED, maskProperties, maskTags, SENSITIVE_KEY_PATTERNS } from "./mask";
+import { readMarkers } from "./markers";
+import { isSensitiveKey as chantIsSensitiveKey, SENSITIVE_KEY_PATTERNS as chantPatterns } from "../sensitive-key";
+
+describe("listed node ids", () => {
+  it("are path-style and parse back, with slashes in the type and the native id", () => {
+    const parts = {
+      substrate: "azure" as const,
+      scopeId: "sub-1",
+      location: "eastus",
+      listedType: "microsoft.storage/storageaccounts",
+      nativeId: "/subscriptions/sub-1/resourceGroups/rg/providers/Microsoft.Storage/storageAccounts/sa",
+    };
+    const id = listedNodeId(parts);
+    expect(id).toBe("azure/sub-1/eastus/microsoft.storage%2Fstorageaccounts//subscriptions/sub-1/resourceGroups/rg/providers/Microsoft.Storage/storageAccounts/sa");
+    expect(parseListedNodeId(id)).toEqual(parts);
+  });
+
+  it("keep an aws identifier verbatim as the last part", () => {
+    const id = listedNodeId({ substrate: "aws", scopeId: "000000000000", location: "us-east-1", listedType: "AWS::EC2::SecurityGroupIngress", nativeId: "sg-1|tcp|80" });
+    expect(id).toBe("aws/000000000000/us-east-1/AWS::EC2::SecurityGroupIngress/sg-1|tcp|80");
+    expect(parseListedNodeId(id)?.nativeId).toBe("sg-1|tcp|80");
+  });
+
+  it("escape a percent sign so it parses back", () => {
+    const parts = { substrate: "kubernetes" as const, scopeId: "c%1", location: "ns", listedType: "v1/Pod", nativeId: "ns/p" };
+    expect(parseListedNodeId(listedNodeId(parts))).toEqual(parts);
+  });
+});
+
+describe("masking", () => {
+  it("masks by key at any depth and in key/value pairs", () => {
+    const masked = maskProperties({
+      Name: "db",
+      MasterUserPassword: "hunter2",
+      Nested: { list: [{ clientSecret: "s" }, { ok: 1 }] },
+      Tags: [{ Key: "github-token", Value: "ghp_x" }, { Key: "env", Value: "prod" }],
+      KeyName: "deploy-key",
+    });
+    expect(masked).toEqual({
+      Name: "db",
+      MasterUserPassword: MASKED,
+      Nested: { list: [{ clientSecret: MASKED }, { ok: 1 }] },
+      Tags: [{ Key: "github-token", Value: MASKED }, { Key: "env", Value: "prod" }],
+      KeyName: "deploy-key",
+    });
+    expect(maskTags({ "db-password": "x", env: "prod" })).toEqual({ "db-password": MASKED, env: "prod" });
+  });
+
+  it("is chant's one key list (../sensitive-key.ts), not a copy", () => {
+    expect(SENSITIVE_KEY_PATTERNS).toBe(chantPatterns);
+    for (const k of ["password", "Secret", "apiToken", "private_key", "credentials", "ConnectionString", "Key", "KeyName"]) {
+      expect(isSensitiveKey(k)).toBe(chantIsSensitiveKey(k));
+    }
+  });
+});
+
+describe("markers", () => {
+  it("reads choudoufu's, plunge's and chant's keys, in that order", () => {
+    expect(readMarkers({ "tofu-estate": "web", "tofu-address": "module.app.aws_eip.pool[1]", "chant:managed-by": "chant" }, { labels: false })).toEqual({
+      owner: "web",
+      address: "module.app.aws_eip.pool[1]",
+      encoding: "escaped",
+      source: "live",
+    });
+    expect(readMarkers({ "plunge-stack": "app/dev", "plunge-urn": "urn:pulumi:", "plunge-urn-2": "dev::app" }, { labels: false })).toEqual({
+      owner: "app/dev",
+      address: "urn:pulumi:dev::app",
+      encoding: "plain",
+      source: "live",
+    });
+    expect(readMarkers({ "Chant-Managed-By": "chant", "chant-stack": "web" }, { labels: false })).toEqual({ owner: "web", encoding: "plain", source: "live" });
+    expect(readMarkers({ "managed-by": "terraform" }, { labels: true })).toBeUndefined();
+  });
+});

package/src/cloud-lister/sigv4.ts

@@ -0,0 +1,70 @@
+/**
+ * behold#1029: AWS Signature Version 4 for the lister's one AWS call.
+ *
+ * Signed by hand with node:crypto rather than through the AWS SDK, so the
+ * lister builds no SDK client (no client to hold a mutating command, no
+ * default provider chain) and adds no dependency. Only what Cloud Control's
+ * JSON protocol needs: a POST to `/` with no query string.
+ */
+
+import { createHash, createHmac } from "node:crypto";
+import type { AwsStaticCredentials } from "./credentials";
+
+function sha256Hex(data: string): string {
+  return createHash("sha256").update(data, "utf8").digest("hex");
+}
+
+function hmac(key: Buffer | string, data: string): Buffer {
+  return createHmac("sha256", key).update(data, "utf8").digest();
+}
+
+/** `20261026T120000Z` and `20261026` for a date. */
+export function amzDates(now: Date): { amzDate: string; dateStamp: string } {
+  const iso = now.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}/, "");
+  return { amzDate: iso, dateStamp: iso.slice(0, 8) };
+}
+
+/**
+ * The headers to send, `Authorization` included. `headers` must not already
+ * hold `host` or `x-amz-date`; they are added here.
+ */
+export function signV4(input: {
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  body: string;
+  region: string;
+  service: string;
+  credentials: AwsStaticCredentials;
+  now: Date;
+}): Record<string, string> {
+  const url = new URL(input.url);
+  const { amzDate, dateStamp } = amzDates(input.now);
+  const headers: Record<string, string> = {};
+  for (const [k, v] of Object.entries(input.headers)) headers[k.toLowerCase()] = v.trim();
+  headers.host = url.host;
+  headers["x-amz-date"] = amzDate;
+  if (input.credentials.sessionToken) headers["x-amz-security-token"] = input.credentials.sessionToken;
+  const payloadHash = sha256Hex(input.body);
+
+  const names = Object.keys(headers).sort();
+  const canonicalHeaders = names.map((n) => `${n}:${headers[n]}\n`).join("");
+  const signedHeaders = names.join(";");
+  const canonicalQuery = [...url.searchParams.entries()]
+    .map(([k, v]) => [encodeURIComponent(k), encodeURIComponent(v)])
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([k, v]) => `${k}=${v}`)
+    .join("&");
+  const canonicalRequest = [input.method, url.pathname || "/", canonicalQuery, canonicalHeaders, signedHeaders, payloadHash].join("\n");
+
+  const scope = `${dateStamp}/${input.region}/${input.service}/aws4_request`;
+  const stringToSign = ["AWS4-HMAC-SHA256", amzDate, scope, sha256Hex(canonicalRequest)].join("\n");
+  const kDate = hmac(`AWS4${input.credentials.secretAccessKey}`, dateStamp);
+  const kRegion = hmac(kDate, input.region);
+  const kService = hmac(kRegion, input.service);
+  const kSigning = hmac(kService, "aws4_request");
+  const signature = createHmac("sha256", kSigning).update(stringToSign, "utf8").digest("hex");
+
+  headers.authorization = `AWS4-HMAC-SHA256 Credential=${input.credentials.accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+  return headers;
+}