@intentius/chant 0.124.52 → 0.124.54

package/dist/cloud-lister/kubernetes.js

@@ -0,0 +1,276 @@
+/**
+ * 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.js";
+import { buildResource, describeFailure, listedVerdict, noteTagFilter, withThrottleRetry } from "./common.js";
+import { ListerConfigError } from "./credentials.js";
+import { maskKubernetesObject } from "./mask.js";
+import { jsonBody } from "./transport.js";
+const PAGE_SIZE = 500;
+const MAX_PAGES = 10000;
+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, version, kind) {
+    return group === "" ? `${version}/${kind}` : `${group}/${version}/${kind}`;
+}
+function apiUrl(target, path, query) {
+    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) {
+    return { accept: "application/json", ...(target.token ? { authorization: `Bearer ${target.token}` } : {}) };
+}
+async function get(ctx, target, path, query, retryDelays) {
+    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) {
+    const body = jsonBody(res);
+    return describeFailure(res, body?.reason, body?.message);
+}
+function resourcesOf(body, group, version) {
+    const list = body?.resources ?? [];
+    const out = [];
+    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, target, requested, retryDelays) {
+    const kinds = [];
+    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)?.groups ?? [];
+    for (const g of list) {
+        if (!g.name)
+            continue;
+        const versions = new Set();
+        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) {
+    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, target, retryDelays) {
+    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;
+    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 = [];
+        let cont;
+        let failed;
+        for (let page = 0; page < MAX_PAGES; page++) {
+            const query = { 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);
+            for (const item of body?.items ?? []) {
+                const meta = (item.metadata ?? {});
+                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 = { ...item, apiVersion: k.group === "" ? k.version : `${k.group}/${k.version}`, kind: k.kind };
+                const { managedFields: _mf, ...restMeta } = meta;
+                obj.metadata = restMeta;
+                const tags = {};
+                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, opts = {}) {
+    const doc = parseYAML(text);
+    const named = (list, name, field) => {
+        for (const e of Array.isArray(list) ? list : []) {
+            const o = e;
+            if (o?.name === name)
+                return o[field];
+        }
+        return undefined;
+    };
+    const contextName = opts.context ?? (typeof doc["current-context"] === "string" ? doc["current-context"] : undefined);
+    if (!contextName)
+        throw new ListerConfigError("the kubeconfig names no context and none was given");
+    const context = named(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(doc.clusters, clusterName, "cluster");
+    if (!cluster || typeof cluster.server !== "string")
+        throw new ListerConfigError(`the kubeconfig's cluster ${clusterName} has no server`);
+    const user = named(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) => {
+        if (typeof p !== "string" || !p)
+            return undefined;
+        const path = p.startsWith("/") || !opts.baseDir ? p : `${opts.baseDir}/${p}`;
+        return readFileSync(path, "utf8");
+    };
+    const b64 = (d) => (typeof d === "string" && d ? Buffer.from(d, "base64").toString("utf8") : undefined);
+    const tls = {};
+    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 : file(user.tokenFile)?.trim();
+    return { server: cluster.server, ...(token ? { token } : {}), tls, contextName, clusterName };
+}

package/dist/cloud-lister/markers.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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.js";
+/**
+ * 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 declare function readMarkers(tags: Record<string, string>, opts: {
+    labels: boolean;
+}): MarkerFact | undefined;
+//# sourceMappingURL=markers.d.ts.map

package/dist/cloud-lister/markers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markers.d.ts","sourceRoot":"","sources":["../../src/cloud-lister/markers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAgB1C;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG,UAAU,GAAG,SAAS,CA8B3G"}

package/dist/cloud-lister/markers.js

@@ -0,0 +1,73 @@
+/**
+ * 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.
+ */
+function lookup(tags, key) {
+    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 = [
+    { 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, opts) {
+    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/dist/cloud-lister/mask.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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.js";
+export { isSensitiveKey, SENSITIVE_KEY_PATTERNS };
+/** What a masked value becomes. A fixed string, so a masked value never diffs. */
+export declare 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 declare function maskValue(value: unknown): unknown;
+export declare function maskProperties(props: Record<string, unknown>): Record<string, unknown>;
+export declare function maskTags(tags: Record<string, string>): Record<string, string>;
+/** A Kubernetes object, masked: key names everywhere, and a Secret's payload whole. */
+export declare function maskKubernetesObject(obj: Record<string, unknown>): Record<string, unknown>;
+//# sourceMappingURL=mask.d.ts.map

package/dist/cloud-lister/mask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mask.d.ts","sourceRoot":"","sources":["../../src/cloud-lister/mask.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE1E,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,CAAC;AAElD,kFAAkF;AAClF,eAAO,MAAM,MAAM,aAAa,CAAC;AAEjC;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAgBjD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEtF;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAI7E;AAID,uFAAuF;AACvF,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgB1F"}

package/dist/cloud-lister/mask.js

@@ -0,0 +1,74 @@
+/**
+ * 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.js";
+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) {
+    if (Array.isArray(value))
+        return value.map((v) => maskValue(v));
+    if (value === null || typeof value !== "object")
+        return value;
+    const obj = value;
+    const pairKey = typeof obj.Key === "string" ? obj.Key : typeof obj.key === "string" ? obj.key : undefined;
+    const out = {};
+    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) {
+    return maskValue(props);
+}
+export function maskTags(tags) {
+    const out = {};
+    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) {
+    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).map((k) => [k, MASKED]));
+            }
+        }
+    }
+    const metadata = masked.metadata;
+    const annotations = metadata?.annotations;
+    if (annotations && LAST_APPLIED in annotations && obj.kind === "Secret") {
+        annotations[LAST_APPLIED] = MASKED;
+    }
+    return masked;
+}

package/dist/cloud-lister/sigv4.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 type { AwsStaticCredentials } from "./credentials.js";
+/** `20261026T120000Z` and `20261026` for a date. */
+export declare function amzDates(now: Date): {
+    amzDate: string;
+    dateStamp: string;
+};
+/**
+ * The headers to send, `Authorization` included. `headers` must not already
+ * hold `host` or `x-amz-date`; they are added here.
+ */
+export declare function signV4(input: {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body: string;
+    region: string;
+    service: string;
+    credentials: AwsStaticCredentials;
+    now: Date;
+}): Record<string, string>;
+//# sourceMappingURL=sigv4.d.ts.map

package/dist/cloud-lister/sigv4.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sigv4.d.ts","sourceRoot":"","sources":["../../src/cloud-lister/sigv4.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAU1D,oDAAoD;AACpD,wBAAgB,QAAQ,CAAC,GAAG,EAAE,IAAI,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAG1E;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,oBAAoB,CAAC;IAClC,GAAG,EAAE,IAAI,CAAC;CACX,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA8BzB"}

package/dist/cloud-lister/sigv4.js

@@ -0,0 +1,54 @@
+/**
+ * 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";
+function sha256Hex(data) {
+    return createHash("sha256").update(data, "utf8").digest("hex");
+}
+function hmac(key, data) {
+    return createHmac("sha256", key).update(data, "utf8").digest();
+}
+/** `20261026T120000Z` and `20261026` for a date. */
+export function amzDates(now) {
+    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) {
+    const url = new URL(input.url);
+    const { amzDate, dateStamp } = amzDates(input.now);
+    const headers = {};
+    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;
+}

package/dist/cloud-lister/transport.d.ts

@@ -0,0 +1,55 @@
+/**
+ * behold#1029: the lister's one way onto the network.
+ *
+ * {@link Transport.send} runs, in order: the read-only check
+ * (packages/core/src/cloud-lister/guard.ts), the origin pin, then the fetcher. The pin is
+ * the goal's never-public-cloud rule in code: when a run names its own
+ * endpoint (an emulator), every call must go to that endpoint's origin, so a
+ * URL built wrong can never reach a public cloud host. A test passes its own
+ * {@link Fetcher}; production uses {@link nodeFetcher}, which is node's own
+ * http/https so a cluster's CA and client certificate can be passed
+ * explicitly.
+ */
+import { type WireCall } from "./guard.js";
+export interface WireResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+/** TLS material for one target, passed explicitly; nothing is read from the environment. */
+export interface TlsOptions {
+    ca?: string;
+    cert?: string;
+    key?: string;
+    /** Only for a local emulator whose certificate the caller chose not to pin. */
+    insecureSkipVerify?: boolean;
+}
+export type Fetcher = (call: WireCall, tls: TlsOptions | undefined) => Promise<WireResponse>;
+export declare class OriginRefused extends Error {
+    readonly url: string;
+    readonly allowed: string;
+    constructor(url: string, allowed: string);
+}
+export interface TransportOptions {
+    fetcher?: Fetcher;
+    /** When set, every call must go to this origin (an explicit endpoint). */
+    pinnedOrigin?: string;
+    tls?: TlsOptions;
+    /** Called with each call that passed the guard, before it is sent (tests record with it). */
+    onSend?: (call: WireCall, operation: string) => void;
+}
+export declare class Transport {
+    private readonly options;
+    readonly calls: Array<{
+        call: WireCall;
+        operation: string;
+    }>;
+    private readonly fetcher;
+    constructor(options?: TransportOptions);
+    send(call: WireCall): Promise<WireResponse>;
+}
+/** node's http/https, one request, the whole body read as text. */
+export declare const nodeFetcher: Fetcher;
+/** The body parsed as JSON, or `undefined` when it is not JSON. */
+export declare function jsonBody(res: WireResponse): unknown;
+//# sourceMappingURL=transport.d.ts.map

package/dist/cloud-lister/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/cloud-lister/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,4FAA4F;AAC5F,MAAM,WAAW,UAAU;IACzB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,MAAM,OAAO,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,UAAU,GAAG,SAAS,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;AAE7F,qBAAa,aAAc,SAAQ,KAAK;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM;IAA1D,YAAqB,GAAG,EAAE,MAAM,EAAW,OAAO,EAAE,MAAM,EAGzD;CACF;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,6FAA6F;IAC7F,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CACtD;AAED,qBAAa,SAAS;IAIR,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,QAAQ,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAM;IAClE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAElC,YAA6B,OAAO,GAAE,gBAAqB,EAE1D;IAEK,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,YAAY,CAAC,CAShD;CACF;AAED,mEAAmE;AACnE,eAAO,MAAM,WAAW,EAAE,OAqCtB,CAAC;AAEL,mEAAmE;AACnE,wBAAgB,QAAQ,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAMnD"}