@intentius/chant 0.52.2 → 0.53.1

package/src/cli/main.ts

@@ -23,14 +23,14 @@ import { runCarveAdvise, runCarveUnknown } from "./handlers/carve";
 import { runCarveEmit } from "./handlers/carve-emit";
 import { runCarveBridge } from "./handlers/carve-bridge";
 import { runCarveApply } from "./handlers/carve-apply";
-import { runLifecycleSnapshot, runLifecycleShow, runLifecycleDiff, runLifecycleRollback, runLifecyclePlan, runLifecycleAffected, runLifecycleLog, runLifecycleTeardown, runLifecycleUnknown } from "./handlers/lifecycle";
+import { runLifecycleSnapshot, runLifecycleShow, runLifecycleDiff, runLifecycleRollback, runLifecyclePlan, runLifecycleAffected, runLifecycleLog, runLifecycleTeardown, runLifecycleWhoami, runLifecycleUnknown } from "./handlers/lifecycle";
 import { runComponentsStatus, runComponentsReleaseRecord, runComponentsExport, runComponentsUnknown } from "./handlers/components";
 import { runScenarioCheck, runScenarioUnknown } from "./handlers/scenario";
 import { runGraph } from "./handlers/graph";
 import { runExplain } from "./handlers/explain";
 import { runSearch } from "./handlers/search";
 import { runOp, runOpList, runOpStatus, runOpSignal, runOpCancel, runOpLog } from "./handlers/run";
-import { runOperator, runOperatorStatus, runApprove } from "./handlers/operator";
+import { runOperator, runOperatorStatus, runOperatorLog, runApprove } from "./handlers/operator";
 import { runEmulator } from "./handlers/emulator";
 import { splitJoinedFlags, dispatchCommandGroup, collectCommandGroups, formatCommandGroupsHelp, type CommandGroup } from "./command-group";
 import type { LexiconPlugin } from "../lexicon";
@@ -388,6 +388,16 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.once = true;
     } else if (arg === "--note") {
       result.note = args[++i];
+    } else if (arg === "--url") {
+      result.url = args[++i];
+    } else if (arg === "--op") {
+      result.op = args[++i];
+    } else if (arg === "--since") {
+      result.since = args[++i];
+    } else if (arg === "--limit") {
+      // Parsed here, validated by the handler — `parseArgs` reports shape, not
+      // policy, the same split every other value flag here uses.
+      result.limit = Number(args[++i]);
     } else if (arg.startsWith("--")) {
       // chant #1127 — every recognized flag is matched above; anything left
       // starting with `--` is unrecognized, whether it arrived bare
@@ -461,10 +471,12 @@ Commands:
                          --all-projects)
   migrate <file>        Translate a workflow between lexicons
                         (default: --from github --to gitlab)
-  carve advise          Read-only Terraform peelability advisor: rank which
-                        --from <tf-dir>   resources are cheap to carve into native chant
+  carve advise          Read-only peelability advisor: rank which resources
+                        --from <dir>      are cheap to carve into native chant
                         (--json, --report <path>). Emits nothing, changes nothing.
-                        Needs @cdktf/hcl2json (npm install -D @cdktf/hcl2json).
+                        --from a Terraform dir needs @cdktf/hcl2json
+                        (npm install -D @cdktf/hcl2json); --from a CDK cloud
+                        assembly (cdk.out) needs nothing and ranks constructs.
   carve emit            Adopt a selected TF resource into chant source + report
                         --from <tf-dir>   its boundary. --state <tfstate> adopts offline
                         --select <addr>   (recommended for TF-managed resources); --env
@@ -522,11 +534,21 @@ Ops:
                         ConvergeOp, read from the chant/lifecycle orphan
                         branch alone — no daemon needs to be running
                         (--env <env>, --json)
+  operator log           Converge tick history and the gate resolutions
+                        against it, merged into one timestamp-ordered
+                        timeline, from the same orphan branch (--env <env>,
+                        --op <name>, --since <iso>, --limit <n>, --json).
+                        --json also carries the count of ledger lines that
+                        were unreadable, so a short timeline is never
+                        silently short
   approve <op> <gate>    Record a gate's out-of-band resolution fact
-                        (--actor <name>, --note <text>) — the durable
-                        counterpart to a converge tick's gate-as-fact
-                        outcome; see the pending-gates list in operator
-                        status. Does not itself unblock the gated op's local
+                        (--actor <name>, --note <text>, --url <url>) — the
+                        durable counterpart to a converge tick's
+                        gate-as-fact outcome; see the pending-gates list in
+                        operator status. --url is the PR/MR the resolution
+                        happened at, recorded typed rather than as free text,
+                        and defaults to the PR/MR of the surrounding CI job.
+                        Does not itself unblock the gated op's local
                         dispatch (re-run --temporal, or merge its PR)
 
   graph                 Show Op dependency graph (--stacks for cross-stack order,
@@ -556,6 +578,9 @@ Lifecycle (alias: lc):
   lifecycle plan <env>      Typed change set (create/update/delete/adopt) vs live
   lifecycle affected        Stacks a change affects (--base <ref> [--include-dependents])
                             --json: emit the ChangeSet as JSON
+  lifecycle whoami <env>    Who chant would act as in each configured lexicon,
+                            and what that principal is scoped to — read-only,
+                            before anything acts (--json, --strict)
   lifecycle teardown <env>  Plan what deleting the environment would remove —
                             marker-scoped (this project's stack + env); --yes
                             executes the plan (production-like names also need
@@ -646,7 +671,8 @@ Options:
   --from <name>         Source lexicon for migrate (default: github)
   --to <name>           Target lexicon for migrate (default: gitlab)
   --emit <fmt>          Migration output format: yaml (default) or ts
-  --strict              Escalate needs-review/validation to errors (migrate)
+  --strict              Escalate needs-review/validation to errors (migrate);
+                        exit nonzero on an unresolved identity (lifecycle whoami)
   --validate            Run external validator (glci/glab) after migrate
   --use-composites      Rewrite to composite calls when patterns match (migrate)
   --components          Target discovered Component declarations instead of
@@ -869,6 +895,7 @@ const registry: CommandDef[] = [
   { name: "run", handler: runOp },
 
   { name: "operator status", handler: runOperatorStatus },
+  { name: "operator log", handler: runOperatorLog },
   { name: "operator", handler: runOperator },
   { name: "approve", handler: runApprove },
 
@@ -882,6 +909,7 @@ const registry: CommandDef[] = [
   { name: "lifecycle rollback", handler: runLifecycleRollback },
   { name: "lifecycle plan", requiresPlugins: true, handler: runLifecyclePlan },
   { name: "lifecycle affected", requiresPlugins: true, handler: runLifecycleAffected },
+  { name: "lifecycle whoami", requiresPlugins: true, handler: runLifecycleWhoami },
   { name: "lifecycle teardown", requiresPlugins: true, handler: runLifecycleTeardown },
   { name: "lifecycle log", handler: runLifecycleLog },
 

package/src/cli/registry.ts

@@ -285,8 +285,16 @@ export interface ParsedArgs {
   leaseTtl?: string;
   /** `chant operator --once` (#1485) — run a single round and exit, instead of looping until Ctrl-C. Also the offline test/cron-invoker story. */
   once?: boolean;
-  /** `chant approve <op> <gate> --note <text>` (#1485) — optional free-text context recorded on the gate-resolution fact (e.g. a PR URL). */
+  /** `chant approve <op> <gate> --note <text>` (#1485) — optional free-text prose recorded on the gate-resolution fact. The PR link belongs in `--url` since #2028; this is for everything that isn't the link. */
   note?: string;
+  /** `chant operator log --op <name>` (#2029) — restrict the tick history to one ConvergeOp by name. Omitted, every discovered ConvergeOp's ticks are merged into one timeline. */
+  op?: string;
+  /** `chant operator log --since <iso>` (#2029) — only entries at or after this ISO-8601 instant. */
+  since?: string;
+  /** `chant operator log --limit <n>` (#2029) — keep only the newest n entries (still printed oldest-first). */
+  limit?: number;
+  /** `chant approve <op> <gate> --url <url>` (#2028) — the address this resolution happened at (the PR/MR that carried the change), recorded typed on the gate-resolution fact so a reader is not sniffing `--note` for something link-shaped. Defaults to the PR/MR the surrounding CI job is for, when there is one. Must be an absolute http/https URL. */
+  url?: string;
 }
 
 /**

package/src/identity.test.ts

@@ -0,0 +1,199 @@
+import { describe, test, expect } from "vitest";
+import {
+  describeIdentities,
+  identityRowFor,
+  identityStatusText,
+  isUnresolvedIdentity,
+  redactCredentialMaterial,
+  redactIdentityRow,
+  REDACTED,
+  type IdentityPlugin,
+} from "./identity";
+
+describe("the identity tri-state (#1982)", () => {
+  test("a lexicon with no describeIdentity is not-reported, never an empty identity", async () => {
+    const rows = await describeIdentities([{ name: "github" }], { environment: "prod" }, {});
+    expect(rows).toEqual([{ lexicon: "github", status: "not-reported" }]);
+    expect(rows[0].identity).toBeUndefined();
+    expect(identityStatusText(rows[0])).toContain("not reported");
+  });
+
+  test("a resolved identity carries principal, scope, source and endpoint", async () => {
+    const plugin: IdentityPlugin = {
+      name: "aws",
+      describeIdentity: async () => ({
+        identity: "arn:aws:sts::491500000000:assumed-role/deploy/ci",
+        scope: "491500000000 us-east-1",
+        source: "env AWS_ACCESS_KEY_ID",
+        endpoint: "https://sts.us-east-1.amazonaws.com/",
+      }),
+    };
+    const [row] = await describeIdentities([plugin], { environment: "prod" }, {});
+    expect(row).toEqual({
+      lexicon: "aws",
+      status: "reported",
+      identity: "arn:aws:sts::491500000000:assumed-role/deploy/ci",
+      scope: "491500000000 us-east-1",
+      source: "env AWS_ACCESS_KEY_ID",
+      endpoint: "https://sts.us-east-1.amazonaws.com/",
+    });
+  });
+
+  test("no credentials and could-not-determine are distinguishable answers", async () => {
+    const rows = await describeIdentities(
+      [
+        { name: "aws", describeIdentity: async () => ({ unresolved: { reason: "no-credentials" } }) },
+        {
+          name: "k8s",
+          describeIdentity: async () => ({ unresolved: { reason: "read-failed", detail: "connection refused" } }),
+        },
+      ],
+      { environment: "prod" },
+      {},
+    );
+    expect(rows[0]).toEqual({ lexicon: "aws", status: "unresolved", reason: "no-credentials" });
+    expect(identityStatusText(rows[0])).toContain("no identity is configured");
+    expect(rows[1]).toEqual({
+      lexicon: "k8s",
+      status: "unresolved",
+      reason: "read-failed",
+      detail: "connection refused",
+    });
+    expect(identityStatusText(rows[1])).toContain("self-query failed");
+    // The point of the distinction: "nothing is configured" and "I could not
+    // find out" must never render as the same row.
+    expect(identityStatusText(rows[0])).not.toBe(identityStatusText(rows[1]));
+  });
+
+  test("an empty principal is refused rather than reported as an identity", () => {
+    const row = identityRowFor("gcp", { identity: "   ", scope: "acme-prod", source: "ADC" }, {});
+    expect(row.status).toBe("unresolved");
+    expect(row.reason).toBe("read-failed");
+    expect(row.identity).toBeUndefined();
+  });
+
+  test("a lexicon that throws degrades to read-failed and never fails the run", async () => {
+    const rows = await describeIdentities(
+      [
+        {
+          name: "azure",
+          describeIdentity: async () => {
+            throw new Error("az CLI is not installed");
+          },
+        },
+        { name: "aws", describeIdentity: async () => ({ identity: "arn:x", scope: "s", source: "env" }) },
+      ],
+      { environment: "prod" },
+      {},
+    );
+    expect(rows[0]).toEqual({
+      lexicon: "azure",
+      status: "unresolved",
+      reason: "read-failed",
+      detail: "az CLI is not installed",
+    });
+    expect(rows[1].status).toBe("reported");
+  });
+
+  test("rows come back in the order the lexicons were configured", async () => {
+    const names = ["k8s", "aws", "gcp", "github"];
+    const rows = await describeIdentities(
+      names.map((name) => ({ name })),
+      { environment: "prod" },
+      {},
+    );
+    expect(rows.map((r) => r.lexicon)).toEqual(names);
+  });
+
+  test("the environment, region and cwd reach the lexicon unchanged", async () => {
+    const seen: unknown[] = [];
+    await describeIdentities(
+      [
+        {
+          name: "aws",
+          describeIdentity: async (options) => {
+            seen.push(options);
+            return { identity: "arn:x", scope: "s", source: "env" };
+          },
+        },
+      ],
+      { environment: "prod", region: "eu-west-1", cwd: "/repo" },
+      {},
+    );
+    expect(seen).toEqual([{ environment: "prod", region: "eu-west-1", cwd: "/repo" }]);
+  });
+
+  test("isUnresolvedIdentity discriminates the two return shapes", () => {
+    expect(isUnresolvedIdentity({ unresolved: { reason: "no-binding" } })).toBe(true);
+    expect(isUnresolvedIdentity({ identity: "a", scope: "b", source: "c" })).toBe(false);
+  });
+});
+
+describe("no credential reaches the output (#1982)", () => {
+  test("a value held in a credential-named env var is redacted wherever it appears", () => {
+    const env = { GITHUB_TOKEN: "ghp_averyrealtokenvalue", HOME: "/Users/x" };
+    expect(redactCredentialMaterial("authorized by ghp_averyrealtokenvalue", env)).toBe(
+      `authorized by ${REDACTED}`,
+    );
+  });
+
+  test("every free-text field of a row is scrubbed, not just the identity", () => {
+    const env = { AWS_SECRET_ACCESS_KEY: "wJalrXUtnFEMIsecretKEY" };
+    const row = redactIdentityRow(
+      {
+        lexicon: "aws",
+        status: "reported",
+        identity: "wJalrXUtnFEMIsecretKEY",
+        scope: "wJalrXUtnFEMIsecretKEY",
+        source: "signed with wJalrXUtnFEMIsecretKEY",
+        endpoint: "https://sts.amazonaws.com/?k=wJalrXUtnFEMIsecretKEY",
+        detail: "wJalrXUtnFEMIsecretKEY",
+      },
+      env,
+    );
+    for (const field of [row.identity, row.scope, row.source, row.endpoint, row.detail]) {
+      expect(field).not.toContain("wJalrXUtnFEMIsecretKEY");
+      expect(field).toContain(REDACTED);
+    }
+  });
+
+  test("a short env value is not treated as a credential", () => {
+    // Redacting "dev" out of every identity would be worse than the leak.
+    expect(redactCredentialMaterial("cluster dev-a", { AUTH_TOKEN: "dev" })).toBe("cluster dev-a");
+  });
+
+  test("literal credential shapes are redacted with no env var involved", () => {
+    const jwt = "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIn0.dBjftJeZ4CVPmB92K27u";
+    expect(redactCredentialMaterial(jwt, {})).toBe(REDACTED);
+    expect(redactCredentialMaterial("Bearer abcdefghijklmnopqrstuvwxyz012345", {})).toBe(REDACTED);
+    expect(
+      redactCredentialMaterial("-----BEGIN RSA PRIVATE KEY-----\nAAAA\n-----END RSA PRIVATE KEY-----", {}),
+    ).toBe(REDACTED);
+  });
+
+  test("real principals survive redaction unchanged", () => {
+    // A mangled principal is a wrong answer, not a safe one. Nothing here is
+    // entropy-scored, so these pass through whole.
+    const env = { AWS_SESSION_TOKEN: "FwoGZXIvYXdzEBYaDLONGSESSIONTOKEN" };
+    for (const principal of [
+      "arn:aws:sts::491500000000:assumed-role/deploy/ci",
+      "system:serviceaccount:chant:deployer",
+      "deploy@acme.iam.gserviceaccount.com",
+      "https://prod-eks-a.eu-west-1.eks.amazonaws.com",
+      "491500000000 us-east-1",
+    ]) {
+      expect(redactCredentialMaterial(principal, env)).toBe(principal);
+    }
+  });
+
+  test("an identity built out of the session token is redacted, not printed", () => {
+    const env = { AWS_SESSION_TOKEN: "FwoGZXIvYXdzEBYaDLONGSESSIONTOKEN" };
+    const row = identityRowFor(
+      "aws",
+      { identity: "FwoGZXIvYXdzEBYaDLONGSESSIONTOKEN", scope: "us-east-1", source: "env" },
+      env,
+    );
+    expect(row.identity).toBe(REDACTED);
+    expect(row.identity).not.toContain("FwoGZXIvYXdz");
+  });
+});

package/src/identity.ts

@@ -0,0 +1,346 @@
+/**
+ * The identity contract (#1982) — which principal chant would act as in each
+ * substrate, reported before it acts.
+ *
+ * Every native observer already resolves this. `ObserverAdapter.bind()`
+ * (./observation.ts) reaches the provider on the applier's own transport, the
+ * k8s connector resolves a kubeconfig context and says which binding produced
+ * it, the aws read client resolves a region and an endpoint. All of it is
+ * discarded. The only way the answer has ever surfaced is as an `unobserved`
+ * entry with reason `no-credentials`, or — worse — as a successful read
+ * against the wrong account.
+ *
+ * A project spanning aws, k8s, gcp and github reaches four substrates with
+ * four credential sets, and nothing says which identity each one resolves to.
+ * `chant lifecycle whoami <env>` asks each configured lexicon that question
+ * and prints one row per lexicon.
+ *
+ * ## The tri-state
+ *
+ * The same discipline the observation contract draws between "absent" and
+ * "not observed" applies here, because the same mistake is available: an empty
+ * identity reads as "nobody", and "nobody" is not what "I could not find out"
+ * means.
+ *
+ *   - **REPORTED** — the lexicon asked the substrate and it answered. A
+ *     principal, a scope, and where the binding came from.
+ *   - **UNRESOLVED** — the lexicon tried and could not, carrying a total
+ *     {@link UnobservedReason}. `no-credentials` is "no identity is
+ *     configured"; `no-binding` and `read-failed` are "could not determine".
+ *     Those are different answers and the reason keeps them apart.
+ *   - **NOT REPORTED** — the lexicon implements no {@link
+ *     import("./lexicon").LexiconPlugin.describeIdentity}. It answers for
+ *     nothing, which is honest; it is never rendered as an empty identity.
+ *
+ * ## Read-only, and never a gate
+ *
+ * `whoami` mutates nothing and blocks nothing. It exits 0 whatever the rows
+ * say unless the caller asks for a non-zero exit on an unresolved row with
+ * `--strict`. A lexicon's implementation is held to the same rule: a self-query
+ * that reaches the substrate must be one the substrate treats as a read of the
+ * caller's own identity.
+ *
+ * ## No credential ever reaches the output
+ *
+ * An identity is a principal and a scope — an account id, a project, an org, a
+ * cluster context, a service-account name. It is never a token, a key, a
+ * password or a certificate. The rule is on the lexicon: report the fact, not
+ * the value, and where a substrate's only identity signal IS a secret, say so
+ * without it.
+ *
+ * {@link redactCredentialMaterial} is the backstop core applies to every field
+ * of every row regardless, not a license to be careless. It is deliberately
+ * structural rather than heuristic — it redacts what the process actually
+ * holds in a credential-shaped environment variable, plus the three literal
+ * shapes (PEM block, JWT, `Bearer …`) that no principal string can be — so an
+ * account id, an ARN and a `system:serviceaccount:…` subject survive it intact.
+ */
+
+import type { UnobservedReason } from "./observation";
+
+/** The identity one lexicon resolved, and the scope it resolves to. */
+export interface ResolvedIdentity {
+  /**
+   * The principal, as the substrate names it — an STS ARN, a
+   * `system:serviceaccount:<ns>:<name>` subject, a service-account email. Never
+   * a credential.
+   */
+  identity: string;
+  /**
+   * What that principal is scoped to here — an account id plus region, a
+   * cluster context, a project, an org. The half that answers "acting on
+   * WHAT", which is where a wrong-account read is actually visible.
+   */
+  scope: string;
+  /**
+   * Where the binding came from, in the project's own vocabulary:
+   * `k8s.profiles.prod.context`, `AWS_PROFILE`, `ADC`, `stacks[].region`. An
+   * identity with no provenance cannot be corrected by whoever reads it.
+   */
+  source: string;
+  /**
+   * The resolved address the self-query was issued against. Must be the address
+   * this lexicon's live read resolves for the same environment — a whoami that
+   * reports a binding the read does not use is worse than no whoami.
+   */
+  endpoint?: string;
+}
+
+/** Why one lexicon could not resolve an identity. Total, and reason-typed. */
+export interface UnresolvedIdentity {
+  /**
+   * Total verdict, from the same set an unobservable entity uses.
+   * `no-credentials` — nothing is configured to act as. `no-binding` — the
+   * environment resolves to no concrete target. `read-failed` — the substrate
+   * was reached and the self-query errored.
+   */
+  reason: UnobservedReason;
+  /** Human-readable detail: the call that failed, the missing binding key. */
+  detail?: string;
+}
+
+/**
+ * What `describeIdentity()` may return: the resolved identity, or a typed
+ * refusal. Discriminated by the `unresolved` key, the same shape
+ * {@link import("./observation").EntityObservation} uses.
+ */
+export type DescribeIdentityResult = ResolvedIdentity | { unresolved: UnresolvedIdentity };
+
+/** True when a lexicon answered with a typed refusal rather than an identity. */
+export function isUnresolvedIdentity(
+  value: DescribeIdentityResult,
+): value is { unresolved: UnresolvedIdentity } {
+  return typeof value === "object" && value !== null && "unresolved" in value;
+}
+
+/** The tri-state, as one row's verdict. */
+export type IdentityStatus = "reported" | "unresolved" | "not-reported";
+
+/** One lexicon's answer, normalized — the unit `whoami` renders and `--json` emits. */
+export interface IdentityRow {
+  lexicon: string;
+  status: IdentityStatus;
+  /** REPORTED only. */
+  identity?: string;
+  /** REPORTED only. */
+  scope?: string;
+  /** REPORTED only. */
+  source?: string;
+  /** REPORTED only, and only when the lexicon named one. */
+  endpoint?: string;
+  /** UNRESOLVED only. */
+  reason?: UnobservedReason;
+  /** UNRESOLVED only, when the lexicon supplied one. */
+  detail?: string;
+}
+
+/** What core hands a lexicon's `describeIdentity`. */
+export interface DescribeIdentityOptions {
+  environment: string;
+  /**
+   * The region the environment's stacks declare, when they declare exactly one
+   * (`stacks[].region`, #1261). Omitted when they declare none or disagree, in
+   * which case the lexicon resolves the region its own read path would.
+   */
+  region?: string;
+  /** Project root whose `chant.config.ts` carries the binding. Defaults to cwd. */
+  cwd?: string;
+}
+
+/** The subset of a plugin this module needs — narrower than importing the whole contract. */
+export interface IdentityPlugin {
+  name: string;
+  describeIdentity?(options: DescribeIdentityOptions): Promise<DescribeIdentityResult>;
+}
+
+/** The marker a redacted field carries. Fixed text so a consumer can match it. */
+export const REDACTED = "[redacted]";
+
+/**
+ * Environment variables whose VALUE is credential material. Matched on the
+ * name, so a lexicon that echoes one of these into an identity string has the
+ * value removed before it is printed or serialized.
+ */
+const CREDENTIAL_ENV_NAME =
+  /(SECRET|TOKEN|PASSWORD|PASSWD|CREDENTIAL|PRIVATE_KEY|APIKEY|API_KEY|ACCESS_KEY|SESSION_KEY|AUTH)/i;
+
+/** Shortest env value worth redacting. Below this a "secret" is a false positive. */
+const MIN_CREDENTIAL_LENGTH = 8;
+
+/**
+ * Literal credential shapes. Each is something a principal string cannot be,
+ * so matching one is proof rather than a guess.
+ */
+const CREDENTIAL_SHAPES: RegExp[] = [
+  // A PEM block of any key type.
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+  // A JWT: three base64url segments, the first starting with the `{"` header.
+  /\beyJ[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]*/g,
+  // An `Authorization`-style scheme plus its value.
+  /\b(?:Bearer|Basic)\s+[A-Za-z0-9\-._~+/]{16,}={0,2}/g,
+];
+
+/**
+ * Strip credential material from one reported field.
+ *
+ * Two rules, both structural. Any value this process holds in a
+ * credential-named environment variable is replaced wherever it appears, which
+ * covers the realistic accident — a lexicon echoing `$GITHUB_TOKEN` or
+ * `$AWS_SECRET_ACCESS_KEY` into a `source`. And the three literal shapes above
+ * are replaced on sight.
+ *
+ * Nothing is entropy-scored, so an ARN, an account id, a service-account email
+ * and a cluster context name pass through unchanged — which matters, because a
+ * mangled principal is a wrong answer, not a safe one.
+ */
+export function redactCredentialMaterial(
+  value: string,
+  env: Record<string, string | undefined> = process.env,
+): string {
+  let out = value;
+  for (const [name, secret] of Object.entries(env)) {
+    if (!secret || secret.length < MIN_CREDENTIAL_LENGTH) continue;
+    if (!CREDENTIAL_ENV_NAME.test(name)) continue;
+    if (!out.includes(secret)) continue;
+    out = out.split(secret).join(REDACTED);
+  }
+  for (const shape of CREDENTIAL_SHAPES) out = out.replace(shape, REDACTED);
+  return out;
+}
+
+/** Apply {@link redactCredentialMaterial} to every free-text field of a row. */
+export function redactIdentityRow(
+  row: IdentityRow,
+  env: Record<string, string | undefined> = process.env,
+): IdentityRow {
+  const clean = (v: string | undefined): string | undefined =>
+    v === undefined ? undefined : redactCredentialMaterial(v, env);
+  return {
+    ...row,
+    ...(row.identity !== undefined ? { identity: clean(row.identity) } : {}),
+    ...(row.scope !== undefined ? { scope: clean(row.scope) } : {}),
+    ...(row.source !== undefined ? { source: clean(row.source) } : {}),
+    ...(row.endpoint !== undefined ? { endpoint: clean(row.endpoint) } : {}),
+    ...(row.detail !== undefined ? { detail: clean(row.detail) } : {}),
+  };
+}
+
+/**
+ * Normalize one lexicon's answer into a row.
+ *
+ * Every degradation lands somewhere honest. No method at all is NOT REPORTED.
+ * A throw is UNRESOLVED with `read-failed` — the lexicon reached for the
+ * substrate and something broke, which is a different claim from having no
+ * credentials. An answer that carries no identity string is UNRESOLVED too: a
+ * lexicon cannot report an empty principal, because an empty principal renders
+ * as "acting as nobody", and nobody is a claim.
+ */
+export function identityRowFor(
+  lexicon: string,
+  result: DescribeIdentityResult | undefined,
+  env: Record<string, string | undefined> = process.env,
+): IdentityRow {
+  if (result === undefined) return { lexicon, status: "not-reported" };
+  if (isUnresolvedIdentity(result)) {
+    return redactIdentityRow(
+      {
+        lexicon,
+        status: "unresolved",
+        reason: result.unresolved.reason,
+        ...(result.unresolved.detail ? { detail: result.unresolved.detail } : {}),
+      },
+      env,
+    );
+  }
+  if (!result.identity || result.identity.trim() === "") {
+    return {
+      lexicon,
+      status: "unresolved",
+      reason: "read-failed",
+      detail: "the lexicon reported an identity with no principal in it",
+    };
+  }
+  return redactIdentityRow(
+    {
+      lexicon,
+      status: "reported",
+      identity: result.identity,
+      scope: result.scope,
+      source: result.source,
+      ...(result.endpoint ? { endpoint: result.endpoint } : {}),
+    },
+    env,
+  );
+}
+
+/**
+ * Ask every plugin who it would act as. One call per lexicon, concurrently,
+ * in the order the plugins were configured so the report is stable.
+ *
+ * A plugin that throws never fails the run: the throw becomes that lexicon's
+ * UNRESOLVED row. Reporting is the whole point, and a report that aborts on
+ * the first broken substrate is exactly the report nobody can use.
+ */
+export async function describeIdentities(
+  plugins: readonly IdentityPlugin[],
+  options: DescribeIdentityOptions,
+  env: Record<string, string | undefined> = process.env,
+): Promise<IdentityRow[]> {
+  return Promise.all(
+    plugins.map(async (plugin): Promise<IdentityRow> => {
+      if (!plugin.describeIdentity) return { lexicon: plugin.name, status: "not-reported" };
+      try {
+        return identityRowFor(plugin.name, await plugin.describeIdentity(options), env);
+      } catch (err) {
+        return identityRowFor(
+          plugin.name,
+          {
+            unresolved: {
+              reason: "read-failed",
+              detail: err instanceof Error ? err.message : String(err),
+            },
+          },
+          env,
+        );
+      }
+    }),
+  );
+}
+
+/**
+ * A row's verdict as one short cell, for the IDENTITY column. Deliberately
+ * without the `detail`, which is a sentence and belongs under the table rather
+ * than inside a column every other row has to be padded to.
+ */
+export function identityStatusText(row: IdentityRow): string {
+  switch (row.status) {
+    case "reported":
+      return row.identity ?? "";
+    case "unresolved":
+      return `could not determine — ${unresolvedReasonText(row.reason)}`;
+    case "not-reported":
+      return "not reported — this lexicon does not answer for an identity";
+  }
+}
+
+/**
+ * Why an identity did not resolve, in words. Deliberately distinct from
+ * `unobservedReasonText`: `no-credentials` here means "no identity is
+ * configured for this substrate", which is an answer, not a failure to look.
+ */
+export function unresolvedReasonText(reason: UnobservedReason | undefined): string {
+  switch (reason) {
+    case "no-credentials":
+      return "no identity is configured for this substrate";
+    case "no-binding":
+      return "this environment resolves to no target";
+    case "read-failed":
+      return "the substrate was reached and the self-query failed";
+    case "unsupported-kind":
+      return "the substrate exposes no self-query";
+    case "filtered":
+      return "withheld";
+    default:
+      return "no reason given";
+  }
+}