@geekmidas/cli 10.0.0-alpha.11 → 10.0.0-alpha.110

package/dist/deploy-H2S8_mTx.mjs

@@ -0,0 +1,2317 @@
+import { t as GkmError } from "./errors-D8Gwp5kU.mjs";
+import { s as gkmHome } from "./run-BJLIerMM.mjs";
+import { r as storedCredentials } from "./credentials-B5N5yKk6.mjs";
+import { $ as IamUserNotOwned, G as checkS3Config, J as BucketNameUnavailable, K as AccessKeyLimit, L as resolveStageTelemetry, N as assertDeployedStage, Q as BucketRegionUnknown, U as stageProvider, W as S3_PROVISIONING, X as BucketProbeFailed, Y as BucketOwnedByAnotherProject, Z as BucketRegionMismatch, et as ProvisionedBucketUnreachable, ht as isReservedStageKey, nt as RotationInProgress, q as BucketKeySetElsewhere, rt as S3RegionRequired, tt as RecordedBucketUnreachable, u as getAppBuildOrder } from "./workspace-D1QbNd55.mjs";
+import { S as deploysWithCompose, _ as backupExpiries, c as stageDnsDomains, d as BACKUPS_URL_KEY, n as dnsCredentials, u as BACKUPS_SERVICE, x as stageBackups, y as backupsPrefix } from "./dns-pFMShDqW.mjs";
+import { o as builtinTarget } from "./define-6poNqm5O.mjs";
+import { $ as devServicesUsed, $n as resolveHost, A as assertStageProvidersEnabled, Fn as usesTelemetry, It as secretsStoreFor, M as stageProviderNotes, N as PROVIDER_KINDS, Qn as isMainFrontendApp, X as ExternalServicesNotConfigured, Y as DevServicesNeedServerTarget, Zn as NoDomainForStage, _ as createComposeState, at as appEnvKeys, dt as constructGlobs, et as externalServices, rt as stageServiceDeclarations, tt as reportDevServices, u as DeployJournal, v as createEmptyState, zt as initStageSecrets } from "./seeds-BjcO4DDa.mjs";
+import { n as derivedApps, t as appKey } from "./derive-B4vDpzgP.mjs";
+import { n as deployIdentity, t as applicationName } from "./identity-CBXr4wNi.mjs";
+import { i as discover, p as withOutput } from "./discover-Ca8U75dl.mjs";
+import { c as withSandbox } from "./sandbox-CbVB7uOD.mjs";
+import { findWorkspaceRoot, loadWorkspaceConfig } from "./config.mjs";
+import { a as parseTargetOptions, o as resolveTarget } from "./resolve-BMpPd8x3.mjs";
+import { t as LocalSandbox } from "./local-BwC2v2Y8.mjs";
+import { E as eventError, S as createStateStore, v as assertStateOutlivesRun, y as assertStateRoom } from "./sniffer-b0XPmSyT.mjs";
+import { a as findProjectBucket, i as ensureProjectBucket, o as projectBucketName, r as callerAccountId, s as reconcileProjectBucketLifecycle } from "./projectBucket-C_DN4WzF.mjs";
+import { n as assertStageCredentials } from "./credentialSchemas-Cf5Pf8VE.mjs";
+import { resolve } from "node:path";
+import { randomInt } from "node:crypto";
+import { dependentsOf, kebabCase, provideKey, providedKeyFor } from "@geekmidas/manifest";
+import * as s3Url from "@geekmidas/storage/s3-url";
+//#region src/providers/aws.ts
+/**
+* The AWS account a provider provisions in — the stage's, found the way the
+* SSM and Secrets Manager stores find it.
+*
+* 1. `--profile`, resolved on its own: exported keys left over from another
+*    account never win over a profile someone named.
+* 2. `AWS_PROFILE`, else `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY` — the
+*    deploy's own `aws` credential kind (`storedCredentials`).
+* 3. The SDK's default chain: `~/.aws` default profile, SSO, a role. In CI,
+*    whatever `aws-actions/configure-aws-credentials` exported.
+*
+* None of them: the provider has no provisioning credentials, and the stage
+* is treated as `external`.
+*/
+async function awsProvisioningCredentials(lookup) {
+	const region = lookup.env.AWS_REGION ?? lookup.env.AWS_DEFAULT_REGION;
+	const where = region ? { region } : {};
+	if (lookup.profile) return {
+		profile: lookup.profile,
+		...where
+	};
+	const stored = await storedCredentials({
+		env: lookup.env,
+		...lookup.home ? { home: lookup.home } : {}
+	}).get({
+		kind: "aws",
+		stage: lookup.stage
+	});
+	if (stored) return stored;
+	try {
+		const { fromNodeProviderChain } = await import("@aws-sdk/credential-providers");
+		await fromNodeProviderChain({
+			timeout: 1e3,
+			maxRetries: 0
+		})();
+		return {
+			chain: true,
+			...where
+		};
+	} catch {
+		return;
+	}
+}
+/**
+* An S3-compatible endpoint the environment points the SDK at — the AWS
+* emulator in tests. The SDK reads it itself; it is read here too, because
+* an emulator takes path-style requests, and a key written for one has to
+* say where it is.
+*/
+function awsEndpoint(env, service) {
+	return env[`AWS_ENDPOINT_URL_${service}`] ?? env.AWS_ENDPOINT_URL;
+}
+/** An SDK client's config for a provisioning credential. */
+async function awsClientConfig(credential, region) {
+	if ("profile" in credential) {
+		const { fromIni } = await import("@aws-sdk/credential-providers");
+		return {
+			region,
+			credentials: fromIni({ profile: credential.profile })
+		};
+	}
+	if ("accessKeyId" in credential) return {
+		region,
+		credentials: {
+			accessKeyId: credential.accessKeyId,
+			secretAccessKey: credential.secretAccessKey,
+			...credential.sessionToken ? { sessionToken: credential.sessionToken } : {}
+		}
+	};
+	return { region };
+}
+//#endregion
+//#region src/target/secrets.ts
+/**
+* A stage's secrets as a target sees them: read and written through the
+* stage's own store, and masked in everything the run prints once read.
+*/
+/**
+* Shorter values are left alone: what a progress line legitimately prints —
+* a port, a stage, an app name — would otherwise come out as `***` wherever
+* a secret happened to share it.
+*/
+const SHORTEST_MASKED = 6;
+/** The values a run must never print, and the rewrite that keeps it so. */
+var Redactor = class {
+	values = /* @__PURE__ */ new Set();
+	add(value) {
+		if (value && value.length >= SHORTEST_MASKED) this.values.add(value);
+	}
+	/** `text` with every masked value replaced by `***`, longest first. */
+	redact(text) {
+		if (this.values.size === 0) return text;
+		let out = text;
+		const longestFirst = [...this.values].sort((a, b) => b.length - a.length);
+		for (const value of longestFirst) out = out.replaceAll(value, "***");
+		return out;
+	}
+};
+/** Every value in `secrets` that is a secret rather than a label. */
+function secretValues(secrets) {
+	return [
+		secrets.seed,
+		...Object.entries(secrets.custom ?? {}).filter(([key]) => !isReservedStageKey(key)).map(([, value]) => value),
+		...Object.values(secrets.urls ?? {}),
+		...Object.values(secrets.services ?? {}).map((service) => service?.password)
+	].filter((value) => typeof value === "string");
+}
+/**
+* The stage's secrets through the store `secrets.store` names for it. Opening
+* one builds a client and makes no request, so a target that never reads them
+* costs nothing.
+*/
+async function deploySecrets(workspace, stage, redactor, options = {}) {
+	const store = await secretsStoreFor(workspace, stage, options);
+	const mask = (secrets) => {
+		for (const value of secretValues(secrets)) redactor.add(value);
+	};
+	return {
+		store: store.name,
+		async read() {
+			const secrets = await store.read(stage);
+			if (secrets) mask(secrets);
+			return secrets;
+		},
+		async write(secrets) {
+			mask(secrets);
+			await store.write(stage, secrets);
+		},
+		mask: (value) => redactor.add(value)
+	};
+}
+const SUFFIX_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+/** A name that S3 would refuse — what the name builder never returns. */
+var InvalidBucketName = class extends GkmError {
+	bucket;
+	reason;
+	constructor(bucket, reason) {
+		super(`'${bucket}' is not a valid S3 bucket name: ${reason}. Rename the construct or set deploy.namespace in gkm.config.ts to something that leaves room for it.`);
+		this.bucket = bucket;
+		this.reason = reason;
+		this.name = "InvalidBucketName";
+	}
+};
+/** Lowercase `[a-z0-9-]`, runs of anything else one `-`, no edge dashes. */
+function part(value) {
+	return kebabCase(value).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+/**
+* `parts` joined by `-`, shortened to `max` characters by trimming the longest
+* part one character at a time — so a long construct id gives way before a
+* short stage name does, and every part keeps its start.
+*/
+function fitParts(parts, max) {
+	const kept = parts.map(part).filter(Boolean);
+	const length = () => kept.reduce((sum, p) => sum + p.length, 0) + kept.length - 1;
+	while (length() > max) {
+		let longest = 0;
+		for (let i = 1; i < kept.length; i++) if (kept[i].length > kept[longest].length) longest = i;
+		if (kept[longest].length <= 1) break;
+		kept[longest] = kept[longest].slice(0, -1).replace(/-+$/, "");
+	}
+	return kept.join("-");
+}
+/** Why `name` is not a valid bucket name, or undefined when it is. */
+function bucketNameProblem(name) {
+	if (name.length < 3 || name.length > 63) return `it is ${name.length} characters, and S3 takes 3 to 63`;
+	if (!/^[a-z0-9-]+$/.test(name)) return "it may hold only lowercase letters, digits and -";
+	if (!/^[a-z0-9].*[a-z0-9]$/.test(name)) return "it must start and end with a letter or a digit";
+	if (name.startsWith("xn--") || name.startsWith("sthree-")) return "it starts with a prefix S3 reserves ('xn--', 'sthree-')";
+	if (name.endsWith("-s3alias") || name.endsWith("--ol-s3")) return "it ends with a suffix S3 reserves ('-s3alias', '--ol-s3')";
+}
+/**
+* The good name: `<namespace>-<project>-<stage>-<bucket id>`, lowercased, no
+* dots, shortened to leave room for a clash's suffix.
+*
+* @throws {InvalidBucketName} when nothing usable is left
+*/
+function bucketName(input) {
+	const name = fitParts([
+		input.scope,
+		input.stage,
+		input.id
+	], 56);
+	const problem = bucketNameProblem(name);
+	if (problem) throw new InvalidBucketName(name, problem);
+	return name;
+}
+/** Six random `[a-z0-9]` characters. */
+function randomSuffix(random = randomInt) {
+	let suffix = "";
+	for (let i = 0; i < 6; i++) suffix += SUFFIX_ALPHABET[random(36)];
+	return suffix;
+}
+/** The good name with a clash's suffix. */
+function suffixedBucketName(good, suffix) {
+	return `${good}-${suffix}`;
+}
+/**
+* The IAM user a bucket is reached with on a stage:
+* `gkm-<project>-<stage>-<bucket id>`, at most 64 characters.
+*/
+function iamUserName(input) {
+	return fitParts([
+		"gkm",
+		input.scope,
+		input.stage,
+		input.id
+	], 64);
+}
+/** The path every user gkm creates is under, so it finds its own. */
+const IAM_USER_PATH = "/gkm/";
+/** The inline policy each user is given. */
+const IAM_POLICY_NAME = "gkm-bucket";
+//#endregion
+//#region src/providers/s3/policy.ts
+const bucketArn = (bucket) => `arn:aws:s3:::${bucket}`;
+/**
+* What the app's key may do: objects in this bucket, and listing it — and
+* nothing else in the account.
+*
+* Multipart uploads are in it because a presigned upload of a large file is
+* one, and an abandoned one is cleaned up by the app. Reading old versions is
+* added only when the bucket keeps them.
+*/
+function userPolicy(bucket, options = {}) {
+	return {
+		Version: "2012-10-17",
+		Statement: [{
+			Sid: "GkmObjects",
+			Effect: "Allow",
+			Action: [
+				"s3:GetObject",
+				"s3:PutObject",
+				"s3:DeleteObject",
+				"s3:AbortMultipartUpload",
+				"s3:ListMultipartUploadParts",
+				...options.versioning ? ["s3:GetObjectVersion"] : []
+			],
+			Resource: `${bucketArn(bucket)}/*`
+		}, {
+			Sid: "GkmBucket",
+			Effect: "Allow",
+			Action: [
+				"s3:ListBucket",
+				"s3:GetBucketLocation",
+				"s3:ListBucketMultipartUploads"
+			],
+			Resource: bucketArn(bucket)
+		}]
+	};
+}
+/**
+* One open pattern as the resource it is public on. A `**` is S3's `*`; a
+* single `*` is too, which crosses `/` where the construct's own check does
+* not — the construct is the stricter of the two (see `bucketPolicy` in
+* reconcile, which the local MinIO is given the same way).
+*/
+function openResource(bucket, pattern) {
+	const path = pattern.replace(/^\/+/, "").replace(/\*\*/g, "*");
+	return `${bucketArn(bucket)}/${path}`;
+}
+/**
+* The bucket's own policy: every request refused unless it came over TLS,
+* and — only when a file server opens paths on it — anonymous `s3:GetObject`
+* on exactly those prefixes.
+*/
+function bucketPolicy(bucket, open = []) {
+	const statements = [{
+		Sid: "GkmDenyInsecureTransport",
+		Effect: "Deny",
+		Principal: "*",
+		Action: "s3:*",
+		Resource: [bucketArn(bucket), `${bucketArn(bucket)}/*`],
+		Condition: { Bool: { "aws:SecureTransport": "false" } }
+	}];
+	if (open.length > 0) statements.push({
+		Sid: "GkmOpenPaths",
+		Effect: "Allow",
+		Principal: "*",
+		Action: "s3:GetObject",
+		Resource: [...new Set(open.map((p) => openResource(bucket, p)))].sort()
+	});
+	return {
+		Version: "2012-10-17",
+		Statement: statements
+	};
+}
+/**
+* Block Public Access. All four flags on, unless the bucket has open paths:
+* then a *policy* may make it public (`BlockPublicPolicy`,
+* `RestrictPublicBuckets` off), and ACLs still may not.
+*/
+function publicAccessBlock(open) {
+	return {
+		BlockPublicAcls: true,
+		IgnorePublicAcls: true,
+		BlockPublicPolicy: !open,
+		RestrictPublicBuckets: !open
+	};
+}
+function corsRule(origins) {
+	return {
+		AllowedMethods: [
+			"GET",
+			"HEAD",
+			"POST",
+			"PUT"
+		],
+		AllowedOrigins: [...new Set(origins)].sort(),
+		AllowedHeaders: ["*"],
+		ExposeHeaders: ["ETag"],
+		MaxAgeSeconds: 3e3
+	};
+}
+/**
+* A policy document in one canonical form — keys sorted, a lone string a
+* one-element list, lists sorted — so one AWS reformatted reads as the same
+* document rather than as drift.
+*/
+function canonicalPolicy(value) {
+	return JSON.stringify(canonical(value));
+}
+function canonical(value, key) {
+	if (Array.isArray(value)) {
+		const items = value.map((v) => canonical(v));
+		return key === "Statement" ? items : items.map((v) => JSON.stringify(v)).sort();
+	}
+	if (value && typeof value === "object") return Object.fromEntries(Object.keys(value).sort().map((k) => {
+		const v = value[k];
+		return [k, canonical(k === "Action" || k === "Resource" || k === "AWS" ? Array.isArray(v) ? v : [v] : v, k)];
+	}));
+	return value;
+}
+//#endregion
+//#region src/providers/iam.ts
+/**
+* An IAM user gkm creates for one thing on a stage, its inline policy, and
+* the access key written into the stage's secrets as an `s3://` URL — what
+* the `s3` provider gives each bucket, and the deploy gives a stage's
+* backups.
+*
+* - **The user** is under `/gkm/`, tagged with the deploy identity, the stage
+*   and what it is for. One that exists without those tags is someone
+*   else's, and is refused rather than taken over.
+* - **Its policy** is read on every run and put back when it drifted.
+* - **Its key**: one, written into the stage's secrets the moment IAM shows
+*   its secret. `--rotate-keys` issues a successor and keeps the old one
+*   active until the stage has deployed with the new one; the next run after
+*   that — or `--retire-old-keys` — deletes it.
+* - **A new key** takes IAM seconds to become usable: the state records when
+*   it was issued, and a check made with it waits that out
+*   ({@link whileKeyIsNew}).
+*/
+/** The tags gkm finds its own buckets and users by. */
+const TAG_PROJECT = "gkm:project";
+const TAG_STAGE = "gkm:stage";
+const TAG_CONSTRUCT = "gkm:construct";
+/** The keys gkm tags a bucket and a user with. */
+function identityTags(ctx, id) {
+	return [
+		{
+			Key: TAG_PROJECT,
+			Value: ctx.identity.key
+		},
+		{
+			Key: TAG_STAGE,
+			Value: ctx.stage
+		},
+		{
+			Key: TAG_CONSTRUCT,
+			Value: id
+		}
+	];
+}
+/** A read whose "there is none" answer is one of `missing`. */
+async function readOr$1(read, missing) {
+	try {
+		return await read();
+	} catch (error) {
+		const e = error;
+		if (missing.includes(e?.Code ?? e?.name ?? "")) return void 0;
+		throw error;
+	}
+}
+/** IAM returns a policy document URL-encoded; an emulator may not. */
+function decodePolicy(document) {
+	try {
+		return decodeURIComponent(document);
+	} catch {
+		return document;
+	}
+}
+/**
+* The user and its inline policy: found — and refused when it is not this
+* stage's — or created, and the policy put back when it drifted.
+*
+* @throws {IamUserNotOwned}
+*/
+async function ensureIamUser(ctx, clients, input) {
+	const { IAM, iam } = clients;
+	const { id, user, policy } = input;
+	const entry = {
+		key: `iam-user:${id}`,
+		type: "iam-user"
+	};
+	const found = await readOr$1(() => iam.send(new IAM.GetUserCommand({ UserName: user })), ["NoSuchEntity", "NoSuchEntityException"]);
+	if (found?.User) {
+		const tags = await iam.send(new IAM.ListUserTagsCommand({ UserName: user }));
+		const tag = (key) => tags.Tags?.find((t) => t.Key === key)?.Value;
+		if (found.User.Path !== "/gkm/" || tag("gkm:project") !== ctx.identity.key || tag("gkm:stage") !== ctx.stage) throw new IamUserNotOwned(user, ctx.identity.key, ctx.stage);
+		await ctx.state.ready(entry, user);
+	} else await ctx.change({
+		construct: id,
+		resource: `IAM user ${user}`,
+		change: `create under ${IAM_USER_PATH}`
+	}, async () => {
+		await ctx.state.pending(entry);
+		await iam.send(new IAM.CreateUserCommand({
+			UserName: user,
+			Path: IAM_USER_PATH,
+			Tags: identityTags(ctx, id)
+		}));
+		await ctx.state.ready(entry, user);
+	});
+	const exists = Boolean(found?.User) || !ctx.dryRun;
+	const current = exists ? await readOr$1(() => iam.send(new IAM.GetUserPolicyCommand({
+		UserName: user,
+		PolicyName: input.policyName
+	})), ["NoSuchEntity", "NoSuchEntityException"]) : void 0;
+	const document = current?.PolicyDocument ? JSON.parse(decodePolicy(current.PolicyDocument)) : void 0;
+	if (!document || canonicalPolicy(document) !== canonicalPolicy(policy)) await ctx.change({
+		construct: id,
+		resource: `IAM user ${user}`,
+		change: `policy ${input.policyName}: ${input.describe}`
+	}, async () => {
+		await iam.send(new IAM.PutUserPolicyCommand({
+			UserName: user,
+			PolicyName: input.policyName,
+			PolicyDocument: JSON.stringify(policy)
+		}));
+	});
+	return {
+		user,
+		exists
+	};
+}
+/**
+* The user's access key, in the stage's secrets as the bucket's URL.
+*
+* - First run: one key, written into the stage's secrets.
+* - `--rotate-keys`: a second key, written in place of the first; the first
+*   stays active until the stage has deployed with the second, and the next
+*   run after that deploy — or `--retire-old-keys` — deletes it.
+* - A key the secrets no longer hold (a store emptied by hand): replaced the
+*   same way, since its secret cannot be read back.
+*
+* @throws {BucketKeySetElsewhere} when the secret names another bucket
+* @throws {RotationInProgress} on `--rotate-keys` with the last rotation's old key still active
+* @throws {AccessKeyLimit} when the user has two keys gkm did not record
+*/
+async function ensureAccessKey(ctx, clients, input) {
+	const { IAM, iam } = clients;
+	const { id, bucket, user, urlKey } = input;
+	const entryKey = `iam-access-key:${id}`;
+	const record = ctx.state.record(entryKey);
+	const given = ctx.secrets[urlKey];
+	let inUrl;
+	let parsed;
+	if (given !== void 0) {
+		try {
+			parsed = s3Url.parse(given);
+		} catch {
+			parsed = void 0;
+		}
+		if (parsed?.bucket !== bucket) throw new BucketKeySetElsewhere(urlKey, bucket, parsed?.bucket ?? given.replace(/\/\/[^@]*@/, "//"), ctx.stage);
+		inUrl = parsed.accessKeyId;
+	}
+	const listed = input.exists ? (await iam.send(new IAM.ListAccessKeysCommand({ UserName: user }))).AccessKeyMetadata?.map((k) => k.AccessKeyId) ?? [] : [];
+	let current = record?.status === "ready" ? record.id : void 0;
+	let previous = typeof record?.data?.previous === "string" ? record.data.previous : void 0;
+	const rotatedAt = typeof record?.data?.rotatedAt === "string" ? record.data.rotatedAt : void 0;
+	const entry = (data = {}) => ({
+		key: entryKey,
+		type: "iam-access-key",
+		data: {
+			user,
+			...data
+		}
+	});
+	if (previous && current) {
+		const deployed = rotatedAt !== void 0 && ctx.state.lastDeployedAt !== void 0 && ctx.state.lastDeployedAt > rotatedAt;
+		if (ctx.retireOldKeys || deployed) {
+			const old = previous;
+			const keep = current;
+			await ctx.change({
+				construct: id,
+				resource: `IAM user ${user}`,
+				change: `delete the rotated-out access key ${old}`
+			}, async () => {
+				if (listed.includes(old)) await iam.send(new IAM.DeleteAccessKeyCommand({
+					UserName: user,
+					AccessKeyId: old
+				}));
+				await ctx.state.ready(entry(), keep);
+			});
+			previous = void 0;
+		} else ctx.log(`   ${id}: the old access key ${previous} stays active until '${ctx.stage}' is deployed with the new one; the next deploy after that deletes it (or pass --retire-old-keys)`);
+	}
+	if (!current && inUrl && listed.includes(inUrl)) {
+		await ctx.state.ready(entry(), inUrl);
+		current = inUrl;
+	}
+	if (current !== void 0 && listed.includes(current) && inUrl === current && !ctx.rotateKeys) {
+		if (parsed && parsed.region !== clients.region) {
+			const address = parsed;
+			await ctx.change({
+				construct: id,
+				resource: urlKey,
+				change: `name ${clients.region}, the bucket's region (it said ${address.region ?? "none"})`
+			}, () => ctx.writeSecrets({ [urlKey]: s3Url.build({
+				...address,
+				region: clients.region
+			}) }));
+		}
+		return;
+	}
+	if (ctx.rotateKeys && previous) throw new RotationInProgress(id, previous, ctx.stage);
+	const outgoing = current && listed.includes(current) ? current : void 0;
+	if (listed.length >= 2) throw new AccessKeyLimit(user, listed);
+	const why = !current ? "create an access key" : ctx.rotateKeys ? "rotate: issue a new access key" : "issue a new access key (the secrets no longer hold the recorded one)";
+	await ctx.change({
+		construct: id,
+		resource: `IAM user ${user}`,
+		change: why
+	}, async () => {
+		await ctx.state.pending(entry(outgoing ? { previous: outgoing } : {}));
+		const key = (await iam.send(new IAM.CreateAccessKeyCommand({ UserName: user }))).AccessKey;
+		await ctx.writeSecrets({ [urlKey]: s3Url.build({
+			bucket,
+			region: clients.region,
+			...clients.endpoint ? {
+				endpoint: clients.endpoint,
+				forcePathStyle: true
+			} : {},
+			accessKeyId: key.AccessKeyId,
+			secretAccessKey: key.SecretAccessKey
+		}) });
+		const issuedAt = (/* @__PURE__ */ new Date()).toISOString();
+		await ctx.state.ready(entry(outgoing ? {
+			previous: outgoing,
+			rotatedAt: issuedAt,
+			issuedAt
+		} : { issuedAt }), key.AccessKeyId);
+	});
+	if (outgoing) ctx.log(`   ${urlKey} holds the new key. This deploy moves '${ctx.stage}' onto it; the next deploy after it deletes the old key ${outgoing}`);
+}
+/** How long a key issued this recently counts as new to IAM. */
+const NEW_KEY_WINDOW_MS = 6e5;
+/** The waits between asks while a new key becomes usable: about a minute. */
+let newKeyWaits = [
+	2e3,
+	4e3,
+	8e3,
+	15e3,
+	15e3,
+	15e3
+];
+/**
+* When the key in a URL was issued, if the stage's state says it was just
+* now — the record of `id`'s key naming that very key.
+*/
+function issuedJustNow(resources, id, accessKeyId) {
+	const record = resources?.[`iam-access-key:${id}`];
+	const issuedAt = record?.data?.issuedAt;
+	if (record?.id !== accessKeyId || typeof issuedAt !== "string") return;
+	const age = Date.now() - Date.parse(issuedAt);
+	return age >= 0 && age < NEW_KEY_WINDOW_MS ? issuedAt : void 0;
+}
+/**
+* `ask` again, for about a minute, while it is `refused` and the key was
+* issued just now — IAM refuses a key for seconds after making it. Returns
+* the last answer and how long was waited.
+*/
+async function whileKeyIsNew(first, options) {
+	let answer = first;
+	let waited = 0;
+	if (!options.issuedAt || !options.refused(answer)) return {
+		answer,
+		waited
+	};
+	options.onWait?.();
+	for (const wait of newKeyWaits) {
+		await new Promise((resolve) => setTimeout(resolve, wait));
+		waited += wait;
+		answer = await options.ask();
+		if (!options.refused(answer)) break;
+	}
+	return {
+		answer,
+		waited
+	};
+}
+//#endregion
+//#region src/backups/provision.ts
+/** What the backups user and its key are recorded and tagged as. */
+const BACKUPS_ID = "backups";
+/** The backups user's inline policy's name. */
+const BACKUPS_POLICY_NAME = "gkm-backups";
+/** Where a deploy's check puts its marker, under the backups prefix. */
+const VERIFY_MARKER = ".gkm-verify";
+/** The backups user's name: `gkm-<project>-<stage>-backups`. */
+function backupsUserName(scope, stage) {
+	return iamUserName({
+		scope,
+		stage,
+		id: BACKUPS_ID
+	});
+}
+/**
+* The backups key's policy: put objects under the stage's backups prefix.
+* Uploading in parts is `s3:PutObject` too; aborting one is not, and the
+* bucket's lifecycle does it instead.
+*/
+function backupsPolicy(bucket, prefix) {
+	return {
+		Version: "2012-10-17",
+		Statement: [{
+			Sid: "GkmBackupsPut",
+			Effect: "Allow",
+			Action: ["s3:PutObject"],
+			Resource: `arn:aws:s3:::${bucket}/${prefix}/*`
+		}]
+	};
+}
+/** A stage that backs up, and no AWS credentials to create its key with. */
+var BackupsCredentialsMissing = class extends GkmError {
+	stage;
+	constructor(stage) {
+		super(`'${stage}' runs Postgres, so the deploy backs it up — and creates the IAM user and key it backs up with in the stage's AWS account — and it found no AWS credentials to do it with. On this machine, supply ${S3_PROVISIONING.describe}. In CI, the step that runs the deploy needs the stage's role (AWS_ROLE_ARN, from gkm deploy:github). To take no backups, set deploy.backups.${stage}: false.`);
+		this.stage = stage;
+		this.name = "BackupsCredentialsMissing";
+	}
+};
+/** No region to create the project bucket in. */
+var BackupsRegionRequired = class extends GkmError {
+	stage;
+	constructor(stage) {
+		super(`'${stage}' is backed up to the project bucket, and there is no region to find it in: set state: { provider: 's3', region } in gkm.config.ts, or AWS_REGION.`);
+		this.stage = stage;
+		this.name = "BackupsRegionRequired";
+	}
+};
+/** A bucket construct whose IAM user would be the backups user. */
+var BackupsUserNameTaken = class extends GkmError {
+	stage;
+	construct;
+	constructor(stage, construct) {
+		super(`The bucket '${construct}' is reached on '${stage}' with the IAM user the stage's backups are put with — both are named after 'backups'. Rename the construct, or set deploy.backups.${stage}: false.`);
+		this.stage = stage;
+		this.construct = construct;
+		this.name = "BackupsUserNameTaken";
+	}
+};
+/** The backups key could not put its marker: backups would fail too. */
+var BackupsKeyRefused = class extends GkmError {
+	stage;
+	bucket;
+	key;
+	said;
+	constructor(stage, bucket, key, said) {
+		super(`The ${BACKUPS_URL_KEY} key of '${stage}' could not put s3://${bucket}/${key} (${said}), so its backups would fail the same way. Run the deploy with the stage's AWS credentials to put its user and policy back, or --rotate-keys to issue it a new key.`);
+		this.stage = stage;
+		this.bucket = bucket;
+		this.key = key;
+		this.said = said;
+		this.name = "BackupsKeyRefused";
+	}
+};
+/**
+* The region the project bucket is in: the state's, when it is kept in S3,
+* the secrets store's when that is in AWS, the credential's, `AWS_REGION`.
+*/
+function backupsRegion(workspace, stage, credential, env = process.env) {
+	const state = workspace.state;
+	const store = workspace.secrets?.store;
+	const region = (state && "region" in state ? state.region : void 0) ?? (store && typeof store === "object" && "region" in store ? store.region : void 0) ?? credential?.region ?? env.AWS_REGION ?? env.AWS_DEFAULT_REGION;
+	if (!region) throw new BackupsRegionRequired(stage);
+	return region;
+}
+/**
+* The stage's backups bucket, lifecycle, user and key — or, for a stage set
+* to `false`, a notice and nothing else. Returns what the stage's backups
+* came to.
+*
+* @throws {BackupsCredentialsMissing} when there are no AWS credentials
+*/
+async function ensureStageBackups(input) {
+	const { workspace, manifest, stage, ctx } = input;
+	const env = input.env ?? process.env;
+	const choice = stageBackups(workspace, manifest, stage);
+	if (choice.mode === "disabled") {
+		ctx.log(`💾 backups: off — deploy.backups.${stage} is false. Nothing is backed up, and nothing already backed up is deleted.`);
+		return choice;
+	}
+	if (choice.mode !== "on") return choice;
+	if (stageProvider(workspace, "objects", stage).mode === "provider") {
+		const clash = Object.entries(manifest).find(([id, d]) => d.kind === "objects" && appKey(id) === "backups");
+		if (clash) throw new BackupsUserNameTaken(stage, clash[0]);
+	}
+	const credential = await awsProvisioningCredentials({
+		stage,
+		env,
+		...input.profile ? { profile: input.profile } : {},
+		...input.home ? { home: input.home } : {}
+	});
+	if (!credential) throw new BackupsCredentialsMissing(stage);
+	const region = backupsRegion(workspace, stage, credential, env);
+	const clients = await backupsClients(credential, region, env);
+	const bucket = projectBucketName(ctx.identity.scope, await callerAccountId(clients.sts));
+	const prefix = backupsPrefix(workspace, stage);
+	const expiries = backupExpiries(workspace, manifest);
+	ctx.log(`💾 backups: ${choice.backups.describe}, to s3://${bucket}/${prefix}/${ctx.dryRun ? " (dry run)" : ""}`);
+	if (await findProjectBucket(clients.s3, bucket) === "none") await ctx.change({
+		construct: BACKUPS_SERVICE,
+		resource: `bucket ${bucket}`,
+		change: `create in ${region}, expiring each stage's backups`
+	}, async () => {
+		await ensureProjectBucket(clients.s3, {
+			bucket,
+			region,
+			identity: ctx.identity,
+			expiries
+		});
+	});
+	else if (await reconcileProjectBucketLifecycle(clients.s3, bucket, expiries, { dryRun: true })) await ctx.change({
+		construct: BACKUPS_SERVICE,
+		resource: `bucket ${bucket}`,
+		change: `lifecycle: ${expiries.map((e) => `${e.prefix} after ${e.days} days`).join(", ")}`
+	}, async () => {
+		await reconcileProjectBucketLifecycle(clients.s3, bucket, expiries);
+	});
+	const user = await ensureIamUser(ctx, clients, {
+		id: BACKUPS_ID,
+		user: backupsUserName(ctx.identity.scope, stage),
+		policyName: BACKUPS_POLICY_NAME,
+		policy: backupsPolicy(bucket, prefix),
+		describe: `put objects under ${prefix}/ only`
+	});
+	await ensureAccessKey(ctx, clients, {
+		id: BACKUPS_ID,
+		bucket,
+		urlKey: BACKUPS_URL_KEY,
+		...user
+	});
+	return choice;
+}
+/** The clients a backups run creates through. */
+async function backupsClients(credential, region, env) {
+	const S3 = await import("@aws-sdk/client-s3");
+	const IAM = await import("@aws-sdk/client-iam");
+	const { STSClient } = await import("@aws-sdk/client-sts");
+	const config = await awsClientConfig(credential, region);
+	const endpoint = awsEndpoint(env, "S3");
+	return {
+		IAM,
+		iam: new IAM.IAMClient(config),
+		s3: new S3.S3Client({
+			...config,
+			...endpoint ? {
+				endpoint,
+				forcePathStyle: true
+			} : {}
+		}),
+		sts: new STSClient(config),
+		region,
+		...endpoint ? { endpoint } : {}
+	};
+}
+/**
+* The stage's backups key puts its marker under the prefix — the one thing
+* it may do. A key issued by this deploy is waited for, as a bucket's is.
+* Returns whether there was a key to check.
+*
+* @throws {BackupsKeyRefused}
+*/
+async function verifyStageBackups(input) {
+	const { stage } = input;
+	if (stageBackups(input.workspace, input.manifest, stage).mode !== "on") return false;
+	const url = input.secrets[BACKUPS_URL_KEY];
+	if (!url) return false;
+	const address = (await import("@geekmidas/storage/s3-url")).parse(url);
+	if (!address.accessKeyId || !address.secretAccessKey) return false;
+	const S3 = await import("@aws-sdk/client-s3");
+	const client = new S3.S3Client({
+		region: address.region ?? "us-east-1",
+		credentials: {
+			accessKeyId: address.accessKeyId,
+			secretAccessKey: address.secretAccessKey
+		},
+		...address.endpoint ? { endpoint: address.endpoint } : {},
+		...address.forcePathStyle ? { forcePathStyle: true } : {}
+	});
+	const Key = `${backupsPrefix(input.workspace, stage)}/${VERIFY_MARKER}`;
+	const put = async () => {
+		try {
+			await client.send(new S3.PutObjectCommand({
+				Bucket: address.bucket,
+				Key,
+				Body: (/* @__PURE__ */ new Date()).toISOString(),
+				ContentType: "text/plain"
+			}));
+			return {
+				ok: true,
+				said: ""
+			};
+		} catch (error) {
+			const e = error;
+			const status = e.$metadata?.httpStatusCode;
+			return {
+				ok: false,
+				...status !== void 0 ? { status } : {},
+				said: `HTTP ${status ?? "no response"} ${e.name ?? "Error"}: ${e.message ?? ""}`
+			};
+		}
+	};
+	try {
+		const { answer } = await whileKeyIsNew(await put(), {
+			issuedAt: issuedJustNow(input.resources, BACKUPS_ID, address.accessKeyId),
+			refused: (answer) => !answer.ok && answer.status === 403,
+			ask: put,
+			onWait: () => input.log?.(`   backups: waiting for the new key ${address.accessKeyId} to become active…`)
+		});
+		if (!answer.ok) throw new BackupsKeyRefused(stage, address.bucket, Key, answer.said);
+		return true;
+	} finally {
+		client.destroy();
+	}
+}
+//#endregion
+//#region src/providers/s3/origins.ts
+/**
+* Which browser origins may call a bucket: the stage's sites that depend on
+* an API using it.
+*
+* The same reading of the graph an API's own CORS origins are — its callers —
+* taken one step further: a site that calls an API which hands it a presigned
+* upload URL is a site whose browser PUTs to the bucket. A site that reads the
+* bucket (or a file server over it) itself is one too. Nothing is written
+* down: add a site that calls the API and the next provision run allows it.
+*/
+/** The keys a reader of this bucket holds: its URL, and each server's over it. */
+function bucketKeys(manifest, bucket) {
+	return [provideKey(bucket, "url"), ...Object.entries(manifest).filter(([, d]) => d.kind === "file-server" && d.of === bucket).map(([id]) => provideKey(id, "url"))];
+}
+function bucketOrigins(input) {
+	const { manifest, workspace, stage } = input;
+	const keys = bucketKeys(manifest, input.bucket);
+	const readers = Object.entries(manifest).filter(([, d]) => d.kind === "rest-api" || d.kind === "site").filter(([id]) => {
+		const env = appEnvKeys(manifest, appKey(id), input.runnables);
+		return env !== void 0 && keys.some((key) => env.has(key));
+	});
+	const sites = /* @__PURE__ */ new Set();
+	for (const [id, declaration] of readers) {
+		if (declaration.kind === "site") {
+			sites.add(id);
+			continue;
+		}
+		for (const caller of dependentsOf(manifest, id)) if (manifest[caller]?.kind === "site") sites.add(caller);
+	}
+	const origins = /* @__PURE__ */ new Set();
+	const unresolved = [];
+	for (const id of [...sites].sort()) {
+		const name = appKey(id);
+		const app = workspace.apps[name];
+		if (!app) {
+			unresolved.push(name);
+			continue;
+		}
+		try {
+			const host = resolveHost(name, app, stage, workspace.domains, isMainFrontendApp(name, app, workspace.apps));
+			origins.add(`https://${host}`);
+		} catch (error) {
+			if (!(error instanceof NoDomainForStage)) throw error;
+			unresolved.push(name);
+		}
+	}
+	return {
+		origins: [...origins].sort(),
+		unresolved
+	};
+}
+//#endregion
+//#region src/providers/s3/index.ts
+function bucketConstructs(manifest) {
+	return Object.entries(manifest).filter(([, d]) => d.kind === "objects").map(([id, d]) => ({
+		id,
+		versioned: d.versioned === true,
+		servers: Object.entries(manifest).filter(([, s]) => s.kind === "file-server" && s.of === id).map(([sid, s]) => ({
+			id: sid,
+			open: s.open ?? []
+		})).sort((a, b) => a.id.localeCompare(b.id))
+	})).sort((a, b) => a.id.localeCompare(b.id));
+}
+/**
+* The region the stage's buckets are created in: the entry's, the secrets
+* store's when it is in AWS, the credential's, `AWS_REGION`.
+*/
+function s3Region(ctx, env = process.env) {
+	const store = ctx.workspace.secrets?.store;
+	const storeRegion = store && typeof store === "object" && "region" in store ? store.region : void 0;
+	const region = ctx.config.region ?? storeRegion ?? ctx.credential?.region ?? env.AWS_REGION ?? env.AWS_DEFAULT_REGION;
+	if (!region) throw new S3RegionRequired(ctx.stage);
+	return region;
+}
+/**
+* The address a file server over `bucket` serves on: the bucket's regional
+* virtual-host endpoint, which is what `FileServer.url(key)` appends a key to
+* — `https://<bucket>.s3.<region>.amazonaws.com/<key>`. Against an emulator,
+* its path-style address.
+*/
+function bucketPublicUrl(bucket, region, endpoint) {
+	if (endpoint) return `${endpoint.replace(/\/+$/, "")}/${bucket}`;
+	return `https://${bucket}.s3.${region}.amazonaws.com`;
+}
+/** What an AWS SDK error is called, whichever field carries it. */
+function errorName(error) {
+	const e = error;
+	return e?.Code ?? e?.name ?? "";
+}
+/** The answer an SDK call failed with. */
+function s3Answer(error) {
+	const e = error;
+	const headers = Object.fromEntries(Object.entries(e?.$response?.headers ?? {}).map(([k, v]) => [k.toLowerCase(), v]));
+	const status = e?.$metadata?.httpStatusCode ?? e?.$response?.statusCode;
+	const region = headers["x-amz-bucket-region"];
+	const requestId = e?.$metadata?.requestId ?? headers["x-amz-request-id"];
+	const id2 = e?.$metadata?.extendedRequestId ?? headers["x-amz-id-2"];
+	return {
+		...status !== void 0 ? { status } : {},
+		name: errorName(error) || "Error",
+		message: e?.message ?? String(error),
+		...region ? { region } : {},
+		...requestId ? { requestId } : {},
+		...id2 ? { id2 } : {}
+	};
+}
+/**
+* `HTTP 403 Unknown: UnknownError [x-amz-bucket-region: eu-west-1,
+* x-amz-request-id: …, x-amz-id-2: …]` — everything S3 said, for a message.
+*/
+function describeAnswer(answer) {
+	const said = answer.message && answer.message !== answer.name ? `${answer.name}: ${answer.message}` : answer.name;
+	const headers = [
+		answer.region && `x-amz-bucket-region: ${answer.region}`,
+		answer.requestId && `x-amz-request-id: ${answer.requestId}`,
+		answer.id2 && `x-amz-id-2: ${answer.id2}`
+	].filter(Boolean);
+	return `${answer.status === void 0 ? "no response" : `HTTP ${answer.status}`} ${said}` + (headers.length > 0 ? ` [${headers.join(", ")}]` : "");
+}
+/** `HeadBucket`: the bucket's region when it answers, else what S3 said. */
+async function headBucket(S3, client, bucket) {
+	try {
+		const out = await client.send(new S3.HeadBucketCommand({ Bucket: bucket }));
+		return {
+			ok: true,
+			...out.BucketRegion ? { region: out.BucketRegion } : {}
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			...s3Answer(error)
+		};
+	}
+}
+/** `GetBucketLocation`'s answer as a region: none is us-east-1, `EU` eu-west-1. */
+async function bucketLocation(S3, client, bucket) {
+	try {
+		const location = (await client.send(new S3.GetBucketLocationCommand({ Bucket: bucket }))).LocationConstraint;
+		return { region: !location ? "us-east-1" : location === "EU" ? "eu-west-1" : location };
+	} catch (error) {
+		return { failed: s3Answer(error) };
+	}
+}
+/**
+* Where `bucket` is: `HeadBucket`'s `x-amz-bucket-region` — on a 200, a 301
+* or a 400 alike — else `GetBucketLocation`.
+*
+* @throws {BucketRegionUnknown}
+*/
+async function bucketRegion(clients, bucket) {
+	const { S3, s3 } = clients;
+	const head = await headBucket(S3, s3, bucket);
+	if (head.region) return head.region;
+	const location = await bucketLocation(S3, s3, bucket);
+	if ("region" in location) return location.region;
+	throw new BucketRegionUnknown(bucket, head.ok ? "HTTP 200 without x-amz-bucket-region" : describeAnswer(head), describeAnswer(location.failed));
+}
+/** A read whose "there is none" answer is one of `missing`. */
+async function readOr(read, missing) {
+	try {
+		return await read();
+	} catch (error) {
+		if (missing.includes(errorName(error))) return void 0;
+		throw error;
+	}
+}
+const defaultClients = async (credential, region) => {
+	const S3 = await import("@aws-sdk/client-s3");
+	const IAM = await import("@aws-sdk/client-iam");
+	const config = await awsClientConfig(credential, region);
+	const endpoint = awsEndpoint(process.env, "S3");
+	return {
+		S3,
+		IAM,
+		s3: new S3.S3Client({
+			...config,
+			...endpoint ? {
+				endpoint,
+				forcePathStyle: true
+			} : {}
+		}),
+		iam: new IAM.IAMClient(config),
+		region,
+		...endpoint ? { endpoint } : {}
+	};
+};
+/** For tests: what makes the clients. */
+let makeClients = defaultClients;
+async function ensureS3(ctx) {
+	const region = s3Region(ctx);
+	const clients = await makeClients(ctx.credential, region);
+	for (const construct of bucketConstructs(ctx.manifest)) await ensureBucket(ctx, clients, construct);
+}
+async function ensureBucket(ctx, stageClients, construct) {
+	const { id } = construct;
+	const nameInput = {
+		scope: ctx.identity.scope,
+		stage: ctx.stage,
+		id: appKey(id)
+	};
+	const versioning = ctx.config.versioning ?? construct.versioned;
+	const open = [...new Set(construct.servers.flatMap((s) => s.open))].sort();
+	const located = await ensureBucketName(ctx, stageClients, id, bucketName(nameInput));
+	const { bucket, exists } = located;
+	let clients = stageClients;
+	if (located.region !== stageClients.region) {
+		clients = await makeClients(ctx.credential, located.region);
+		ctx.log(`   '${bucket}' is in ${located.region}, not ${stageClients.region}: '${id}' is reached and addressed there`);
+	}
+	await ensureBucketSettings(ctx, clients, {
+		id,
+		bucket,
+		exists,
+		versioning,
+		open
+	});
+	const user = await ensureIamUser(ctx, clients, {
+		id,
+		user: iamUserName(nameInput),
+		policyName: IAM_POLICY_NAME,
+		policy: userPolicy(bucket, { versioning }),
+		describe: "this bucket only"
+	});
+	await ensureAccessKey(ctx, clients, {
+		id,
+		bucket,
+		urlKey: provideKey(id, "url"),
+		...user
+	});
+	const publicUrl = bucketPublicUrl(bucket, clients.region, clients.endpoint);
+	for (const server of construct.servers) {
+		const key = provideKey(server.id, "url");
+		const entry = {
+			key: `file-server:${server.id}`,
+			type: "url"
+		};
+		const recorded = ctx.state.record(entry.key)?.id;
+		const current = ctx.secrets[key];
+		if (current === publicUrl) {
+			await ctx.state.ready(entry, publicUrl);
+			continue;
+		}
+		if (current !== void 0 && current !== recorded) {
+			ctx.log(`   ${key} is set to ${current} by you, and kept — the bucket's own address is ${publicUrl}`);
+			continue;
+		}
+		await ctx.change({
+			construct: server.id,
+			resource: key,
+			change: `set to ${publicUrl}`
+		}, async () => {
+			await ctx.writeSecrets({ [key]: publicUrl });
+			await ctx.state.ready(entry, publicUrl);
+		});
+	}
+}
+/**
+* The bucket's name: the recorded one, else the good name, else the good
+* name with a random suffix — up to {@link SUFFIX_ATTEMPTS} times.
+*/
+async function ensureBucketName(ctx, clients, id, good) {
+	const { S3, s3, region } = clients;
+	const key = `s3-bucket:${id}`;
+	const record = ctx.state.record(key);
+	const entry = (name, where) => ({
+		key,
+		type: "s3-bucket",
+		data: {
+			name,
+			region: where
+		}
+	});
+	/**
+	* Whether this account holds `name`: yes, no, or someone else does. Read
+	* by status — a `HEAD` has no body, so its error is named `Unknown` — and,
+	* when S3 says the bucket is in another region, asked again there.
+	*/
+	const probe = async (name) => {
+		let head = await headBucket(S3, s3, name);
+		if (!head.ok && head.region && head.region !== region && (head.status === 301 || head.status === 400)) {
+			const there = await makeClients(ctx.credential, head.region);
+			head = await headBucket(there.S3, there.s3, name);
+		}
+		if (head.ok) return "ours";
+		if (head.status === 404) return "none";
+		if (head.status === 403) return "taken";
+		throw new BucketProbeFailed(name, describeAnswer(head));
+	};
+	/** Where the bucket is now — read, not assumed: it may be adopted. */
+	const located = async (name, made) => ctx.dryRun && made === "created" ? region : bucketRegion(clients, name);
+	const create = async (name) => {
+		if (ctx.dryRun) {
+			const found = await probe(name);
+			if (found === "none") {
+				await ctx.change({
+					construct: id,
+					resource: `bucket ${name}`,
+					change: `create in ${region}`
+				}, async () => {});
+				return "created";
+			}
+			return found;
+		}
+		await ctx.state.pending(entry(name, region));
+		try {
+			await s3.send(new S3.CreateBucketCommand({
+				Bucket: name,
+				...region === "us-east-1" ? {} : { CreateBucketConfiguration: { LocationConstraint: region } }
+			}));
+		} catch (error) {
+			const code = errorName(error);
+			if (code === "BucketAlreadyOwnedByYou") return "ours";
+			if (code === "BucketAlreadyExists") return "taken";
+			throw error;
+		}
+		await ctx.change({
+			construct: id,
+			resource: `bucket ${name}`,
+			change: `create in ${region}`
+		}, async () => {});
+		return "created";
+	};
+	const adopt = async (name, where) => {
+		const there = where === region ? clients : await makeClients(ctx.credential, where);
+		const owner = (await readOr(() => there.s3.send(new there.S3.GetBucketTaggingCommand({ Bucket: name })), ["NoSuchTagSet", "NoSuchTagSetError"]))?.TagSet?.find((t) => t.Key === TAG_PROJECT)?.Value;
+		if (owner && owner !== ctx.identity.key) throw new BucketOwnedByAnotherProject(name, owner, ctx.identity.key);
+	};
+	if (record?.status === "ready" && record.id) {
+		const found = await probe(record.id);
+		if (found === "taken") throw new RecordedBucketUnreachable(id, record.id);
+		const made = found === "ours" ? "ours" : await create(record.id);
+		if (made === "taken") throw new RecordedBucketUnreachable(id, record.id);
+		const where = await located(record.id, made);
+		if (!ctx.dryRun) await ctx.state.ready(entry(record.id, where), record.id);
+		return {
+			bucket: record.id,
+			exists: made === "ours",
+			region: where
+		};
+	}
+	const pending = record?.data?.name;
+	const names = [
+		...typeof pending === "string" && pending !== good ? [pending] : [],
+		good,
+		...Array.from({ length: 5 }, () => suffixedBucketName(good, randomSuffix()))
+	];
+	const tried = [];
+	for (const name of names) {
+		tried.push(name);
+		const made = await create(name);
+		if (made === "taken") continue;
+		const where = await located(name, made);
+		if (made === "ours") await adopt(name, where);
+		if (!ctx.dryRun) await ctx.state.ready(entry(name, where), name);
+		if (name !== good) ctx.log(`   '${good}' is taken by another account; '${id}' is '${name}', recorded in the stage's state`);
+		return {
+			bucket: name,
+			exists: made === "ours",
+			region: where
+		};
+	}
+	throw new BucketNameUnavailable(id, tried.filter((n) => n !== pending));
+}
+/** Tags, Block Public Access, encryption, policy, versioning and CORS. */
+async function ensureBucketSettings(ctx, clients, input) {
+	const { S3, s3 } = clients;
+	const { id, bucket } = input;
+	const Bucket = bucket;
+	const fresh = ctx.dryRun && !input.exists;
+	const read = async (fn, missing) => fresh ? void 0 : readOr(fn, missing);
+	const set = (change, apply) => ctx.change({
+		construct: id,
+		resource: `bucket ${bucket}`,
+		change
+	}, () => apply().then(() => void 0));
+	const tagged = await read(() => s3.send(new S3.GetBucketTaggingCommand({ Bucket })), ["NoSuchTagSet", "NoSuchTagSetError"]);
+	const ours = identityTags(ctx, id);
+	const others = (tagged?.TagSet ?? []).filter((t) => !ours.some((o) => o.Key === t.Key));
+	if (ours.some((o) => !tagged?.TagSet?.some((t) => t.Key === o.Key && t.Value === o.Value))) await set("tag", () => s3.send(new S3.PutBucketTaggingCommand({
+		Bucket,
+		Tagging: { TagSet: [...others, ...ours].map((t) => ({
+			Key: t.Key,
+			Value: t.Value
+		})) }
+	})));
+	const isOpen = input.open.length > 0;
+	const block = publicAccessBlock(isOpen);
+	const ensureBlock = async () => {
+		const now = (await read(() => s3.send(new S3.GetPublicAccessBlockCommand({ Bucket })), ["NoSuchPublicAccessBlockConfiguration"]))?.PublicAccessBlockConfiguration;
+		if (!(now && Object.keys(block).every((k) => (now[k] ?? false) === block[k]))) await set(isOpen ? "block public access (ACLs; the policy opens the open paths)" : "block all public access", () => s3.send(new S3.PutPublicAccessBlockCommand({
+			Bucket,
+			PublicAccessBlockConfiguration: block
+		})));
+	};
+	const policy = bucketPolicy(bucket, input.open);
+	const ensurePolicy = async () => {
+		const current = await read(() => s3.send(new S3.GetBucketPolicyCommand({ Bucket })), ["NoSuchBucketPolicy"]);
+		if (!(current?.Policy !== void 0 && canonicalPolicy(JSON.parse(current.Policy)) === canonicalPolicy(policy))) await set(isOpen ? `policy: TLS only, public read on ${input.open.join(", ")}` : "policy: TLS only", () => s3.send(new S3.PutBucketPolicyCommand({
+			Bucket,
+			Policy: JSON.stringify(policy)
+		})));
+	};
+	if (isOpen) {
+		await ensureBlock();
+		await ensurePolicy();
+	} else {
+		await ensurePolicy();
+		await ensureBlock();
+	}
+	if ((await read(() => s3.send(new S3.GetBucketEncryptionCommand({ Bucket })), ["ServerSideEncryptionConfigurationNotFoundError"]))?.ServerSideEncryptionConfiguration?.Rules?.[0]?.ApplyServerSideEncryptionByDefault?.SSEAlgorithm !== "AES256" && !fresh) await set("encrypt by default (SSE-S3)", () => s3.send(new S3.PutBucketEncryptionCommand({
+		Bucket,
+		ServerSideEncryptionConfiguration: { Rules: [{ ApplyServerSideEncryptionByDefault: { SSEAlgorithm: "AES256" } }] }
+	})));
+	const status = (await read(() => s3.send(new S3.GetBucketVersioningCommand({ Bucket })), []))?.Status;
+	if (input.versioning && status !== "Enabled") await set("enable versioning", () => s3.send(new S3.PutBucketVersioningCommand({
+		Bucket,
+		VersioningConfiguration: { Status: "Enabled" }
+	})));
+	else if (!input.versioning && status === "Enabled") await set("suspend versioning", () => s3.send(new S3.PutBucketVersioningCommand({
+		Bucket,
+		VersioningConfiguration: { Status: "Suspended" }
+	})));
+	const { origins, unresolved } = bucketOrigins({
+		workspace: ctx.workspace,
+		manifest: ctx.manifest,
+		runnables: ctx.runnables,
+		stage: ctx.stage,
+		bucket: id
+	});
+	if (unresolved.length > 0) ctx.log(`   ${unresolved.join(", ")} ${unresolved.length === 1 ? "has" : "have"} no address on '${ctx.stage}' (domains.${ctx.stage}), so ${unresolved.length === 1 ? "is" : "are"} not in '${bucket}''s CORS`);
+	if (origins.length === 0) return;
+	const rule = corsRule(origins);
+	const cors = await read(() => s3.send(new S3.GetBucketCorsCommand({ Bucket })), ["NoSuchCORSConfiguration"]);
+	if (!(cors?.CORSRules?.length === 1 && canonicalCors(cors.CORSRules[0]) === canonicalCors(rule))) await set(`CORS for ${origins.join(", ")}`, () => s3.send(new S3.PutBucketCorsCommand({
+		Bucket,
+		CORSConfiguration: { CORSRules: [rule] }
+	})));
+}
+function canonicalCors(rule) {
+	const sorted = (list) => [...list ?? []].sort();
+	return JSON.stringify({
+		AllowedMethods: sorted(rule.AllowedMethods),
+		AllowedOrigins: sorted(rule.AllowedOrigins),
+		AllowedHeaders: sorted(rule.AllowedHeaders),
+		ExposeHeaders: sorted(rule.ExposeHeaders),
+		MaxAgeSeconds: rule.MaxAgeSeconds ?? null
+	});
+}
+/**
+* Each provisioned bucket answers `HeadBucket` to the key in the stage's
+* secrets — the one the apps will use. A bucket whose URL carries no key is
+* not one this provider wrote, and the deploy's own check covers a URL that
+* is missing.
+*
+* A failure is read by its status, never its name — a `HEAD` has no body,
+* so SDK v3 calls a 301, 400 or 403 `Unknown` — and the message carries
+* everything S3 said: status, error, region, request ids.
+*
+* @throws {BucketRegionMismatch} the bucket is in another region than its URL says
+* @throws {ProvisionedBucketUnreachable}
+*/
+async function verifyS3(ctx) {
+	const S3 = await import("@aws-sdk/client-s3");
+	for (const { id } of bucketConstructs(ctx.manifest)) {
+		const urlKey = provideKey(id, "url");
+		const url = ctx.secrets[urlKey];
+		if (url === void 0) continue;
+		const address = s3Url.parse(url);
+		if (!address.accessKeyId || !address.secretAccessKey) continue;
+		const asked = address.region ?? ctx.config.region ?? "us-east-1";
+		const client = new S3.S3Client({
+			region: asked,
+			credentials: {
+				accessKeyId: address.accessKeyId,
+				secretAccessKey: address.secretAccessKey
+			},
+			...address.endpoint ? { endpoint: address.endpoint } : {},
+			...address.forcePathStyle ? { forcePathStyle: true } : {}
+		});
+		try {
+			const issuedAt = issuedJustNow(ctx.resources, id, address.accessKeyId);
+			const { answer: head, waited } = await whileKeyIsNew(await headBucket(S3, client, address.bucket), {
+				issuedAt,
+				refused: (answer) => !answer.ok && answer.status === 403,
+				ask: () => headBucket(S3, client, address.bucket),
+				onWait: () => ctx.log?.(`   ${id}: waiting for the new key ${address.accessKeyId} to become active…`)
+			});
+			if (head.ok) continue;
+			const fail = (reason) => new ProvisionedBucketUnreachable(id, address.bucket, ctx.stage, reason);
+			const said = describeAnswer(head);
+			if (head.status === 301 || head.status === 400 && head.region && head.region !== asked) {
+				let where = head.region;
+				let located = "";
+				if (!where) {
+					const location = await bucketLocation(S3, client, address.bucket);
+					if ("region" in location) where = location.region;
+					else located = `; GetBucketLocation answered ${describeAnswer(location.failed)}`;
+				}
+				if (where && where !== asked) throw new BucketRegionMismatch(id, address.bucket, ctx.stage, urlKey, where, address.region, asked, said);
+				throw fail(`S3 redirected the request (${said}${located})`);
+			}
+			if (head.status === 404) throw fail(`it does not exist (${said})`);
+			if (head.status === 403) throw fail(`the key is refused — AccessDenied, or an invalid or not-yet-active key (${said})` + (issuedAt ? `. The key was issued at ${issuedAt} by this deploy, and IAM keys take seconds to become usable: it was still refused after waiting ${Math.round(waited / 1e3)}s` : ""));
+			throw fail(said);
+		} finally {
+			client.destroy();
+		}
+	}
+}
+//#endregion
+//#region src/providers/registry.ts
+/**
+* The providers gkm ships, by kind and name — registered the way a deploy
+* target's built-ins are (`target/builtins.ts`). A provider from a package is
+* one more entry here once there is a loading story for it.
+*/
+const BUILTIN_PROVIDERS = { objects: { s3: {
+	kind: "objects",
+	name: "s3",
+	check: checkS3Config,
+	provisioning: S3_PROVISIONING,
+	credentials: awsProvisioningCredentials,
+	runtimeKeys(manifest) {
+		return bucketConstructs(manifest).flatMap((b) => [provideKey(b.id, "url"), ...b.servers.map((s) => provideKey(s.id, "url"))]);
+	},
+	ensure: ensureS3,
+	verify: verifyS3
+} } };
+/** The provider `kind` names `name`, if gkm has one. */
+function builtinProvider(kind, name) {
+	return Object.hasOwn(BUILTIN_PROVIDERS[kind], name) ? BUILTIN_PROVIDERS[kind][name] : void 0;
+}
+//#endregion
+//#region src/providers/index.ts
+/** The constructs of a kind: `objects` is every bucket. */
+function constructsOf(manifest, kind) {
+	return Object.entries(manifest).filter(([, d]) => d.kind === kind).map(([id]) => id).sort();
+}
+/**
+* What every deploy runs: each provider's `verify()` — the cheap check that
+* what it created is still there and the stage's key reaches it. Nothing on
+* the local stage, and nothing for a kind on `external` or `false` — a kind
+* the stage has none of is the deploy's readiness check's to refuse.
+*/
+async function verifyStageProviders(input) {
+	const verified = [];
+	for (const kind of PROVIDER_KINDS) {
+		if (constructsOf(input.manifest, kind).length === 0) continue;
+		const choice = stageProvider(input.workspace, kind, input.stage);
+		if (choice.mode !== "provider") continue;
+		const provider = builtinProvider(kind, choice.name);
+		await provider.verify({
+			workspace: input.workspace,
+			manifest: input.manifest,
+			stage: input.stage,
+			config: choice.config,
+			secrets: input.secrets,
+			...input.resources ? { resources: input.resources } : {},
+			...input.log ? { log: input.log } : {}
+		});
+		verified.push(`${kind}: ${provider.name}`);
+	}
+	if (await verifyStageBackups(input)) verified.push("backups: s3");
+	return verified;
+}
+/**
+* A stage whose provider creates its resources, and no credentials to create
+* them with. Raised before anything is created, built or started.
+*/
+var ProviderCredentialsMissing = class extends GkmError {
+	stage;
+	kind;
+	provider;
+	ids;
+	env;
+	describe;
+	login;
+	constructor(stage, kind, provider, ids, env, describe, login) {
+		super(`deploy.${kind}.${stage} is ${provider}, so the deploy creates what ${ids.join(", ")} ${ids.length === 1 ? "is" : "are"} backed by on '${stage}' and writes ${ids.length === 1 ? "its key" : "their keys"} into the stage's secrets — and it found no ${provider} credentials to do it with. On this machine, supply ${describe}` + (login ? `, or run gkm login --provider ${login}` : "") + `. In CI, the step that runs the deploy needs them: the '${stage}' environment's role (AWS_ROLE_ARN, from gkm deploy:github), assumed before that step. With the keys set by hand instead, set deploy.${kind}.${stage} to 'external'.`);
+		this.stage = stage;
+		this.kind = kind;
+		this.provider = provider;
+		this.ids = ids;
+		this.env = env;
+		this.describe = describe;
+		this.login = login;
+		this.name = "ProviderCredentialsMissing";
+	}
+};
+/**
+* `ensure()` for every provider the stage configures — find or create, fix
+* drift, record in the stage's state, write the runtime keys into its
+* secrets. Run by the deploy, which holds the stage's lock. A provider with
+* no provisioning credentials stops the run with
+* {@link ProviderCredentialsMissing} before anything is created.
+*/
+async function provisionStage(options) {
+	const { workspace, stage, manifest } = options;
+	const dryRun = options.dryRun === true;
+	const env = options.env ?? process.env;
+	const log = options.log ?? ((line) => console.log(line));
+	const runnables = options.runnables ?? {};
+	const reports = [];
+	const configured = [];
+	for (const kind of PROVIDER_KINDS) {
+		const choice = stageProvider(workspace, kind, stage);
+		if (choice.mode !== "provider") {
+			reports.push({
+				kind,
+				mode: choice.mode,
+				actions: [],
+				planned: []
+			});
+			continue;
+		}
+		const provider = builtinProvider(kind, choice.name);
+		const report = {
+			kind,
+			mode: "provider",
+			provider: provider.name,
+			actions: [],
+			planned: []
+		};
+		reports.push(report);
+		const ids = constructsOf(manifest, kind);
+		if (ids.length === 0) continue;
+		const credential = await provider.credentials({
+			stage,
+			env,
+			...options.profile ? { profile: options.profile } : {},
+			...options.home ? { home: options.home } : {}
+		});
+		if (credential === void 0) throw new ProviderCredentialsMissing(stage, kind, provider.name, ids, provider.provisioning.env, provider.provisioning.describe, provider.provisioning.login);
+		configured.push({
+			kind,
+			provider,
+			config: choice.config,
+			credential,
+			report
+		});
+	}
+	const backups = stageBackups(workspace, manifest, stage);
+	if (configured.length === 0 && backups.mode !== "on") {
+		if (backups.mode === "disabled") log(`💾 backups: off — deploy.backups.${stage} is false. Nothing is backed up, and nothing already backed up is deleted.`);
+		return reports;
+	}
+	const identity = deployIdentity(workspace, stage);
+	let secrets = (await options.secrets.read())?.custom ?? {};
+	for (const entry of configured) entry.report.planned = entry.provider.runtimeKeys(manifest).filter((key) => secrets[key] === void 0);
+	const state = dryRun ? await readOnlyState(options.state, stage) : journalState(await DeployJournal.open(options.state, stage, () => deploysWithCompose(workspace) ? createComposeState(stage) : createEmptyState(stage, "", "")));
+	const writeSecrets = async (values) => {
+		if (dryRun) return;
+		const stored = await options.secrets.read() ?? initStageSecrets(stage);
+		const next = {
+			...stored,
+			custom: {
+				...stored.custom,
+				...values
+			},
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		await options.secrets.write(next);
+		secrets = next.custom;
+	};
+	for (const entry of configured) {
+		log(`☁️  ${entry.kind}: ${entry.provider.name}${dryRun ? " (dry run)" : ""}`);
+		await entry.provider.ensure({
+			workspace,
+			manifest,
+			runnables,
+			stage,
+			identity,
+			config: entry.config,
+			credential: entry.credential,
+			get secrets() {
+				return secrets;
+			},
+			state,
+			dryRun,
+			rotateKeys: options.rotateKeys === true,
+			retireOldKeys: options.retireOldKeys === true,
+			async change(action, apply) {
+				if (!dryRun) await apply();
+				entry.report.actions.push(action);
+				log(`   ${dryRun ? "would " : ""}${action.change} — ${action.resource}`);
+			},
+			writeSecrets,
+			log
+		});
+		if (entry.report.actions.length === 0) log("   up to date");
+	}
+	if (backups.mode === "on" || backups.mode === "disabled") {
+		const report = {
+			kind: "backups",
+			mode: backups.mode === "on" ? "provider" : "none",
+			actions: [],
+			planned: backups.mode === "on" && secrets["BACKUPS_URL"] === void 0 ? [BACKUPS_URL_KEY] : []
+		};
+		reports.push(report);
+		await ensureStageBackups({
+			workspace,
+			manifest,
+			stage,
+			...options.profile ? { profile: options.profile } : {},
+			...options.home ? { home: options.home } : {},
+			env,
+			ctx: {
+				identity,
+				stage,
+				state,
+				dryRun,
+				get secrets() {
+					return secrets;
+				},
+				rotateKeys: options.rotateKeys === true,
+				retireOldKeys: options.retireOldKeys === true,
+				async change(action, apply) {
+					if (!dryRun) await apply();
+					report.actions.push(action);
+					log(`   ${dryRun ? "would " : ""}${action.change} — ${action.resource}`);
+				},
+				writeSecrets,
+				log
+			}
+		});
+		if (backups.mode === "on" && report.actions.length === 0) log("   up to date");
+	}
+	return reports;
+}
+/** The journal as `ensure()` sees it. */
+function journalState(journal) {
+	return {
+		record: (key) => journal.record(key),
+		pending: (entry) => journal.pending(entry),
+		ready: (entry, id) => journal.ready(entry, id),
+		lastDeployedAt: journal.existed ? journal.state.lastDeployedAt : void 0
+	};
+}
+/** What a dry run reads, and the writes it does not make. */
+async function readOnlyState(store, stage) {
+	const stored = await store.read(stage);
+	return {
+		record: (key) => stored?.resources[key],
+		pending: async () => {},
+		ready: async () => {},
+		...stored ? { lastDeployedAt: stored.state.lastDeployedAt } : {}
+	};
+}
+//#endregion
+//#region src/secrets/stale.ts
+/**
+* Stored secrets an older gkm generated that now shadow a derived value.
+*
+* Before constructs, initialising a stage wrote an address for each app into
+* its custom secrets: `<APP>_DATABASE_URL` as a `postgresql://…@localhost`
+* URL with a password of its own, and `http://localhost:<port>` for a site or
+* an auth server. Those keys are now a construct's — `database.schema('AuthDatabase')`
+* provides `AUTH_DATABASE_URL`, `new BetterAuth('Auth')` provides `AUTH_URL`
+* — and a deploy derives them. A value the stage holds is a value set by hand,
+* and set by hand wins: the container is handed `localhost`, where nothing
+* answers, with a password no role has.
+*
+* So a deploy refuses such a stage rather than run it, naming each key and
+* the command that removes it. Nothing is deleted for the user: the value is
+* theirs, and only they can say it is stale. A URL that names a real host — a
+* managed database — is a deliberate choice and still wins.
+*/
+/** The kinds whose URL an older gkm wrote into a stage's secrets. */
+const ADDRESSED = /* @__PURE__ */ new Set([
+	"database",
+	"database-reader",
+	"database-schema",
+	"rest-api",
+	"site"
+]);
+/** Hosts that are this machine — never anything, inside a container. */
+const LOOPBACK = /* @__PURE__ */ new Set([
+	"localhost",
+	"127.0.0.1",
+	"[::1]",
+	"::1"
+]);
+/**
+* A stage holds a construct's address as a custom secret, pointing at
+* `localhost` — what an older `gkm secrets:init`, `gkm setup` or `gkm init`
+* generated. Set by hand wins over derived, so the app would be handed it.
+*/
+var StaleStageSecrets = class extends GkmError {
+	stage;
+	stale;
+	constructor(stage, stale) {
+		const one = stale.length === 1;
+		super(`The stage '${stage}' holds ${one ? "a value" : "values"} an older gkm generated for ${one ? "an address a construct" : "addresses constructs"} now ${one ? "provides" : "provide"}:\n` + stale.map((s) => `  ${s.key}: ${s.construct}'s, stored pointing at ${s.host}`).join("\n") + `
+A stored value wins over the derived one, so the app would be handed an address where nothing answers inside its container. Remove ${one ? "it" : "each"}, and the construct's own value is used:\n` + stale.map((s) => `  gkm secrets:unset ${s.key} --stage ${stage}`).join("\n") + "\nA managed service set with its real host is not affected.");
+		this.stage = stage;
+		this.stale = stale;
+		this.name = "StaleStageSecrets";
+	}
+};
+/** The host a stored value names, if it is a URL. */
+function hostOf(value) {
+	try {
+		return new URL(value).hostname;
+	} catch {
+		return;
+	}
+}
+/**
+* Each stored key that a construct provides an address for, holding an
+* address on this machine.
+*/
+function staleStageSecrets(manifest, supplied) {
+	const stale = [];
+	for (const [id, declaration] of Object.entries(manifest)) {
+		if (!ADDRESSED.has(declaration.kind)) continue;
+		const key = providedKeyFor(id, declaration.kind, "url");
+		const value = supplied[key];
+		if (value === void 0) continue;
+		const host = hostOf(value);
+		if (host === void 0 || !LOOPBACK.has(host)) continue;
+		stale.push({
+			key,
+			construct: id,
+			host
+		});
+	}
+	return stale.sort((a, b) => a.key.localeCompare(b.key));
+}
+/**
+* Refuse a stage whose stored secrets would shadow a construct's address with
+* `localhost`.
+*
+* @throws {StaleStageSecrets} naming each key and the command removing it
+*/
+function assertNoStaleSecrets(options) {
+	const stale = staleStageSecrets(options.manifest, options.supplied);
+	if (stale.length > 0) throw new StaleStageSecrets(options.stage, stale);
+}
+//#endregion
+//#region src/deploy/readiness.ts
+/**
+* Whether a stage is ready to be deployed: the one check, run once by every
+* deploy through a server target — after the stage's providers have created
+* what they create and written its keys, and before the target touches
+* anything.
+*
+* A build is not a deploy. Images carry no stage's keys, so a build-only run
+* (`gkm compose --build --push`) never calls this: a key the deploy itself
+* writes — a provider's bucket URL — is not there yet when CI builds, and
+* must not stop the build.
+*/
+/**
+* The stage has every key it needs, read from its secrets as the providers
+* left them:
+*
+* 1. no kind it declares is one the stage set to `false`;
+* 2. its mail and storage are its own — or a dev service, where allowed,
+*    reported once, loudly;
+* 3. what its providers created is still there, and its key reaches it;
+* 4. no key holds an address an older gkm stored for what a construct now
+*    provides;
+* 5. each third party's credentials match their construct's schema.
+*
+* The local stage derives its mail and storage, so only 4 and 5 apply to it.
+*
+* @throws {StageProviderDisabled}
+* @throws {ExternalServicesNotConfigured} naming every missing key at once
+* @throws {StaleStageSecrets}
+* @throws {CredentialsInvalid}
+*/
+async function assertStageReady(ctx) {
+	const { workspace, manifest, stage } = ctx;
+	const supplied = (await ctx.secrets.read())?.custom ?? {};
+	if (stage !== workspace.stages.local) {
+		assertStageProvidersEnabled(workspace, manifest, stage);
+		const domain = workspace.domains?.[stage];
+		const services = externalServices({
+			stage,
+			declarations: stageServiceDeclarations({
+				manifest,
+				...ctx.runnables ? { runnables: ctx.runnables } : {}
+			}),
+			supplied,
+			allow: ctx.allowDevServices,
+			...domain ? { domain } : {},
+			providers: stageProviderNotes(workspace, stage)
+		});
+		if (services.missing.length > 0) throw new ExternalServicesNotConfigured(stage, services.missing);
+		reportDevServices(ctx, devServicesUsed(services));
+		const verified = await verifyStageProviders({
+			workspace,
+			manifest,
+			stage,
+			secrets: supplied,
+			resources: (await ctx.state.read(stage))?.resources ?? {},
+			log: (line) => ctx.logger.info(line)
+		});
+		for (const line of verified) ctx.logger.info(`✓ ${line} verified`);
+	}
+	assertNoStaleSecrets({
+		manifest,
+		stage,
+		supplied
+	});
+	await assertStageCredentials({
+		root: workspace.root,
+		patterns: constructGlobs(workspace),
+		manifest,
+		stage,
+		supplied
+	});
+}
+//#endregion
+//#region src/deploy/orchestrate.ts
+/**
+* The run around a target: what every deploy does whatever it deploys
+* through.
+*
+* It loads the workspace, resolves the target, works out the apps and the
+* identity, takes the stage's lock, and calls the target's phases in order,
+* reporting each as it starts, finishes or fails. Everything that is about
+* *where* the stage goes is the target's.
+*/
+/** Apps were asked for by name that the workspace does not have. */
+var UnknownDeployApps = class extends GkmError {
+	apps;
+	available;
+	constructor(apps, available) {
+		super(`Unknown apps: ${apps.join(", ")}\nAvailable apps: ${available.join(", ")}`);
+		this.apps = apps;
+		this.available = available;
+		this.name = "UnknownDeployApps";
+	}
+};
+/** Every app asked for deploys through some other target. */
+var NoDeployableApps = class extends GkmError {
+	stage;
+	target;
+	constructor(stage, target) {
+		super(`No apps to deploy through "${target}": every selected app deploys somewhere else. Pick the target with --target, or set each app's deploy in gkm.config.ts.`);
+		this.stage = stage;
+		this.target = target;
+		this.name = "NoDeployableApps";
+	}
+};
+/** A build-only run through a target with no build phase. */
+var TargetBuildsNothing = class extends GkmError {
+	target;
+	constructor(target) {
+		super(`"${target}" has no build phase, so a build-only run would do nothing. Deploy it in full, or build through a target that builds images (compose).`);
+		this.target = target;
+		this.name = "TargetBuildsNothing";
+	}
+};
+/** A failed rollback, after the failure that called for it. */
+var RollbackFailed = class extends Error {
+	target;
+	failure;
+	constructor(target, failure, cause) {
+		super(`Deploying through "${target}" failed, and so did rolling it back: ${cause instanceof Error ? cause.message : String(cause)}. The stage may be part-released; deploy again, or roll it back by hand. The first failure: ${failure instanceof Error ? failure.message : String(failure)}`, { cause });
+		this.target = target;
+		this.failure = failure;
+		this.name = "RollbackFailed";
+	}
+};
+/**
+* Generate image tag from stage and timestamp
+*/
+function generateTag(stage) {
+	return `${stage}-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19)}`;
+}
+/** Why an app that deploys through another target is left out. */
+function elsewhere(target, stage) {
+	const instead = builtinTarget(target)?.instead?.(stage);
+	if (instead) return `it deploys through "${target}" — ${instead}`;
+	return `it deploys through "${target}" — run \`gkm deploy --target ${target} --stage ${stage}\``;
+}
+/**
+* Deploy a workspace's stage through its target.
+*
+* The engine under `deploy()` and `gkm deploy`. It never prompts and never
+* exits: credentials come from `ctx.credentials`, progress goes to
+* `ctx.emit` and to `output`, and every failure is thrown.
+*
+* @internal
+*/
+async function runDeploy(source, request, ctx) {
+	const { stage } = request;
+	const redactor = ctx.redactor ?? new Redactor();
+	const emit = (event) => ctx.emit(event.type === "log" ? {
+		...event,
+		message: redactor.redact(event.message)
+	} : event);
+	/** Run one phase between its events. */
+	const phase = async (name, body) => {
+		ctx.signal?.throwIfAborted();
+		emit({
+			type: "phase.started",
+			phase: name
+		});
+		try {
+			const value = await body();
+			emit({
+				type: "phase.finished",
+				phase: name
+			});
+			return value;
+		} catch (error) {
+			emit({
+				type: "phase.failed",
+				phase: name,
+				error: eventError(error)
+			});
+			throw error;
+		}
+	};
+	ctx.signal?.throwIfAborted();
+	emit({
+		type: "phase.started",
+		phase: "validate"
+	});
+	let prepared;
+	try {
+		prepared = await prepare(source, request, ctx, emit, redactor);
+	} catch (error) {
+		emit({
+			type: "phase.failed",
+			phase: "validate",
+			error: eventError(error)
+		});
+		throw error;
+	}
+	const { resolved, phaseCtx, store } = prepared;
+	const { target } = resolved;
+	const resources = !ctx.buildOnly && phaseCtx.stage !== phaseCtx.workspace.stages.local;
+	const provision = async () => {
+		if (!request.skipDns && resolved.target.runtime === "server") try {
+			await dnsCredentials(phaseCtx.stage, stageDnsDomains(phaseCtx.stage, phaseCtx.workspace.domains, phaseCtx.workspace.dns), ctx.credentials);
+		} catch (error) {
+			emit({
+				type: "phase.failed",
+				phase: "validate",
+				error: eventError(error)
+			});
+			throw error;
+		}
+		await provisionResources(phaseCtx, request, ctx, store, emit);
+	};
+	if (ctx.dryRun) {
+		if (resources) await provision();
+		const run = await validate(phaseCtx, emit, () => readyToDeploy(target, phaseCtx));
+		await phase("plan", () => target.plan(phaseCtx, run));
+		return target.result(phaseCtx, run);
+	}
+	if (ctx.buildOnly) {
+		if (!target.build) throw new TargetBuildsNothing(resolved.name);
+		const run = await validate(phaseCtx, emit, () => target.validate(phaseCtx));
+		await phase("build", () => target.build(phaseCtx, run));
+		return target.result(phaseCtx, run);
+	}
+	let lock;
+	try {
+		assertStateOutlivesRun(phaseCtx.workspace, stage, "deploy");
+		lock = await store.lock(stage, { operation: "deploy" });
+	} catch (error) {
+		emit({
+			type: "phase.failed",
+			phase: "validate",
+			error: eventError(error)
+		});
+		throw error;
+	}
+	try {
+		try {
+			await assertStateRoom(store, stage);
+		} catch (error) {
+			emit({
+				type: "phase.failed",
+				phase: "validate",
+				error: eventError(error)
+			});
+			throw error;
+		}
+		if (resources) await provision();
+		const run = await validate(phaseCtx, emit, () => readyToDeploy(target, phaseCtx));
+		if (target.provision) await phase("provision", () => target.provision(phaseCtx, run));
+		if (target.build) await phase("build", () => target.build(phaseCtx, run));
+		let releasing = "release";
+		try {
+			await phase("release", () => target.release(phaseCtx, run));
+			releasing = "verify";
+			if (target.verify) await phase("verify", () => target.verify(phaseCtx, run));
+		} catch (error) {
+			if (ctx.signal?.aborted || !target.capabilities.rollback) throw error;
+			if (!target.rollback) throw error;
+			try {
+				await phase("rollback", () => target.rollback(phaseCtx, run, {
+					phase: releasing,
+					error
+				}));
+			} catch (rollbackError) {
+				throw new RollbackFailed(resolved.name, error, rollbackError);
+			}
+			throw error;
+		}
+		return await target.result(phaseCtx, run);
+	} finally {
+		await lock.release();
+	}
+}
+/**
+* The stage's providers, run inside the validate phase. A dry run plans them
+* and, so the checks after it see the stage as the run would leave it, reads
+* the keys they would write as placeholders.
+*/
+async function provisionResources(phaseCtx, request, ctx, store, emit) {
+	try {
+		const reports = await provisionStage({
+			workspace: phaseCtx.workspace,
+			stage: phaseCtx.stage,
+			manifest: phaseCtx.manifest,
+			runnables: phaseCtx.runnables ?? {},
+			secrets: phaseCtx.secrets,
+			state: store,
+			dryRun: ctx.dryRun,
+			...request.rotateKeys ? { rotateKeys: true } : {},
+			...request.retireOldKeys ? { retireOldKeys: true } : {},
+			...ctx.home ? { home: ctx.home } : {},
+			log: (line) => phaseCtx.logger.info(line)
+		});
+		if (!ctx.dryRun) return;
+		const planned = reports.flatMap((r) => r.planned);
+		if (planned.length === 0) return;
+		const secrets = phaseCtx.secrets;
+		phaseCtx.secrets = {
+			...secrets,
+			async read() {
+				const stored = await secrets.read() ?? initStageSecrets(phaseCtx.stage);
+				const custom = { ...stored.custom };
+				for (const key of planned) custom[key] ??= PLANNED_BY_THE_DEPLOY;
+				return {
+					...stored,
+					custom
+				};
+			}
+		};
+	} catch (error) {
+		emit({
+			type: "phase.failed",
+			phase: "validate",
+			error: eventError(error)
+		});
+		throw error;
+	}
+}
+/** What a dry run reads for a key its providers would write. */
+const PLANNED_BY_THE_DEPLOY = "s3://planned-by-this-deploy";
+/**
+* What a deploy validates: the stage ready to be deployed — every key it
+* needs, read as its providers left them — then what the target would run,
+* then whatever only the target checks. A build-only run validates the
+* target's run alone: it calls neither readiness check.
+*/
+async function readyToDeploy(target, phaseCtx) {
+	if (target.runtime === "server") await assertStageReady(phaseCtx);
+	const run = await target.validate(phaseCtx);
+	await target.ready?.(phaseCtx, run);
+	return run;
+}
+/** `body`, then the run's `deploy.started`, inside the validate phase. */
+async function validate(phaseCtx, emit, body) {
+	try {
+		const run = await body();
+		const skipped = new Set(phaseCtx.skipped.map((s) => s.app));
+		emit({
+			type: "deploy.started",
+			stage: phaseCtx.stage,
+			target: phaseCtx.target,
+			identity: phaseCtx.identity.key,
+			tag: phaseCtx.tag,
+			apps: phaseCtx.apps.filter((app) => !skipped.has(app)),
+			dryRun: phaseCtx.dryRun
+		});
+		emit({
+			type: "phase.finished",
+			phase: "validate"
+		});
+		return run;
+	} catch (error) {
+		emit({
+			type: "phase.failed",
+			phase: "validate",
+			error: eventError(error)
+		});
+		throw error;
+	}
+}
+/** Everything the phases are handed, worked out before the first of them. */
+async function prepare(source, request, ctx, emit, redactor) {
+	const { stage } = request;
+	const configured = typeof source === "function" ? await source() : source;
+	const local = stage === configured.stages.local;
+	if (!local) assertDeployedStage(configured.stages, stage);
+	const targetName = request.target ?? configured.deploy?.default ?? "dokploy";
+	const resolved = await resolveTarget(targetName, {
+		workspace: configured,
+		stage,
+		...ctx.targets ? { host: ctx.targets } : {}
+	});
+	if (local && !resolved.target.capabilities.localStage) assertDeployedStage(configured.stages, stage);
+	const options = await parseTargetOptions(resolved);
+	const allowDevServices = request.allowDevServices === true;
+	if (allowDevServices && resolved.target.runtime === "aws") throw new DevServicesNeedServerTarget(targetName);
+	const runnables = {};
+	const background = {};
+	const manifest = await discover({
+		patterns: constructGlobs(configured),
+		cwd: configured.root,
+		runnables,
+		background
+	});
+	resolveStageTelemetry({
+		...configured.deploy?.telemetry ? { telemetry: configured.deploy.telemetry } : {},
+		stage,
+		local,
+		target: targetName,
+		runtime: resolved.target.runtime,
+		selfHosted: resolved.target.capabilities.selfHostedTelemetry === true,
+		used: usesTelemetry(manifest)
+	});
+	const units = derivedApps(manifest, configured);
+	const workspace = Object.keys(units).length > 0 ? {
+		...configured,
+		apps: units
+	} : configured;
+	const identity = deployIdentity(workspace, stage);
+	const tag = request.tag ?? (resolved.target.tag ? await resolved.target.tag({
+		cwd: workspace.root,
+		stage
+	}) : generateTag(stage));
+	const buildOrder = getAppBuildOrder(workspace);
+	let selected = buildOrder;
+	if (request.apps && request.apps.length > 0) {
+		const unknown = request.apps.filter((name) => !workspace.apps[name]);
+		if (unknown.length > 0) throw new UnknownDeployApps(unknown, Object.keys(workspace.apps));
+		selected = buildOrder.filter((name) => request.apps.includes(name));
+	}
+	const skipped = [];
+	const skip = (app, reason) => {
+		skipped.push({
+			app,
+			reason
+		});
+		emit({
+			type: "app.skipped",
+			app,
+			reason
+		});
+	};
+	const byDefault = configured.deploy?.default ?? "dokploy";
+	const apps = selected.filter((name) => {
+		const own = workspace.apps[name].resolvedDeployTarget;
+		const deploysThrough = own === byDefault ? targetName : own;
+		if (deploysThrough === targetName) return true;
+		skip(name, elsewhere(deploysThrough, stage));
+		return false;
+	});
+	if (apps.length === 0) throw new NoDeployableApps(stage, targetName);
+	const store = await createStateStore({
+		config: stage === workspace.stages.local ? void 0 : workspace.state,
+		workspaceRoot: workspace.root,
+		workspaceName: workspace.name,
+		namespace: workspace.deploy?.namespace
+	});
+	const secrets = await deploySecrets(workspace, stage, redactor, { ...ctx.home ? { home: ctx.home } : {} });
+	const line = (level) => (message) => emit({
+		type: "log",
+		level,
+		message
+	});
+	const logger = {
+		info: line("info"),
+		warn: line("warn"),
+		error: line("error")
+	};
+	return {
+		resolved,
+		phaseCtx: {
+			target: targetName,
+			cwd: workspace.root,
+			stage,
+			tag,
+			tagGiven: request.tag !== void 0,
+			apps,
+			skipped,
+			identity,
+			workspace,
+			manifest,
+			runnables,
+			background,
+			options,
+			dryRun: ctx.dryRun,
+			atomic: request.atomic ?? false,
+			allowDevServices,
+			...request.skipDns ? { skipDns: true } : {},
+			credentials: ctx.credentials,
+			state: store,
+			secrets,
+			logger,
+			signal: ctx.signal ?? new AbortController().signal,
+			childOutput: ctx.childOutput ?? "inherit",
+			emit,
+			skip,
+			name: (resource) => applicationName(identity, resource)
+		},
+		store
+	};
+}
+//#endregion
+//#region src/deploy/deploy.ts
+/**
+* `deploy()`: a deploy as a library call.
+*
+* `gkm deploy` could only be driven from an interactive terminal: it prompted
+* for what it lacked and exited the process on failure, worked out of
+* `process.cwd()`, and reported progress by printing. Here the caller says
+* where the project is, hands over the credentials and a signal, and gets back
+* a run — events to iterate while it goes, and a structured result at the end.
+* Nothing below this asks a person anything or ends the process; `gkm deploy`
+* is a thin wrapper that does both.
+*/
+/**
+* Every event a run emits, kept so that each iteration — however late it
+* starts — sees the run from its first event to its last.
+*/
+var EventLog = class {
+	events = [];
+	closed = false;
+	waiting = [];
+	push(event) {
+		this.events.push(event);
+		this.wake();
+	}
+	close() {
+		this.closed = true;
+		this.wake();
+	}
+	wake() {
+		const waiting = this.waiting;
+		this.waiting = [];
+		for (const resume of waiting) resume();
+	}
+	async *iterate() {
+		let next = 0;
+		while (true) if (next < this.events.length) yield this.events[next++];
+		else if (this.closed) return;
+		else await new Promise((resume) => this.waiting.push(resume));
+	}
+};
+function forward(logger, level, message) {
+	if (!logger) return;
+	if (level === "info") logger.info(message);
+	else if (level === "error" && logger.error) logger.error(message);
+	else logger.warn(message);
+}
+/**
+* Deploy a project's stage.
+*
+* ```ts
+* import { deploy } from '@geekmidas/cli/deploy';
+*
+* const run = deploy({ cwd: '/srv/checkouts/shop', stage: 'production' });
+* for await (const event of run) {
+*   if (event.type === 'app.deployed') console.log(event.app, event.url);
+* }
+* const result = await run.result;
+* ```
+*
+* The run starts at once; iterating it is optional, and an iteration started
+* late still sees every event from the first.
+*/
+function deploy(input) {
+	const log = new EventLog();
+	const redactor = new Redactor();
+	const emit = (event) => {
+		const masked = event.type === "log" ? {
+			...event,
+			message: redactor.redact(event.message)
+		} : event;
+		log.push(masked);
+		if (masked.type === "log") forward(input.logger, masked.level, masked.message);
+	};
+	const ctx = {
+		emit,
+		credentials: input.credentials ?? storedCredentials({ home: input.home ?? gkmHome() }),
+		dryRun: input.dryRun ?? false,
+		...input.buildOnly ? { buildOnly: true } : {},
+		home: input.home ?? gkmHome(),
+		redactor,
+		...input.signal ? { signal: input.signal } : {},
+		...input.childOutput ? { childOutput: input.childOutput } : {},
+		...input.targets ? { targets: input.targets } : {}
+	};
+	const result = withOutput((level, message) => emit({
+		type: "log",
+		level,
+		message
+	}), async () => {
+		try {
+			input.signal?.throwIfAborted();
+			const sandbox = input.sandbox ?? new LocalSandbox({ root: findWorkspaceRoot(resolve(input.cwd)) });
+			const deployed = await withSandbox(sandbox, () => runDeploy(() => load(input, sandbox), {
+				stage: input.stage,
+				...input.target ? { target: input.target } : {},
+				...input.tag ? { tag: input.tag } : {},
+				...input.apps ? { apps: input.apps } : {},
+				...input.atomic ? { atomic: true } : {},
+				...input.allowDevServices ? { allowDevServices: input.allowDevServices } : {},
+				...input.skipDns ? { skipDns: true } : {},
+				...input.rotateKeys ? { rotateKeys: true } : {},
+				...input.retireOldKeys ? { retireOldKeys: true } : {}
+			}, ctx));
+			emit({
+				type: "deploy.finished",
+				result: deployed
+			});
+			return deployed;
+		} catch (error) {
+			emit({
+				type: "deploy.failed",
+				error: eventError(error)
+			});
+			throw error;
+		} finally {
+			log.close();
+		}
+	});
+	result.catch(() => {});
+	return {
+		result,
+		[Symbol.asyncIterator]: () => log.iterate()
+	};
+}
+/**
+* The workspace at `input.cwd`. The stage is checked by the run, once it
+* knows the target: one that runs on this machine may take the local stage.
+*/
+async function load(input, sandbox) {
+	const { workspace } = await loadWorkspaceConfig(resolve(input.cwd), { sandbox });
+	return workspace;
+}
+//#endregion
+export { UnknownDeployApps as a, bucketName as c, awsEndpoint as d, awsProvisioningCredentials as f, TargetBuildsNothing as i, iamUserName as l, NoDeployableApps as n, backupsUserName as o, RollbackFailed as r, IAM_USER_PATH as s, deploy as t, awsClientConfig as u };
+
+//# sourceMappingURL=deploy-H2S8_mTx.mjs.map