@geekmidas/cloud 10.0.0-alpha.45 → 10.0.0-alpha.47

package/README.md

@@ -105,17 +105,25 @@ const cron = new Cron(stack, 'Nightly', { processor: fn, schedule: 'rate(1 day)'
 
 ### From a `gkm build` manifest
 
-`gkm build` emits a deployment manifest (types in `@geekmidas/manifest`). Each
-construct has a static `fromManifest` factory that maps it straight into infra:
+The root `gkm build` writes the application's manifest to
+`.gkm/manifest/aws.ts` (types in `@geekmidas/manifest`), and `fromManifest`
+maps it straight into infra:
 
 ```ts
-import routes from './.gkm/routes-manifest.json';
+// sst.config.ts
+const { App, fromManifest, Stack } = await import('@geekmidas/cloud/sst');
+const { backends, constructs } = await import('./.gkm/manifest/aws.js');
 
-const api     = Api.fromManifest(stack, 'Api', routes, { links: [db], authorizers });
-const workers = Function.fromManifest(stack, functionsManifest, { links: [db] });
-const crons   = Cron.fromManifest(stack, cronsManifest, { links: [db] });
+fromManifest(new Stack(app, 'Shop'), constructs, { Database: { vpc } }, backends);
 ```
 
+`constructs` is every declared construct keyed by id; the overrides are keyed
+by the same ids. One call provisions the resources, each `RestApi`'s endpoints
+(each a Lambda linked only to its own dependencies, placed in the database's
+VPC when it reaches one, with the `iam` authorizer enforced by the gateway),
+queue consumers, every function (a Lambda with an IAM-authorized URL) and every
+cron (a Lambda on its schedule).
+
 ## `@geekmidas/cloud/utils` (runtime)
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekmidas/cloud",
-  "version": "10.0.0-alpha.45",
+  "version": "10.0.0-alpha.47",
   "type": "module",
   "files": [
     "dist",
@@ -41,8 +41,8 @@
   },
   "dependencies": {
     "lodash.snakecase": "~4.1.1",
-    "@geekmidas/envkit": "10.0.0-alpha.45",
-    "@geekmidas/manifest": "10.0.0-alpha.45"
+    "@geekmidas/envkit": "10.0.0-alpha.47",
+    "@geekmidas/manifest": "10.0.0-alpha.47"
   },
   "devDependencies": {
     "@types/lodash.get": "~4.4.9",
@@ -58,10 +58,10 @@
     "@pulumi/aws": ">=7.47.0",
     "@pulumi/random": ">=4.21.2",
     "@pulumi/pulumi": ">=3.263.0",
-    "@geekmidas/manifest": "^10.0.0-alpha.45",
-    "@geekmidas/storage": "^10.0.0-alpha.45",
-    "@geekmidas/events": "^10.0.0-alpha.45",
-    "@geekmidas/db": "^10.0.0-alpha.45"
+    "@geekmidas/manifest": "^10.0.0-alpha.47",
+    "@geekmidas/storage": "^10.0.0-alpha.47",
+    "@geekmidas/events": "^10.0.0-alpha.47",
+    "@geekmidas/db": "^10.0.0-alpha.47"
   },
   "peerDependenciesMeta": {
     "@geekmidas/manifest": {

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

@@ -183,49 +183,3 @@ describe('Api', () => {
 		expect(recorded(api).authorizers).toEqual([]);
 	});
 });
-
-describe('Api.fromManifest', () => {
-	it('turns built routes, flat or partitioned, into the route table', () => {
-		const routes = {
-			public: [
-				{
-					method: 'GET',
-					path: '/orders',
-					handler: '.gkm/aws-lambda/routes/orders.handler',
-					environment: ['DB_URL'],
-					authorizer: 'iam',
-					timeout: 30,
-					memorySize: 1024,
-				},
-			],
-			internal: [
-				{
-					method: 'POST',
-					path: '/jobs',
-					handler: '.gkm/aws-lambda/routes/jobs.handler',
-					environment: [],
-				},
-			],
-		};
-
-		const api = Api.fromManifest(stack, 'Http', routes as never, {
-			links: [db],
-		});
-		const { routes: recordedRoutes } = recorded(api);
-
-		expect(recordedRoutes.map((r) => r.key)).toEqual([
-			'GET /orders',
-			'POST /jobs',
-		]);
-		expect(recordedRoutes[0]!.handler).toMatchObject({
-			timeout: '30 seconds',
-			memory: '1024 MB',
-			link: [db],
-		});
-		expect(recordedRoutes[0]!.args).toEqual({ auth: { iam: true } });
-		expect(recordedRoutes[1]!.handler).toMatchObject({
-			timeout: undefined,
-			memory: undefined,
-		});
-	});
-});

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

@@ -0,0 +1,90 @@
+import { ResourceType } from '@geekmidas/envkit/sst';
+import { providedKeyFor, provideKey } from '@geekmidas/manifest';
+import { describe, expect, it, vi } from 'vitest';
+import { Encryption } from '../aws/Encryption';
+import { provisionerFor, resolveEdges } from '../fromManifest';
+
+// A KMS key, as far as the component reads one: what it was created with, and
+// an ARN. The SST globals are stubbed the same way for every component.
+vi.mock('@pulumi/aws', () => ({
+	kms: {
+		Key: class {
+			readonly arn: string;
+			constructor(
+				readonly name: string,
+				readonly args: Record<string, unknown>,
+			) {
+				this.arn = `arn:aws:kms:eu-west-1:123456789012:key/${name}`;
+			}
+		},
+	},
+}));
+
+const stack = {} as never;
+
+describe('Encryption on AWS', () => {
+	it('is two KMS keys: one that rotates for data, one HMAC key for the index', () => {
+		const pii = new Encryption(stack, 'Pii', { region: 'eu-west-1' });
+
+		expect(pii.key).toMatchObject({
+			name: 'PiiKey',
+			args: { enableKeyRotation: true, deletionWindowInDays: 30 },
+		});
+		expect(pii.indexKey).toMatchObject({
+			name: 'PiiIndexKey',
+			args: {
+				keyUsage: 'GENERATE_VERIFY_MAC',
+				customerMasterKeySpec: 'HMAC_256',
+			},
+		});
+	});
+
+	it('provides one kms:// URL, under the key the construct declared', () => {
+		const pii = new Encryption(stack, 'Pii', { region: 'eu-west-1' });
+		const url = new URL(pii.provides().url as string);
+
+		expect(url.protocol).toBe('kms:');
+		expect(url.hostname).toBe('eu-west-1');
+		expect(url.searchParams.get('key')).toBe(pii.key.arn);
+		expect(url.searchParams.get('index')).toBe(pii.indexKey.arn);
+		expect(
+			Object.keys(pii.provides()).map((role) =>
+				providedKeyFor('Pii', 'encryption', role),
+			),
+		).toEqual([provideKey('Pii', 'url')]);
+		expect(pii._type).toBe(ResourceType.Encryption);
+	});
+
+	it('grants a linked function the calls the cipher makes, on these keys only', () => {
+		const pii = new Encryption(stack, 'Pii', { region: 'eu-west-1' });
+
+		expect(pii.getSSTLink().include).toEqual([
+			{
+				permission: {
+					actions: ['kms:GenerateDataKey', 'kms:Decrypt'],
+					resources: [pii.key.arn],
+				},
+			},
+			{
+				permission: {
+					actions: ['kms:GenerateMac'],
+					resources: [pii.indexKey.arn],
+				},
+			},
+		]);
+	});
+
+	it('is provisioned from the manifest in the stage’s region, and links its URL', () => {
+		const pii = provisionerFor('encryption')(
+			stack,
+			{ kind: 'encryption', id: 'Pii', provides: ['PII_URL'] },
+			{},
+			{} as never,
+		) as Encryption;
+
+		expect(new URL(pii.provides().url as string).hostname).toBe('eu-west-1');
+		expect(
+			resolveEdges([{ target: 'Pii', kind: 'encryption' }], { Pii: pii }),
+		).toEqual({ link: [pii], envKeys: ['PII_URL'] });
+	});
+});

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

@@ -1,15 +1,24 @@
 import { resolveEnvKeys } from '@geekmidas/envkit/sst';
 import { NoUrlForStage, providedKeyFor, provideKey } from '@geekmidas/manifest';
 import { describe, expect, it } from 'vitest';
+import { App } from '../App';
+import { Cron } from '../aws/Cron';
+import { Database } from '../aws/Database';
+import { DatabaseSchema } from '../aws/DerivedDatabase';
+import { Function } from '../aws/Function';
 import { ObjectStorage } from '../aws/ObjectStorage';
+import { RestApiSurface } from '../aws/RestApiSurface';
 import { type ProvidesMismatch, UnknownDeclarationKind } from '../errors';
 import {
 	assertProvides,
+	mountRoutes,
 	PROVISIONED_ELSEWHERE,
 	type ProvisionedManifest,
+	provisionCompute,
 	provisionerFor,
 	resolveEdges,
 	subscribeConsumers,
+	vpcFor,
 } from '../fromManifest';
 
 /**
@@ -363,7 +372,7 @@ describe('a queue’s one consumer', () => {
 					provides: ['EMAILS_PUBLISHER_CONNECTION_STRING'],
 					worker: {
 						id: 'EmailsWorker',
-						handler: '.gkm/aws-lambda/queues/emails.handler',
+						handler: 'apps/api/.gkm/aws/queues/emails.handler',
 						dependencies: [{ target: 'Uploads', kind: 'objects' }],
 					},
 				},
@@ -372,7 +381,7 @@ describe('a queue’s one consumer', () => {
 		);
 
 		expect(consumed).toEqual([
-			{ handler: '.gkm/aws-lambda/queues/emails.handler', link: [uploads] },
+			{ handler: 'apps/api/.gkm/aws/queues/emails.handler', link: [uploads] },
 		]);
 	});
 
@@ -391,6 +400,162 @@ describe('a queue’s one consumer', () => {
 	});
 });
 
+describe('a surface’s endpoints', () => {
+	const routesOf = (surface: RestApiSurface) =>
+		(
+			surface as unknown as {
+				routes: { key: string; handler: any; args: unknown }[];
+			}
+		).routes;
+
+	it('are mounted from the handlers the build wrote, each linked to what it depends on', () => {
+		// An API Gateway with no routes 404s everything — which is what a deploy
+		// produced while the routes sat in the manifest with nothing reading them.
+		const api = new RestApiSurface({} as never, 'Api');
+		const uploads = { _id: 'Uploads', _type: 'sst.aws.Bucket' };
+
+		mountRoutes(
+			{
+				Uploads: { kind: 'objects', id: 'Uploads', provides: ['UPLOADS_URL'] },
+				Api: {
+					kind: 'rest-api',
+					id: 'Api',
+					provides: ['API_URL'],
+					endpoints: [
+						{
+							id: 'ApiGET/users/{id}',
+							method: 'GET',
+							path: '/users/{id}',
+							handler: 'apps/api/.gkm/aws/routes/getUser.handler',
+							dependencies: [{ target: 'Uploads', kind: 'objects' }],
+							authorizer: 'none',
+						},
+						{
+							id: 'ApiGET/health',
+							method: 'GET',
+							path: '/health',
+							handler: 'apps/api/.gkm/aws/routes/health.handler',
+							dependencies: [],
+						},
+					],
+				},
+			} as never,
+			{ Uploads: uploads, Api: api } as unknown as ProvisionedManifest,
+		);
+
+		const [getUser, health] = routesOf(api);
+		expect(getUser?.key).toBe('GET /users/{id}');
+		expect(getUser?.handler.handler).toBe(
+			'apps/api/.gkm/aws/routes/getUser.handler',
+		);
+		expect(getUser?.handler.link).toEqual([uploads]);
+		expect(getUser?.args).toEqual({});
+		// Least privilege: an endpoint is linked to its own edges, not the app's.
+		expect(health?.key).toBe('GET /health');
+		expect(health?.handler.link).toEqual([]);
+	});
+
+	it('leaves IAM to the gateway, and every other authorizer to the handler', () => {
+		const api = new RestApiSurface({} as never, 'Api');
+
+		api.mount({
+			method: 'POST',
+			path: '/x',
+			handler: 'x.handler',
+			authorizer: 'iam',
+		});
+		api.mount({
+			method: 'POST',
+			path: '/y',
+			handler: 'y.handler',
+			authorizer: 'session',
+		});
+
+		const [x, y] = routesOf(api);
+		expect(x?.args).toEqual({ auth: { iam: true } });
+		expect(y?.args).toEqual({});
+	});
+
+	it('runs a handler that reaches a database inside the database’s network', () => {
+		const vpc = { id: 'stub-vpc' } as never;
+		const cluster = new Database({} as never, 'Orders', { vpc });
+		const tenant = new DatabaseSchema('Billing', cluster, 'billing');
+
+		expect(vpcFor([cluster as never])).toBe(vpc);
+		// A schema tenant lives in its parent's cluster, so in its network too.
+		expect(vpcFor([{ _id: 'Uploads' } as never, tenant as never])).toBe(vpc);
+		expect(vpcFor([{ _id: 'Uploads' } as never])).toBeUndefined();
+	});
+});
+
+describe('functions and crons', () => {
+	const stack = new App({
+		name: 'shop',
+		stage: 'prod',
+		domain: 'example.com',
+		hostedZoneId: 'Z',
+		region: 'eu-west-1',
+	}).stack('jobs');
+	const argsOf = (component: unknown) =>
+		(component as { args: Record<string, any> }).args;
+
+	it('are deployed from the declarations, each linked to its own edges', () => {
+		// The `manifest.crons` / `manifest.functions` tables they were built from
+		// are gone: the declarations carry the handler, schedule and edges.
+		const vpc = { id: 'stub-vpc' } as never;
+		const orders = new Database({} as never, 'Orders', { vpc });
+		const uploads = { _id: 'Uploads', _type: 'sst.aws.Bucket' };
+		const provisioned = {
+			Orders: orders,
+			Uploads: uploads,
+		} as unknown as ProvisionedManifest;
+
+		const [digest] = provisionCompute(
+			stack,
+			{
+				Orders: { kind: 'database', id: 'Orders' },
+				Uploads: { kind: 'objects', id: 'Uploads', provides: ['UPLOADS_URL'] },
+				Invoice: {
+					kind: 'function',
+					id: 'Invoice',
+					handler: 'apps/api/.gkm/aws/functions/invoice.handler',
+					dependencies: [{ target: 'Uploads', kind: 'objects' }],
+					provides: ['INVOICE_URL'],
+				},
+				Digest: {
+					kind: 'cron',
+					id: 'Digest',
+					handler: 'apps/api/.gkm/aws/crons/digest.handler',
+					schedule: 'rate(1 day)',
+					dependencies: [{ target: 'Orders', kind: 'database' }],
+				},
+			} as never,
+			provisioned,
+		);
+
+		const invoice = provisioned.Invoice as unknown as Function;
+		expect(invoice).toBeInstanceOf(Function);
+		expect(argsOf(invoice)).toMatchObject({
+			name: stack.logicalPrefixedName('Invoice'),
+			handler: 'apps/api/.gkm/aws/functions/invoice.handler',
+			link: [uploads],
+			url: { authorization: 'iam' },
+		});
+		expect(argsOf(invoice).vpc).toBeUndefined();
+
+		// A cron is a schedule, not something to link to; its Lambda reaches
+		// the database, so it runs in the database's network.
+		expect(provisioned.Digest).toBeUndefined();
+		expect(digest).toBeInstanceOf(Cron);
+		expect(argsOf(digest).schedule).toBe('rate(1 day)');
+		expect(argsOf(digest!.processor)).toMatchObject({
+			handler: 'apps/api/.gkm/aws/crons/digest.handler',
+			link: [orders],
+			vpc,
+		});
+	});
+});
+
 describe('kinds provisioned elsewhere', () => {
 	it('skips a worker, which is a process rather than a resource', () => {
 		// A worker in the manifest used to throw UnknownDeclarationKind at synth,

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

@@ -79,46 +79,6 @@ describe('Function', () => {
 			invalidVars: ['SMTP_URL'],
 		});
 	});
-
-	it('builds one function per manifest entry, named for the stack', () => {
-		const functions = Function.fromManifest(
-			stack,
-			{
-				billing: [
-					{
-						name: 'Invoice',
-						handler: '.gkm/aws-lambda/functions/invoice.handler',
-						environment: ['DB_URL'],
-						timeout: 60,
-						memorySize: 512,
-					},
-				],
-				ops: [
-					{
-						name: 'Ping',
-						handler: '.gkm/aws-lambda/functions/ping.handler',
-						environment: [],
-					},
-				],
-			} as never,
-			{ links: [db] },
-		);
-
-		expect(functions.map((f) => argsOf(f))).toEqual([
-			expect.objectContaining({
-				name: stack.logicalPrefixedName('Invoice'),
-				timeout: '60 seconds',
-				memory: '512 MB',
-				link: [db],
-			}),
-			expect.objectContaining({
-				name: stack.logicalPrefixedName('Ping'),
-				timeout: undefined,
-				memory: undefined,
-				link: [],
-			}),
-		]);
-	});
 });
 
 describe('Cron', () => {
@@ -136,37 +96,6 @@ describe('Cron', () => {
 			function: processor.arn,
 		});
 	});
-
-	it('builds a validated function and a schedule per manifest cron', () => {
-		const crons = Cron.fromManifest(
-			stack,
-			[
-				{
-					name: 'Digest',
-					handler: '.gkm/aws-lambda/crons/digest.handler',
-					schedule: 'cron(0 8 * * ? *)',
-					environment: ['DB_URL'],
-					timeout: 120,
-					memorySize: 1024,
-				},
-				{
-					name: 'Sweep',
-					handler: '.gkm/aws-lambda/crons/sweep.handler',
-					schedule: 'rate(1 hour)',
-					environment: [],
-				},
-			] as never,
-			{ links: [db], enabled: true },
-		);
-
-		const [digest, sweep] = crons.map((c) => argsOf(c));
-		expect(digest).toMatchObject({
-			schedule: 'cron(0 8 * * ? *)',
-			enabled: true,
-			function: expect.stringContaining('DigestFunction'),
-		});
-		expect(sweep).toMatchObject({ schedule: 'rate(1 hour)' });
-	});
 });
 
 describe('App and Stack', () => {

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';
@@ -157,44 +152,6 @@ export class Api<
 		}
 	}
 
-	/**
-	 * 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>,

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/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/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

@@ -87,6 +87,7 @@ export class Queue<
 				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 } } : {},
@@ -104,10 +105,12 @@ export class Queue<
 
 /** The queue's one consumer, as {@link Queue.consume} subscribes it. */
 export interface QueueConsumer {
-	/** The built handler — `.gkm/aws-lambda/queues/emails.handler`. */
+	/** 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;
 }

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;
+}

package/src/sst/fromManifest.ts

@@ -41,12 +41,15 @@ import {
 	withCacheTable,
 } from './aws/Cache';
 import { Credential } from './aws/Credential';
+import { Cron, type CronSchedule } from './aws/Cron';
 import { Database, DatabaseNeedsVpc, type DatabaseProps } from './aws/Database';
 import { DatabaseBootstrap } from './aws/DatabaseBootstrap';
 import { DatabaseReader, DatabaseSchema } from './aws/DerivedDatabase';
 import { Email, EmailNeedsSender } from './aws/Email';
+import { Encryption, type EncryptionProps } from './aws/Encryption';
 import { ExternalApi, type ExternalApiProps } from './aws/ExternalApi';
 import { FileServer } from './aws/FileServer';
+import { Function } from './aws/Function';
 import { ObjectStorage } from './aws/ObjectStorage';
 import { Queue } from './aws/Queue';
 import { RestApiSurface } from './aws/RestApiSurface';
@@ -378,17 +381,12 @@ const PROVISIONERS: Partial<Record<DeclarationKind, Provisioner>> = {
 	},
 
 	/**
-	 * The surface, without its routes.
+	 * The surface, without its routes yet.
 	 *
-	 * An API Gateway with no routes 404s everything, and that is the honest
-	 * state: the *surface* is what this kind declares, and mounting handlers on
-	 * it is the endpoint merge that has not landed — routes still reach the
-	 * deploy target through the separate `RouteInfo[]` pipeline.
-	 *
-	 * Provisioning it anyway is not ceremony. Its address is what a site inlines
-	 * as `VITE_API_URL`, what an auth server puts on its trusted-origin list, and
-	 * what the cookie domain derives from — so everything downstream of the API
-	 * is blocked on the API *existing*, not on it answering.
+	 * Its address is what a site inlines as `VITE_API_URL`, what an auth server
+	 * puts on its trusted-origin list, and what the cookie domain derives from —
+	 * so it is provisioned in order, and its endpoints are mounted by
+	 * {@link mountRoutes} once everything they link to exists.
 	 */
 	'rest-api': (stack, d, props, context) =>
 		new RestApiSurface(stack, d.id, {
@@ -401,6 +399,17 @@ const PROVISIONERS: Partial<Record<DeclarationKind, Provisioner>> = {
 	// The same storage as a secret, under a different role — see the component.
 	credential: (stack, d, props) => new Credential(stack, d.id, props),
 
+	// In the stage's region, as mail is: a key in another region is a key
+	// every call crosses the world to reach.
+	encryption: (stack, d, props) =>
+		new Encryption(stack, d.id, {
+			...(props as Partial<EncryptionProps>),
+			region:
+				(props as Partial<EncryptionProps>).region ??
+				$app.providers?.aws?.region ??
+				'us-east-1',
+		}),
+
 	// Nothing to provision: the URL this stage calls, and the credentials kept
 	// as a secret.
 	'external-api': (stack, d, props) => {
@@ -593,9 +602,7 @@ function rootCluster(component: Provisioned): Database {
  * printed: one line per route, naming what it can reach.
  *
  * A surface with no routes says so rather than printing nothing, because "no
- * routes yet" and "this printed nothing" look identical otherwise — and for an
- * application's own API that is currently the true state, pending the endpoint
- * merge.
+ * routes" and "this printed nothing" look identical otherwise.
  *
  * Pure, so what gets printed can be asserted without a deploy.
  */
@@ -751,21 +758,132 @@ export function isServed(id: string, manifest: ConstructManifest): boolean {
 }
 
 /**
- * Kinds this stack provisions nothing for of their own.
+ * Kinds the in-order pass skips.
  *
  * - `mobile-app` ships through EAS and the stores. It is in the manifest for
  *   what it makes the surfaces trust, which `callersOf` reads off the graph.
  * - `worker` is a process, not a resource: what it runs is provisioned as
  *   what it is — a queue's consumer by {@link subscribeConsumers}.
- * - `cron` and `function` are Lambdas built from `manifest.crons` and
- *   `manifest.functions` (`Cron.fromManifest`, `Function.fromManifest`).
+ * - `cron` and `function` are Lambdas linked to what they depend on, so they
+ *   are provisioned once all of it exists, by {@link provisionCompute}.
  */
 export const PROVISIONED_ELSEWHERE: ReadonlySet<DeclarationKind> =
 	new Set<DeclarationKind>(['mobile-app', 'worker', 'cron', 'function']);
 
+/**
+ * Every function and cron: a Lambda running the handler the build wrote,
+ * linked to exactly what it depends on, in the database's network when it
+ * reaches one. A cron is that Lambda on its schedule; a function is reached
+ * at its URL, which only callers granted IAM access can invoke.
+ *
+ * After everything else is provisioned, because each links to things
+ * `provisionOrder` does not order before it.
+ */
+export function provisionCompute(
+	stack: StackType,
+	manifest: ConstructManifest,
+	provisioned: ProvisionedManifest,
+): Cron[] {
+	const crons: Cron[] = [];
+
+	for (const [id, declaration] of Object.entries(manifest)) {
+		if (declaration?.kind !== 'function' && declaration?.kind !== 'cron') {
+			continue;
+		}
+
+		const { link } = resolveEdges(declaration.dependencies, provisioned);
+		const vpc = vpcFor(link);
+		const lambda = new Function(
+			stack,
+			declaration.kind === 'cron' ? `${id}Function` : id,
+			{
+				name: stack.logicalPrefixedName(id),
+				handler: declaration.handler,
+				link,
+				...(vpc ? { vpc } : {}),
+				...(declaration.kind === 'function'
+					? { url: { authorization: 'iam' } }
+					: {}),
+			},
+		);
+
+		if (declaration.kind === 'cron') {
+			crons.push(
+				new Cron(stack, id, {
+					processor: lambda,
+					schedule: declaration.schedule as CronSchedule,
+				}),
+			);
+			continue;
+		}
+
+		assertProvides(
+			id,
+			declaration.provides,
+			Object.keys(lambda.provides()).map((role) =>
+				providedKeyFor(id, declaration.kind, role),
+			),
+		);
+		provisioned[id] = lambda;
+	}
+
+	return crons;
+}
+
 /** A provisioned queue: what {@link subscribeConsumers} subscribes through. */
 interface Consumable {
-	consume(consumer: { handler: string; link?: unknown[] }): unknown;
+	consume(consumer: {
+		handler: string;
+		link?: unknown[];
+		vpc?: sst.aws.Vpc;
+	}): unknown;
+}
+
+/**
+ * The network a function has to run in to reach what it links to.
+ *
+ * A database is private to its VPC, so a handler linked to one — or to a
+ * schema tenant or reader of one — runs inside it, or its connection times out.
+ */
+export function vpcFor(link: readonly Provisioned[]): sst.aws.Vpc | undefined {
+	for (const component of link) {
+		const cluster = rootCluster(component);
+		if (cluster instanceof Database) return cluster.vpc;
+	}
+
+	return undefined;
+}
+
+/**
+ * Mount every surface's endpoints — the handlers the build wrote, each linked
+ * to exactly what that endpoint depends on.
+ *
+ * After every construct is provisioned, for the reason consumers are: an
+ * endpoint links to things `provisionOrder` does not order before its surface.
+ */
+export function mountRoutes(
+	manifest: ConstructManifest,
+	provisioned: ProvisionedManifest,
+): void {
+	for (const [id, declaration] of Object.entries(manifest)) {
+		if (declaration?.kind !== 'rest-api') continue;
+
+		const surface = provisioned[id];
+		if (!(surface instanceof RestApiSurface)) continue;
+
+		for (const endpoint of declaration.endpoints) {
+			const { link } = resolveEdges(endpoint.dependencies, provisioned);
+			const vpc = vpcFor(link);
+			surface.mount({
+				method: endpoint.method,
+				path: endpoint.path,
+				handler: endpoint.handler,
+				link,
+				...(vpc ? { vpc } : {}),
+				...(endpoint.authorizer ? { authorizer: endpoint.authorizer } : {}),
+			});
+		}
+	}
 }
 
 /**
@@ -786,7 +904,12 @@ export function subscribeConsumers(
 		if (!queue) continue;
 
 		const { link } = resolveEdges(declaration.worker.dependencies, provisioned);
-		queue.consume({ handler: declaration.worker.handler, link });
+		const vpc = vpcFor(link);
+		queue.consume({
+			handler: declaration.worker.handler,
+			link,
+			...(vpc ? { vpc } : {}),
+		});
 	}
 }
 
@@ -902,8 +1025,11 @@ export function fromManifest(
 		provisioned[id] = component;
 	}
 
-	// Each queue's one consumer, once everything it links to exists.
+	// The functions and crons, each queue's one consumer and each surface's
+	// endpoints, once everything they link to exists.
+	provisionCompute(stack, manifest, provisioned);
 	subscribeConsumers(manifest, provisioned);
+	mountRoutes(manifest, provisioned);
 
 	for (const line of describeRoutes(manifest)) console.log(line);
 

package/src/sst/index.ts

@@ -34,6 +34,7 @@ export {
 } from './aws/DatabaseBootstrap';
 export { DatabaseReader, DatabaseSchema } from './aws/DerivedDatabase';
 export { Email, EmailNeedsUrl, type EmailProps } from './aws/Email';
+export { Encryption, type EncryptionProps } from './aws/Encryption';
 export { FileServer, type FileServerProps } from './aws/FileServer';
 export { Function, type FunctionProps } from './aws/Function';
 export {

package/src/sst/__type-tests__/manifest.type-test.ts

@@ -1,77 +0,0 @@
-// Type-level checks that the `fromManifest` integrators accept the unified
-// `gkm build` manifest shape (`export const manifest = { … } as const`) — both
-// the flat and the partitioned `ManifestField` forms. Checked by `ts:check:sst`.
-
-import type { Manifest, ManifestField, RouteInfo } from '@geekmidas/manifest';
-import { App } from '../App';
-import { Api } from '../aws/Api';
-import { Cron } from '../aws/Cron';
-import { Function } from '../aws/Function';
-import { type GkmLinkable, ResourceType } from '../Linkable';
-
-const stack = new App({
-	name: 'a',
-	stage: 'dev',
-	domain: 'example.com',
-	hostedZoneId: 'Z',
-	region: 'us-east-1',
-}).stack('api');
-
-const db: GkmLinkable = { _id: 'db', _type: ResourceType.Postgres };
-
-// Mirrors a generated `manifest/aws.ts` — one object, `as const`.
-const manifest = {
-	routes: [
-		{
-			path: '/users/{id}',
-			method: 'GET',
-			handler: 'users.handler',
-			authorizer: 'none',
-			environment: ['DB_HOST'],
-			timeout: 30,
-			memorySize: 1024,
-		},
-	],
-	functions: [
-		{ name: 'worker', handler: 'worker.handler', environment: ['DB_URL'] },
-	],
-	crons: [
-		{ name: 'nightly', handler: 'nightly.handler', schedule: 'rate(1 day)' },
-	],
-} as const satisfies Manifest;
-
-// Each integrator takes the manifest *field*.
-export const api = Api.fromManifest(stack, 'Api', manifest.routes, {
-	links: [db],
-	authorizers: { jwt: { issuer: 'https://i', audiences: ['a'] } },
-});
-export const workers = Function.fromManifest(stack, manifest.functions, {
-	links: [db],
-});
-export const crons = Cron.fromManifest(stack, manifest.crons, { links: [db] });
-
-// The partitioned `ManifestField` form is also accepted.
-const partitionedRoutes = {
-	admin: [
-		{
-			path: '/admin',
-			method: 'GET',
-			handler: 'admin.handler',
-			authorizer: 'iam',
-		},
-	],
-	default: [
-		{
-			path: '/health',
-			method: 'GET',
-			handler: 'health.handler',
-			authorizer: 'none',
-		},
-	],
-} satisfies ManifestField<RouteInfo>;
-export const partitionedApi = Api.fromManifest(
-	stack,
-	'PartApi',
-	partitionedRoutes,
-	{ links: [db] },
-);