@caelo-cms/provisioning 0.10.29 → 0.10.30

package/dist/stack-contract.d.ts

@@ -0,0 +1,231 @@
+export type GcpProvider = "gcp" | "gcp-firebase";
+export type CloudRunSlug = "admin" | "gateway";
+/**
+ * One container env var, in the shape Pulumi's `gcp.cloudrunv2.Service`
+ * `envs` accepts. `V` is the value type: `pulumi.Input<string>` in the
+ * stacks, `string` in upgrade.
+ */
+export type CloudRunEnvVar<V = string> = {
+    readonly name: string;
+    readonly value: V;
+} | {
+    readonly name: string;
+    readonly valueSource: {
+        readonly secretKeyRef: {
+            readonly secret: V;
+            readonly version: string;
+        };
+    };
+};
+/** Install metadata every service's env derives from. */
+export interface ServiceEnvInputs {
+    readonly provider: GcpProvider;
+    readonly projectId: string;
+    /** Pulumi stack name (`production`). */
+    readonly env: string;
+    /** Install domain; the public site is served at its apex. */
+    readonly domain: string;
+    readonly region: string;
+}
+/** The password-less connection URLs of the install's Cloud SQL databases. */
+export interface DatabaseUrls<V = string> {
+    /** admin_role on cms_admin — the admin's primary pool. */
+    readonly admin: V;
+    /** admin_role on cms_public — the admin's second pool (DDL, migrations). */
+    readonly publicAdmin: V;
+    /** public_role on cms_public — the gateway's visitor-write pool. */
+    readonly public: V;
+}
+/**
+ * Password-less connection URLs for a Cloud SQL instance at `host`. The
+ * password reaches the apps separately, as a Secret Manager reference
+ * ({@link SERVICE_SECRET_ENV}).
+ */
+export declare function databaseUrls(host: string): DatabaseUrls;
+/** What a running service's env derives from: install metadata + the database. */
+export interface RuntimeEnvInputs<V = string> extends ServiceEnvInputs {
+    /** From the Cloud SQL private IP — an Output in the stacks. */
+    readonly databaseUrls: DatabaseUrls<V>;
+}
+/**
+ * What the admin's env derives from. Most values come from install metadata;
+ * the few Pulumi generates (database host, Firebase site id, the gateway's
+ * auto-named Cloud Run service) are passed in — as Outputs by the stack, as
+ * discovered strings by upgrade.
+ */
+export type AdminEnvInputs<V = string> = (RuntimeEnvInputs<V> & {
+    readonly provider: "gcp";
+}) | (RuntimeEnvInputs<V> & {
+    readonly provider: "gcp-firebase";
+    readonly firebaseSiteId: V;
+    readonly gatewayService: V;
+});
+/** The public site's base URL, as the admin seeds `site_base_url` from it (#551). */
+export declare function publicSiteUrl(domain: string): string;
+/**
+ * The admin env var naming the MCP service account (issue #37). `upgrade`
+ * leaves it untouched when it could not set that account up.
+ */
+export declare const MCP_ENV_VAR = "CAELO_MCP_IAP_SERVICE_ACCOUNT";
+/**
+ * The admin env var naming the operator-access sync job. `upgrade` leaves it
+ * untouched when it could not set the job up.
+ */
+export declare const OPERATOR_ACCESS_JOB_ENV_VAR = "CAELO_OPERATOR_ACCESS_JOB";
+/**
+ * The Secret Manager secrets admin + gateway read at runtime, by logical
+ * name ({@link gcpSecretId} gives the secret id).
+ */
+export type RuntimeSecret = "postgres-password" | "secret-kek" | "internal-secret" | "tool-approval-secret";
+/**
+ * Secrets the CLI generates and stores (runtime-secrets.ts
+ * `ensureGeneratedSecrets`) rather than Pulumi: the wizard creates them
+ * before `pulumi up`, upgrade creates them on installs that predate them.
+ * Pulumi only references them, so a `pulumi up` after an upgrade never
+ * collides with a secret upgrade created.
+ */
+export declare const CLI_GENERATED_SECRETS: readonly ["internal-secret", "tool-approval-secret"];
+/**
+ * Each service's Secret Manager-backed env vars and the secret each reads.
+ * The services' run SAs get `secretAccessor` on exactly these secrets
+ * ({@link runtimeSecretBindings}), so this table is also the least-privilege
+ * boundary between the two services.
+ */
+export declare const SERVICE_SECRET_ENV: Readonly<Record<CloudRunSlug, Readonly<Record<string, RuntimeSecret>>>>;
+/** The secrets `service` reads (deduplicated, table order). */
+export declare function serviceSecrets(service: CloudRunSlug): RuntimeSecret[];
+/**
+ * Env vars an older stack set that the contract no longer gives a service;
+ * upgrade removes them. The gateway never used the KEK, and its run SA
+ * cannot read it.
+ */
+export declare const RETIRED_SERVICE_ENV: Readonly<Record<CloudRunSlug, readonly string[]>>;
+/**
+ * The env of the gateway service. Order is stable so the stacks see no
+ * spurious diffs.
+ */
+export declare function gatewayEnvContract<V>(inputs: RuntimeEnvInputs<V>): CloudRunEnvVar<V | string>[];
+/**
+ * The env of the admin service.
+ *
+ * @example
+ *   adminEnvContract({ provider: "gcp", projectId: "p", env: "production",
+ *     domain: "example.com", region: "europe-west1",
+ *     databaseUrls: databaseUrls("10.20.0.3") })
+ *   // → [{ name: "CAELO_PROVIDER", value: "gcp" }, …,
+ *   //    { name: "CAELO_SITE_URL", value: "https://example.com" }, …,
+ *   //    { name: "CAELO_SECRET_KEK", valueSource: { secretKeyRef: … } }, …]
+ */
+export declare function adminEnvContract<V>(inputs: AdminEnvInputs<V>): CloudRunEnvVar<V | string>[];
+/**
+ * Cloud CDN policy of the `gcp` stack's static backend bucket. The GCS
+ * publisher sets an explicit Cache-Control on every object: content-hashed
+ * assets `max-age=31536000, immutable`, pages `max-age=60` + SWR. In
+ * CACHE_ALL_STATIC mode `clientTtl` clamps the max-age browsers see and
+ * `maxTtl` caps the edge TTL, so both must allow a year or the immutable
+ * policy is cut back to 1h (#555). `defaultTtl` applies only to responses
+ * without a max-age.
+ */
+export declare const STATIC_CDN_POLICY: {
+    readonly cacheMode: "CACHE_ALL_STATIC";
+    readonly defaultTtl: 3600;
+    readonly maxTtl: 31536000;
+    readonly clientTtl: 31536000;
+};
+/** Who an IAM invariant grants a role to. */
+export type IamPrincipal = 
+/** The runtime SA the admin (and the migration jobs) run as. */
+"run-sa"
+/** The runtime SA the gateway runs as. */
+ | "gateway-sa"
+/** The `gcp` stack's static-publisher SA. */
+ | "static-publisher-sa"
+/** IAP's Google-managed service agent (forwards IAP traffic to Cloud Run). */
+ | "iap-service-agent" | "allUsers";
+/** The resource an IAM invariant's binding lives on. */
+export type IamTarget = {
+    readonly kind: "project";
+} | {
+    readonly kind: "secret";
+    readonly name: string;
+} | {
+    readonly kind: "bucket";
+    readonly bucket: "media" | "static" | "staging";
+} | {
+    readonly kind: "run-service";
+    readonly service: CloudRunSlug;
+};
+/**
+ * One IAM binding a stack declares and upgrade ensures.
+ *
+ * `onFailure` decides what upgrade does when it can neither find nor add the
+ * binding: `abort` (before any traffic shifts) when the install cannot work
+ * without it, `warn` when only something non-essential degrades.
+ */
+export interface IamInvariant {
+    /**
+     * Logical name of the stack resource that declares the binding, without
+     * the `${namePrefix}-` prefix — the parity test finds it in the stack by
+     * this name.
+     */
+    readonly stackResource: string;
+    readonly role: string;
+    readonly member: IamPrincipal;
+    readonly target: IamTarget;
+    readonly onFailure: "abort" | "warn";
+    readonly why: string;
+}
+/** One `secretAccessor` binding a stack declares for a service's run SA. */
+export interface RuntimeSecretBinding {
+    readonly service: CloudRunSlug;
+    readonly secret: RuntimeSecret;
+    /** Logical stack resource name, without the `${namePrefix}-` prefix. */
+    readonly stackResource: string;
+}
+/**
+ * The `secretAccessor` bindings both stacks declare: each service's run SA
+ * on exactly the secrets its env reads ({@link SERVICE_SECRET_ENV}).
+ */
+export declare function runtimeSecretBindings(): RuntimeSecretBinding[];
+/** Every IAM binding upgrade ensures on an install of `provider`. */
+export declare function stackIamInvariants(provider: GcpProvider): IamInvariant[];
+/**
+ * IAM bindings the stacks declare that upgrade deliberately does not ensure,
+ * keyed by provider and the stack resource's logical name as written in the
+ * stack source, with each `${…}` placeholder written as `*`.
+ */
+export declare const STACK_IAM_NOT_ENSURED: Record<GcpProvider, Readonly<Record<string, string>>>;
+/** The IAM member string for a principal on a concrete install. */
+export declare function iamMember(principal: IamPrincipal, install: {
+    readonly projectId: string;
+    readonly projectNumber: string;
+    readonly env: string;
+}): string;
+/** Name prefix of the `gcp` stack's static backend bucket (Pulumi auto-suffixed). */
+export declare function staticBackendBucketPrefix(env: string): string;
+/**
+ * #553 — the admin's memory, in Cloud Run / Kubernetes quantity notation.
+ * The admin runs the quality audit (Lighthouse driving the bundled
+ * Chromium in a child process) next to the editor's requests; 1 GiB left
+ * no headroom for both, 2 GiB does. Every adapter exposes the same
+ * `adminMemory` knob with this default (CLAUDE.md §11.B), and `upgrade`
+ * raises an existing install's admin to it (never lowers a larger value).
+ */
+export declare const ADMIN_MEMORY_DEFAULT = "2Gi";
+/**
+ * Parse a memory quantity (`512Mi`, `2Gi`, `2G`, `1.5Gi`) to MiB; null when
+ * it is not a quantity this contract understands.
+ */
+/**
+ * #553 — Azure Container Apps (Consumption) only accepts fixed CPU/memory
+ * pairs: 0.25 vCPU / 0.5Gi up to 4 vCPU / 8Gi in 0.25 vCPU steps, memory
+ * always 2 GiB per vCPU. Map `adminMemory` onto that pair, or throw with
+ * the accepted values — an unsupported size must fail before `pulumi up`
+ * does, not deploy something else.
+ */
+export declare function azureContainerAppResources(quantity: string): {
+    readonly cpu: number;
+    readonly memory: string;
+};
+export declare function memoryQuantityMiB(quantity: string): number | null;
+//# sourceMappingURL=stack-contract.d.ts.map

package/dist/stack-contract.d.ts.map

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