@geekmidas/manifest 10.0.0-alpha.15 → 10.0.0-alpha.151

package/dist/index.cjs

@@ -33,6 +33,27 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 * this.
 */
 const DEFAULT_POSTGRES_VERSION = 18;
+/** A site's subdomain that means every subdomain — see `SiteDeclaration`. */
+const WILDCARD_SUBDOMAIN = "*";
+/**
+* Whether a declaration is a site answering on every subdomain.
+*/
+function isWildcardSite(declaration) {
+	return declaration?.kind === "site" && declaration.subdomain === "*";
+}
+/**
+* What a `Telemetry` node provides to each process with an edge to it.
+*
+* `OTEL_SERVICE_NAME` is resolved per process — the app's name — so it is
+* listed here but composed by whichever target hands it over.
+*/
+const TELEMETRY_KEYS = [
+	"OTEL_EXPORTER_OTLP_ENDPOINT",
+	"OTEL_EXPORTER_OTLP_HEADERS",
+	"OTEL_SERVICE_NAME",
+	"OTEL_TRACES_SAMPLER",
+	"OTEL_TRACES_SAMPLER_ARG"
+];
 /**
 * What each kind may derive from.
 *
@@ -57,21 +78,27 @@ const DERIVES_FROM = {
 const PUBLIC = {
 	objects: [],
 	"file-server": ["url"],
-	email: [],
+	email: ["inboxUrl"],
+	inbox: [],
 	database: [],
 	"database-reader": [],
 	"database-schema": [],
 	cache: [],
 	secret: [],
 	credential: [],
+	encryption: [],
 	"rest-api": ["url"],
+	"websocket-api": ["url"],
 	queue: [],
 	topic: [],
 	oidc: ["issuer", "audience"],
+	"external-api": [],
 	function: [],
 	cron: [],
+	"mobile-app": [],
 	site: ["url"],
-	worker: []
+	worker: [],
+	telemetry: []
 };
 //#endregion
 //#region src/errors.ts
@@ -846,7 +873,9 @@ function cookieDomain(urls) {
 * cannot catch anything.
 */
 function providedKeyFor(id, kind, role) {
-	return kind === "secret" ? environmentCase(id) : provideKey(id, role);
+	if (kind === "secret") return environmentCase(id);
+	if (kind === "telemetry") return "OTEL_EXPORTER_OTLP_ENDPOINT";
+	return provideKey(id, role);
 }
 //#endregion
 //#region src/derive.ts
@@ -907,12 +936,17 @@ function provisionOrder(manifest) {
 */
 function dependenciesOf(declaration) {
 	const own = "dependencies" in declaration ? declaration.dependencies ?? [] : [];
-	const calls = "calls" in declaration ? declaration.calls ?? [] : [];
-	const nested = declaration.kind === "rest-api" ? declaration.endpoints.flatMap((endpoint) => endpoint.dependencies) : [];
+	const auth = (declaration.kind === "rest-api" || declaration.kind === "websocket-api") && declaration.auth ? [declaration.auth] : [];
+	const nested = declaration.kind === "rest-api" ? declaration.endpoints.flatMap((endpoint) => endpoint.dependencies) : declaration.kind === "websocket-api" ? (declaration.routes ?? []).flatMap((route) => route.dependencies) : [];
+	const telemetry = "telemetry" in declaration && typeof declaration.telemetry === "string" ? [{
+		target: declaration.telemetry,
+		kind: "telemetry"
+	}] : [];
 	return [
 		...own,
-		...calls,
-		...nested
+		...auth,
+		...nested,
+		...telemetry
 	];
 }
 /**
@@ -946,11 +980,13 @@ function dependentsOf(manifest, id) {
 const PUBLIC_PREFIX = {
 	static: "VITE_",
 	tanstack: "VITE_",
-	next: "NEXT_PUBLIC_"
+	next: "NEXT_PUBLIC_",
+	expo: "EXPO_PUBLIC_"
 };
 /**
 * The keys a site's bundle needs, mapped to the key each value comes from —
-* `{ VITE_API_URL: 'API_URL' }`.
+* `{ VITE_API_URL: 'API_URL' }` — its edges' public values, and a site's own
+* address (`{ VITE_WEB_URL: 'WEB_URL' }`).
 *
 * A rename, not a second derivation: `API_URL` is resolved once, by whatever
 * resolved it for the server, and the site reads the same value under the name
@@ -969,6 +1005,14 @@ const PUBLIC_PREFIX = {
 function publicEnvFor(declaration, manifest) {
 	const prefix = PUBLIC_PREFIX[declaration.variant];
 	const keys = {};
+	if (declaration.kind === "site") {
+		const own = provideKey(declaration.id, "url");
+		keys[`${prefix}${own}`] = own;
+	}
+	if (isWildcardSite(declaration)) for (const role of ["domain", "protectedSubdomains"]) {
+		const key = provideKey(declaration.id, role);
+		keys[`${prefix}${key}`] = key;
+	}
 	for (const edge of declaration.dependencies) {
 		const target = manifest[edge.target];
 		if (!target) continue;
@@ -980,36 +1024,425 @@ function publicEnvFor(declaration, manifest) {
 	return keys;
 }
 //#endregion
-//#region src/index.ts
-/** Flatten a manifest field (array or partitioned) into a plain array. */
-function flattenManifestField(field) {
-	if (!field) return [];
-	return Array.isArray(field) ? [...field] : Object.values(field).flat();
+//#region src/derived.ts
+/** Where a processor keeps what it made, in the bucket it reads. */
+const DERIVED_PREFIX = ".gkm-derived/";
+/** How long a derivative is kept when its file server does not say. */
+const DEFAULT_DERIVED_DAYS = 30;
+/**
+* The days a bucket keeps what is under each prefix: what it declared, and —
+* when a file server over it has processors — the derived prefix, for the
+* longest any of those servers asked. `undefined` when it expires nothing.
+*/
+function bucketExpiry(manifest, bucketId) {
+	const expire = { ...manifest[bucketId]?.expire ?? {} };
+	const processed = Object.values(manifest).filter((d) => d.kind === "file-server" && d.of === bucketId && (d.processors?.length ?? 0) > 0);
+	if (processed.length > 0 && expire[".gkm-derived/"] === void 0) expire[DERIVED_PREFIX] = Math.max(...processed.map((s) => s.derivedDays ?? 30));
+	return Object.keys(expire).length > 0 ? expire : void 0;
+}
+//#endregion
+//#region src/encryption.ts
+/**
+* The `kms://` URL an `Encryption` construct reads on AWS.
+*
+* Here because two packages meet on it: `@geekmidas/cloud` composes it from
+* the keys it provisioned, and `@geekmidas/constructs` parses it to reach
+* them. One function, so the two cannot disagree about a parameter's name.
+*/
+const KMS_SCHEME = "kms:";
+/**
+* `kms://<region>?key=<key arn>&index=<hmac key arn>[&endpoint=<url>]`
+*
+* `endpoint` reaches an emulator instead of AWS — floci, locally and in tests —
+* the same parameter an `sns://` connection string carries for the same reason.
+*/
+function kmsUrl(input) {
+	const query = new URLSearchParams({
+		key: input.key,
+		index: input.index,
+		...input.endpoint ? { endpoint: input.endpoint } : {}
+	});
+	return `${KMS_SCHEME}//${input.region}?${query}`;
+}
+//#endregion
+//#region src/external.ts
+/** The key in a by-stage `url` that answers for every stage not listed. */
+const DEFAULT_STAGE_URL = "default";
+/**
+* Where an external API answers on a deployed stage.
+*
+* One URL answers every stage; a record answers by stage name, falling back
+* to `default`. Read at build and deploy, so a stage nobody gave a URL fails
+* there — with the stage named — rather than at the first request.
+*
+* @throws {NoUrlForStage} when a record names neither the stage nor a default.
+*/
+function externalApiUrl(declaration, stage) {
+	const { url } = declaration;
+	if (typeof url === "string") return url;
+	const resolved = url[stage] ?? url["default"];
+	if (!resolved) throw new NoUrlForStage(declaration.id, stage, Object.keys(url));
+	return resolved;
+}
+/** An external API's `url` record has nothing for the stage being deployed. */
+var NoUrlForStage = class extends Error {
+	id;
+	stage;
+	stages;
+	constructor(id, stage, stages) {
+		super(`'${id}' has no URL for the stage '${stage}': its url names ${stages.length ? stages.map((s) => `'${s}'`).join(", ") : "no stages"}. Add '${stage}', or a '${DEFAULT_STAGE_URL}' for every stage not listed.`);
+		this.id = id;
+		this.stage = stage;
+		this.stages = stages;
+		this.name = "NoUrlForStage";
+	}
+};
+//#endregion
+//#region src/headers.ts
+/**
+* Headers gkm reserves for its own services' calls to each other.
+*
+* Shared by `@geekmidas/constructs`, which sends and reads them, and
+* `@geekmidas/cli`, whose edges strip them from every request that arrives
+* from outside — so the two cannot name them differently.
+*/
+/**
+* The address of the client a service-to-service call is made on behalf of.
+*
+* An API asking its auth server for a session sends the client's address in
+* this rather than `X-Forwarded-For`: a forwarding header marks a request as
+* outside traffic, which would start the auth server's span in a new trace,
+* and the address is still needed — Better Auth rate-limits per client.
+*
+* Reserved: the stack's edge (Caddy, Traefik, the `gkm dev` edge) removes it
+* from every request that does not carry the stack's token
+* ({@link EDGE_TOKEN_HEADER}), and the auth server ignores it on any request
+* that neither carries the token nor is an internal caller's, so it cannot be
+* spoofed from outside.
+*/
+const CLIENT_IP_HEADER = "x-gkm-client-ip";
+/**
+* The token a service of a stack sends beside {@link CLIENT_IP_HEADER} when
+* it calls a sibling through the stack's edge, at its public address.
+*
+* A request carries a forwarding header once it has passed an edge, so the
+* peer alone no longer says it came from inside the stack. The token does:
+* it is derived from the stage's seed, handed to every process of the stack
+* as {@link EDGE_TOKEN_KEY}, and known to the edge. The edge keeps
+* `x-gkm-client-ip` only on a request carrying it, and strips the header from
+* every other; the auth server honours the header only from an internal
+* caller or a request carrying its own token. A browser never has it.
+*/
+const EDGE_TOKEN_HEADER = "x-gkm-edge-token";
+/** Where a stack's processes read the token {@link EDGE_TOKEN_HEADER} carries. */
+const EDGE_TOKEN_KEY = "GKM_EDGE_TOKEN";
+//#endregion
+//#region src/inbox.ts
+/** The event type a received message is announced as on its inbox's topic. */
+const INBOX_EVENT = "email.received";
+/**
+* Where an inbox's raw messages are kept in its bucket: SES's S3 action
+* writes `<prefix><message id>`, and `gkm dev` and the test mailbox write the
+* same layout.
+*/
+const INBOX_MESSAGES_PREFIX = "messages/";
+/**
+* The recipient `address` is to `inbox` on `domain`, or `undefined` when the
+* inbox does not receive at it.
+*
+* - The local part is a declared address, or one with a `+tag` after it.
+* - Without `subdomains`, the domain is the stage's domain itself; with it,
+*   exactly one label in front of the stage's domain — `acme.fixwell.example`
+*   — and never the bare domain, whose mail would belong to no tenant.
+*
+* Case-insensitive, as mail addresses are in practice.
+*/
+function inboxRecipient(address, inbox, domain) {
+	const normalized = address.trim().toLowerCase();
+	const at = normalized.lastIndexOf("@");
+	if (at <= 0) return void 0;
+	const localPart = normalized.slice(0, at);
+	const host = normalized.slice(at + 1);
+	const base = domain.toLowerCase();
+	let subdomain;
+	if (inbox.subdomains) {
+		if (!host.endsWith(`.${base}`)) return void 0;
+		subdomain = host.slice(0, -(base.length + 1));
+		if (!subdomain || subdomain.includes(".")) return void 0;
+	} else if (host !== base) return;
+	const plus = localPart.indexOf("+");
+	const local = plus === -1 ? localPart : localPart.slice(0, plus);
+	const tag = plus === -1 ? void 0 : localPart.slice(plus + 1);
+	if (!inbox.addresses.some((declared) => declared.toLowerCase() === local)) return;
+	return {
+		address: normalized,
+		local,
+		...tag ? { tag } : {},
+		...subdomain ? { subdomain } : {}
+	};
+}
+/**
+* The recipients a deployed receipt rule names for `inbox` on `domain`.
+*
+* Without `subdomains`, each address on the domain: SES matches an address
+* condition's `+label` variants too, so `requests@` takes `requests+t_8f3k@`.
+* With it, every subdomain (`.fixwell.example`): a condition cannot say
+* "`requests` on any subdomain", so the rule takes the subdomains' mail and
+* the decoder in front of the handler drops what {@link inboxRecipient} does
+* not match.
+*/
+function receiptRecipients(inbox, domain) {
+	const base = domain.toLowerCase();
+	return inbox.subdomains ? [`.${base}`] : inbox.addresses.map((address) => `${address.toLowerCase()}@${base}`);
+}
+//#endregion
+//#region src/migrations.ts
+/** Where every construct's folder lives, from the project root. */
+const MIGRATIONS_ROOT = "db";
+/** The two folders a construct's folder holds, and nothing else. */
+const DATABASE_FOLDERS = ["migrations", "seeds"];
+/**
+* The constructs that take migrations, parents before the tenants inside them.
+*
+* A database and each schema tenant: every one has an owner role and a schema
+* of its own, and so a history of its own. A reader has neither — it reads its
+* parent's schema — and a cache's table is created by provisioning, not by a
+* migration anyone writes.
+*/
+function migrationTargets(manifest) {
+	return provisionOrder(manifest).flatMap((id) => {
+		const declaration = manifest[id];
+		if (!declaration) return [];
+		if (declaration.kind === "database") return [target(id)];
+		if (declaration.kind === "database-schema") return [{
+			...target(id),
+			of: declaration.of
+		}];
+		return [];
+	});
+}
+/**
+* A construct's folder, relative to the project root.
+*
+* Named by the construct — `AuthDatabase` is `db/auth-database` — in the case
+* every other name outside TypeScript takes. Lowercase, because a folder that
+* differs from another only in case is two folders on Linux and one on a Mac;
+* and `canonicalId` reads it back to the construct exactly, which is how a
+* folder naming nothing is caught rather than skipped.
+*/
+function databaseFolder(id) {
+	return `db/${kebabCase(id)}`;
+}
+/** Where a construct's migrations live: `db/auth-database/migrations`. */
+function migrationFolder(id) {
+	return `${databaseFolder(id)}/migrations`;
+}
+/**
+* Where a construct's seeds live: `db/auth-database/seeds`.
+*
+* Reference data the app needs to run — a permission catalogue, roles, lookup
+* tables. Seeds are upserts run on every pass, after the migrations, so a
+* changed seed is applied by running it again. Sample data is factories'.
+*/
+function seedFolder(id) {
+	return `${databaseFolder(id)}/seeds`;
+}
+function target(id) {
+	return {
+		id,
+		folder: databaseFolder(id),
+		migrations: migrationFolder(id),
+		seeds: seedFolder(id)
+	};
+}
+//#endregion
+//#region src/mobile.ts
+/**
+* How a mobile app is reached: its URL scheme, and the origins a surface trusts
+* for it.
+*
+* Stated once, here, because three targets ask — the local one (`gkm dev`,
+* `gkm test`), Dokploy and AWS — and a scheme one of them derived differently
+* would be an app whose sign-in callback the auth server refuses on exactly one
+* of them.
+*/
+/**
+* An app's scheme: the one given, or the project's name made a valid scheme.
+*
+* One for every stage. A development build and the store build register the
+* same scheme, so the auth server of whichever stage a build talks to trusts
+* it, and nothing about the app differs between stages but its URLs.
+*
+* A scheme is a letter followed by letters, digits, `+`, `-` or `.` — so
+* `Corner Shop` becomes `corner-shop`, and a name that starts with a digit gets a
+* leading `app`.
+*/
+function schemeBase(project, given) {
+	const raw = (given ?? project).toLowerCase().replace(/[^a-z0-9+.-]+/g, "-").replace(/^-+|-+$/g, "");
+	if (!raw) return "app";
+	return /^[a-z]/.test(raw) ? raw : `app${raw}`;
+}
+/**
+* The origins a surface trusts for a mobile caller.
+*
+* Better Auth's Expo plugin sends the app's scheme as its origin
+* (`shop://`), and a link can carry a path after it (`shop://*`).
+* In development, Expo Go sends `exp://<host>:<port>` instead — so a local
+* stage adds the hosts a device actually reaches Metro on, and Metro's port
+* when the target placed it: a whole subnet is not trusted because one phone
+* is on it.
+*/
+function mobileOrigins(scheme, metro) {
+	return [
+		`${scheme}://`,
+		`${scheme}://*`,
+		...(metro?.hosts ?? []).flatMap((host) => [`exp://${host}:${metro?.port ?? "*"}`, `exp://${host}:${metro?.port ?? "*"}/**`])
+	];
+}
+/** Whether an origin is a web one — what a cookie domain is derived from. */
+function isWebOrigin(origin) {
+	return origin.startsWith("http://") || origin.startsWith("https://");
+}
+//#endregion
+//#region src/origins.ts
+/**
+* Whether a request from `origin` comes from one of `trusted`.
+*
+* An entry matches exactly — scheme, host and port — or, written
+* `https://*.example.com`, matches any one label in place of the `*`:
+* `https://acme.example.com`, never `https://example.com` and never
+* `https://a.b.example.com`. That is the origin a wildcard site's tenants
+* call from, and it is as wide as a wildcard certificate, no wider.
+*
+* A bare `*` trusts nothing: a surface that answers any origin has not said
+* which sites are its own.
+*/
+function trustsOrigin(origin, trusted) {
+	const request = parse(origin);
+	if (!request) return false;
+	return trusted.some((entry) => {
+		const allowed = parse(entry);
+		if (!allowed) return false;
+		if (allowed.scheme !== request.scheme) return false;
+		if (allowed.port !== request.port) return false;
+		const domain = wildcardDomainOf(allowed.host);
+		if (domain === void 0) return allowed.host === request.host;
+		const dot = request.host.indexOf(".");
+		return dot > 0 && LABEL.test(request.host.slice(0, dot)) && request.host.slice(dot + 1) === domain;
+	});
+}
+/**
+* The domain under a wildcard host — `example.com` for `*.example.com` — or
+* `undefined` for a host that is not one.
+*/
+function wildcardDomainOf(host) {
+	return host.startsWith("*.") ? host.slice(2) : void 0;
+}
+/** One DNS label, as a tenant's slug is. */
+const LABEL = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+function parse(origin) {
+	if (!origin || origin === "*") return void 0;
+	try {
+		const url = new URL(origin);
+		if (url.origin === "null") return void 0;
+		return {
+			scheme: url.protocol,
+			host: url.hostname.toLowerCase(),
+			port: url.port
+		};
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/secret.ts
+/**
+* What a generated secret looks like, and the one way every stage draws it.
+*
+* A server deploy draws from `crypto`, `gkm dev` and `gkm test` from a hash of
+* the project, stage and id, and an AWS deploy asks Pulumi for the same
+* alphabet. Sharing this is what keeps a password that passes a third party's
+* rules on one stage from failing them on the next.
+*/
+/** 43 characters from 64 is 256 bits — as much as anything here needs. */
+const SECRET_LENGTH = 43;
+/**
+* Two symbols nothing has to escape — not a URL, a connection string, a shell
+* or a `.env` file — which with letters and digits is base64url's alphabet.
+*/
+const SECRET_SYMBOLS = "-_";
+const LETTERS_AND_DIGITS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+/**
+* A secret in `format`, each character chosen by `pick(n)` — an integer in
+* `[0, n)` from whatever source the caller trusts.
+*
+* When there are symbols, one is guaranteed: a rule that demands a symbol is
+* the reason anyone names them, and leaving it to chance fails it often —
+* about one draw in seven at 24 characters.
+*/
+function drawSecret(pick, format = {}) {
+	const length = format.length ?? 43;
+	const symbols = [...new Set(format.symbols ?? "-_")].join("");
+	const alphabet = LETTERS_AND_DIGITS + symbols;
+	const chars = Array.from({ length }, () => alphabet[pick(alphabet.length)]);
+	if (symbols && !chars.some((char) => symbols.includes(char))) chars[pick(length)] = symbols[pick(symbols.length)];
+	return chars.join("");
 }
 //#endregion
+exports.CLIENT_IP_HEADER = CLIENT_IP_HEADER;
+exports.DATABASE_FOLDERS = DATABASE_FOLDERS;
+exports.DEFAULT_DERIVED_DAYS = DEFAULT_DERIVED_DAYS;
 exports.DEFAULT_POSTGRES_VERSION = DEFAULT_POSTGRES_VERSION;
+exports.DEFAULT_STAGE_URL = DEFAULT_STAGE_URL;
+exports.DERIVED_PREFIX = DERIVED_PREFIX;
 exports.DERIVES_FROM = DERIVES_FROM;
+exports.EDGE_TOKEN_HEADER = EDGE_TOKEN_HEADER;
+exports.EDGE_TOKEN_KEY = EDGE_TOKEN_KEY;
+exports.INBOX_EVENT = INBOX_EVENT;
+exports.INBOX_MESSAGES_PREFIX = INBOX_MESSAGES_PREFIX;
 exports.IllegalDerivation = IllegalDerivation;
 exports.InvalidConstructId = InvalidConstructId;
+exports.KMS_SCHEME = KMS_SCHEME;
+exports.MIGRATIONS_ROOT = MIGRATIONS_ROOT;
+exports.NoUrlForStage = NoUrlForStage;
 exports.PUBLIC = PUBLIC;
 exports.PUBLIC_PREFIX = PUBLIC_PREFIX;
+exports.SECRET_LENGTH = SECRET_LENGTH;
+exports.SECRET_SYMBOLS = SECRET_SYMBOLS;
+exports.TELEMETRY_KEYS = TELEMETRY_KEYS;
 exports.UnknownParent = UnknownParent;
+exports.WILDCARD_SUBDOMAIN = WILDCARD_SUBDOMAIN;
 exports.assertDerivations = assertDerivations;
+exports.bucketExpiry = bucketExpiry;
 exports.cacheTable = cacheTable;
 exports.canonicalId = canonicalId;
 exports.cloudName = cloudName;
 exports.cookieDomain = cookieDomain;
+exports.databaseFolder = databaseFolder;
 exports.dependenciesOf = dependenciesOf;
 exports.dependentsOf = dependentsOf;
+exports.drawSecret = drawSecret;
 exports.environmentCase = environmentCase;
-exports.flattenManifestField = flattenManifestField;
+exports.externalApiUrl = externalApiUrl;
+exports.inboxRecipient = inboxRecipient;
 exports.isDerived = isDerived;
+exports.isWebOrigin = isWebOrigin;
+exports.isWildcardSite = isWildcardSite;
 exports.kebabCase = kebabCase;
+exports.kmsUrl = kmsUrl;
+exports.migrationFolder = migrationFolder;
+exports.migrationTargets = migrationTargets;
+exports.mobileOrigins = mobileOrigins;
 exports.provideKey = provideKey;
 exports.providedKeyFor = providedKeyFor;
 exports.provisionOrder = provisionOrder;
 exports.publicEnvFor = publicEnvFor;
+exports.receiptRecipients = receiptRecipients;
+exports.schemeBase = schemeBase;
 exports.scopedName = scopedName;
+exports.seedFolder = seedFolder;
 exports.serviceKey = serviceKey;
+exports.trustsOrigin = trustsOrigin;
+exports.wildcardDomainOf = wildcardDomainOf;
 
 //# sourceMappingURL=index.cjs.map