@intentius/chant-lexicon-sql 0.124.52 → 0.124.55

package/src/token-source-traded.test.ts

@@ -0,0 +1,75 @@
+/**
+ * #4572: in a CI job that traded its OIDC token through chant's
+ * ci.identity, the cloud token sources mint from what the trade left, and
+ * run no cloud command line. Test values only; nothing reaches a cloud.
+ */
+
+import { describe, expect, test } from "vitest";
+import { AZURE_DATABASE_TOKEN_ENV as CORE_AZURE_DATABASE_TOKEN_ENV } from "@intentius/chant/ci-identity";
+import { AZURE_DATABASE_TOKEN_ENV, credentialSource, tradedToken, TokenSourceError, type RunCommand } from "./token-source";
+
+const RDS_URL = "postgres://db.abc123.eu-west-1.rds.amazonaws.com:5433/shop";
+const AWS = { AWS_ACCESS_KEY_ID: "AKIDEXAMPLE", AWS_SECRET_ACCESS_KEY: "secret", AWS_SESSION_TOKEN: "session", AWS_REGION: "eu-west-1" };
+const NOW = new Date("2026-10-27T12:00:00Z");
+
+describe("tradedToken", () => {
+  test("rds-iam presigns connect for the host, port and user with the traded keys", () => {
+    const token = tradedToken({ token: "rds-iam" }, { url: RDS_URL, user: "app", env: AWS }, NOW)!;
+    expect(token.startsWith("db.abc123.eu-west-1.rds.amazonaws.com:5433/?")).toBe(true);
+    const q = new URLSearchParams(token.slice(token.indexOf("?") + 1));
+    expect(q.get("Action")).toBe("connect");
+    expect(q.get("DBUser")).toBe("app");
+    expect(q.get("X-Amz-Credential")).toBe("AKIDEXAMPLE/20261027/eu-west-1/rds-db/aws4_request");
+    expect(q.get("X-Amz-Expires")).toBe("900");
+    expect(q.get("X-Amz-Security-Token")).toBe("session");
+    expect(q.get("X-Amz-Signature")).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  test("rds-iam without traded keys falls through to the command line", () => {
+    expect(tradedToken({ token: "rds-iam" }, { url: RDS_URL, user: "app", env: {} }, NOW)).toBeUndefined();
+  });
+
+  test("rds-iam with keys still needs a user and a region", () => {
+    expect(() => tradedToken({ token: "rds-iam" }, { url: RDS_URL, env: AWS }, NOW)).toThrow(TokenSourceError);
+    const { AWS_REGION: _r, ...noRegion } = AWS;
+    expect(() => tradedToken({ token: "rds-iam" }, { url: "postgres://db.internal/shop", user: "app", env: noRegion }, NOW)).toThrow(/region/);
+  });
+
+  test("cloud-sql-iam is the traded Google access token", () => {
+    expect(tradedToken({ token: "cloud-sql-iam" }, { url: "postgres://10.0.0.3/shop", env: { GOOGLE_OAUTH_ACCESS_TOKEN: "ya29.x" } })).toBe("ya29.x");
+    expect(tradedToken({ token: "cloud-sql-iam" }, { url: "postgres://10.0.0.3/shop", env: { CLOUDSDK_AUTH_ACCESS_TOKEN: "ya29.y" } })).toBe("ya29.y");
+    expect(tradedToken({ token: "cloud-sql-iam" }, { url: "postgres://10.0.0.3/shop", env: {} })).toBeUndefined();
+  });
+
+  test("entra is the database token, never the ARM one", () => {
+    expect(tradedToken({ token: "entra" }, { url: "postgres://x.postgres.database.azure.com/shop", env: { [AZURE_DATABASE_TOKEN_ENV]: "eyJdb" } })).toBe("eyJdb");
+    expect(tradedToken({ token: "entra" }, { url: "postgres://x.postgres.database.azure.com/shop", env: { AZURE_ACCESS_TOKEN: "eyJarm" } })).toBeUndefined();
+  });
+
+  test("command never takes a traded token", () => {
+    expect(tradedToken({ token: "command", command: ["./mint.sh"] }, { url: "postgres://x/shop", env: AWS })).toBeUndefined();
+  });
+
+  test("the variable is the one core's trade sets", () => {
+    expect(AZURE_DATABASE_TOKEN_ENV).toBe(CORE_AZURE_DATABASE_TOKEN_ENV);
+  });
+});
+
+describe("credentialSource with a traded identity", () => {
+  test("mints without running a command, and caches", async () => {
+    let ran = 0;
+    const run: RunCommand = async () => {
+      ran += 1;
+      return "from-cli";
+    };
+    const src = credentialSource({ token: "cloud-sql-iam" }, { url: "postgres://10.0.0.3/shop", env: { GOOGLE_OAUTH_ACCESS_TOKEN: "ya29.x" }, source: "sql.profiles.prod.password", run });
+    expect(await src.get()).toBe("ya29.x");
+    expect(await src.get()).toBe("ya29.x");
+    expect(ran).toBe(0);
+  });
+
+  test("runs the command line when the job traded nothing", async () => {
+    const src = credentialSource({ token: "entra" }, { url: "postgres://x/shop", env: {}, source: "sql.profiles.prod.password", run: async () => "from-az\n" });
+    expect(await src.get()).toBe("from-az");
+  });
+});

package/src/token-source.ts

@@ -21,6 +21,22 @@
  * - `entra`: `az account get-access-token` for Azure Database for PostgreSQL.
  * - `command`: any command that prints a password on its standard output.
  *
+ * In a CI job that traded its OIDC token through chant's `ci.identity`
+ * (`@intentius/chant/ci-identity`, #4296, #4572), the cloud sources mint
+ * from what the trade left instead, with no cloud command line in the
+ * image ({@link tradedToken}):
+ *
+ * - `rds-iam` presigns the token with the traded AWS keys
+ *   (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`),
+ *   through chant's SigV4 signer, as `aws rds generate-db-auth-token` does.
+ * - `cloud-sql-iam` is the traded Google access token
+ *   (`GOOGLE_OAUTH_ACCESS_TOKEN`), which Cloud SQL's IAM sign-in takes.
+ * - `entra` is `AZURE_DATABASE_ACCESS_TOKEN`, which the trade sets with
+ *   `ci.identity.cloud.azure.database`. The ARM token it always sets is
+ *   for another scope, so without `database` `entra` still runs `az`.
+ *
+ * Outside CI none of these variables is set and the command lines run.
+ *
  * A token is reused until most of its lifetime has passed and minted again
  * after, so a long apply, whose ClickHouse requests each carry the password
  * and whose Postgres connections each authenticate when opened, never sends
@@ -29,6 +45,7 @@
 
 import { execFile } from "node:child_process";
 import { z } from "zod";
+import { presignV4 } from "@intentius/chant/cloud-lister/sigv4";
 
 const ttl = z.number().int().positive().optional();
 
@@ -104,6 +121,56 @@ export interface CredentialSource {
   invalidate(): void;
 }
 
+/** The variable chant's trade sets to an Azure Database for PostgreSQL token (`AZURE_DATABASE_TOKEN_ENV` in `@intentius/chant/ci-identity`, #4572). */
+export const AZURE_DATABASE_TOKEN_ENV = "AZURE_DATABASE_ACCESS_TOKEN";
+
+/** The region an `rds-iam` token is signed for: the config's, `AWS_REGION`, `AWS_DEFAULT_REGION`, else the RDS host name's. */
+function rdsRegion(config: { region?: string }, hostname: string, env: Record<string, string | undefined>): string | undefined {
+  return config.region ?? env.AWS_REGION ?? env.AWS_DEFAULT_REGION ?? /\.([a-z]{2}(?:-[a-z]+)+-\d+)\.rds\.amazonaws\.com$/.exec(hostname)?.[1];
+}
+
+/**
+ * The token a cloud source takes from chant's traded identity (#4572), when
+ * the job's environment holds it; undefined otherwise, and for `command`.
+ * Pure but for `now`, for tests.
+ */
+export function tradedToken(
+  config: TokenSourceConfig,
+  input: { url: string; user?: string; env: Record<string, string | undefined> },
+  now: Date = new Date(),
+): string | undefined {
+  const env = input.env;
+  switch (config.token) {
+    case "command":
+      return undefined;
+    case "cloud-sql-iam":
+      return env.GOOGLE_OAUTH_ACCESS_TOKEN || env.CLOUDSDK_AUTH_ACCESS_TOKEN || undefined;
+    case "entra":
+      return env[AZURE_DATABASE_TOKEN_ENV] || undefined;
+    case "rds-iam": {
+      const accessKeyId = env.AWS_ACCESS_KEY_ID;
+      const secretAccessKey = env.AWS_SECRET_ACCESS_KEY;
+      if (!accessKeyId || !secretAccessKey) return undefined;
+      if (input.user === undefined) throw new TokenSourceError("rds-iam mints a token for one database user; the profile names no user");
+      const url = new URL(input.url);
+      const region = rdsRegion(config, url.hostname, env);
+      if (region === undefined) throw new TokenSourceError(`rds-iam signs its token for a region; set the token source's region or AWS_REGION for ${url.hostname}`);
+      const target = new URL(`https://${url.hostname}:${url.port || "5432"}/`);
+      target.searchParams.set("Action", "connect");
+      target.searchParams.set("DBUser", input.user);
+      const signed = presignV4({
+        url: target.toString(),
+        region,
+        service: "rds-db",
+        credentials: { accessKeyId, secretAccessKey, ...(env.AWS_SESSION_TOKEN ? { sessionToken: env.AWS_SESSION_TOKEN } : {}) },
+        seconds: DEFAULT_TTL_SECONDS["rds-iam"],
+        now,
+      });
+      return signed.replace(/^https:\/\//, "");
+    }
+  }
+}
+
 /** The program a source runs. Pure, for tests. */
 export function tokenCommand(
   config: TokenSourceConfig,
@@ -119,7 +186,7 @@ export function tokenCommand(
     case "rds-iam": {
       const url = new URL(input.url);
       if (input.user === undefined) throw new TokenSourceError("rds-iam mints a token for one database user; the profile names no user");
-      const region = config.region ?? input.env.AWS_REGION ?? input.env.AWS_DEFAULT_REGION ?? /\.([a-z]{2}(?:-[a-z]+)+-\d+)\.rds\.amazonaws\.com$/.exec(url.hostname)?.[1];
+      const region = rdsRegion(config, url.hostname, input.env);
       return [
         "aws",
         "rds",
@@ -158,6 +225,12 @@ export function credentialSource(
   let cached: { token: string; until: number } | undefined;
   let pending: Promise<string> | undefined;
   const mint = async (): Promise<string> => {
+    // #4572: a CI job that traded its OIDC token through chant mints from what the trade left.
+    const traded = tradedToken(config, input, new Date(now()));
+    if (traded !== undefined) {
+      cached = { token: traded, until: now() + lifetimeMs };
+      return traded;
+    }
     const argv = tokenCommand(config, input);
     let out: string;
     try {

package/src/yodel-run.ts

@@ -0,0 +1,175 @@
+/**
+ * Running sql-yodeler's versioned migration engine (`yodel`) for the sql
+ * lexicon's `sql-migrate` capability (#4569). The ruling on
+ * sql-yodeler#285 (A) keeps the engine in sql-yodeler and has chant run it
+ * through a fixed argv list, the way the pulumi lexicon runs plunge
+ * (`lexicons/pulumi/src/run.ts`). {@link YODEL_COMMANDS} is that list, and
+ * {@link runAllowedYodel} refuses any argv off it before it reaches the
+ * runner, so no later caller can make this module run another yodel verb.
+ *
+ * The three commands, each the engine's own entry point:
+ *
+ * - `yodel plan <env> --part <file>`: the pending migrations as a chant
+ *   change-set part (sql-yodeler#237, built by this lexicon's
+ *   `sqlVersionedPlanPart`), one entry per object with its change classes.
+ *   Reads only.
+ * - `yodel apply <env> --wave-plan <file> --spec <spec>`: the wave plan the
+ *   op wave's gate binds. Its digest covers the migrations' digest, the
+ *   environment's gate policy at the base commit, whether a pending step is
+ *   destructive, and the promotion evidence. Reads only.
+ * - `yodel apply <env> --wave-apply <file> --spec <spec>`: applies that
+ *   plan under the engine's lock. The engine plans again under the lock and
+ *   refuses a plan that moved, and it checks chant's decision for the wave
+ *   and the gate ledger's approval itself (ruling A on sql-yodeler#300).
+ *
+ * Each may carry, in this order and no other, `--dir <project>`, `--op
+ * <name>` and `--allow-out-of-order`. A value must not start with a dash.
+ *
+ * ## Credentials
+ *
+ * The two planning commands run with the writer taken out of their
+ * environment ({@link readerEnv}): no `YODEL_ROLE` or `YODEL_CREDENTIALS`,
+ * which pick the writer, and no `<ENV>_<DIALECT>_WRITER_USER` or
+ * `..._WRITER_PASSWORD`, the writer's default variables. Only the apply runs
+ * with the job's environment as given, so the writer reaches the apply
+ * alone even when one job plans and applies.
+ *
+ * The runner is injectable, so the tests run no binary.
+ */
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+/** What one yodel run gave. Never thrown: a non-zero exit is a `code`. */
+export interface YodelRun {
+  /** The exit status; null when the process did not exit by itself or never started. */
+  code: number | null;
+  stdout: string;
+  stderr: string;
+  /** No yodel binary was found. */
+  missingBinary?: boolean;
+}
+
+/** Runs yodel with these arguments in `cwd`, with `env`. Injectable so tests need no binary. */
+export type YodelRunner = (args: string[], opts: { cwd: string; env: NodeJS.ProcessEnv; dir?: string }) => Promise<YodelRun>;
+
+/**
+ * The only yodel commands chant runs (ruling A on sql-yodeler#285). Each
+ * may be followed by `--dir <project>`, `--op <name>` and
+ * `--allow-out-of-order`, in that order ({@link YODEL_OPTIONAL_FLAGS}).
+ */
+export const YODEL_COMMANDS: readonly string[] = [
+  "yodel plan <env> --part <file>",
+  "yodel apply <env> --wave-plan <file> --spec <spec>",
+  "yodel apply <env> --wave-apply <file> --spec <spec>",
+];
+
+/** The flags any of {@link YODEL_COMMANDS} may end with, in this order. */
+export const YODEL_OPTIONAL_FLAGS: readonly string[] = ["--dir <project>", "--op <name>", "--allow-out-of-order"];
+
+/** The options every command takes. */
+export interface YodelCommonOptions {
+  /** The yodel project directory, passed as `--dir`. */
+  dir?: string;
+  /** The migrations Op, when more than one applies the environment. */
+  op?: string;
+  allowOutOfOrder?: boolean;
+}
+
+function common(opts: YodelCommonOptions): string[] {
+  return [...(opts.dir ? ["--dir", opts.dir] : []), ...(opts.op ? ["--op", opts.op] : []), ...(opts.allowOutOfOrder ? ["--allow-out-of-order"] : [])];
+}
+
+/** `yodel plan <env> --part <file>`, without the binary. */
+export function yodelPlanArgs(env: string, part: string, opts: YodelCommonOptions = {}): string[] {
+  return ["plan", env, "--part", part, ...common(opts)];
+}
+
+/** `yodel apply <env> --wave-plan <file> --spec <spec>`, without the binary. */
+export function yodelWavePlanArgs(env: string, file: string, spec: string, opts: YodelCommonOptions = {}): string[] {
+  return ["apply", env, "--wave-plan", file, "--spec", spec, ...common(opts)];
+}
+
+/** `yodel apply <env> --wave-apply <file> --spec <spec>`, without the binary. */
+export function yodelWaveApplyArgs(env: string, file: string, spec: string, opts: YodelCommonOptions = {}): string[] {
+  return ["apply", env, "--wave-apply", file, "--spec", spec, ...common(opts)];
+}
+
+/** A value after a flag: present, and not itself a flag. */
+const value = (v: string | undefined): boolean => typeof v === "string" && v.length > 0 && !v.startsWith("-");
+
+/** The optional tail: `--dir <d>`, `--op <n>`, `--allow-out-of-order`, each at most once, in that order. */
+function allowedTail(rest: readonly string[]): boolean {
+  let i = 0;
+  if (rest[i] === "--dir") {
+    if (!value(rest[i + 1])) return false;
+    i += 2;
+  }
+  if (rest[i] === "--op") {
+    if (!value(rest[i + 1])) return false;
+    i += 2;
+  }
+  if (rest[i] === "--allow-out-of-order") i += 1;
+  return i === rest.length;
+}
+
+/** Whether `args` is one of {@link YODEL_COMMANDS} with an allowed tail. */
+export function allowedYodelArgv(args: readonly string[]): boolean {
+  if (!value(args[1])) return false;
+  if (args[0] === "plan") return args[2] === "--part" && value(args[3]) && allowedTail(args.slice(4));
+  if (args[0] === "apply") {
+    return (args[2] === "--wave-plan" || args[2] === "--wave-apply") && value(args[3]) && args[4] === "--spec" && value(args[5]) && allowedTail(args.slice(6));
+  }
+  return false;
+}
+
+/** Whether `args` is the apply, the one command that writes. */
+export function isYodelApplyArgv(args: readonly string[]): boolean {
+  return args[0] === "apply" && args[2] === "--wave-apply";
+}
+
+/** Run `args` through `run`, refusing any argv off {@link YODEL_COMMANDS}. */
+export async function runAllowedYodel(run: YodelRunner, args: string[], opts: { cwd: string; env: NodeJS.ProcessEnv; dir?: string }): Promise<YodelRun> {
+  if (!allowedYodelArgv(args)) {
+    throw new Error(`chant runs only ${YODEL_COMMANDS.join(", ")} (each optionally with ${YODEL_OPTIONAL_FLAGS.join(", ")}) for a SQL member, not yodel ${args.join(" ")}`);
+  }
+  return run(args, opts);
+}
+
+/** The variables that pick the writer (sql-yodeler `credentials.ts`). */
+export const YODEL_ROLE_VARIABLES: readonly string[] = ["YODEL_ROLE", "YODEL_CREDENTIALS"];
+
+/** A writer's default user and password variables, `<ENV>_<DIALECT>_WRITER_USER` and `..._WRITER_PASSWORD`. */
+const WRITER_VARIABLE = /^[A-Z0-9_]+_(CLICKHOUSE|POSTGRES)_WRITER_(USER|PASSWORD)$/;
+
+/** `env` with the writer taken out: what the planning commands run with. */
+export function readerEnv(env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  const out: NodeJS.ProcessEnv = {};
+  for (const [k, v] of Object.entries(env)) {
+    if (YODEL_ROLE_VARIABLES.includes(k) || WRITER_VARIABLE.test(k)) continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * The yodel binary: the project's `node_modules/.bin/yodel`, else the
+ * working directory's, else `yodel` on PATH. Always a file named `yodel`.
+ */
+export function yodelBinary(cwd: string, dir?: string): string {
+  for (const base of [...(dir ? [join(cwd, dir)] : []), cwd]) {
+    const bin = join(base, "node_modules", ".bin", "yodel");
+    if (existsSync(bin)) return bin;
+  }
+  return "yodel";
+}
+
+export const defaultYodelRunner: YodelRunner = (args, opts) =>
+  new Promise((resolve) => {
+    execFile(yodelBinary(opts.cwd, opts.dir), args, { cwd: opts.cwd, env: opts.env, maxBuffer: 64 * 1024 * 1024 }, (err, stdout, stderr) => {
+      if (!err) return resolve({ code: 0, stdout, stderr });
+      const e = err as NodeJS.ErrnoException & { code?: unknown };
+      if (e.code === "ENOENT") return resolve({ code: null, stdout, stderr: stderr || e.message, missingBinary: true });
+      resolve({ code: typeof e.code === "number" ? e.code : null, stdout, stderr: stderr || e.message });
+    });
+  });