@intentius/chant 0.124.52 → 0.124.54

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

@@ -0,0 +1,40 @@
+/**
+ * behold#1029: what every substrate's lister shares: building one masked
+ * {@link ListedResource}, recording coverage and notes, and the coverage rule
+ * for a tag filter.
+ */
+import type { Transport, WireResponse } from "./transport.js";
+import type { CloudId, CloudScope, CoverageEntry, IndexNote, ListedResource } from "./types.js";
+export interface ListerContext {
+    scope: CloudScope;
+    transport: Transport;
+    now: () => Date;
+    resources: ListedResource[];
+    coverage: CoverageEntry[];
+    notes: IndexNote[];
+}
+export declare function buildResource(ctx: ListerContext, r: {
+    listedType: string;
+    location: string;
+    nativeId: string;
+    cloudIds: CloudId[];
+    tags: Record<string, string>;
+    properties: Record<string, unknown>;
+    observedAt: string;
+    labels: boolean;
+}): ListedResource;
+/**
+ * The verdict for a (type, location) the lister read in full. Under a tag
+ * filter it is `filtered`, because a filtered listing cannot tell an untagged
+ * object from a missing one (#1025 "Coverage"); the objects it did list are
+ * still observed.
+ */
+export declare function listedVerdict(scope: CloudScope): Pick<CoverageEntry, "verdict" | "detail">;
+export declare function noteTagFilter(ctx: ListerContext, how: string): void;
+export declare function sortResult(ctx: ListerContext): void;
+/** A short, credential-free description of a failed response for a note or a coverage detail. */
+export declare function describeFailure(res: WireResponse, code?: string, message?: string): string;
+export declare const sleep: (ms: number) => Promise<void>;
+/** Retries a throttled call (HTTP 429 or a substrate's throttling code) a few times with backoff. */
+export declare function withThrottleRetry(send: () => Promise<WireResponse>, isThrottled: (res: WireResponse) => boolean, delays?: readonly number[]): Promise<WireResponse>;
+//# sourceMappingURL=common.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/cloud-lister/common.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE7F,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,UAAU,CAAC;IAClB,SAAS,EAAE,SAAS,CAAC;IACrB,GAAG,EAAE,MAAM,IAAI,CAAC;IAChB,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAED,wBAAgB,aAAa,CAC3B,GAAG,EAAE,aAAa,EAClB,CAAC,EAAE;IACD,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;CACjB,GACA,cAAc,CAehB;AAeD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC,aAAa,EAAE,SAAS,GAAG,QAAQ,CAAC,CAK1F;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAMnE;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CAKnD;AAED,iGAAiG;AACjG,wBAAgB,eAAe,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAK1F;AAED,eAAO,MAAM,KAAK,OAAQ,MAAM,kBAAgD,CAAC;AAEjF,qGAAqG;AACrG,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,EACjC,WAAW,EAAE,CAAC,GAAG,EAAE,YAAY,KAAK,OAAO,EAC3C,MAAM,GAAE,SAAS,MAAM,EAAsB,GAC5C,OAAO,CAAC,YAAY,CAAC,CAQvB"}

package/dist/cloud-lister/common.js

@@ -0,0 +1,83 @@
+/**
+ * behold#1029: what every substrate's lister shares: building one masked
+ * {@link ListedResource}, recording coverage and notes, and the coverage rule
+ * for a tag filter.
+ */
+import { listedNodeId } from "./ids.js";
+import { readMarkers } from "./markers.js";
+import { maskProperties, maskTags } from "./mask.js";
+export function buildResource(ctx, r) {
+    const tags = maskTags(r.tags);
+    const markers = readMarkers(r.tags, { labels: r.labels });
+    const cloudIds = dedupeCloudIds(r.cloudIds);
+    return {
+        id: listedNodeId({ substrate: ctx.scope.substrate, scopeId: ctx.scope.scopeId, location: r.location, listedType: r.listedType, nativeId: r.nativeId }),
+        listedType: r.listedType,
+        location: r.location,
+        nativeId: r.nativeId,
+        cloudIds,
+        tags,
+        properties: maskProperties(r.properties),
+        observedAt: r.observedAt,
+        facts: { ...(markers ? { markers } : {}), cloudIds, observedAt: r.observedAt },
+    };
+}
+function dedupeCloudIds(ids) {
+    const seen = new Set();
+    const out = [];
+    for (const id of ids) {
+        if (!id.value)
+            continue;
+        const key = `${id.kind}\u0000${id.value}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(id);
+    }
+    return out;
+}
+/**
+ * The verdict for a (type, location) the lister read in full. Under a tag
+ * filter it is `filtered`, because a filtered listing cannot tell an untagged
+ * object from a missing one (#1025 "Coverage"); the objects it did list are
+ * still observed.
+ */
+export function listedVerdict(scope) {
+    if (scope.tagFilter && Object.keys(scope.tagFilter).length > 0) {
+        return { verdict: "filtered", detail: `tag filter ${JSON.stringify(scope.tagFilter)}` };
+    }
+    return { verdict: "listed" };
+}
+export function noteTagFilter(ctx, how) {
+    if (!ctx.scope.tagFilter || Object.keys(ctx.scope.tagFilter).length === 0)
+        return;
+    ctx.notes.push({
+        code: "tag-filter",
+        message: `the tag filter ${JSON.stringify(ctx.scope.tagFilter)} was applied ${how}; every coverage entry is "filtered", since a tag-filtered listing cannot say an untagged object is absent`,
+    });
+}
+export function sortResult(ctx) {
+    ctx.resources.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    ctx.coverage.sort((a, b) => a.listedType !== b.listedType ? (a.listedType < b.listedType ? -1 : 1) : a.location < b.location ? -1 : a.location > b.location ? 1 : 0);
+}
+/** A short, credential-free description of a failed response for a note or a coverage detail. */
+export function describeFailure(res, code, message) {
+    const parts = [`HTTP ${res.status}`];
+    if (code)
+        parts.push(code);
+    if (message)
+        parts.push(message.length > 300 ? `${message.slice(0, 300)}...` : message);
+    return parts.join(": ");
+}
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Retries a throttled call (HTTP 429 or a substrate's throttling code) a few times with backoff. */
+export async function withThrottleRetry(send, isThrottled, delays = [500, 2000, 5000]) {
+    let res = await send();
+    for (const d of delays) {
+        if (!isThrottled(res))
+            return res;
+        await sleep(d);
+        res = await send();
+    }
+    return res;
+}

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

@@ -0,0 +1,50 @@
+/**
+ * behold#1029: where the lister's credentials come from.
+ *
+ * The goal's hard rule: against an emulator the lister takes explicit
+ * endpoints and static credentials only, and never the AWS SDK's default
+ * provider chain, Azure's DefaultAzureCredential or google-auth's
+ * application-default credentials. So:
+ *
+ *  - a target that names an `endpoint` must carry its credentials (a static
+ *    AWS key pair, an Azure bearer token, a GCP token or an explicit `null`
+ *    for an anonymous emulator). Without them the run is refused with
+ *    {@link ListerConfigError}, and no chain is loaded;
+ *  - only a target with no endpoint (a real cloud, which the maintainer runs)
+ *    may fall back to a cloud SDK's chain. Those SDKs are optional peers,
+ *    imported lazily by name, so chant's install and bundle do not grow for
+ *    people who never index; their absence is a clear error naming the
+ *    package.
+ *
+ * The lister itself reads no environment variable. `chant index` (chant#4532)
+ * turns its flags into these targets.
+ */
+export declare class ListerConfigError extends Error {
+    constructor(message: string);
+}
+export interface AwsStaticCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+}
+/** The SDK chains a real-cloud run may use; replaced in tests so a test can prove none was touched. */
+export interface CredentialChains {
+    aws(): Promise<AwsStaticCredentials>;
+    azure(): Promise<string>;
+    gcp(): Promise<string>;
+}
+export declare const sdkCredentialChains: CredentialChains;
+export declare function resolveAwsCredentials(target: {
+    endpoint?: string;
+    credentials?: AwsStaticCredentials;
+}, chains: CredentialChains): Promise<AwsStaticCredentials>;
+export declare function resolveAzureToken(target: {
+    endpoint?: string;
+    token?: string;
+}, chains: CredentialChains): Promise<string>;
+/** `null` is an explicit anonymous call (floci-gcp with IAM enforcement off). */
+export declare function resolveGcpToken(target: {
+    endpoint?: string;
+    token?: string | null;
+}, chains: CredentialChains): Promise<string | null>;
+//# sourceMappingURL=credentials.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../../src/cloud-lister/credentials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,uGAAuG;AACvG,MAAM,WAAW,gBAAgB;IAC/B,GAAG,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACrC,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACzB,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACxB;AAcD,eAAO,MAAM,mBAAmB,EAAE,gBAqBjC,CAAC;AAEF,wBAAsB,qBAAqB,CACzC,MAAM,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,oBAAoB,CAAA;CAAE,EACjE,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,oBAAoB,CAAC,CAM/B;AAED,wBAAsB,iBAAiB,CACrC,MAAM,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EAC7C,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,MAAM,CAAC,CAMjB;AAED,iFAAiF;AACjF,wBAAsB,eAAe,CACnC,MAAM,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EACpD,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAMxB"}

package/dist/cloud-lister/credentials.js

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

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

@@ -0,0 +1,27 @@
+/**
+ * behold#1029: test doubles for the lister. Nothing here opens a socket: a
+ * fake fetcher answers from a route function and throws on any call it was
+ * not given an answer for, and fake credential chains count their calls so a
+ * test can show none was touched.
+ */
+import type { WireCall } from "./guard.js";
+import type { CredentialChains } from "./credentials.js";
+import type { Fetcher, WireResponse } from "./transport.js";
+export declare function json(status: number, body: unknown, headers?: Record<string, string>): WireResponse;
+export interface FakeFetcher {
+    fetcher: Fetcher;
+    calls: WireCall[];
+}
+export declare function fakeFetcher(route: (call: WireCall) => WireResponse | undefined): FakeFetcher;
+export interface CountingChains extends CredentialChains {
+    count: {
+        aws: number;
+        azure: number;
+        gcp: number;
+    };
+}
+/** Chains that fail if used; `count` says how often each was asked. */
+export declare function refusingChains(): CountingChains;
+/** A fixed clock that advances one second per reading, so timestamps are predictable. */
+export declare function steppingClock(start?: string): () => Date;
+//# sourceMappingURL=fakes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fakes.d.ts","sourceRoot":"","sources":["../../src/cloud-lister/fakes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEzD,wBAAgB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAAG,YAAY,CAEtG;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,YAAY,GAAG,SAAS,GAAG,WAAW,CAW5F;AAED,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACtD,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CACpD;AAED,uEAAuE;AACvE,wBAAgB,cAAc,IAAI,cAAc,CAiB/C;AAED,yFAAyF;AACzF,wBAAgB,aAAa,CAAC,KAAK,SAAyB,GAAG,MAAM,IAAI,CAOxE"}

package/dist/cloud-lister/fakes.js

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

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

@@ -0,0 +1,42 @@
+/**
+ * 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 { type ListerContext } from "./common.js";
+import { type CredentialChains } from "./credentials.js";
+import { type TlsOptions, type WireResponse } from "./transport.js";
+export interface GcpTarget {
+    /** An emulator's Cloud Asset base, e.g. `http://localhost:4588/cloudasset`. Absent means `https://cloudasset.googleapis.com`. */
+    endpoint?: string;
+    /** An OAuth access token; `null` sends none (an emulator with IAM enforcement off). Required with an endpoint. */
+    token?: string | null;
+    tls?: TlsOptions;
+}
+export declare function enableCommand(project: string): string;
+export declare function searchUrl(target: GcpTarget, project: string, params: {
+    assetTypes?: readonly string[];
+    query?: string;
+    pageToken?: string;
+}): string;
+/** The `query` for a tag filter, or undefined. Exported for tests. */
+export declare function labelQuery(filter: Readonly<Record<string, string>> | undefined): string | undefined;
+export declare function isServiceDisabled(res: WireResponse): boolean;
+export declare function listGcp(ctx: ListerContext, target: GcpTarget, chains: CredentialChains, retryDelays?: readonly number[]): Promise<void>;
+//# sourceMappingURL=gcp.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gcp.d.ts","sourceRoot":"","sources":["../../src/cloud-lister/gcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAmF,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAC/H,OAAO,EAAsC,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC1F,OAAO,EAAY,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3E,MAAM,WAAW,SAAS;IACxB,iIAAiI;IACjI,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kHAAkH;IAClH,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,GAAG,CAAC,EAAE,UAAU,CAAC;CAClB;AAOD,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE;IAAE,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAQpJ;AAED,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CASnG;AAoBD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAI5D;AAED,wBAAsB,OAAO,CAC3B,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,gBAAgB,EACxB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAC9B,OAAO,CAAC,IAAI,CAAC,CA+Df"}

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"}