@intentius/chant 0.124.51 → 0.124.54

package/dist/cloud-lister/gcp.js

@@ -0,0 +1,143 @@
+/**
+ * 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 } from "./common.js";
+import { resolveGcpToken, ListerConfigError } from "./credentials.js";
+import { jsonBody } from "./transport.js";
+const PAGE_SIZE = 500;
+const MAX_PAGES = 10000;
+const PROJECT = /^[A-Za-z0-9._:-]+$/;
+const LABEL_PART = /^[A-Za-z0-9_\-]+$/;
+export function enableCommand(project) {
+    return `gcloud services enable cloudasset.googleapis.com --project=${project}`;
+}
+export function searchUrl(target, project, params) {
+    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) {
+    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 ");
+}
+function gcpError(res) {
+    const body = jsonBody(res);
+    const e = Array.isArray(body) ? body[0]?.error : body?.error;
+    const reasons = [...(e?.details ?? []), ...(e?.errors ?? [])]
+        .map((d) => d.reason ?? "")
+        .filter(Boolean);
+    return { status: e?.status ?? "", message: e?.message ?? "", reasons };
+}
+export function isServiceDisabled(res) {
+    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, target, chains, retryDelays) {
+    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 = [];
+    let pageToken;
+    for (let page = 0; page < MAX_PAGES; page++) {
+        const url = searchUrl(target, scope.scopeId, { assetTypes, query, pageToken });
+        const headers = { 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);
+        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 = {};
+            if (r.labels && typeof r.labels === "object") {
+                for (const [k, v] of Object.entries(r.labels))
+                    tags[k] = String(v ?? "");
+            }
+            const cloudIds = [{ kind: "provider-id", value: name }];
+            const attrs = r.additionalAttributes;
+            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/dist/cloud-lister/guard.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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.js";
+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 declare const READ_OPERATIONS: Readonly<Record<Substrate, readonly string[]>>;
+export declare class MutatingCallRefused extends Error {
+    readonly call: Pick<WireCall, "substrate" | "method" | "url">;
+    readonly operation: string;
+    constructor(call: Pick<WireCall, "substrate" | "method" | "url">, operation: string);
+}
+/**
+ * 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 declare function classifyCall(call: WireCall): string;
+/** Throws {@link MutatingCallRefused} unless the call is one of {@link READ_OPERATIONS}. */
+export declare function assertReadCall(call: WireCall): string;
+//# sourceMappingURL=guard.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/cloud-lister/guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAE1F,4CAA4C;AAC5C,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,EAAE,UAAU,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,6DAA6D;AAC7D,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC,CAK1E,CAAC;AAEF,qBAAa,mBAAoB,SAAQ,KAAK;IAE1C,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,WAAW,GAAG,QAAQ,GAAG,KAAK,CAAC;IAC7D,QAAQ,CAAC,SAAS,EAAE,MAAM;IAF5B,YACW,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,WAAW,GAAG,QAAQ,GAAG,KAAK,CAAC,EACpD,SAAS,EAAE,MAAM,EAI3B;CACF;AAQD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAqCnD;AAED,4FAA4F;AAC5F,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAIrD"}

package/dist/cloud-lister/guard.js

@@ -0,0 +1,103 @@
+/**
+ * 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.
+ */
+/** The only operations the lister may send, by substrate. */
+export const READ_OPERATIONS = {
+    aws: ["cloudcontrol:ListResources"],
+    azure: ["resourcegraph:resources"],
+    gcp: ["cloudasset:searchAllResources"],
+    kubernetes: ["k8s:discovery", "k8s:list"],
+};
+export class MutatingCallRefused extends Error {
+    constructor(call, operation) {
+        super(`chant's cloud lister refused ${call.method} ${call.url} (${operation}): only ${READ_OPERATIONS[call.substrate].join(", ")} may be sent`);
+        this.call = call;
+        this.operation = operation;
+        this.name = "MutatingCallRefused";
+    }
+}
+function header(headers, name) {
+    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) {
+    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) {
+    const operation = classifyCall(call);
+    if (!READ_OPERATIONS[call.substrate].includes(operation))
+        throw new MutatingCallRefused(call, operation);
+    return operation;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * 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.js";
+export interface ListedNodeIdParts {
+    substrate: Substrate;
+    scopeId: string;
+    location: string;
+    listedType: string;
+    nativeId: string;
+}
+export declare function listedNodeId(parts: ListedNodeIdParts): string;
+/** The parts back from an id {@link listedNodeId} wrote; `undefined` for anything else. */
+export declare function parseListedNodeId(id: string): ListedNodeIdParts | undefined;
+//# sourceMappingURL=ids.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../src/cloud-lister/ids.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAUzC,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,SAAS,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAQ7D;AAED,2FAA2F;AAC3F,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAY3E"}

package/dist/cloud-lister/ids.js

@@ -0,0 +1,42 @@
+/**
+ * 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`.
+ */
+function escapeSegment(s) {
+    return s.replace(/%/g, "%25").replace(/\//g, "%2F");
+}
+function unescapeSegment(s) {
+    return s.replace(/%2F/gi, "/").replace(/%25/g, "%");
+}
+export function listedNodeId(parts) {
+    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) {
+    const parts = [];
+    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/dist/cloud-lister/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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 { type AwsTarget } from "./aws.js";
+import { type AzureTarget } from "./azure.js";
+import { type GcpTarget } from "./gcp.js";
+import { type KubernetesTarget } from "./kubernetes.js";
+import { type CredentialChains } from "./credentials.js";
+import { type Fetcher, type TransportOptions } from "./transport.js";
+import type { CloudScope, ListingResult } from "./types.js";
+export type { CloudScope, ListingResult, ListedResource, CoverageEntry, IndexNote, CloudId, ListedFacts, MarkerFact, Substrate, TagFilter } from "./types.js";
+export type { AwsTarget } from "./aws.js";
+export type { AzureTarget } from "./azure.js";
+export type { GcpTarget } from "./gcp.js";
+export type { KubernetesTarget } from "./kubernetes.js";
+export { kubeTargetFromKubeconfig } from "./kubernetes.js";
+export { ListerConfigError } from "./credentials.js";
+export { MutatingCallRefused, READ_OPERATIONS } from "./guard.js";
+export { OriginRefused } from "./transport.js";
+export { listedNodeId, parseListedNodeId } from "./ids.js";
+/** 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"];
+}
+/** The scope as the stamp records it: lists sorted and deduplicated (#1025 "Stamp"). */
+export declare function canonicalScope(scope: CloudScope): CloudScope;
+export declare function listCloud(scope: CloudScope, target: SubstrateTarget, options?: ListOptions): Promise<ListingResult>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cloud-lister/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAW,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAChD,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,EAAW,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAChD,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,EAAuB,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,EAAa,KAAK,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC9F,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAEzD,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,cAAc,EAAE,aAAa,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC3J,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAC;AAExD,8FAA8F;AAC9F,MAAM,MAAM,eAAe,GACvB;IAAE,SAAS,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,SAAS,CAAA;CAAE,GACpC;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,GAC1C;IAAE,SAAS,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,SAAS,CAAA;CAAE,GACpC;IAAE,SAAS,EAAE,YAAY,CAAC;IAAC,UAAU,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAE9D,MAAM,WAAW,WAAW;IAC1B,oCAAoC;IACpC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,oGAAoG;IACpG,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,gDAAgD;IAChD,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,MAAM,CAAC,EAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAC;CACrC;AAOD,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAU5D;AAeD,wBAAsB,SAAS,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,eAAe,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,aAAa,CAAC,CAyC7H"}

package/dist/cloud-lister/index.js

@@ -0,0 +1,102 @@
+/**
+ * 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 } from "./common.js";
+import { listAws } from "./aws.js";
+import { listAzure } from "./azure.js";
+import { listGcp } from "./gcp.js";
+import { listKubernetes } from "./kubernetes.js";
+import { sdkCredentialChains } from "./credentials.js";
+import { Transport } from "./transport.js";
+export { kubeTargetFromKubeconfig } from "./kubernetes.js";
+export { ListerConfigError } from "./credentials.js";
+export { MutatingCallRefused, READ_OPERATIONS } from "./guard.js";
+export { OriginRefused } from "./transport.js";
+export { listedNodeId, parseListedNodeId } from "./ids.js";
+function sortedUnique(values) {
+    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) {
+    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) {
+    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, target, options = {}) {
+    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 = { 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/dist/cloud-lister/kubernetes.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 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 { type ListerContext } from "./common.js";
+import { type TlsOptions } from "./transport.js";
+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;
+}
+export declare function listedTypeOf(group: string, version: string, kind: string): string;
+/**
+ * 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 declare function discover(ctx: ListerContext, target: KubernetesTarget, requested: ReadonlySet<string> | undefined, retryDelays?: readonly number[]): Promise<ServedKind[]>;
+/** `labelSelector` for a tag filter, or undefined. Exported for tests. */
+export declare function labelSelector(filter: Readonly<Record<string, string>> | undefined): string | undefined;
+export declare function listKubernetes(ctx: ListerContext, target: KubernetesTarget, retryDelays?: readonly number[]): Promise<void>;
+/**
+ * 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 declare function kubeTargetFromKubeconfig(text: string, opts?: {
+    context?: string;
+    baseDir?: string;
+}): KubernetesTarget & {
+    contextName: string;
+    clusterName: string;
+};
+//# sourceMappingURL=kubernetes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"kubernetes.d.ts","sourceRoot":"","sources":["../../src/cloud-lister/kubernetes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,EAAmF,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAG/H,OAAO,EAAY,KAAK,UAAU,EAAqB,MAAM,aAAa,CAAC;AAE3E,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,UAAU,CAAC;CAClB;AAED,8CAA8C;AAC9C,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,OAAO,CAAC;IACpB,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;CACpB;AASD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjF;AAkCD;;;GAGG;AACH,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,gBAAgB,EACxB,SAAS,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,SAAS,EAC1C,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAC9B,OAAO,CAAC,UAAU,EAAE,CAAC,CAiCvB;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAStG;AAED,wBAAsB,cAAc,CAAC,GAAG,EAAE,aAAa,EAAE,MAAM,EAAE,gBAAgB,EAAE,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA0FjI;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,gBAAgB,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAqCzK"}