@caelo-cms/provisioning 0.10.29 → 0.10.31

package/dist/regions.js

@@ -0,0 +1,247 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * The cloud region an install runs in: which regions each provider adapter
+ * can be installed in, what the wizard suggests, and the rule that the
+ * region is fixed once an install exists (#607).
+ *
+ * Why a static list instead of asking the cloud at run time: none of the
+ * providers offers one query for "every service this stack needs is
+ * available here". GCP's `gcloud run regions list` only covers Cloud Run and
+ * needs a project with the API already enabled — i.e. after we created
+ * billable state. So each catalog below is the intersection of the per-
+ * service region lists from the provider's own documentation (URLs next to
+ * each list). Azure is the exception: Microsoft documents no static
+ * Container Apps list and names `az provider show` as the source of truth,
+ * so the Azure catalog adds that live check on top of its static list and
+ * fails loudly when it can't run.
+ *
+ * The region is immutable after install: Cloud SQL, buckets, secrets, Cloud
+ * Run services and the scheduler job all live in it, and moving them is a
+ * migration Caelo does not do. A different region on a re-run or `upgrade`
+ * is refused, never applied.
+ */
+import { spawn } from "node:child_process";
+import { AWS_REGIONS, AZURE_REGIONS, GCP_REGION_NAMES, GCP_RESTRICTED_REGIONS, GCP_SERVICE_REGIONS, GCP_SERVICES, } from "./region-data.js";
+/** Default {@link CliRunner}: spawns the binary; a missing binary is a failed result. */
+export const runCli = (cmd, args) => new Promise((resolve) => {
+    const child = spawn(cmd, [...args], { stdio: ["ignore", "pipe", "pipe"] });
+    const out = [];
+    const err = [];
+    child.stdout.on("data", (c) => out.push(c));
+    child.stderr.on("data", (c) => err.push(c));
+    child.on("error", (e) => resolve({ ok: false, stdout: "", stderr: e.message }));
+    child.on("close", (code) => resolve({
+        ok: code === 0,
+        stdout: Buffer.concat(out).toString("utf8"),
+        stderr: Buffer.concat(err).toString("utf8"),
+    }));
+});
+/**
+ * Regions where Azure Container Apps managed environments are offered for
+ * the signed-in subscription, as the Azure CLI reports them. Never throws;
+ * a missing CLI or no permission is an error result.
+ */
+async function queryAzureContainerAppsRegions(run) {
+    const r = await run("az", [
+        "provider",
+        "show",
+        "--namespace",
+        "Microsoft.App",
+        "--query",
+        "resourceTypes[?resourceType=='managedEnvironments'].locations | [0]",
+        "--output",
+        "json",
+    ]);
+    if (!r.ok) {
+        return {
+            ok: false,
+            error: `could not ask Azure where Container Apps is available (az provider show --namespace Microsoft.App): ${r.stderr.trim() || "no output"}. Install the Azure CLI and run \`az login\`, then re-run.`,
+        };
+    }
+    let names;
+    try {
+        names = JSON.parse(r.stdout);
+    }
+    catch {
+        return { ok: false, error: `az provider show returned unparseable output: ${r.stdout.trim()}` };
+    }
+    if (!Array.isArray(names) || names.length === 0) {
+        return { ok: false, error: "az provider show listed no Container Apps regions." };
+    }
+    // The API reports display names ("West Europe"); region ids are the
+    // lower-cased name without spaces ("westeurope").
+    return {
+        ok: true,
+        regions: new Set(names.map((n) => String(n).toLowerCase().replace(/\s+/g, ""))),
+    };
+}
+function gcpCatalog(provider) {
+    const services = [...GCP_SERVICES];
+    if (provider === "gcp-firebase")
+        services.push("Cloud Run domain mapping");
+    const lists = services.map((s) => new Set(GCP_SERVICE_REGIONS[s] ?? []));
+    const regions = Object.keys(GCP_REGION_NAMES)
+        .filter((id) => !GCP_RESTRICTED_REGIONS.includes(id) && lists.every((l) => l.has(id)))
+        .map((id) => ({ id, name: GCP_REGION_NAMES[id] }));
+    return { provider, euDefault: "europe-west1", regions, services };
+}
+/** The region catalog for `provider`. */
+export function regionCatalog(provider) {
+    switch (provider) {
+        case "gcp":
+        case "gcp-firebase":
+            return gcpCatalog(provider);
+        case "aws":
+            return {
+                provider,
+                euDefault: "eu-central-1",
+                regions: AWS_REGIONS,
+                services: ["ECS Fargate", "RDS for PostgreSQL", "S3", "Secrets Manager"],
+            };
+        case "azure":
+            return {
+                provider,
+                euDefault: "westeurope",
+                regions: AZURE_REGIONS,
+                services: ["Container Apps", "Database for PostgreSQL flexible server", "Key Vault"],
+                liveRegions: queryAzureContainerAppsRegions,
+            };
+    }
+}
+/**
+ * The regions `provider` can be installed in right now: the static catalog,
+ * narrowed by the live query where the catalog has one.
+ */
+export async function installableRegions(provider, run = runCli) {
+    const catalog = regionCatalog(provider);
+    if (!catalog.liveRegions)
+        return { ok: true, regions: [...catalog.regions] };
+    const live = await catalog.liveRegions(run);
+    if (!live.ok)
+        return live;
+    return { ok: true, regions: catalog.regions.filter((r) => live.regions.has(r.id)) };
+}
+/** The "valid regions" list for error messages. */
+export function formatRegionList(regions) {
+    return regions.map((r) => `${r.id} (${r.name})`).join(", ");
+}
+/**
+ * Check `region` against the installable regions. The error names every
+ * valid region, so a non-interactive caller can fix its `--region`.
+ */
+export function checkRegion(provider, region, regions) {
+    if (regions.some((r) => r.id === region))
+        return { ok: true };
+    const services = regionCatalog(provider).services.join(", ");
+    return {
+        ok: false,
+        error: `"${region}" is not a region the ${provider} install can use (it needs ${services} in the same region). Valid regions: ${formatRegionList(regions)}.`,
+    };
+}
+/**
+ * The default region configured in the provider's CLI, or null when none
+ * is set or the CLI isn't installed (the wizard then suggests the EU
+ * default; the operator confirms either way).
+ */
+export async function detectCliRegion(provider, run = runCli, env = process.env) {
+    const first = (r) => {
+        const v = r.ok ? r.stdout.trim().split("\n")[0]?.trim() : "";
+        return v && v !== "(unset)" ? v : null;
+    };
+    switch (provider) {
+        case "gcp":
+        case "gcp-firebase":
+            return (first(await run("gcloud", ["config", "get-value", "run/region"])) ??
+                first(await run("gcloud", ["config", "get-value", "compute/region"])));
+        case "aws":
+            return (env.AWS_REGION?.trim() ||
+                env.AWS_DEFAULT_REGION?.trim() ||
+                first(await run("aws", ["configure", "get", "region"])));
+        case "azure":
+            return first(await run("az", ["config", "get", "defaults.location", "--query", "value", "-o", "tsv"]));
+    }
+}
+/**
+ * The region the picker preselects: the CLI default when it is installable,
+ * otherwise the catalog's EU default. `note` explains a skipped CLI default.
+ */
+export function suggestRegion(provider, cliRegion, regions) {
+    const euDefault = regionCatalog(provider).euDefault;
+    if (cliRegion && regions.some((r) => r.id === cliRegion)) {
+        return { region: cliRegion, source: "cli" };
+    }
+    return {
+        region: euDefault,
+        source: "eu-default",
+        ...(cliRegion
+            ? {
+                note: `Your CLI's default region ${cliRegion} lacks a service this install needs (${regionCatalog(provider).services.join(", ")}); suggesting ${euDefault} instead.`,
+            }
+            : {}),
+    };
+}
+/** Why a region differs from the one an install was created in. */
+export function regionChangeRefusal(installId, recorded, requested) {
+    return (`Install ${installId} runs in ${recorded}; its region is fixed after install, so ${requested} can't be applied. ` +
+        `Its Cloud SQL database, buckets, secrets and services live in ${recorded}, and moving them is a migration Caelo does not do. ` +
+        `Re-run without --region (or with --region ${recorded}). For another region, provision a new install there.`);
+}
+/** Decide the install region; see {@link RegionDecision}. */
+export function decideRegion(input) {
+    if (input.recorded && input.deployed && input.recorded !== input.deployed) {
+        return {
+            kind: "refuse",
+            error: `install.json records region ${input.recorded} for ${input.installId}, but its services run in ${input.deployed}. Fix install.json to the region the install runs in, then re-run.`,
+        };
+    }
+    const fixed = input.recorded ?? input.deployed;
+    if (fixed) {
+        if (input.requested && input.requested !== fixed) {
+            return {
+                kind: "refuse",
+                error: regionChangeRefusal(input.installId, fixed, input.requested),
+            };
+        }
+        return { kind: "keep", region: fixed, from: input.recorded ? "install.json" : "deployed" };
+    }
+    if (input.requested) {
+        const check = checkRegion(input.provider, input.requested, input.regions);
+        return check.ok
+            ? { kind: "use", region: input.requested }
+            : { kind: "refuse", error: check.error };
+    }
+    const preselected = input.preselected && checkRegion(input.provider, input.preselected, input.regions).ok
+        ? input.preselected
+        : null;
+    if (input.nonInteractive) {
+        if (preselected)
+            return { kind: "use", region: preselected };
+        return {
+            kind: "refuse",
+            error: `--region is required with --non-interactive: the region is fixed after install, so Caelo won't pick one for you. Valid regions: ${formatRegionList(input.regions)}.`,
+        };
+    }
+    return preselected ? { kind: "prompt", preselected } : { kind: "prompt" };
+}
+/**
+ * The region an existing install runs in, for lifecycle commands. Throws an
+ * actionable error when install.json has none (no silent default — §2).
+ */
+export function requireInstallRegion(meta) {
+    if (!meta.region) {
+        throw new Error(`install ${meta.installId} has no region recorded in install.json. Re-run the installer (\`bunx @caelo-cms/provisioning\`, pick "Resume wizard"): it reads the region from the deployed services and records it.`);
+    }
+    return meta.region;
+}
+/**
+ * Refuse a `--region` that differs from the install's recorded one (used by
+ * `upgrade`, which never moves an install). No `requested` passes.
+ */
+export function assertRegionUnchanged(meta, requested) {
+    const recorded = requireInstallRegion(meta);
+    if (requested && requested !== recorded) {
+        throw new Error(regionChangeRefusal(meta.installId, recorded, requested));
+    }
+    return recorded;
+}
+//# sourceMappingURL=regions.js.map

package/dist/regions.js.map

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

package/dist/runtime-secrets.d.ts

@@ -0,0 +1,128 @@
+import { type GcloudRunner, type Sleep } from "./gcloud-retry.js";
+import { CLI_GENERATED_SECRETS, type CloudRunSlug } from "./stack-contract.js";
+export interface RuntimeDeps {
+    readonly run?: GcloudRunner;
+    readonly sleep?: Sleep;
+    /** Generates a new secret value (default: 32 random bytes, hex). */
+    readonly generate?: () => string;
+}
+/** 32 random bytes as hex — the shape of every secret the stacks generate. */
+export declare function generateSecretValue(): string;
+export interface EnsureOutcome {
+    readonly id: string;
+    readonly status: "present" | "applied" | "failed";
+    readonly error?: string;
+}
+/** Create the gateway's run SA unless it exists. */
+export declare function ensureGatewayServiceAccount(install: {
+    readonly projectId: string;
+    readonly env: string;
+}, deps?: RuntimeDeps): Promise<EnsureOutcome>;
+/**
+ * Values of CLI-generated secrets a service runs with as plain env vars,
+ * for {@link ensureGeneratedSecrets}'s `seed`.
+ */
+export declare function plainGeneratedSecretSeed(liveEnv: ReadonlyMap<string, {
+    readonly kind: string;
+    readonly value?: string;
+}>): Partial<Record<(typeof CLI_GENERATED_SECRETS)[number], string>>;
+/** Where Secret Manager keeps a secret's payload. */
+export type SecretReplication = {
+    readonly kind: "automatic";
+} | {
+    readonly kind: "user-managed";
+    readonly locations: readonly string[];
+};
+/** The stacks' `secretReplication` config value as a {@link SecretReplication}. */
+export declare function stackSecretReplication(mode: "auto" | "regional", region: string): SecretReplication;
+/**
+ * The replication of the install's existing `postgres-password` secret, so
+ * secrets created later match what the stack pinned (orgs with a
+ * `gcp.resourceLocations` policy reject `automatic`).
+ */
+export declare function readSecretReplication(install: {
+    readonly projectId: string;
+    readonly env: string;
+}, deps?: RuntimeDeps): Promise<{
+    ok: true;
+    replication: SecretReplication;
+} | {
+    ok: false;
+    error: string;
+}>;
+/**
+ * Create each secret in `CLI_GENERATED_SECRETS` that is missing, and give
+ * one that exists without an enabled version a first version. A secret that
+ * already has an enabled version is never touched, so re-runs keep values.
+ *
+ * `seed` carries values a service already runs with as plain env vars (an
+ * operator-set `CAELO_INTERNAL_SECRET`): the new secret starts with that
+ * value, so moving the var to Secret Manager migrates the credential
+ * instead of silently rotating it under callers that sign with it.
+ */
+export declare function ensureGeneratedSecrets(install: {
+    readonly projectId: string;
+    readonly env: string;
+    readonly replication: SecretReplication;
+    readonly seed?: Readonly<Partial<Record<(typeof CLI_GENERATED_SECRETS)[number], string>>>;
+}, deps?: RuntimeDeps): Promise<EnsureOutcome[]>;
+/** The secrets `rotate-secret` can rotate. */
+export declare const ROTATABLE_SECRETS: readonly ["postgres-password", "internal-secret", "tool-approval-secret"];
+export type RotatableSecret = (typeof ROTATABLE_SECRETS)[number];
+/**
+ * Why `name` cannot be rotated, or `null` when it can.
+ *
+ * The KEK is refused: AI provider keys and other at-rest secrets in
+ * cms_admin are encrypted under it, and a new KEK without re-encrypting
+ * them would make them unreadable.
+ */
+export declare function rotationRefusal(name: string): string | null;
+/** The deployed install `rotateRuntimeSecret` works on. */
+export interface RotationTarget {
+    readonly projectId: string;
+    readonly region: string;
+    readonly env: string;
+    /** Deployed (Pulumi-suffixed) Cloud Run service names. */
+    readonly services: Readonly<Record<CloudRunSlug, string>>;
+    /** Cloud SQL instance name — needed for `postgres-password`. */
+    readonly sqlInstance?: string;
+}
+export interface RotationReport {
+    readonly ok: boolean;
+    /** What happened, in order, for the operator. */
+    readonly steps: string[];
+    readonly error?: string;
+}
+/** Minimal `fetch` the Cloud SQL Admin API calls need (injectable for tests). */
+export type HttpFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}>;
+/**
+ * Rotate one runtime secret: store a new value as a new Secret Manager
+ * version and roll every service that reads it, so new revisions resolve
+ * `latest` to the new value.
+ *
+ * Nothing changes unless every reader takes the secret from Secret Manager
+ * at `latest` ({@link checkRotationReaders}).
+ *
+ * `postgres-password` also changes the password of both database roles,
+ * first, so the new version never holds a password the database rejects.
+ * The password goes to the Cloud SQL Admin API in a request body, never on
+ * argv. If a step before the new version is stored fails, the roles are
+ * set back to the previous value. Between the password change and the
+ * roll, instances of the old revision keep their open connections but
+ * cannot open new ones — the roll follows immediately, and it is attempted
+ * for every reader even when one fails, so one failed service never leaves
+ * the other behind. A failed roll is resumed with the printed commands
+ * (rolling again picks up the stored value; it does not rotate again).
+ */
+export declare function rotateRuntimeSecret(target: RotationTarget, secret: RotatableSecret, deps?: RuntimeDeps & {
+    readonly http?: HttpFetch;
+}): Promise<RotationReport>;
+//# sourceMappingURL=runtime-secrets.d.ts.map

package/dist/runtime-secrets.d.ts.map

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