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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekmidas/cloud",
-  "version": "10.0.0-alpha.46",
+  "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.46",
-    "@geekmidas/manifest": "10.0.0-alpha.46"
+    "@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.46",
-    "@geekmidas/storage": "^10.0.0-alpha.46",
-    "@geekmidas/events": "^10.0.0-alpha.46",
-    "@geekmidas/db": "^10.0.0-alpha.46"
+    "@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__/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__/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/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/fromManifest.ts

@@ -46,6 +46,7 @@ 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';
@@ -398,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) => {

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 {