@intentius/chant 0.124.51 → 0.124.54

package/src/cloud-lister/aws.ts

@@ -0,0 +1,226 @@
+/**
+ * behold#1029: AWS, through Cloud Control `ListResources`, one call (and its
+ * pages) per type and region.
+ *
+ * Cloud Control lists one type at a time, so `types: "*"` lists
+ * {@link DEFAULT_AWS_TYPES} and says so in a note; every other type is left
+ * without a coverage entry, which reads as not observed. Regions must be
+ * named: listing "every region" would need a call outside the allowlist.
+ * Global types (IAM, CloudFront, Route 53, Organizations, Global Accelerator)
+ * are listed once, from us-east-1, with location `global`.
+ *
+ * A tag filter is applied to the listed objects here, because
+ * `ListResources` takes none: a filtered run costs the same calls as a full
+ * one (#1029's listing-cost note).
+ *
+ * The pinned floci (ghcr.io/lex00/floci, source c688f52ee) serves
+ * `ListResources` with no paging and answers a type it does not model with an
+ * empty list rather than an error, so on floci an empty `listed` entry is
+ * weaker evidence than on AWS. See behold#1029's emulator comment.
+ */
+
+import { buildResource, describeFailure, listedVerdict, noteTagFilter, withThrottleRetry, type ListerContext } from "./common";
+import { resolveAwsCredentials, ListerConfigError, type AwsStaticCredentials, type CredentialChains } from "./credentials";
+import { signV4 } from "./sigv4";
+import { jsonBody, type TlsOptions, type WireResponse } from "./transport";
+import type { CloudId } from "./types";
+
+export interface AwsTarget {
+  /** An emulator's endpoint, e.g. `http://localhost:4566`. Absent means AWS's own regional endpoint. */
+  endpoint?: string;
+  credentials?: AwsStaticCredentials;
+  tls?: TlsOptions;
+}
+
+/** What `types: "*"` lists: common types Cloud Control lists without a parent identifier. */
+export const DEFAULT_AWS_TYPES: readonly string[] = [
+  "AWS::CloudFront::Distribution",
+  "AWS::DynamoDB::Table",
+  "AWS::EC2::Instance",
+  "AWS::EC2::InternetGateway",
+  "AWS::EC2::LaunchTemplate",
+  "AWS::EC2::NatGateway",
+  "AWS::EC2::RouteTable",
+  "AWS::EC2::SecurityGroup",
+  "AWS::EC2::Subnet",
+  "AWS::EC2::VPC",
+  "AWS::ECR::Repository",
+  "AWS::ECS::Cluster",
+  "AWS::EKS::Cluster",
+  "AWS::ElasticLoadBalancingV2::LoadBalancer",
+  "AWS::Events::EventBus",
+  "AWS::IAM::InstanceProfile",
+  "AWS::IAM::ManagedPolicy",
+  "AWS::IAM::Role",
+  "AWS::IAM::User",
+  "AWS::KMS::Key",
+  "AWS::Lambda::Function",
+  "AWS::Logs::LogGroup",
+  "AWS::RDS::DBCluster",
+  "AWS::RDS::DBInstance",
+  "AWS::Route53::HostedZone",
+  "AWS::S3::Bucket",
+  "AWS::SNS::Topic",
+  "AWS::SQS::Queue",
+  "AWS::SecretsManager::Secret",
+  "AWS::StepFunctions::StateMachine",
+];
+
+const GLOBAL_TYPE_PREFIXES = ["AWS::IAM::", "AWS::CloudFront::", "AWS::Route53::", "AWS::Organizations::", "AWS::GlobalAccelerator::"];
+
+export function isGlobalAwsType(type: string): boolean {
+  return GLOBAL_TYPE_PREFIXES.some((p) => type.startsWith(p));
+}
+
+const GLOBAL_SIGNING_REGION = "us-east-1";
+const MAX_PAGES = 1000;
+
+export function cloudControlUrl(target: AwsTarget, region: string): string {
+  if (target.endpoint !== undefined) return new URL("/", target.endpoint).toString();
+  return `https://cloudcontrolapi.${region}.amazonaws.com/`;
+}
+
+interface AwsError {
+  code: string;
+  message: string;
+}
+
+function awsError(res: WireResponse): AwsError {
+  const body = jsonBody(res) as Record<string, unknown> | undefined;
+  const raw = String(body?.__type ?? body?.code ?? res.headers["x-amzn-errortype"] ?? "");
+  const code = raw.includes("#") ? raw.slice(raw.lastIndexOf("#") + 1) : raw.split(":")[0];
+  const message = String(body?.message ?? body?.Message ?? "");
+  return { code, message };
+}
+
+const CREDENTIAL_CODES = /^(AccessDenied|AccessDeniedException|UnrecognizedClientException|InvalidClientTokenId|ExpiredToken|ExpiredTokenException|InvalidSignatureException|SignatureDoesNotMatch|MissingAuthenticationToken)$/;
+
+function tagsOf(props: Record<string, unknown>): Record<string, string> {
+  const raw = props.Tags;
+  const out: Record<string, string> = {};
+  if (Array.isArray(raw)) {
+    for (const t of raw) {
+      if (t && typeof t === "object") {
+        const o = t as Record<string, unknown>;
+        if (typeof o.Key === "string") out[o.Key] = String(o.Value ?? "");
+      }
+    }
+  } else if (raw && typeof raw === "object") {
+    for (const [k, v] of Object.entries(raw as Record<string, unknown>)) out[k] = String(v ?? "");
+  }
+  return out;
+}
+
+function matchesTagFilter(tags: Record<string, string>, filter: Readonly<Record<string, string>> | undefined): boolean {
+  if (!filter) return true;
+  return Object.entries(filter).every(([k, v]) => tags[k] === v);
+}
+
+export async function listAws(
+  ctx: ListerContext,
+  target: AwsTarget,
+  chains: CredentialChains,
+  retryDelays?: readonly number[],
+): Promise<void> {
+  const { scope } = ctx;
+  if (scope.locations === "*") {
+    throw new ListerConfigError("aws needs its regions named: listing every region would need ec2:DescribeRegions, which the lister does not call");
+  }
+  const credentials = await resolveAwsCredentials(target, chains);
+  let types: readonly string[];
+  if (scope.types === "*") {
+    types = DEFAULT_AWS_TYPES;
+    ctx.notes.push({
+      code: "default-types",
+      message: `Cloud Control lists one type per call, so types "*" listed ${DEFAULT_AWS_TYPES.length} default types; every other type has no coverage entry and reads as not observed. Name the types to list others.`,
+    });
+  } else {
+    types = scope.types;
+  }
+  noteTagFilter(ctx, "to the listed objects, after a full ListResources per type (Cloud Control takes no tag filter)");
+
+  for (const type of types) {
+    const global = isGlobalAwsType(type);
+    const regions = global ? [GLOBAL_SIGNING_REGION] : scope.locations;
+    for (const region of regions) {
+      const location = global ? "global" : region;
+      await listOne(ctx, target, credentials, type, region, location, retryDelays);
+    }
+  }
+}
+
+async function listOne(
+  ctx: ListerContext,
+  target: AwsTarget,
+  credentials: AwsStaticCredentials,
+  type: string,
+  region: string,
+  location: string,
+  retryDelays?: readonly number[],
+): Promise<void> {
+  const url = cloudControlUrl(target, region);
+  let nextToken: string | undefined;
+  const found: Parameters<typeof buildResource>[1][] = [];
+  for (let page = 0; page < MAX_PAGES; page++) {
+    const body = JSON.stringify({ TypeName: type, MaxResults: 100, ...(nextToken ? { NextToken: nextToken } : {}) });
+    const send = () => {
+      const headers = signV4({
+        method: "POST",
+        url,
+        headers: { "content-type": "application/x-amz-json-1.0", "x-amz-target": "CloudApiService.ListResources" },
+        body,
+        region,
+        service: "cloudcontrolapi",
+        credentials,
+        now: ctx.now(),
+      });
+      return ctx.transport.send({ substrate: "aws", method: "POST", url, headers, body });
+    };
+    const res = await withThrottleRetry(send, (r) => r.status === 429 || (r.status >= 400 && /Throttl/.test(awsError(r).code)), retryDelays);
+    const observedAt = ctx.now().toISOString();
+    if (res.status >= 400) {
+      recordFailure(ctx, type, location, res);
+      return;
+    }
+    const parsed = jsonBody(res) as { ResourceDescriptions?: Array<{ Identifier?: string; Properties?: string }>; NextToken?: string } | undefined;
+    for (const d of parsed?.ResourceDescriptions ?? []) {
+      if (!d.Identifier) continue;
+      let props: Record<string, unknown> = {};
+      try {
+        const p = typeof d.Properties === "string" ? JSON.parse(d.Properties) : d.Properties;
+        if (p && typeof p === "object") props = p as Record<string, unknown>;
+      } catch {
+        props = {};
+      }
+      const tags = tagsOf(props);
+      if (!matchesTagFilter(tags, ctx.scope.tagFilter)) continue;
+      const cloudIds: CloudId[] = [];
+      if (d.Identifier.startsWith("arn:")) cloudIds.push({ kind: "arn", value: d.Identifier });
+      if (typeof props.Arn === "string" && props.Arn.startsWith("arn:")) cloudIds.push({ kind: "arn", value: props.Arn });
+      cloudIds.push({ kind: "import-id", value: d.Identifier });
+      found.push({ listedType: type, location, nativeId: d.Identifier, cloudIds, tags, properties: props, observedAt, labels: false });
+    }
+    nextToken = parsed?.NextToken || undefined;
+    if (!nextToken) break;
+  }
+  for (const r of found) ctx.resources.push(buildResource(ctx, r));
+  ctx.coverage.push({ listedType: type, location, ...listedVerdict(ctx.scope) });
+}
+
+function recordFailure(ctx: ListerContext, type: string, location: string, res: WireResponse): void {
+  const err = awsError(res);
+  const detail = describeFailure(res, err.code, err.message);
+  if (err.code === "UnsupportedActionException" || err.code === "TypeNotFoundException") {
+    ctx.coverage.push({ listedType: type, location, verdict: "unsupported-kind", detail });
+    ctx.notes.push({ code: "no-lister", listedType: type, location, message: `Cloud Control cannot list ${type}: ${detail}` });
+  } else if (err.code === "InvalidRequestException" && /ResourceModel|parent/i.test(err.message)) {
+    ctx.coverage.push({ listedType: type, location, verdict: "unsupported-kind", detail: `type needs a parent identifier: ${detail}` });
+    ctx.notes.push({ code: "needs-parent", listedType: type, location, message: `${type} lists only under a parent identifier (a ResourceModel), which an account-wide listing does not have: ${detail}` });
+  } else if (res.status === 401 || res.status === 403 || CREDENTIAL_CODES.test(err.code)) {
+    ctx.coverage.push({ listedType: type, location, verdict: "no-credentials", detail });
+    ctx.notes.push({ code: "no-credentials", listedType: type, location, message: `the credentials cannot call cloudformation:ListResources for ${type}: ${detail}` });
+  } else {
+    ctx.coverage.push({ listedType: type, location, verdict: "read-failed", detail });
+    ctx.notes.push({ code: "read-failed", listedType: type, location, message: `ListResources for ${type} in ${location} failed: ${detail}` });
+  }
+}

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

@@ -0,0 +1,132 @@
+/**
+ * behold#1029: the Azure lister against a fake Resource Graph. Shapes follow
+ * the pinned floci-az's docs/services/resource-graph.md (source 7f079c2):
+ * `{ totalRecords, count, data, facets, resultTruncated }`, `$skipToken`
+ * for the next page, `type` lowercase.
+ */
+import { describe, expect, it } from "vitest";
+import { listCloud } from "./index";
+import { resourceGraphQuery } from "./azure";
+import { ListerConfigError } from "./credentials";
+import { MASKED } from "./mask";
+import { fakeFetcher, json, refusingChains, steppingClock } from "./fakes";
+
+const SUB = "00000000-0000-0000-0000-000000000001";
+const ENDPOINT = "https://localhost:4577";
+const ID_A = `/subscriptions/${SUB}/resourceGroups/RG-Web/providers/Microsoft.Storage/storageAccounts/webassets`;
+const ID_B = `/subscriptions/${SUB}/resourceGroups/rg-web/providers/Microsoft.KeyVault/vaults/kv1`;
+
+describe("the Resource Graph query", () => {
+  it("narrows by type, location and tag, and orders by id", () => {
+    const q = resourceGraphQuery({
+      substrate: "azure",
+      scopeId: SUB,
+      types: ["microsoft.storage/storageaccounts"],
+      locations: ["eastus"],
+      tagFilter: { "tofu-estate": "web" },
+    });
+    expect(q).toBe(
+      [
+        "Resources",
+        "| where type in~ ('microsoft.storage/storageaccounts')",
+        "| where location in~ ('eastus')",
+        "| where tags['tofu-estate'] == 'web'",
+        "| project id, name, type, kind, location, resourceGroup, subscriptionId, managedBy, tags, sku, plan, identity, zones, extendedLocation, properties",
+        "| order by id asc",
+      ].join("\n"),
+    );
+  });
+
+  it("adds resource groups for every type", () => {
+    expect(resourceGraphQuery({ substrate: "azure", scopeId: SUB, types: "*", locations: "*" }).split("\n")[0]).toBe(
+      "Resources | union (ResourceContainers | where type =~ 'microsoft.resources/subscriptions/resourcegroups')",
+    );
+  });
+
+  it("refuses a value that could change the query", () => {
+    expect(() => resourceGraphQuery({ substrate: "azure", scopeId: SUB, types: ["x') | union (Secrets"], locations: "*" })).toThrow(ListerConfigError);
+  });
+});
+
+describe("listing azure", () => {
+  it("pages and fills the listing-result shape", async () => {
+    const fake = fakeFetcher((call) => {
+      const body = JSON.parse(call.body ?? "{}");
+      expect(body.subscriptions).toEqual([SUB]);
+      if (!body.options.$skipToken) {
+        return json(200, {
+          totalRecords: 2,
+          count: 1,
+          data: [{ id: ID_A, name: "webassets", type: "microsoft.storage/storageaccounts", location: "eastus", tags: { "chant-managed-by": "chant", "chant-stack": "web" }, properties: { primaryEndpoints: {} } }],
+          $skipToken: "1",
+        });
+      }
+      return json(200, {
+        totalRecords: 2,
+        count: 1,
+        data: [{ id: ID_B, name: "kv1", type: "microsoft.keyvault/vaults", location: "EastUS", tags: {}, properties: { adminPassword: "p@ss", connectionString: "Server=x" } }],
+      });
+    });
+    const result = await listCloud(
+      { substrate: "azure", scopeId: SUB, types: "*", locations: "*" },
+      { substrate: "azure", azure: { endpoint: ENDPOINT, token: "static-token" } },
+      { fetcher: fake.fetcher, chains: refusingChains(), now: steppingClock(), retryDelays: [] },
+    );
+    expect(fake.calls.length).toBe(2);
+    expect(fake.calls[0].url).toBe(`${ENDPOINT}/providers/Microsoft.ResourceGraph/resources?api-version=2022-10-01`);
+    expect(fake.calls[0].headers.authorization).toBe("Bearer static-token");
+
+    const sa = result.resources.find((r) => r.nativeId === ID_A)!;
+    expect(sa.id).toBe(`azure/${SUB}/eastus/microsoft.storage%2Fstorageaccounts/${ID_A}`);
+    expect(sa.cloudIds).toEqual([
+      { kind: "provider-id", value: ID_A },
+      { kind: "provider-id", value: ID_A.toLowerCase() },
+    ]);
+    expect(sa.facts.markers).toEqual({ owner: "web", encoding: "plain", source: "live" });
+    expect(sa.properties).not.toHaveProperty("tags");
+
+    const kv = result.resources.find((r) => r.nativeId === ID_B)!;
+    expect(kv.location).toBe("eastus");
+    expect((kv.properties.properties as Record<string, unknown>).adminPassword).toBe(MASKED);
+    expect((kv.properties.properties as Record<string, unknown>).connectionString).toBe(MASKED);
+
+    expect(result.coverage).toEqual([{ listedType: "*", location: "*", verdict: "listed" }]);
+  });
+
+  it("covers each named type and location", async () => {
+    const fake = fakeFetcher(() => json(200, { data: [] }));
+    const result = await listCloud(
+      { substrate: "azure", scopeId: SUB, types: ["Microsoft.Storage/storageAccounts", "microsoft.keyvault/vaults"], locations: ["westus", "eastus"] },
+      { substrate: "azure", azure: { endpoint: ENDPOINT, token: "t" } },
+      { fetcher: fake.fetcher, chains: refusingChains(), now: steppingClock(), retryDelays: [] },
+    );
+    expect(result.coverage.map((c) => `${c.listedType}@${c.location}:${c.verdict}`)).toEqual([
+      "microsoft.keyvault/vaults@eastus:listed",
+      "microsoft.keyvault/vaults@westus:listed",
+      "microsoft.storage/storageaccounts@eastus:listed",
+      "microsoft.storage/storageaccounts@westus:listed",
+    ]);
+  });
+
+  it("reports a refused token as no-credentials", async () => {
+    const fake = fakeFetcher(() => json(401, { error: { code: "InvalidAuthenticationToken", message: "The access token is invalid." } }));
+    const result = await listCloud(
+      { substrate: "azure", scopeId: SUB, types: "*", locations: "*" },
+      { substrate: "azure", azure: { endpoint: ENDPOINT, token: "bad" } },
+      { fetcher: fake.fetcher, chains: refusingChains(), now: steppingClock(), retryDelays: [] },
+    );
+    expect(result.resources).toEqual([]);
+    expect(result.coverage).toEqual([{ listedType: "*", location: "*", verdict: "no-credentials", detail: "HTTP 401: InvalidAuthenticationToken: The access token is invalid." }]);
+    expect(result.notes[0].code).toBe("no-credentials");
+  });
+
+  it("never asks DefaultAzureCredential when an endpoint is given", async () => {
+    const chains = refusingChains();
+    const fake = fakeFetcher(() => undefined);
+    await expect(
+      listCloud({ substrate: "azure", scopeId: SUB, types: "*", locations: "*" }, { substrate: "azure", azure: { endpoint: ENDPOINT } }, { fetcher: fake.fetcher, chains }),
+    ).rejects.toThrow(/needs a static bearer token/);
+    expect(chains.count.azure).toBe(0);
+    expect(fake.calls).toEqual([]);
+  });
+});

package/src/cloud-lister/azure.ts

@@ -0,0 +1,142 @@
+/**
+ * behold#1029: Azure, through Resource Graph: one KQL query per run, paged,
+ * over the `Resources` table and the subscription's resource groups.
+ *
+ * Resource Graph answers for every ARM type with one call shape, so coverage
+ * is the scope's own types and locations, each `listed` (or `filtered` under
+ * a tag filter, which goes into the query). Types are the lowercase ARM types
+ * Resource Graph returns (`microsoft.storage/storageaccounts`).
+ *
+ * Every value that goes into the query (types, locations, tag keys and
+ * values) is checked against a plain character set rather than escaped, so a
+ * scope can never change the query's shape.
+ *
+ * The pinned floci-az (ghcr.io/lex00/floci-az, source 7f079c2) serves this
+ * call: `POST /providers/Microsoft.ResourceGraph/resources`, the KQL subset
+ * used here (`where`, `in~`, `union`, `project`, `order by`), and
+ * `$top`/`$skipToken` paging (docs/services/resource-graph.md).
+ */
+
+import { buildResource, describeFailure, listedVerdict, noteTagFilter, withThrottleRetry, type ListerContext } from "./common";
+import { resolveAzureToken, ListerConfigError, type CredentialChains } from "./credentials";
+import { jsonBody, type TlsOptions, type WireResponse } from "./transport";
+import type { CloudId } from "./types";
+
+export interface AzureTarget {
+  /** An emulator's ARM endpoint, e.g. `https://localhost:4577`. Absent means `https://management.azure.com`. */
+  endpoint?: string;
+  /** A bearer token for ARM. Required with an endpoint. */
+  token?: string;
+  tls?: TlsOptions;
+}
+
+export const RESOURCE_GRAPH_API_VERSION = "2022-10-01";
+const RESOURCE_GROUP_TYPE = "microsoft.resources/subscriptions/resourcegroups";
+const PAGE_SIZE = 1000;
+const MAX_PAGES = 10_000;
+const SAFE = /^[A-Za-z0-9._\-\/: ]+$/;
+
+function safe(what: string, value: string): string {
+  if (!SAFE.test(value)) throw new ListerConfigError(`azure ${what} ${JSON.stringify(value)} has characters a Resource Graph query does not take from a flag`);
+  return value;
+}
+
+function list(values: readonly string[], what: string): string {
+  return values.map((v) => `'${safe(what, v)}'`).join(", ");
+}
+
+/** The KQL for a scope. Exported for tests. */
+export function resourceGraphQuery(scope: ListerContext["scope"]): string {
+  const lines: string[] = [];
+  const wantsGroups = scope.types === "*" || scope.types.some((t) => t.toLowerCase() === RESOURCE_GROUP_TYPE);
+  lines.push(wantsGroups ? `Resources | union (ResourceContainers | where type =~ '${RESOURCE_GROUP_TYPE}')` : "Resources");
+  if (scope.types !== "*") lines.push(`| where type in~ (${list(scope.types, "type")})`);
+  if (scope.locations !== "*") lines.push(`| where location in~ (${list(scope.locations, "location")})`);
+  for (const [k, v] of Object.entries(scope.tagFilter ?? {})) {
+    lines.push(`| where tags['${safe("tag key", k)}'] == '${safe("tag value", v)}'`);
+  }
+  lines.push("| project id, name, type, kind, location, resourceGroup, subscriptionId, managedBy, tags, sku, plan, identity, zones, extendedLocation, properties");
+  lines.push("| order by id asc");
+  return lines.join("\n");
+}
+
+export function resourceGraphUrl(target: AzureTarget): string {
+  const base = target.endpoint ?? "https://management.azure.com";
+  const url = new URL("/providers/Microsoft.ResourceGraph/resources", base);
+  url.searchParams.set("api-version", RESOURCE_GRAPH_API_VERSION);
+  return url.toString();
+}
+
+function azureError(res: WireResponse): { code: string; message: string } {
+  const body = jsonBody(res) as { error?: { code?: string; message?: string } } | undefined;
+  return { code: body?.error?.code ?? "", message: body?.error?.message ?? "" };
+}
+
+export async function listAzure(
+  ctx: ListerContext,
+  target: AzureTarget,
+  chains: CredentialChains,
+  retryDelays?: readonly number[],
+): Promise<void> {
+  const { scope } = ctx;
+  safe("subscription", scope.scopeId);
+  const query = resourceGraphQuery(scope);
+  const token = await resolveAzureToken(target, chains);
+  const url = resourceGraphUrl(target);
+  noteTagFilter(ctx, "in the Resource Graph query");
+
+  const typesCovered = scope.types === "*" ? ["*"] : [...scope.types].map((t) => t.toLowerCase());
+  const locationsCovered = scope.locations === "*" ? ["*"] : [...scope.locations].map((l) => l.toLowerCase());
+  const found: Parameters<typeof buildResource>[1][] = [];
+  let skipToken: string | undefined;
+  for (let page = 0; page < MAX_PAGES; page++) {
+    const body = JSON.stringify({
+      subscriptions: [scope.scopeId],
+      query,
+      options: { $top: PAGE_SIZE, resultFormat: "objectArray", ...(skipToken ? { $skipToken: skipToken } : {}) },
+    });
+    const send = () =>
+      ctx.transport.send({
+        substrate: "azure",
+        method: "POST",
+        url,
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+        body,
+      });
+    const res = await withThrottleRetry(send, (r) => r.status === 429, retryDelays);
+    const observedAt = ctx.now().toISOString();
+    if (res.status >= 400) {
+      const err = azureError(res);
+      const detail = describeFailure(res, err.code, err.message);
+      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: `Resource Graph query on subscription ${scope.scopeId} failed: ${detail}`,
+      });
+      return;
+    }
+    const parsed = jsonBody(res) as { data?: unknown; $skipToken?: string } | undefined;
+    const rows = Array.isArray(parsed?.data) ? (parsed!.data as Array<Record<string, unknown>>) : [];
+    for (const row of rows) {
+      const id = typeof row.id === "string" ? row.id : undefined;
+      if (!id) continue;
+      const type = String(row.type ?? "").toLowerCase();
+      const loc = String(row.location ?? "").toLowerCase() || "global";
+      const tags: Record<string, string> = {};
+      if (row.tags && typeof row.tags === "object") {
+        for (const [k, v] of Object.entries(row.tags as Record<string, unknown>)) tags[k] = String(v ?? "");
+      }
+      const { tags: _tags, ...properties } = row;
+      const cloudIds: CloudId[] = [
+        { kind: "provider-id", value: id },
+        { kind: "provider-id", value: id.toLowerCase() },
+      ];
+      found.push({ listedType: type, location: loc, nativeId: id, cloudIds, tags, properties, observedAt, labels: false });
+    }
+    skipToken = parsed?.$skipToken || undefined;
+    if (!skipToken) 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/src/cloud-lister/common.ts

@@ -0,0 +1,115 @@
+/**
+ * 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";
+import { readMarkers } from "./markers";
+import { maskProperties, maskTags } from "./mask";
+import type { Transport, WireResponse } from "./transport";
+import type { CloudId, CloudScope, CoverageEntry, IndexNote, ListedResource } from "./types";
+
+export interface ListerContext {
+  scope: CloudScope;
+  transport: Transport;
+  now: () => Date;
+  resources: ListedResource[];
+  coverage: CoverageEntry[];
+  notes: IndexNote[];
+}
+
+export 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 {
+  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: CloudId[]): CloudId[] {
+  const seen = new Set<string>();
+  const out: CloudId[] = [];
+  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: CloudScope): Pick<CoverageEntry, "verdict" | "detail"> {
+  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: ListerContext, how: string): void {
+  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: ListerContext): void {
+  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: WireResponse, code?: string, message?: string): string {
+  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: number) => new Promise<void>((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: () => Promise<WireResponse>,
+  isThrottled: (res: WireResponse) => boolean,
+  delays: readonly number[] = [500, 2000, 5000],
+): Promise<WireResponse> {
+  let res = await send();
+  for (const d of delays) {
+    if (!isThrottled(res)) return res;
+    await sleep(d);
+    res = await send();
+  }
+  return res;
+}