feat(hosting): add secret() for self-hosted deployments

Adds a secret() reference for sensitive values (API keys, third-party
credentials, custom domains) backed by SSM Parameter Store SecureString,
so they are never hardcoded, committed, or written into the CFN template.

- secret('KEY') marker: dependency-free value object in @aws-blocks/hosting
  (re-exported via core/blocks), so @aws-blocks/pipeline can later share it
  without a dependency cycle.
- Two resolution strategies, chosen per prop:
  * compute.environment -> RUNTIME (secure default): inject the SSM param
    NAME as BLOCKS_SECRET_PARAM_<KEY>, grant ssm:GetParameter (scoped) +
    kms:Decrypt (kms:ViaService); getSecret('KEY') fetches+decrypts on first
    use. Value stays encrypted at rest; never in the template.
  * domain.domainName and secret(..., { exposeAsEnv: true }) -> SYNTH TIME
    via SDK GetParameter(WithDecryption), inlined as literal. ssm-secure CFN
    dynamic refs are not allowed in CloudFront Aliases / Lambda env, so
    synth-time SDK resolution is correct; a domain is public anyway. Async,
    so use await Hosting.create(scope, id, props).
- getSecret('KEY') runtime resolver: env-first (local dev / exposeAsEnv),
  else SSM fetch+decrypt, cached per cold start, concurrent calls coalesced.
- secret CLI (runSecretCli/setSecret/listSecrets/removeSecret):
  blocks secret set/list/remove manage SecureStrings at /blocks/secrets/<KEY>
  (flat namespace, 1:1 key<->reference). list returns names only. Wired into
  the nextjs template as npm run secret.

Path convention centralized in secretParameterName() (/blocks/secrets/<KEY>).
Backward compatible: new Hosting() still works; only synth-time secrets need
Hosting.create(). Unit + CDK-assertion tests cover marker, runtime resolver,
partition/resolution helpers, IAM grants, and no-plaintext-leak.

Author: osama-rizk

.changeset/hosting-secrets.md

@@ -0,0 +1,17 @@
+---
+"@aws-blocks/hosting": minor
+"@aws-blocks/core": minor
+---
+
+Add `secret()` support to hosting for self-hosted deployments.
+
+Introduces a `secret()` reference for sensitive values (API keys, third-party credentials, custom domains) backed by an SSM Parameter Store SecureString — so they're never hardcoded in source, committed to git, or written into the CloudFormation template.
+
+- **`secret('KEY')` marker** — exported from `@aws-blocks/hosting` (and re-exported from `@aws-blocks/core` / `@aws-blocks/blocks`). A dependency-free value object so it can later be shared with `@aws-blocks/pipeline` without a dependency cycle. Pass it into `Hosting` props.
+- **Two resolution strategies, chosen per prop:**
+  - `compute.environment` values resolve at **runtime** (the secure default): the SSM parameter *name* (never the value) is injected as `BLOCKS_SECRET_PARAM_<KEY>`, the compute role is granted `ssm:GetParameter` (scoped to that one ARN) + `kms:Decrypt` (conditioned on `kms:ViaService`), and the value is fetched + decrypted on first use via `getSecret('KEY')`. The secret stays encrypted at rest and never enters the template.
+  - `domain.domainName` and `secret(..., { exposeAsEnv: true })` resolve at **synth time** via an SDK `GetParameter(WithDecryption)` call and are inlined as literals. `ssm-secure` CloudFormation dynamic references are restricted to an allowlist that excludes CloudFront `Aliases` and Lambda env vars, so synth-time SDK resolution is the correct mechanism; a domain is public anyway. Synth-time resolution is async — use the new `await Hosting.create(scope, id, props)`.
+- **`getSecret('KEY')` runtime resolver** — reads `process.env.KEY` first (local dev / `exposeAsEnv`), else fetches + decrypts the injected SSM parameter, caching per cold start and coalescing concurrent calls. Mirrors the existing `AppSetting` / external-DB connection-string pattern.
+- **`secret` CLI** (`runSecretCli`, `setSecret`, `listSecrets`, `removeSecret`) — `blocks secret set/list/remove` manage SecureStrings at `/blocks/secrets/<KEY>` (flat namespace, 1:1 key↔reference, no stage scoping). `list` returns names only, never values. Wired into the Next.js template as `npm run secret`.
+
+Path convention is centralized in `secretParameterName()` (`/blocks/secrets/<KEY>`), alongside the existing `/blocks/{stage}/db-connection-string`. Backward compatible: `new Hosting(...)` keeps working for plain config and runtime secrets; only synth-time secrets require `Hosting.create()`.

packages/core/src/hosting-secrets.test.ts

@@ -0,0 +1,105 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+import { secret } from '@aws-blocks/hosting';
+import {
+	collectSynthSecretKeys,
+	partitionEnvironment,
+	resolveDomainNames,
+	resolveSecretsAtSynth,
+} from './hosting-secrets.js';
+
+void describe('partitionEnvironment()', () => {
+	void it('splits plain / runtime-secret / exposeAsEnv', () => {
+		const { plain, runtimeSecrets, exposeSecrets } = partitionEnvironment({
+			FLAG: 'on',
+			STRIPE_KEY: secret('STRIPE_KEY'),
+			LEGACY: secret('LEGACY', { exposeAsEnv: true }),
+		});
+		assert.deepStrictEqual(plain, { FLAG: 'on' });
+		assert.deepStrictEqual(
+			runtimeSecrets.map((s) => s.key),
+			['STRIPE_KEY'],
+		);
+		assert.deepStrictEqual(
+			exposeSecrets.map((s) => s.key),
+			['LEGACY'],
+		);
+	});
+
+	void it('rejects env key / secret key mismatch', () => {
+		assert.throws(
+			() => partitionEnvironment({ STRIPE_KEY: secret('OTHER') }),
+			/must match the environment variable name/,
+		);
+	});
+
+	void it('handles undefined', () => {
+		const { plain, runtimeSecrets, exposeSecrets } = partitionEnvironment(undefined);
+		assert.deepStrictEqual(plain, {});
+		assert.strictEqual(runtimeSecrets.length, 0);
+		assert.strictEqual(exposeSecrets.length, 0);
+	});
+});
+
+void describe('collectSynthSecretKeys()', () => {
+	void it('gathers domain + exposeAsEnv keys, deduped', () => {
+		const keys = collectSynthSecretKeys(
+			['example.com', secret('DOMAIN_PROD')],
+			[secret('LEGACY', { exposeAsEnv: true }), secret('DOMAIN_PROD', { exposeAsEnv: true })],
+		);
+		assert.deepStrictEqual([...keys].sort(), ['DOMAIN_PROD', 'LEGACY']);
+	});
+
+	void it('returns nothing when no synth-time secrets exist', () => {
+		assert.deepStrictEqual(collectSynthSecretKeys('example.com', []), []);
+		assert.deepStrictEqual(collectSynthSecretKeys(undefined, []), []);
+	});
+});
+
+void describe('resolveSecretsAtSynth()', () => {
+	void it('fetches each referenced key with decryption', async () => {
+		const seen: string[] = [];
+		const resolved = await resolveSecretsAtSynth(['DOMAIN_PROD'], async (name) => {
+			seen.push(name);
+			return 'prod.example.com';
+		});
+		assert.deepStrictEqual(seen, ['/blocks/secrets/DOMAIN_PROD']);
+		assert.strictEqual(resolved.get('DOMAIN_PROD'), 'prod.example.com');
+	});
+
+	void it('throws an actionable error when a secret is not set', async () => {
+		await assert.rejects(
+			resolveSecretsAtSynth(['DOMAIN_PROD'], async () => {
+				const e = new Error('not found');
+				e.name = 'ParameterNotFound';
+				throw e;
+			}),
+			/blocks secret set DOMAIN_PROD/,
+		);
+	});
+});
+
+void describe('resolveDomainNames()', () => {
+	void it('replaces markers with resolved literals, preserving shape', () => {
+		const resolved = new Map([['DOMAIN_PROD', 'prod.example.com']]);
+		assert.strictEqual(resolveDomainNames(secret('DOMAIN_PROD'), resolved), 'prod.example.com');
+		assert.deepStrictEqual(resolveDomainNames(['www.example.com', secret('DOMAIN_PROD')], resolved), [
+			'www.example.com',
+			'prod.example.com',
+		]);
+	});
+
+	void it('throws if a marker reached the sync path unresolved', () => {
+		assert.throws(
+			() => resolveDomainNames(secret('DOMAIN_PROD'), new Map()),
+			/requires async resolution.*Hosting\.create/s,
+		);
+	});
+
+	void it('passes literal domains through untouched', () => {
+		assert.strictEqual(resolveDomainNames('example.com', new Map()), 'example.com');
+	});
+});

packages/core/src/hosting-secrets.ts

@@ -0,0 +1,192 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Resolution glue between the dependency-free `secret()` marker (defined in
+ * `@aws-blocks/hosting`) and the `Hosting` CDK block. The marker is inert; this
+ * module is where it actually gets wired into infrastructure.
+ *
+ * Two resolution strategies, chosen by where the marker appears:
+ *
+ *   • `compute.environment` (runtime, the secure default) — we inject the SSM
+ *     parameter NAME (never the value) as `BLOCKS_SECRET_PARAM_<KEY>` and grant
+ *     the compute role `ssm:GetParameter` + `kms:Decrypt`. The value is fetched
+ *     and decrypted on first use at runtime via `getSecret()`. The secret stays
+ *     encrypted at rest; it never enters the CloudFormation template.
+ *
+ *   • `domain.domainName` and `exposeAsEnv` env vars (synth time) — resolved by
+ *     an SDK `GetParameter(WithDecryption)` call DURING `cdk synth` and inlined
+ *     as a literal. A SecureString dynamic reference (`{{resolve:ssm-secure}}`)
+ *     can't be used in CloudFront Aliases (CloudFormation restricts ssm-secure
+ *     to an allowlist of properties), so synth-time SDK resolution is the
+ *     correct mechanism. A domain is public the moment the site is live, so
+ *     inlining the literal loses no confidentiality.
+ *
+ * Synth-time resolution is async, which is why callers that use domain secrets
+ * or `exposeAsEnv` must construct via the async `Hosting.create()`.
+ *
+ * @module
+ */
+
+import { isSecret, type SecretValue, secretEnvVarName, secretParameterName } from '@aws-blocks/hosting';
+import * as cdk from 'aws-cdk-lib';
+import * as iam from 'aws-cdk-lib/aws-iam';
+
+/** A `compute.environment` value: a literal, or a deferred secret reference. */
+export type EnvValue = string | SecretValue;
+
+/** A custom-domain name: a literal, a secret, or a mix in an array. */
+export type DomainNameInput = string | SecretValue | Array<string | SecretValue>;
+
+/**
+ * Split an environment map into the three handling buckets.
+ * - `plain` — literal strings, injected verbatim (today's behavior).
+ * - `runtimeSecrets` — `secret('K')`, resolved lazily at runtime.
+ * - `exposeSecrets` — `secret('K', { exposeAsEnv: true })`, resolved at synth.
+ */
+export function partitionEnvironment(environment: Record<string, EnvValue> | undefined): {
+	plain: Record<string, string>;
+	runtimeSecrets: SecretValue[];
+	exposeSecrets: SecretValue[];
+} {
+	const plain: Record<string, string> = {};
+	const runtimeSecrets: SecretValue[] = [];
+	const exposeSecrets: SecretValue[] = [];
+
+	for (const [key, value] of Object.entries(environment ?? {})) {
+		if (isSecret(value)) {
+			// The env-var key the customer wrote IS the secret's logical key.
+			// (Reject a mismatch so `STRIPE_KEY: secret('OTHER')` can't silently
+			// resolve to the wrong parameter at runtime.)
+			if (value.key !== key) {
+				throw new Error(
+					`Hosting environment '${key}': secret key '${value.key}' must match ` +
+						`the environment variable name. Use ${key}: secret('${key}').`,
+				);
+			}
+			(value.exposeAsEnv ? exposeSecrets : runtimeSecrets).push(value);
+		} else {
+			plain[key] = value;
+		}
+	}
+	return { plain, runtimeSecrets, exposeSecrets };
+}
+
+/** Every secret key that requires a synth-time SDK fetch (domain + exposeAsEnv). */
+export function collectSynthSecretKeys(
+	domainName: DomainNameInput | undefined,
+	exposeSecrets: SecretValue[],
+): string[] {
+	const keys = new Set<string>();
+	for (const name of toDomainArray(domainName)) {
+		if (isSecret(name)) keys.add(name.key);
+	}
+	for (const s of exposeSecrets) keys.add(s.key);
+	return [...keys];
+}
+
+/** Normalize the domain input into an array (without resolving markers). */
+function toDomainArray(domainName: DomainNameInput | undefined): Array<string | SecretValue> {
+	if (domainName === undefined) return [];
+	return Array.isArray(domainName) ? domainName : [domainName];
+}
+
+/**
+ * Resolve a set of secret keys to plaintext via the SSM SDK at synth time.
+ * Each parameter is fetched with decryption. Throws a clear, actionable error
+ * if a referenced secret was never set with `blocks secret set`.
+ */
+export async function resolveSecretsAtSynth(
+	keys: string[],
+	fetcher: SsmGetParameter = defaultSsmGetParameter,
+): Promise<Map<string, string>> {
+	const resolved = new Map<string, string>();
+	await Promise.all(
+		keys.map(async (key) => {
+			const name = secretParameterName(key);
+			try {
+				resolved.set(key, await fetcher(name));
+			} catch (error: unknown) {
+				const e = error as { name?: string };
+				if (e?.name === 'ParameterNotFound') {
+					throw new Error(
+						`Hosting: secret '${key}' is referenced (domain or exposeAsEnv) but ` +
+							`not set. Set it before deploying:\n  blocks secret set ${key} <value>`,
+					);
+				}
+				throw error;
+			}
+		}),
+	);
+	return resolved;
+}
+
+/** Resolve domain markers to literals using the synth-resolved secret map. */
+export function resolveDomainNames(domainName: DomainNameInput, resolved: Map<string, string>): string | string[] {
+	const arr = toDomainArray(domainName).map((name) => {
+		if (!isSecret(name)) return name;
+		const value = resolved.get(name.key);
+		if (value === undefined) {
+			// Marker present but not resolved → caller used `new Hosting()` instead
+			// of the async `Hosting.create()`.
+			throw new Error(
+				`Hosting: domain secret('${name.key}') requires async resolution. ` +
+					`Construct with: await Hosting.create(scope, id, props).`,
+			);
+		}
+		return value;
+	});
+	return Array.isArray(domainName) ? arr : arr[0];
+}
+
+/**
+ * Inject the SSM parameter NAME (not the value) for a runtime secret and grant
+ * the compute role read+decrypt access scoped to that one parameter.
+ */
+export function wireRuntimeSecret(fn: cdk.aws_lambda.Function, key: string): void {
+	const parameterName = secretParameterName(key);
+	fn.addEnvironment(secretEnvVarName(key), parameterName);
+
+	const parameterArn = cdk.Stack.of(fn).formatArn({
+		service: 'ssm',
+		resource: 'parameter',
+		// SSM ARNs omit the leading slash of the parameter name.
+		resourceName: parameterName.replace(/^\//, ''),
+	});
+
+	fn.addToRolePolicy(
+		new iam.PolicyStatement({
+			actions: ['ssm:GetParameter'],
+			resources: [parameterArn],
+		}),
+	);
+	// SecureStrings are encrypted with the default `aws/ssm` KMS key. Grant
+	// Decrypt scoped via `kms:ViaService` so the role can only use the key
+	// through SSM — the same scoping the AppSetting block uses.
+	fn.addToRolePolicy(
+		new iam.PolicyStatement({
+			actions: ['kms:Decrypt'],
+			resources: ['*'],
+			conditions: {
+				StringEquals: {
+					'kms:ViaService': `ssm.${cdk.Stack.of(fn).region}.amazonaws.com`,
+				},
+			},
+		}),
+	);
+}
+
+// ── SDK seam (overridable for tests) ────────────────────────────────────────
+
+export type SsmGetParameter = (parameterName: string) => Promise<string>;
+
+async function defaultSsmGetParameter(parameterName: string): Promise<string> {
+	const { SSMClient, GetParameterCommand } = await import('@aws-sdk/client-ssm');
+	const client = new SSMClient({});
+	const result = await client.send(new GetParameterCommand({ Name: parameterName, WithDecryption: true }));
+	const value = result.Parameter?.Value;
+	if (value === undefined || value === null) {
+		throw new Error(`Secret parameter "${parameterName}" has no value.`);
+	}
+	return value;
+}