@intentius/sql-yodeler 0.3.0 → 0.5.0

package/dist/ci/login.js

@@ -0,0 +1,199 @@
+/**
+ * The cloud login a CI job runs before yodel (#132), when a role it holds
+ * has a password minted by a cloud token source: the job's OIDC token,
+ * exchanged by the cloud's own command line, which then mints the database
+ * token (`aws rds generate-db-auth-token`, `gcloud sql generate-login-token`,
+ * `az account get-access-token`). yodel.config.ts `ci.login` says what to
+ * log in as ({@link CiLogin}); this renders the steps per forge. Nothing
+ * here calls a cloud: the rendered job does, when it runs.
+ *
+ * The token, per forge:
+ * - GitHub: the job requests it for the cloud's audience
+ *   (ACTIONS_ID_TOKEN_REQUEST_URL, granted by `id-token: write`) and writes
+ *   it to the token file.
+ * - GitLab: the job's `id_tokens` variable (AWS_ID_TOKEN, GCP_ID_TOKEN,
+ *   AZURE_ID_TOKEN) is written to the token file.
+ * - Forgejo gives a job no OIDC token: a login is rendered only when the
+ *   config's `tokenFile` names a token the runner provides.
+ *
+ * The login, per cloud, from the token file:
+ * - aws: AWS_ROLE_ARN, AWS_WEB_IDENTITY_TOKEN_FILE and AWS_ROLE_SESSION_NAME,
+ *   which the aws command line assumes the role with.
+ * - gcp: an external_account credential configuration over the token file
+ *   (the workload identity provider, impersonating the service account),
+ *   `gcloud auth login --cred-file` with it, and GOOGLE_APPLICATION_CREDENTIALS.
+ * - azure: `az login --service-principal --federated-token`, and
+ *   AZURE_CLIENT_ID, AZURE_TENANT_ID and AZURE_FEDERATED_TOKEN_FILE.
+ *
+ * On GitHub and Forgejo the variables go to $GITHUB_ENV, so every later step
+ * has them (the report too); on GitLab they are the job's `variables`, so
+ * after_script has them too.
+ */
+export const CLOUDS = ["aws", "gcp", "azure"];
+/** The cloud whose login a token source mints from. */
+export const CLOUD_OF = { "rds-iam": "aws", "cloud-sql-iam": "gcp", entra: "azure" };
+/** The ID token's audience a cloud accepts. GCP's is the workload identity provider's own. */
+export function audience(login) {
+    if (login.cloud === "aws")
+        return "sts.amazonaws.com";
+    if (login.cloud === "gcp")
+        return `https://iam.googleapis.com/${login.config.workloadIdentityProvider}`;
+    return "api://AzureADTokenExchange";
+}
+/** The GitLab ID token variable per cloud, as #50 named them. */
+export const GITLAB_ID_TOKEN = { aws: "AWS_ID_TOKEN", gcp: "GCP_ID_TOKEN", azure: "AZURE_ID_TOKEN" };
+/** The login config for `env`'s roles minted by `token`: the environment's own, else the project's. */
+export function loginFor(login, env, token) {
+    const cloud = CLOUD_OF[token];
+    const config = login?.environments?.[env]?.[cloud] ?? login?.[cloud];
+    return config ? { cloud, config } : undefined;
+}
+/**
+ * The logins of a job holding `held` roles, each cloud once. A job logs in
+ * once per cloud, so two environments it holds that name different logins
+ * for one cloud are refused.
+ */
+export function jobLogins(login, held, cloudOf) {
+    const out = new Map();
+    for (const [env, role] of held) {
+        const token = cloudOf(env, role);
+        if (!token)
+            continue;
+        const l = loginFor(login, env, token);
+        if (!l)
+            continue;
+        const seen = out.get(l.cloud);
+        if (seen && JSON.stringify(seen.login.config) !== JSON.stringify(l.config)) {
+            throw new Error(`yodel.config.ts ci.login: a job holds ${seen.env}'s and ${env}'s roles, which log in to ${l.cloud} differently; a job logs in once per cloud, so give them one ${l.cloud} login`);
+        }
+        if (!seen)
+            out.set(l.cloud, { login: l, env });
+    }
+    return CLOUDS.flatMap((c) => {
+        const l = out.get(c)?.login;
+        return l ? [l] : [];
+    });
+}
+/** Where a job keeps a cloud's token by default. */
+const defaultTokenFile = (forge, cloud) => {
+    if (forge === "github")
+        return `$RUNNER_TEMP/yodel-${cloud}-token`;
+    if (forge === "gitlab")
+        return `/tmp/yodel-${cloud}-token`;
+    return undefined;
+};
+/**
+ * Requests the job's OIDC token for an audience and writes it to a file:
+ * `node -e '<this>' <audience> <file>`, so every image with node runs it.
+ */
+const GITHUB_OIDC = 'const [aud, file] = process.argv.slice(1); const url = process.env.ACTIONS_ID_TOKEN_REQUEST_URL, auth = process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN; if (!url || !auth) { console.error("no OIDC token for this job: the workflow needs permissions id-token: write"); process.exit(1); } fetch(url + "&audience=" + encodeURIComponent(aud), { headers: { Authorization: "bearer " + auth } }).then(async (r) => { if (!r.ok) throw new Error("the OIDC token request answered " + r.status); require("fs").writeFileSync(file, (await r.json()).value, { mode: 0o600 }); }).catch((e) => { console.error(e.message); process.exit(1); })';
+/** Writes the gcloud credential configuration: `node -e '<this>' <provider> <service account> <token file> <config file>`. */
+const GCP_CREDENTIALS = 'const [provider, sa, token, file] = process.argv.slice(1); require("fs").writeFileSync(file, JSON.stringify({ type: "external_account", audience: "//iam.googleapis.com/" + provider, subject_token_type: "urn:ietf:params:oauth:token-type:jwt", token_url: "https://sts.googleapis.com/v1/token", service_account_impersonation_url: "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/" + sa + ":generateAccessToken", credential_source: { file: token } }, null, 2))';
+const quote = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+/** A path that may name a variable ($RUNNER_TEMP): double-quoted, so the shell expands it. */
+const path = (s) => `"${s}"`;
+/** The variables a cloud's login sets, from its token file (and gcp's credential configuration). */
+function loginVariables(l, tokenFile) {
+    if (l.cloud === "aws")
+        return { AWS_ROLE_ARN: l.config.roleArn, AWS_WEB_IDENTITY_TOKEN_FILE: tokenFile, AWS_ROLE_SESSION_NAME: l.config.sessionName ?? "yodel" };
+    if (l.cloud === "gcp")
+        return { GOOGLE_APPLICATION_CREDENTIALS: `${tokenFile}.json` };
+    return { AZURE_CLIENT_ID: l.config.clientId, AZURE_TENANT_ID: l.config.tenantId, AZURE_FEDERATED_TOKEN_FILE: tokenFile };
+}
+const STEP_NAME = { aws: "Log in to AWS (web identity)", gcp: "Log in to Google Cloud (workload identity)", azure: "Log in to Azure (federated token)" };
+/**
+ * The login steps of a job on `forge`, for `logins`. On Forgejo a cloud
+ * without a `tokenFile` is left out: the runner's own identity mints there.
+ */
+export function loginSteps(forge, logins) {
+    const out = { steps: [], variables: {} };
+    for (const l of logins) {
+        const file = l.config.tokenFile ?? defaultTokenFile(forge, l.cloud);
+        if (file === undefined)
+            continue;
+        const lines = [];
+        if (forge === "github")
+            lines.push(`node -e ${quote(GITHUB_OIDC)} ${quote(audience(l))} ${path(file)}`);
+        if (forge === "gitlab")
+            lines.push(`(umask 077 && printf '%s' "$${GITLAB_ID_TOKEN[l.cloud]}" > ${path(file)})`);
+        if (l.cloud === "gcp") {
+            lines.push(`node -e ${quote(GCP_CREDENTIALS)} ${quote(l.config.workloadIdentityProvider)} ${quote(l.config.serviceAccount)} ${path(file)} ${path(`${file}.json`)}`);
+            lines.push(`gcloud auth login --cred-file=${path(`${file}.json`)} --quiet`);
+        }
+        if (l.cloud === "azure") {
+            lines.push(`az login --service-principal --username ${quote(l.config.clientId)} --tenant ${quote(l.config.tenantId)} --federated-token "$(cat ${path(file)})" --allow-no-subscriptions --output none`);
+        }
+        const vars = loginVariables(l, file);
+        if (forge === "gitlab")
+            Object.assign(out.variables, vars);
+        else
+            lines.push(...Object.entries(vars).map(([k, v]) => `echo "${k}=${v}" >> "$GITHUB_ENV"`));
+        out.steps.push({ name: STEP_NAME[l.cloud], lines });
+    }
+    return out;
+}
+// ── yodel.config.ts ci.login, checked ───────────────────────────────────────
+const ROLE_ARN = /^arn:aws[a-z-]*:iam::\d{12}:role\/[\w+=,.@/-]+$/;
+const PROVIDER = /^projects\/\d+\/locations\/global\/workloadIdentityPools\/[a-z0-9-]+\/providers\/[a-z0-9-]+$/;
+const SERVICE_ACCOUNT = /^[a-z0-9-]+@[a-z0-9-]+\.iam\.gserviceaccount\.com$/;
+const AZURE_ID = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+/** A path, optionally under a variable ($RUNNER_TEMP/...): nothing a shell would read as more than that. */
+const TOKEN_FILE = /^(\$[A-Z_][A-Z0-9_]*)?[\w./-]+$/;
+const SESSION_NAME = /^[\w+=,.@-]{2,64}$/;
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const FIELDS = {
+    aws: {
+        roleArn: { re: ROLE_ARN, what: "a role ARN, arn:aws:iam::<account>:role/<name>", required: true },
+        tokenFile: { re: TOKEN_FILE, what: "a file path", required: false },
+        sessionName: { re: SESSION_NAME, what: "2 to 64 of letters, digits and +=,.@_-", required: false },
+    },
+    gcp: {
+        workloadIdentityProvider: { re: PROVIDER, what: "projects/<number>/locations/global/workloadIdentityPools/<pool>/providers/<provider>", required: true },
+        serviceAccount: { re: SERVICE_ACCOUNT, what: "<name>@<project>.iam.gserviceaccount.com", required: true },
+        tokenFile: { re: TOKEN_FILE, what: "a file path", required: false },
+    },
+    azure: {
+        clientId: { re: AZURE_ID, what: "the application (client) id, a GUID", required: true },
+        tenantId: { re: AZURE_ID, what: "the directory (tenant) id, a GUID", required: true },
+        tokenFile: { re: TOKEN_FILE, what: "a file path", required: false },
+    },
+};
+function cloudsProblem(value, where, allowEnvironments) {
+    for (const [k, v] of Object.entries(value)) {
+        if (k === "environments" && allowEnvironments) {
+            if (!isRecord(v))
+                return `${where}.environments: an object keyed by environment, each { aws?, gcp?, azure? }`;
+            for (const [env, logins] of Object.entries(v)) {
+                if (!isRecord(logins))
+                    return `${where}.environments.${env}: expected { aws?, gcp?, azure? }`;
+                const problem = cloudsProblem(logins, `${where}.environments.${env}`, false);
+                if (problem)
+                    return problem;
+            }
+            continue;
+        }
+        if (!CLOUDS.includes(k))
+            return `${where}.${k}: unknown setting (expected ${[...CLOUDS, ...(allowEnvironments ? ["environments"] : [])].join(", ")})`;
+        const fields = FIELDS[k];
+        if (!isRecord(v))
+            return `${where}.${k}: expected { ${Object.keys(fields).join(", ")} }`;
+        for (const f of Object.keys(v))
+            if (!(f in fields))
+                return `${where}.${k}.${f}: unknown setting (expected ${Object.keys(fields).join(", ")})`;
+        for (const [f, spec] of Object.entries(fields)) {
+            const x = v[f];
+            if (x === undefined && !spec.required)
+                continue;
+            if (typeof x !== "string" || !spec.re.test(x))
+                return `${where}.${k}.${f}: ${spec.what}`;
+        }
+    }
+    return undefined;
+}
+/** What is wrong with yodel.config.ts `ci.login`, if anything. */
+export function loginProblem(value, where) {
+    if (!isRecord(value))
+        return `${where}: expected { aws?, gcp?, azure?, environments? }`;
+    return cloudsProblem(value, where, true);
+}
+//# sourceMappingURL=login.js.map

package/dist/ci/login.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"login.js","sourceRoot":"","sources":["../../src/ci/login.ts"],"names":[],"mappings":"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"}

package/dist/ci/render.d.ts

@@ -68,6 +68,8 @@
  * in that image instead, which carries node, yodel, chant and the lexicons
  * on PATH, and no job runs `npm ci` ({@link Toolchain}).
  */
+import { type ApprovalMode, type CiLogin } from "../config/define.js";
+import { type CloudToken, type Role } from "../credentials.js";
 import type { Declarable } from "@intentius/chant/declarable";
 export type Forge = "github" | "gitlab" | "forgejo";
 export declare const FORGES: readonly Forge[];
@@ -107,17 +109,44 @@ export interface Environments {
     jobs?: ProjectJobs;
     /** yodel.config.ts `ci.image`: the yodel image every job runs in, by digest. */
     image?: string;
+    /** yodel.config.ts `ci.resume`: the scheduled job that resumes a wave whose approval arrived. */
+    resume?: {
+        schedule: string;
+    };
     /** The apply pipeline's waves, in order. */
     waves: readonly Wave[];
     /** chant.config.ts declares the `replay` profile, so the lint job runs the replay check. */
     replay: boolean;
+    /** The project has tests/*.test.ts: with the replay profile, the lint job runs yodel test on its server too (#54). */
+    tests?: boolean;
+    /**
+     * The environments whose profile is made with credentials() (#50): the
+     * variables each role reads, and the cloud token source that mints its
+     * password, if any. An environment not here reads the default variables.
+     */
+    credentials?: Record<string, EnvCredentials>;
+    /** yodel.config.ts `ci.login` (#132): the cloud login a job runs before yodel when a role it holds is cloud-minted. */
+    login?: CiLogin;
+}
+/** What a job holding one role of an environment needs: the variables it reads, and the cloud identity its token source mints from. */
+export interface RoleNeeds {
+    variables: string[];
+    cloud?: CloudToken;
 }
+export type EnvCredentials = Record<Role, RoleNeeds>;
 /** DEV_CLICKHOUSE for dev on ClickHouse: what an environment's variables start with. */
 export declare const variablePrefix: (env: string, dialect: Dialect) => string;
-/** The variables a job reading `env` holds: the URL and the reader. */
-export declare const readerVariables: (env: string, dialect: Dialect) => string[];
+/** The variables a job reading `env` holds: the URL and the reader (the variables credentials() names; none for a token-minted password). */
+export declare const readerVariables: (env: string, dialect: Dialect, creds?: EnvCredentials) => string[];
 /** The variables the apply job for `env` holds: the URL and the writer. */
-export declare const writerVariables: (env: string, dialect: Dialect) => string[];
+export declare const writerVariables: (env: string, dialect: Dialect, creds?: EnvCredentials) => string[];
+/** The GitLab ID token per cloud: its variable and its audience. */
+export declare const ID_TOKENS: Record<CloudToken, {
+    variable: string;
+    aud: string;
+}>;
+/** The write probe a pull request job runs before its plan: it holds no writer for `envs`. */
+export declare const writeProbe: (envs: readonly string[]) => string;
 /**
  * The approvals: `chant approve` records them on the chant/lifecycle branch,
  * and approvers push it. A CI checkout fetches one ref, so fetch this one too.
@@ -161,7 +190,17 @@ export declare const REPLAY_SERVICE: Record<Dialect, ReplayService>;
 /** Waits up to 90 s for the replay server's port; a shell-free one-liner, so every forge runs it the same. */
 export declare const waitFor: (host: string, port: number) => string;
 export declare const LINT = "yodel lint";
+/**
+ * The lint job's `yodel lint`, with its findings where the forge shows them
+ * (#129): workflow commands on GitHub and Forgejo, which annotate the
+ * migration files in the pull request; on GitLab the code quality report,
+ * which the job keeps as its `artifacts:reports:codequality`
+ * ({@link CODE_QUALITY_FILE}) and the merge request shows.
+ */
+export declare const lintCommand: (forge: Forge) => string;
 export declare const REPLAY = "yodel lint --replay replay --reset";
+/** yodel test (#54), after the replay check on the same throwaway server, its outcome as JUnit XML. */
+export declare const TEST = "yodel test --env replay --reset --junit yodel-test.xml";
 /** Fails a pull request whose pipelines differ from what yodel ci renders. */
 export declare const CI_CHECK = "yodel ci --check";
 /**
@@ -200,12 +239,15 @@ export interface Wave {
      */
     requires?: string;
     /**
-     * A tenant set's wave (#56): a run per tenant, `<env>/<tenant>`, in place
-     * of the environment's one, all behind the wave's one gate.
+     * A tenant set's wave (#56): a run per tenant, `<env>/<tenant>`, or per
+     * slot of a set read at run time, `<env>/@<i>of<n>`, in place of the
+     * environment's one, all behind the wave's one gate.
      */
     targets?: readonly string[];
     /** Split the wave into a deciding job and this many share jobs (yodel.config.ts `waves[].shares`). */
     shares?: number;
+    /** Which approvals of the wave's digest count (yodel.config.ts `waves[].approval`, #48); absent, `ledger`. */
+    approval?: ApprovalMode;
 }
 /** The waves spec: committed, and read by every wave job (its gate policy at the commit before the push). */
 export declare const WAVES_SPEC = "yodel-waves.json";
@@ -224,25 +266,35 @@ interface WavesSpec {
         }>;
         gate: WaveGate;
         shares?: number;
+        approval?: ApprovalMode;
         environment?: {
             name: string;
         };
         variables?: Record<string, string>;
     }>;
+    /** The scheduled resume job (yodel.config.ts `ci.resume`); only the pipelines are rendered from it, the spec file leaves it out. */
+    resume?: {
+        schedule: string;
+    };
 }
 /**
  * The waves spec. What the file holds is the same for every forge; each
  * forge's jobs get their own variables on top (`variables`).
  */
-export declare function wavesSpec(waves: readonly Wave[], variables?: (env: string) => Record<string, string>): WavesSpec;
+export declare function wavesSpec(waves: readonly Wave[], variables?: (env: string) => Record<string, string>, resume?: {
+    schedule: string;
+}): WavesSpec;
 /** The waves spec file and the apply pipeline on each forge. */
 export declare function applyPipelines(dir: string, envs: Environments): Promise<RenderedFile[]>;
 /** yodel.config.ts `waves`, checked against the environments; one wave per environment, gate `always`, without it. */
 export declare function readWaves(dir: string, envs: readonly string[]): Promise<Wave[]>;
 /**
- * Each wave of an environment with a tenant set (#56), with a run per
- * tenant. A set given by a query is read from the server now, with the
- * environment's profile: run yodel ci again when the tenants change.
+ * Each wave of an environment with a tenant set (#56), with its runs: a
+ * run per tenant of a list or a file, or for a set given by a query,
+ * `shares` slots (one without) that read the tenants when the wave runs.
+ * The query is not run here, so the pipeline stays the same as tenants come
+ * and go; a list or a file is in the repository, and changing it is
+ * rendering again.
  */
 export declare function withTenants(dir: string, waves: readonly Wave[]): Promise<Wave[]>;
 /**
@@ -251,7 +303,7 @@ export declare function withTenants(dir: string, waves: readonly Wave[]): Promis
  * writer's only under its environment, which the watch does not declare), and
  * `NAME: $NAME` there would refer to itself.
  */
-export declare function watchSpec(env: string, dialect: Dialect, forge: Forge): {
+export declare function watchSpec(env: string, dialect: Dialect, forge: Forge, creds?: EnvCredentials): {
     name: string;
     variables?: Record<string, string>;
     permissions?: Record<string, string>;
@@ -259,6 +311,8 @@ export declare function watchSpec(env: string, dialect: Dialect, forge: Forge):
 export declare function watchPipelines(dir: string, envs_: Environments): Promise<RenderedFile[]>;
 /** The dialect and the environments chant.config.ts declares, in order. */
 export declare function environments(dir: string): Promise<Environments>;
+/** The roles of each environment whose profile is made with credentials(). */
+export declare function credentialsIn(profiles: Record<string, unknown>, envs: readonly string[]): Record<string, EnvCredentials>;
 /**
  * The project's own jobs (#65): the module yodel.config.ts `ci.jobs` names,
  * relative to the project, declaring jobs with chant's lexicons. `actions`