refactor(hosting): debrand secret engine + injectable namespace

Decouples the secret mechanism from Blocks branding so @aws-blocks/hosting
stays a framework-neutral leaf that any consumer (a plain framework app, a
future standalone hosting package) can use. No behavior change for Blocks users.

@aws-blocks/hosting (neutral engine):
- secretParameterName(key, prefix?) now takes an injectable SSM prefix,
  defaulting to a neutral DEFAULT_SECRET_PARAMETER_PREFIX = '/aws-hosting/secrets'
  (was hardcoded '/blocks/secrets').
- env var prefix renamed BLOCKS_SECRET_PARAM_ -> HOSTING_SECRET_PARAM_
  (internal wiring, framework-neutral).
- Stripped Blocks-specific wording from doc comments + runtime error messages.

@aws-blocks/core (Blocks namespace):
- New secret-naming.ts: BLOCKS_SECRET_PARAMETER_PREFIX='/blocks/secrets' +
  blocksSecretParameterName() = neutral engine + Blocks prefix. Single place
  Blocks pins its namespace.
- hosting-secrets.ts (CDK wiring) and scripts/secret.ts (CLI) now route through
  blocksSecretParameterName(), so Blocks secrets still land at /blocks/secrets/<KEY>
  -> NO SSM-path migration, Blocks users unaffected.

Why: making the engine brand-neutral now turns a future standalone-secret
extraction into a mechanical move instead of a breaking SSM-path migration.
Full extraction into a standalone package is deliberately deferred to the
standalone-hosting work.

Tests: neutral-default + injected-prefix + neutral-env assertions (hosting),
new secret-naming test (core), updated CDK integration assertion to
HOSTING_SECRET_PARAM_. hosting 708 / core 507 green.

Author: osama-rizk

.changeset/hosting-secrets.md

@@ -9,9 +9,11 @@ Introduces a `secret()` reference for sensitive values (API keys, third-party cr
 
 - **`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.
+  - `compute.environment` values resolve at **runtime** (the secure default): the SSM parameter *name* (never the value) is injected as `HOSTING_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()`.
+**Framework-neutral by design (decoupling).** The secret *mechanism* in `@aws-blocks/hosting` carries no Blocks branding: it defaults to a neutral `/aws-hosting/secrets` prefix (`DEFAULT_SECRET_PARAMETER_PREFIX`) and a neutral `HOSTING_SECRET_PARAM_` env prefix, and `secretParameterName(key, prefix?)` takes an injectable namespace. Blocks pins its own `/blocks/secrets` namespace in `@aws-blocks/core` (`blocksSecretParameterName`, `BLOCKS_SECRET_PARAMETER_PREFIX`), so Blocks users see **no change** while a non-Blocks consumer (a plain framework app, or a future standalone hosting package) never inherits Blocks paths. This keeps `@aws-blocks/hosting` a zero-`@aws-blocks/*`-deps leaf and makes a future extraction of the secret engine into a standalone package a mechanical move rather than a breaking SSM-path migration (which is deliberately deferred to that extraction).
+
+Path convention for Blocks is centralized in `blocksSecretParameterName()` (`/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.ts

@@ -28,9 +28,10 @@
  * @module
  */
 
-import { isSecret, type SecretValue, secretEnvVarName, secretParameterName } from '@aws-blocks/hosting';
+import { isSecret, type SecretValue, secretEnvVarName } from '@aws-blocks/hosting';
 import * as cdk from 'aws-cdk-lib';
 import * as iam from 'aws-cdk-lib/aws-iam';
+import { blocksSecretParameterName } from './secret-naming.js';
 
 /** A `compute.environment` value: a literal, or a deferred secret reference. */
 export type EnvValue = string | SecretValue;
@@ -103,7 +104,7 @@ export async function resolveSecretsAtSynth(
 	const resolved = new Map<string, string>();
 	await Promise.all(
 		keys.map(async (key) => {
-			const name = secretParameterName(key);
+			const name = blocksSecretParameterName(key);
 			try {
 				resolved.set(key, await fetcher(name));
 			} catch (error: unknown) {
@@ -144,7 +145,7 @@ export function resolveDomainNames(domainName: DomainNameInput, resolved: Map<st
  * 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);
+	const parameterName = blocksSecretParameterName(key);
 	fn.addEnvironment(secretEnvVarName(key), parameterName);
 
 	const parameterArn = cdk.Stack.of(fn).formatArn({

packages/core/src/hosting.test.ts

@@ -1531,11 +1531,13 @@ describe('Hosting', () => {
 
       const template = Template.fromStack(stack);
 
-      // The compute Lambda gets the param NAME under BLOCKS_SECRET_PARAM_STRIPE_KEY.
+      // The compute Lambda gets the param NAME under the neutral
+      // HOSTING_SECRET_PARAM_ prefix; the Blocks-pinned /blocks/secrets path is
+      // the value (Blocks injects its own namespace over the neutral engine).
       template.hasResourceProperties('AWS::Lambda::Function', {
         Environment: {
           Variables: Match.objectLike({
-            BLOCKS_SECRET_PARAM_STRIPE_KEY: '/blocks/secrets/STRIPE_KEY',
+            HOSTING_SECRET_PARAM_STRIPE_KEY: '/blocks/secrets/STRIPE_KEY',
           }),
         },
       });

packages/core/src/index.cdk.ts

@@ -24,10 +24,14 @@ export {
   getSecret,
   secretParameterName,
   secretEnvVarName,
-  SECRET_PARAMETER_PREFIX,
+  DEFAULT_SECRET_PARAMETER_PREFIX,
   type SecretValue,
   type SecretOptions,
 } from '@aws-blocks/hosting';
+export {
+  BLOCKS_SECRET_PARAMETER_PREFIX,
+  blocksSecretParameterName,
+} from './secret-naming.js';
 export {
   RawRoute,
   RawRouteErrors,

packages/core/src/scripts/secret.ts

@@ -5,7 +5,8 @@
  * `blocks secret` — manage hosting/pipeline secrets in SSM Parameter Store.
  *
  * Secrets are stored as SecureString parameters under `/blocks/secrets/<KEY>`
- * (see {@link secretParameterName} — the single source of truth for the path).
+ * (see {@link blocksSecretParameterName} — the single source of truth for the
+ * Blocks path; the neutral engine lives in `@aws-blocks/hosting/secret`).
  * This is the out-of-band counterpart to `secret('KEY')` in `hosting.ts`:
  * the customer sets values here once; the deploy only ever READS them.
  *
@@ -21,7 +22,8 @@
  * @module
  */
 
-import { SECRET_PARAMETER_PREFIX, secretEnvVarName, secretParameterName } from '@aws-blocks/hosting/secret';
+import { secretEnvVarName } from '@aws-blocks/hosting/secret';
+import { BLOCKS_SECRET_PARAMETER_PREFIX, blocksSecretParameterName } from '../secret-naming.js';
 
 const KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
@@ -43,7 +45,7 @@ export async function setSecret(key: string, value: string): Promise<void> {
 	}
 	const { SSMClient, PutParameterCommand } = await import('@aws-sdk/client-ssm');
 	const client = new SSMClient({});
-	const name = secretParameterName(key);
+	const name = blocksSecretParameterName(key);
 	await client.send(
 		new PutParameterCommand({
 			Name: name,
@@ -64,14 +66,14 @@ export async function listSecrets(): Promise<string[]> {
 	do {
 		const result = await client.send(
 			new GetParametersByPathCommand({
-				Path: SECRET_PARAMETER_PREFIX,
+				Path: BLOCKS_SECRET_PARAMETER_PREFIX,
 				Recursive: false,
 				WithDecryption: false, // names only — never decrypt for a list
 				NextToken: nextToken,
 			}),
 		);
 		for (const p of result.Parameters ?? []) {
-			if (p.Name) keys.push(p.Name.slice(SECRET_PARAMETER_PREFIX.length + 1));
+			if (p.Name) keys.push(p.Name.slice(BLOCKS_SECRET_PARAMETER_PREFIX.length + 1));
 		}
 		nextToken = result.NextToken;
 	} while (nextToken);
@@ -84,7 +86,7 @@ export async function removeSecret(key: string): Promise<boolean> {
 	const { SSMClient, DeleteParameterCommand } = await import('@aws-sdk/client-ssm');
 	const client = new SSMClient({});
 	try {
-		await client.send(new DeleteParameterCommand({ Name: secretParameterName(key) }));
+		await client.send(new DeleteParameterCommand({ Name: blocksSecretParameterName(key) }));
 		console.log(`🗑️  Secret '${key}' removed.`);
 		return true;
 	} catch (error: unknown) {

packages/core/src/secret-naming.test.ts

@@ -0,0 +1,21 @@
+// 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 { secretParameterName } from '@aws-blocks/hosting/secret';
+import { BLOCKS_SECRET_PARAMETER_PREFIX, blocksSecretParameterName } from './secret-naming.js';
+
+void describe('Blocks secret namespace', () => {
+	void it('pins the Blocks /blocks/secrets prefix (unchanged behavior for Blocks users)', () => {
+		assert.strictEqual(BLOCKS_SECRET_PARAMETER_PREFIX, '/blocks/secrets');
+		assert.strictEqual(blocksSecretParameterName('STRIPE_KEY'), '/blocks/secrets/STRIPE_KEY');
+	});
+
+	void it('is exactly the neutral engine + the Blocks prefix (no divergent logic)', () => {
+		assert.strictEqual(
+			blocksSecretParameterName('DOMAIN_PROD'),
+			secretParameterName('DOMAIN_PROD', BLOCKS_SECRET_PARAMETER_PREFIX),
+		);
+	});
+});

packages/core/src/secret-naming.ts

@@ -0,0 +1,39 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Blocks-owned SSM namespace for hosting secrets.
+ *
+ * The secret *mechanism* (marker, runtime resolver, path/env naming) lives in
+ * the framework-neutral `@aws-blocks/hosting` package, which defaults to a
+ * neutral `/aws-hosting/secrets` prefix so a non-Blocks consumer (a plain
+ * framework app, a future standalone hosting package) never inherits Blocks
+ * branding.
+ *
+ * This module is the ONE place Blocks pins its own namespace. Every Blocks-side
+ * caller — the `secret` CLI (`scripts/secret.ts`) and the CDK wiring
+ * (`hosting-secrets.ts`) — routes through {@link blocksSecretParameterName} so
+ * Blocks secrets consistently land at `/blocks/secrets/<KEY>`, alongside the
+ * existing `/blocks/{stage}/db-connection-string` convention. Keeping the prefix
+ * here (not in the hosting leaf) is what makes the future extraction of the
+ * secret mechanism into a standalone package a mechanical move rather than a
+ * breaking SSM-path migration.
+ *
+ * @module
+ */
+
+import { secretParameterName } from '@aws-blocks/hosting/secret';
+
+/** Blocks SSM prefix for hosting secrets. Blocks pins `/blocks`; the leaf stays neutral. */
+export const BLOCKS_SECRET_PARAMETER_PREFIX = '/blocks/secrets';
+
+/**
+ * Blocks-namespaced SSM parameter name for a secret key.
+ * Thin wrapper over the neutral {@link secretParameterName} that always injects
+ * the Blocks prefix, so callers can't accidentally use the neutral default.
+ *
+ * @example blocksSecretParameterName('STRIPE_KEY') // '/blocks/secrets/STRIPE_KEY'
+ */
+export function blocksSecretParameterName(key: string): string {
+	return secretParameterName(key, BLOCKS_SECRET_PARAMETER_PREFIX);
+}

packages/hosting/src/index.ts

@@ -27,7 +27,7 @@ export {
   secretParameterName,
   secretEnvVarName,
   SECRET_BRAND,
-  SECRET_PARAMETER_PREFIX,
+  DEFAULT_SECRET_PARAMETER_PREFIX,
   type SecretValue,
   type SecretOptions,
 } from './secret.js';

packages/hosting/src/secret-exports.ts

@@ -15,7 +15,7 @@
 export {
 	isSecret,
 	SECRET_BRAND,
-	SECRET_PARAMETER_PREFIX,
+	DEFAULT_SECRET_PARAMETER_PREFIX,
 	type SecretOptions,
 	type SecretValue,
 	secret,

packages/hosting/src/secret-runtime.ts

@@ -10,7 +10,7 @@
  * Resolution order for a key:
  *   1. `process.env[KEY]` — local dev (and the `exposeAsEnv` escape hatch),
  *      where the plaintext is already present. No AWS call, works offline.
- *   2. `process.env[BLOCKS_SECRET_PARAM_<KEY>]` — the SSM parameter NAME the
+ *   2. `process.env[HOSTING_SECRET_PARAM_<KEY>]` — the SSM parameter NAME the
  *      Hosting wiring injected. Fetch + decrypt via SSM, then cache.
  *
  * The value is held only in process memory and only after the first call;
@@ -44,8 +44,8 @@ async function defaultSsmFetcher(parameterName: string): Promise<string> {
 	const value = result.Parameter?.Value;
 	if (value === undefined || value === null) {
 		throw new Error(
-			`[Blocks] Secret parameter "${parameterName}" exists but has no value. ` +
-				`Set it with: blocks secret set <KEY> <value>`,
+			`[hosting] Secret parameter "${parameterName}" exists but has no value. ` +
+				`Set it with your secret CLI (e.g. \`secret set <KEY> <value>\`).`,
 		);
 	}
 	return value;
@@ -75,9 +75,10 @@ export async function getSecret(key: string): Promise<string> {
 	const parameterName = process.env[secretEnvVarName(key)];
 	if (!parameterName) {
 		throw new Error(
-			`[Blocks] getSecret(${JSON.stringify(key)}): no secret reference found. ` +
+			`[hosting] getSecret(${JSON.stringify(key)}): no secret reference found. ` +
 				`Reference it in Hosting props with secret(${JSON.stringify(key)}) so the ` +
-				`parameter is wired, and set its value with: blocks secret set ${key} <value>`,
+				`parameter is wired, and set its value with your secret CLI ` +
+				`(e.g. \`secret set ${key} <value>\`).`,
 		);
 	}