@geekmidas/cloud 10.0.0-alpha.5 → 10.0.0-alpha.50

package/src/sst/__tests__/surfaces.spec.ts

@@ -28,6 +28,11 @@ const manifest = {
 		provides: ['API_URL', 'API_TRUSTED_ORIGINS', 'API_COOKIE_DOMAIN'],
 	},
 	Orders: { kind: 'database', id: 'Orders', provides: ['ORDERS_URL'] },
+	Mailer: {
+		kind: 'email',
+		id: 'Mailer',
+		provides: ['MAILER_URL', 'MAILER_FROM'],
+	},
 	Console: {
 		kind: 'site',
 		id: 'Console',
@@ -37,6 +42,7 @@ const manifest = {
 			{ target: 'Api', kind: 'rest-api' },
 			{ target: 'Orders', kind: 'database' },
 			{ target: 'UploadsServer', kind: 'file-server' },
+			{ target: 'Mailer', kind: 'email' },
 		],
 		provides: ['CONSOLE_URL'],
 	},
@@ -101,6 +107,10 @@ describe('siteEnvironment', () => {
 				Api: provided({ url: 'https://api.example.com' }),
 				Orders: provided({ url: 'postgres://user:pw@db/orders' }),
 				UploadsServer: provided({ url: 'https://files.example.com' }),
+				Mailer: provided({
+					url: 'smtp://user:pw@email-smtp.example.com:587',
+					from: 'hello@shop.test',
+				}),
 			}),
 		);
 
@@ -122,6 +132,13 @@ describe('siteEnvironment', () => {
 		expect(built()).not.toHaveProperty('VITE_ORDERS_URL');
 	});
 
+	it('has no inbox to share for deployed mail, and never shares the mail URL', () => {
+		// The inbox is Mailpit's, and exists only locally: deployed, an app that
+		// reads it falls back to the phone's own mail app.
+		expect(built()).not.toHaveProperty('VITE_MAILER_INBOX_URL');
+		expect(built()).not.toHaveProperty('VITE_MAILER_URL');
+	});
+
 	it('fails loudly on an edge nothing provisioned', () => {
 		// A smaller environment builds and then fails at runtime against
 		// `http:///`, with nothing to point at.

package/src/sst/aws/Api.ts

@@ -1,10 +1,5 @@
 import path from 'node:path';
 import { EnvValidationError } from '@geekmidas/envkit/sst';
-import {
-	flattenManifestField,
-	type ManifestField,
-	type RouteInfo,
-} from '@geekmidas/manifest';
 import { type GkmLinkable, ResourceType } from '../Linkable';
 import { LinkedEnvironment } from '../LinkedEnvironment';
 import type { StackType } from '../Stack';
@@ -153,48 +148,10 @@ export class Api<
 		// Fail the whole synth if any route is misconfigured, with one actionable
 		// message per offending route.
 		if (failures.length) {
-			throw new Error(failures.map((f) => f.message).join('\n\n'));
+			throw new RoutesMissingEnvironment(id, failures);
 		}
 	}
 
-	/**
-	 * Build an `Api` from a `gkm build` manifest's `routes` field (flat or
-	 * partitioned): each `RouteInfo` becomes a route (env vars, authorizer,
-	 * timeout/memory mapped). Supply `authorizers` (JWT/Lambda settings),
-	 * `links`, and any native args via `props`.
-	 *
-	 * ```ts
-	 * import { manifest } from './.gkm/manifest/aws';
-	 * Api.fromManifest(stack, 'Api', manifest.routes, { links: [db] });
-	 * ```
-	 */
-	static fromManifest<
-		TAuthorizers extends Record<string, unknown> = {},
-		TStage extends string = string,
-		TDomain extends string = string,
-	>(
-		stack: StackType<TStage, TDomain>,
-		id: string,
-		routes: ManifestField<RouteInfo>,
-		props: Omit<ApiProps<TAuthorizers>, 'routes'> = {},
-	): Api<TAuthorizers, TStage, TDomain> {
-		const routeTable = flattenManifestField(routes).map(
-			(route): Route<AuthorizerName<TAuthorizers>> => ({
-				method: route.method as Route['method'],
-				path: route.path,
-				handler: route.handler,
-				environment: route.environment,
-				authorizer: route.authorizer as AuthorizerName<TAuthorizers>,
-				timeout: route.timeout ? `${route.timeout} seconds` : undefined,
-				memory: route.memorySize ? `${route.memorySize} MB` : undefined,
-			}),
-		);
-		return new Api(stack, id, {
-			...props,
-			routes: routeTable,
-		} as ApiProps<TAuthorizers>);
-	}
-
 	/** Resolves a route's `authorizer` name to the SST `auth` option. */
 	private static buildRouteAuth(
 		route: Route<string>,
@@ -307,3 +264,18 @@ export interface ApiProps<TAuthorizers extends Record<string, unknown> = {}>
 	 * may override it. */
 	runtime?: sst.aws.FunctionArgs['runtime'];
 }
+
+/**
+ * Routes that read variables nothing links or whitelists. Collected across
+ * every route so one synth reports all of them, each with its own suggestions,
+ * rather than stopping at the first.
+ */
+export class RoutesMissingEnvironment extends Error {
+	constructor(
+		readonly api: string,
+		readonly failures: readonly EnvValidationError[],
+	) {
+		super(failures.map((f) => f.message).join('\n\n'));
+		this.name = 'RoutesMissingEnvironment';
+	}
+}

package/src/sst/aws/Cache.ts

@@ -206,7 +206,7 @@ export function withCacheTable(url: string, table: string): string {
 }
 
 /**
- * `services.cache: 'db'` in an app that declares more than one database.
+ * A `'db'` cache in an app that declares more than one database.
  *
  * Picking one would put the cache somewhere nobody chose, and the symptom —
  * entries that are never found — appears long after the deploy reported
@@ -222,7 +222,7 @@ export class CacheIsAmbiguous extends Error {
 			`'${id}' is a cache backed by the database, and this app declares ` +
 				`${databases.length}: ${databases.join(', ')}. Declare the cache from ` +
 				`its database — e.g. ${databases[0]}.cache('${id}') — rather than ` +
-				`with services.cache.`,
+				`as a bare new Cache().`,
 		);
 		this.name = 'CacheIsAmbiguous';
 	}
@@ -232,8 +232,8 @@ export class CacheNeedsDatabase extends Error {
 	constructor(readonly id: string) {
 		super(
 			`'${id}' is a cache backed by the database, and this app declares no ` +
-				`database for it to live in. Declare one, or set services.cache to ` +
-				`'upstash' or 'elasticache'.`,
+				`database for it to live in. Declare one, or declare the cache from ` +
+				`the database it belongs to.`,
 		);
 		this.name = 'CacheNeedsDatabase';
 	}

package/src/sst/aws/Credential.ts

@@ -1,4 +1,5 @@
-import { Secret, type SecretProps } from './Secret';
+import { type GkmLinkable, ResourceType } from '../Linkable';
+import type { StackType } from '../Stack';
 
 /**
  * `Credential` — a third-party credential SST holds, and the infra half of the
@@ -8,21 +9,53 @@ import { Secret, type SecretProps } from './Secret';
  * the lifecycle rather than the mechanism: a secret is generated and rotated by
  * the platform, while a credential is issued by someone else and has a shape
  * the construct validates on the way in. Both are values you set out of band
- * with `sst secret set`.
+ * with `sst secret set`, under the construct's id.
  *
- * The role is `credential` rather than `value`, and that is not cosmetic. The
+ * The role is `credentials` rather than `value`, and that is not cosmetic. The
  * role *is* the contract — `providedKeyFor` turns it into the key the app
  * declared — so a credential providing `value` would supply `STRIPE_VALUE`
- * against a declared `STRIPE_CREDENTIAL`, and `assertProvides` would reject the
- * stack at synth. Which is the check working; renaming here is the fix.
+ * against a declared `STRIPE_CREDENTIALS`, and `assertProvides` would reject
+ * the stack at synth.
+ *
+ * It holds an `sst.Secret` rather than being one, and reports its own type,
+ * for the same reason one level down: the type decides the keys a link
+ * resolves to. As an SST secret it resolved to `STRIPE`, so a function that
+ * declared `STRIPE_CREDENTIALS` was linked to nothing.
  */
 export class Credential<
 	TStage extends string = string,
 	TDomain extends string = string,
-> extends Secret<TStage, TDomain> {
-	override provides(): Record<string, $util.Input<string>> {
-		return { credential: this.value };
+> implements GkmLinkable
+{
+	readonly _id: string;
+
+	private readonly secret: sst.Secret;
+
+	get _type() {
+		return ResourceType.Credential;
+	}
+
+	constructor(
+		_stack: StackType<TStage, TDomain>,
+		name: string,
+		props: CredentialProps = {},
+	) {
+		this._id = name;
+		// The id itself, as it always was: a value already set with
+		// `sst secret set Stripe …` is still the one read.
+		this.secret = new sst.Secret(name, props.placeholder);
+	}
+
+	provides(): Record<string, $util.Input<string>> {
+		return { credentials: this.secret.value };
+	}
+
+	getSSTLink() {
+		return { properties: { ...this.provides() } };
 	}
 }
 
-export interface CredentialProps extends SecretProps {}
+export interface CredentialProps {
+	/** A value until one is set, for a preview stage. */
+	placeholder?: string;
+}

package/src/sst/aws/Cron.ts

@@ -1,11 +1,5 @@
-import {
-	type CronInfo,
-	flattenManifestField,
-	type ManifestField,
-} from '@geekmidas/manifest';
-import type { GkmLinkable } from '../Linkable';
 import type { StackType } from '../Stack';
-import { Function } from './Function';
+import type { Function } from './Function';
 
 export type CronExpressionValue = number | '*' | '?' | `${number}/${number}`;
 export type CronExpressionDay =
@@ -52,6 +46,9 @@ export class Cron<
 	TStage extends string = string,
 	TDomain extends string = string,
 > extends sst.aws.CronV2 {
+	/** The function it invokes. */
+	readonly processor: CronProps['processor'];
+
 	constructor(
 		_stack: StackType<TStage, TDomain>,
 		name: string,
@@ -63,44 +60,7 @@ export class Cron<
 			schedule,
 			function: processor.arn,
 		});
-	}
-
-	/**
-	 * Build one `Cron` per entry in a `gkm build` manifest's `crons` field (flat
-	 * or partitioned). Each cron's handler becomes a validated `Function` (the
-	 * cron's target), so pass `links` for that function's env validation;
-	 * remaining `props` are CronV2 args.
-	 *
-	 * ```ts
-	 * Cron.fromManifest(stack, manifest.crons, { links: [db] });
-	 * ```
-	 */
-	static fromManifest<
-		TStage extends string = string,
-		TDomain extends string = string,
-	>(
-		stack: StackType<TStage, TDomain>,
-		crons: ManifestField<CronInfo>,
-		props: Omit<CronProps, 'processor' | 'schedule'> & {
-			links?: GkmLinkable[];
-		} = {},
-	): Cron<TStage, TDomain>[] {
-		const { links, ...cronArgs } = props;
-		return flattenManifestField(crons).map((cron) => {
-			const processor = new Function(stack, `${cron.name}Function`, {
-				name: stack.logicalPrefixedName(cron.name),
-				handler: cron.handler,
-				envVars: cron.environment,
-				links,
-				timeout: cron.timeout ? `${cron.timeout} seconds` : undefined,
-				memory: cron.memorySize ? `${cron.memorySize} MB` : undefined,
-			});
-			return new Cron(stack, cron.name, {
-				...cronArgs,
-				processor,
-				schedule: cron.schedule as CronSchedule,
-			});
-		});
+		this.processor = processor;
 	}
 }
 

package/src/sst/aws/Database.ts

@@ -84,7 +84,21 @@ export class Database<
 	 * produces a database that looks empty.
 	 */
 	provides(): Record<string, $util.Input<string>> {
-		return { url: this.urlFor({}) };
+		return { url: this.urlFor(this.role ? { as: this.role } : {}) };
+	}
+
+	/**
+	 * The runtime role this database's own handlers connect as.
+	 *
+	 * Set by the adapter once the bootstrap has registered the role — the
+	 * cluster exists before any role does, so it cannot be a constructor
+	 * argument. Until it is set (and under `roles: false`, where it never is),
+	 * the URL is the master's.
+	 */
+	private role: { user: string; password: $util.Input<string> } | undefined;
+
+	connectAs(role: { user: string; password: $util.Input<string> }): void {
+		this.role = role;
 	}
 
 	/**

package/src/sst/aws/DatabaseBootstrap.ts

@@ -65,6 +65,8 @@ export class DatabaseBootstrap {
 		runtime: string;
 		owner: string;
 		reader?: string;
+		/** The database's own roles, whose owner may create in it. */
+		ownsDatabase?: boolean;
 	}): { runtime: $util.Output<string>; reader?: $util.Output<string> } {
 		const runtime = this.password(tenant.runtime);
 		const reader = tenant.reader ? this.password(tenant.reader) : undefined;
@@ -75,6 +77,7 @@ export class DatabaseBootstrap {
 			runtime: tenant.runtime,
 			owner: tenant.owner,
 			...(tenant.reader ? { reader: tenant.reader } : {}),
+			...(tenant.ownsDatabase ? { ownsDatabase: true } : {}),
 			// Filled in by `bootstrapEvent` once the outputs resolve. The function
 			// reads them straight out of its input and never fetches a secret, so
 			// it needs no IAM to read one.

package/src/sst/aws/Encryption.ts

@@ -0,0 +1,91 @@
+import { kmsUrl } from '@geekmidas/manifest';
+import { kms } from '@pulumi/aws';
+import { type GkmLinkable, ResourceType } from '../Linkable';
+import type { StackType } from '../Stack';
+
+/**
+ * `Encryption` — two KMS keys, and the infra half of the `encryption` kind.
+ *
+ * One key encrypts, by envelope: each value is sealed with a data key KMS
+ * mints and wraps, so the key itself never leaves KMS. It rotates yearly, and
+ * KMS keeps every version it rotated through, so nothing written is ever
+ * stranded. The other is an HMAC key for the blind index, which does not
+ * rotate — a rotated index key would make every stored index miss.
+ *
+ * Both are reached through one `kms://` URL, and a function linked to this is
+ * granted exactly the calls the cipher makes on exactly these two keys. Not
+ * `kms:*`, and not any other key in the account.
+ *
+ * It holds the keys rather than being one, and reports its own type, so a link
+ * resolves to `<ID>_URL` — the key the construct declared.
+ */
+export class Encryption<
+	TStage extends string = string,
+	TDomain extends string = string,
+> implements GkmLinkable
+{
+	readonly _id: string;
+
+	readonly key: kms.Key;
+	readonly indexKey: kms.Key;
+	private readonly region: string;
+
+	get _type() {
+		return ResourceType.Encryption;
+	}
+
+	constructor(
+		_stack: StackType<TStage, TDomain>,
+		name: string,
+		props: EncryptionProps,
+	) {
+		this._id = name;
+		this.region = props.region;
+
+		this.key = new kms.Key(`${name}Key`, {
+			description: `${name}: encrypts what the application stores`,
+			enableKeyRotation: true,
+			deletionWindowInDays: props.deletionWindowInDays ?? 30,
+		});
+		this.indexKey = new kms.Key(`${name}IndexKey`, {
+			description: `${name}: the blind index's HMAC key`,
+			keyUsage: 'GENERATE_VERIFY_MAC',
+			customerMasterKeySpec: 'HMAC_256',
+			deletionWindowInDays: props.deletionWindowInDays ?? 30,
+		});
+	}
+
+	provides(): Record<string, $util.Input<string>> {
+		return {
+			url: $util
+				.all([this.key.arn, this.indexKey.arn])
+				.apply(([key, index]) => kmsUrl({ region: this.region, key, index })),
+		};
+	}
+
+	getSSTLink() {
+		return {
+			properties: { ...this.provides() },
+			include: [
+				sst.aws.permission({
+					actions: ['kms:GenerateDataKey', 'kms:Decrypt'],
+					resources: [this.key.arn],
+				}),
+				sst.aws.permission({
+					actions: ['kms:GenerateMac'],
+					resources: [this.indexKey.arn],
+				}),
+			],
+		};
+	}
+}
+
+export interface EncryptionProps {
+	/** Where the keys live — the stage's region. */
+	region: string;
+	/**
+	 * How long a deleted key can still be recovered, 7–30 days. A key's
+	 * deletion is the deletion of everything it encrypted, so the longest.
+	 */
+	deletionWindowInDays?: number;
+}

package/src/sst/aws/ExternalApi.ts

@@ -0,0 +1,58 @@
+import { externalApiUrl } from '@geekmidas/manifest';
+import { type GkmLinkable, ResourceType } from '../Linkable';
+import type { StackType } from '../Stack';
+
+/**
+ * `ExternalApi` — the infra half of the `external-api` kind.
+ *
+ * Nothing is provisioned: the API is somebody else's. What this holds is the
+ * two facts a function needs to call it on this stage — the URL the
+ * declaration names for it, and the credentials the provider issued, kept as
+ * an SST secret and set out of band:
+ *
+ * ```
+ * sst secret set PolarCredentials '{"clientId":"…","clientSecret":"…"}' --stage prod
+ * ```
+ */
+export class ExternalApi<
+	TStage extends string = string,
+	TDomain extends string = string,
+> implements GkmLinkable
+{
+	readonly _id: string;
+
+	private readonly url: string;
+
+	private readonly credentials: sst.Secret;
+
+	get _type() {
+		return ResourceType.ExternalApi;
+	}
+
+	constructor(
+		stack: StackType<TStage, TDomain>,
+		name: string,
+		props: ExternalApiProps,
+	) {
+		this._id = name;
+		// Read at synth, so a stage the declaration has no URL for fails the
+		// deploy — with the stage named — rather than the first request.
+		this.url = externalApiUrl({ id: name, url: props.url }, stack.stage);
+		this.credentials = new sst.Secret(`${name}Credentials`, props.placeholder);
+	}
+
+	provides(): Record<string, $util.Input<string>> {
+		return { url: this.url, credentials: this.credentials.value };
+	}
+
+	getSSTLink() {
+		return { properties: { ...this.provides() } };
+	}
+}
+
+export interface ExternalApiProps {
+	/** The declaration's `url` — one for every stage, or one per stage name. */
+	url: string | Readonly<Record<string, string>>;
+	/** A value for the credentials secret until one is set, for a preview stage. */
+	placeholder?: string;
+}

package/src/sst/aws/Function.ts

@@ -1,9 +1,4 @@
 import type { EnvValidator, ValidationResult } from '@geekmidas/envkit/sst';
-import {
-	type FunctionInfo,
-	flattenManifestField,
-	type ManifestField,
-} from '@geekmidas/manifest';
 import { type GkmLinkable, ResourceType } from '../Linkable';
 import { LinkedEnvironment } from '../LinkedEnvironment';
 import type { StackType } from '../Stack';
@@ -66,9 +61,10 @@ export class Function<
 		super(id, {
 			...fnArgs,
 			environment: mergedEnvironment,
-			// Linking is managed via the `links`/`envVars` flow, so this overrides
-			// any native `link` passed through `fnArgs`.
-			link: linked.resolveLink(envVars),
+			// Resolved from `links` when `envVars` names what it needs; otherwise
+			// the `link` it was given — the edges a manifest declared.
+			link:
+				envVars.length > 0 ? linked.resolveLink(envVars) : (fnArgs.link ?? []),
 			runtime: runtime ?? 'nodejs24.x',
 			logging: logging ?? { format: 'json' },
 		});
@@ -78,40 +74,15 @@ export class Function<
 		this.envVars = envVars;
 	}
 
+	/** Its address, for whatever declared an edge to it. */
+	provides(): Record<string, $util.Input<string>> {
+		return { url: this.url };
+	}
+
 	/** Re-runs validation and returns the result (does not throw). */
 	validate(): ValidationResult {
 		return this.validator.validate(this.envVars);
 	}
-
-	/**
-	 * Build one `Function` per entry in a `gkm build` manifest's `functions`
-	 * field (flat or partitioned). Shared `props` (e.g. `links`) apply to every
-	 * function.
-	 *
-	 * ```ts
-	 * Function.fromManifest(stack, manifest.functions, { links: [db] });
-	 * ```
-	 */
-	static fromManifest<
-		TStage extends string = string,
-		TDomain extends string = string,
-	>(
-		stack: StackType<TStage, TDomain>,
-		functions: ManifestField<FunctionInfo>,
-		props: Omit<FunctionProps, 'handler'> = {},
-	): Function<TStage, TDomain>[] {
-		return flattenManifestField(functions).map(
-			(fn) =>
-				new Function(stack, fn.name, {
-					...props,
-					name: stack.logicalPrefixedName(fn.name),
-					handler: fn.handler,
-					envVars: fn.environment,
-					timeout: fn.timeout ? `${fn.timeout} seconds` : undefined,
-					memory: fn.memorySize ? `${fn.memorySize} MB` : undefined,
-				}),
-		);
-	}
 }
 
 export interface FunctionProps extends sst.aws.FunctionArgs {

package/src/sst/aws/Queue.ts

@@ -11,7 +11,8 @@ import type { StackType } from '../Stack';
  * work queue. Link it to a producer and the runtime resolves `<NAME>_URL`,
  * `<NAME>_ARN`, and a `<NAME>_PUBLISHER_CONNECTION_STRING` (`sqs://?queueUrl=…`)
  * that `@geekmidas/events`'s `Publisher.fromConnectionString` consumes. Its
- * single consumer is wired by `QueueSubscriber`.
+ * one consumer — the handler the queue was declared with — is subscribed by
+ * {@link Queue.consume}.
  *
  * SST's native `Queue` link exposes only `url`, so `getSSTLink` is overridden to
  * also expose `arn` (what the resolver needs). `QueueProps` extends
@@ -73,6 +74,26 @@ export class Queue<
 		};
 	}
 
+	/**
+	 * Subscribe the queue's one consumer: a Lambda running `handler`, linked to
+	 * what the consumer depends on and to this queue itself.
+	 *
+	 * A queue has exactly one consumer, so this is called once per queue — by
+	 * `fromManifest`, from the handler the build wrote for it.
+	 */
+	consume(consumer: QueueConsumer) {
+		return this.subscribe(
+			{
+				handler: consumer.handler,
+				link: [this, ...(consumer.link ?? [])],
+				runtime: 'nodejs24.x',
+				...(consumer.vpc ? { vpc: consumer.vpc } : {}),
+				...(consumer.timeout ? { timeout: consumer.timeout } : {}),
+			},
+			consumer.batchSize ? { batch: { size: consumer.batchSize } } : {},
+		);
+	}
+
 	override getSSTLink() {
 		const link = super.getSSTLink();
 		return {
@@ -82,6 +103,18 @@ export class Queue<
 	}
 }
 
+/** The queue's one consumer, as {@link Queue.consume} subscribes it. */
+export interface QueueConsumer {
+	/** The built handler — `apps/api/.gkm/aws/queues/emails.handler`. */
+	handler: string;
+	/** What the consumer depends on; the queue itself is always linked. */
+	link?: unknown[];
+	/** The database's network, when the consumer reaches one. */
+	vpc?: sst.aws.Vpc;
+	timeout?: `${number} seconds` | `${number} minutes`;
+	batchSize?: number;
+}
+
 export interface QueueProps extends sst.aws.QueueArgs {
 	/**
 	 * The physical queue name, where the auto-generated one will not do.

package/src/sst/aws/RestApiSurface.ts

@@ -4,20 +4,10 @@ import type { StackType } from '../Stack';
 /**
  * `RestApiSurface` — an HTTP API, and the infra half of the `rest-api` kind.
  *
- * Deliberately *not* `Api`, which takes a route table and validates each
- * route's environment at synth. That component is the endpoint pipeline's, and
- * it needs routes; this one is the manifest's, and the manifest's `rest-api`
- * node currently carries `endpoints: []` for an application's own API.
- *
- * So what this provisions is the surface and nothing on it. An API Gateway with
- * no routes 404s everything, which is the honest state of things — and it is
- * still worth provisioning, because the *address* is what everything downstream
- * needs: a site inlines it as `VITE_API_URL`, an auth server puts it on its
- * trusted-origin list, and the cookie domain derives from it. Those are blocked
- * on the API existing, not on it answering.
- *
- * The two collapse into one component when the endpoint merge lands and the
- * surface node carries its routes.
+ * Provisioned before its routes, because its *address* is what everything
+ * downstream needs: a site inlines it as `VITE_API_URL`, an auth server puts it
+ * on its trusted-origin list, and the cookie domain derives from it. The routes
+ * are mounted once everything they link to exists — see {@link mount}.
  */
 
 export interface RestApiSurfaceProps extends sst.aws.ApiGatewayV2Args {
@@ -82,6 +72,25 @@ export class RestApiSurface<
 		};
 	}
 
+	/**
+	 * Mount one endpoint: a Lambda running the handler the build wrote for it,
+	 * linked to exactly what that endpoint depends on.
+	 */
+	mount(endpoint: SurfaceRoute) {
+		return this.route(
+			`${endpoint.method} ${endpoint.path}`,
+			{
+				handler: endpoint.handler,
+				link: endpoint.link ?? [],
+				runtime: 'nodejs24.x',
+				...(endpoint.vpc ? { vpc: endpoint.vpc } : {}),
+			},
+			// `iam` is the one authorizer the gateway enforces itself; every other
+			// is the endpoint's own, checked in the handler.
+			endpoint.authorizer === 'iam' ? { auth: { iam: true } } : {},
+		);
+	}
+
 	override getSSTLink() {
 		const link = super.getSSTLink();
 		return {
@@ -90,3 +99,16 @@ export class RestApiSurface<
 		};
 	}
 }
+
+/** One endpoint, as {@link RestApiSurface.mount} mounts it. */
+export interface SurfaceRoute {
+	method: string;
+	path: string;
+	/** The built handler — `apps/api/.gkm/aws/routes/getUser.handler`. */
+	handler: string;
+	/** What the endpoint depends on, and nothing else. */
+	link?: unknown[];
+	/** The database's network, when the endpoint reaches one. */
+	vpc?: sst.aws.Vpc;
+	authorizer?: string;
+}