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

[osama-rizk]

What & why

Adds secret() support to hosting and pipeline — a way to reference sensitive values (API keys, third-party credentials, source connection ARNs, custom domains) without hardcoding them in source, committing them to git, or leaking them into the CloudFormation template.

Opt-in and non-blocking — apps not using secret() are unaffected, and apps using native .env / third-party stores keep working.

Target consumers

One shared engine serves the ways an SSR app reaches aws-blocks hosting, with no coupling between them:

Consumer	How it uses hosting	What secret() gives it
Blocks app	via @aws-blocks/core's Hosting block (@aws-blocks/blocks/cdk)	secret() in environment/domain + getSecret() in SSR + npm run secret CLI (/blocks/secrets/<KEY>). Can also keep secrets in a backend AppSetting — both work.
Standalone app	imports only @aws-blocks/hosting (the L3 construct directly, no Blocks backend)	The whole story — no backend, no AppSetting: HostingConstruct wires runtime markers; getSecret() + npm run secret with the app's own prefix.

The key enabler: runtime marker resolution lives in the shared HostingConstruct (not just core.Hosting), so a standalone app that uses the construct directly gets runtime secrets with zero extra code.

How it works

secret('STRIPE_KEY') returns a dependency-free marker (a "claim ticket"), not the value. The value lives encrypted in the store (Secrets Manager by default, per AWS's guidance for application credentials; SSM SecureString via store: 'ssm' for non-sensitive config) and is set out-of-band via the CLI. Markers resolve with one of two strategies, chosen per prop:

Prop	Strategy	Why
compute.environment	Runtime (default) — inject the store locator, grant read on that one resource (secretsmanager:GetSecretValue or ssm:GetParameter) + kms:Decrypt, resolve via getSecret() on first use	Value stays encrypted at rest; never in the template
domain.domainName, secret(…, { exposeAsEnv: true })	Synth-time — SDK fetch, inline literal	ssm-secure CFN dynamic refs aren't allowed in CloudFront Aliases / Lambda env (allowlist-restricted); a domain is public anyway
pipeline source.connectionArn	Synth-time — resolved via the shared hosting resolver	Consumed by the CodePipeline service, which needs a literal ARN in the template
pipeline buildSecrets	Build-time — injected as CodeBuild SECRETS_MANAGER/PARAMETER_STORE env vars	Consumed by your build commands; CodeBuild fetches per build (masked in logs), so no redeploy to rotate

• Store (default: Secrets Manager; SSM opt-in). Follows AWS's public guidance (How to choose the right AWS service for managing secrets and configurations): Secrets Manager for application secrets/credentials, Parameter Store for non-sensitive config. Pick per consumer via store.
• IAM is least-privilege. Each runtime secret grants read (secretsmanager:GetSecretValue or ssm:GetParameter) on that one resource's ARN + kms:Decrypt conditioned on kms:ViaService.
• Never leaves the server. Runtime secrets are fetched inside the compute Lambda and never enter the CloudFormation template, the client bundle, or list output.

Usage

End-to-end, there are three steps: declare the reference in infra, set the value out-of-band once, retrieve it where it's used.

1. Declare — reference the secret in infra

import { Hosting, secret } from '@aws-blocks/blocks/cdk';

// Async create() is required when any secret resolves at synth time
// (a custom domain, or exposeAsEnv). It's safe to use uniformly.
await Hosting.create(stack, 'Web', {
  root: '.', framework: 'nextjs', api: blocksStack,
  environment: {
    STRIPE_KEY: secret('STRIPE_KEY'),                       // runtime, encrypted (default)
    SENTRY_DSN: secret('SENTRY_DSN', { exposeAsEnv: true }),// synth-time plaintext env (escape hatch)
  },
  domain: { domainName: secret('DOMAIN_PROD') },            // synth-time literal
});

A standalone app (no Blocks backend) uses the construct directly:

import { HostingConstruct } from '@aws-blocks/hosting/constructs';
import { secret } from '@aws-blocks/hosting';

new HostingConstruct(stack, 'Web', {
  manifest,                                          // from the framework adapter
  environment: { STRIPE_KEY: secret('STRIPE_KEY') },
  secrets: { prefix: '/myapp/secrets' },             // optional: pin your own namespace/store
});

2. Set — write the value out-of-band (never in source)

npm run secret -- set STRIPE_KEY "sk_live_…"      # writes to the store, encrypted
npm run secret -- list                             # names only, never values
npm run secret -- remove STRIPE_KEY

Choosing the store (default is Secrets Manager; opt into SSM for non-sensitive config): the CLI wrapper passes store: 'ssm'. The CLI and the deploy must agree on the store and prefix so the value is written and read under the same locator.

3. Retrieve — read it at request time

import { getSecret } from '@aws-blocks/blocks';           // or '@aws-blocks/hosting' for a standalone app

export async function GET() {
  const key = await getSecret('STRIPE_KEY');              // fetch + decrypt once, then cached
  // … use `key` server-side; it is never sent to the browser …
}

For an exposeAsEnv secret, process.env.SENTRY_DSN works directly (no runtime call) — at the cost of the value being inlined in the Lambda config.

Per-stage values with shared fallback (optional)

Give one key a different value per environment, falling back to a shared default:

npm run secret -- set STRIPE_KEY "sk_live_prod"  --stage prod
npm run secret -- set STRIPE_KEY "sk_test_shared"           # shared fallback (no --stage)

Resolution tries <prefix>/<stage>/<key> and falls back to the shared <prefix>/<key> when the stage has none — so prod/beta differ while ephemeral PR/preview stages inherit the shared default. For runtime secrets the fallback is a two-try at request time, so a per-stage value can be added or rotated without a redeploy. Omit stage entirely for a flat single namespace (unchanged behavior).

Pipeline secrets

A pipeline uses secret() in two places, for its two different consumers:

import { Pipeline, secret } from '@aws-blocks/pipeline';

await Pipeline.create(stack, 'Pipeline', {
  // (1) The CodePipeline SERVICE authenticates to the repo — resolved at synth.
  source: { repo: 'org/app', connectionArn: secret('CONNECTION_ARN') },

  // (2) Credentials your BUILD COMMANDS need — fetched by CodeBuild at build
  //     time (SECRETS_MANAGER/PARAMETER_STORE env vars, masked in logs).
  buildSecrets: {
    NPM_TOKEN: secret('NPM_TOKEN'),
    DOCKERHUB_PASSWORD: secret('DOCKERHUB_PASSWORD'),
  },
  synth: {
    commands: [
      'npm ci --//registry.npmjs.org/:_authToken=$NPM_TOKEN',
      'docker login -u me -p $DOCKERHUB_PASSWORD',
      'npx cdk synth',
    ],
  },
  branches: [{ branch: 'main', stages: [{ name: 'prod' }] }],
});

Set both with the same CLI (secret set CONNECTION_ARN …, secret set NPM_TOKEN …). connectionArn is synth-time (the service needs a literal ARN in the template); buildSecrets are build-time (CodeBuild fetches them per build, so they rotate without a redeploy).

Rotation

Re-run secret set with the new value. Runtime hosting secrets and pipeline buildSecrets pick it up on the next cold start / next build — no redeploy. Synth-time secrets (exposeAsEnv, domain, connectionArn) are baked in at deploy, so those require a redeploy to re-inline.

Tests

• hosting: marker creation/validation, path/env naming, the resolve engine (partition / resolve-synth / wire-runtime, per-stage + fallback), the CLI core (incl. --stage), getSecret() runtime resolver (env-first, fetch+decrypt, cache, concurrent coalescing, store hint, two-try fallback), and construct-level assertions (locator injected, value absent, exposeAsEnv rejected pre-resolution, IAM scoped).
• pipeline: connectionArn marker resolved at synth + sync-path rejection.
• core: unchanged (marker stripping + Hosting CDK-assertion tests).
• Full suites green: hosting 788, pipeline 84.

End-to-end verification (live deploy)

Each consumer was deployed to a disposable sandbox account and probed at a route that calls getSecret('DEMO_SECRET') in the SSR Lambda. The probe returns only a masked fingerprint (value length + a truncated hash) — never the value — so resolution is proven without exposing the secret.

Verified on each deployed Lambda: the env var carries the store locator (not the value), the raw value is absent from the Lambda env and the CloudFormation template, the compute role's read grant is scoped to that one secret's ARN, and kms:Decrypt is conditioned on kms:ViaService. Both stores were exercised live — the SSM path and the Secrets Manager default each resolved end-to-end with the correct fingerprint and least-privilege IAM. The exposeAsEnv path correctly inlines a plaintext env var (the documented escape hatch). (Live account IDs, distribution hostnames, and secret material are intentionally omitted here.)

Bug caught by the live run (and fixed): the neutral default prefix /aws-hosting/secrets is rejected by AWS — SSM reserves any parameter path starting with aws/ssm. Changed to /hosting/secrets. A second issue on the Secrets Manager path — the created secret name and the IAM ARN the grant scoped to disagreed on the leading slash — is fixed by a single secretStoreLocator() helper shared by the CLI, the grant, and the runtime read.

Follow-ups (not in this PR)

• Region ergonomics — the CLI writes in the default region; if that differs from the deploy region, synth/runtime reports "secret not set". Consider deriving/accepting the deploy region in the CLI.
• Type-safe keys — a defineSecrets({...}) builder (pure TS inference, no codegen) could make a typo in a key a compile error rather than a runtime not-found.

[changeset-bot]

🦋 Changeset detected

Latest commit: 3cf3c2a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 25 packages

Name	Type
@aws-blocks/hosting	Minor
@aws-blocks/core	Minor
@aws-blocks/pipeline	Minor
@aws-blocks/create-blocks-app	Patch
@aws-blocks/bb-kv-store	Patch
@aws-blocks/bb-distributed-table	Patch
@aws-blocks/auth-common	Patch
@aws-blocks/bb-app-setting	Patch
@aws-blocks/bb-data	Patch
@aws-blocks/bb-distributed-data	Patch
@aws-blocks/bb-auth-basic	Patch
@aws-blocks/bb-auth-cognito	Patch
@aws-blocks/bb-auth-oidc	Patch
@aws-blocks/bb-realtime	Patch
@aws-blocks/bb-async-job	Patch
@aws-blocks/bb-dashboard	Patch
@aws-blocks/bb-cron-job	Patch
@aws-blocks/bb-file-bucket	Patch
@aws-blocks/bb-agent	Patch
@aws-blocks/bb-knowledge-base	Patch
@aws-blocks/bb-logger	Patch
@aws-blocks/bb-email-client	Patch
@aws-blocks/bb-tracer	Patch
@aws-blocks/bb-metrics	Patch
@aws-blocks/blocks	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[bobbor]

Hey @osama-rizk, really impressive work here 🙌 The PR description alone deserves a shout-out, and the design has a lot of genuinely great calls: the shared secretStoreLocator() helper (love that it was born from a live-caught bug), the branded-symbol marker, the coalescing cache in getSecret(), the fail-fast on unresolved exposeAsEnv, and the CodeBuild-native buildSecrets wiring. Test coverage actually asserts the security-relevant behavior too, not just the happy paths 👏

That said, I dug in pretty deep and found a couple of things I'd consider blocking, plus some smaller ones. Details are in the inline comments; TL;DR:

🔴 Blocking

1. Cross-stage IAM over-grant: preview/PR stages get standing IAM read on the shared fallback secret (see secret-resolve.ts comment)
2. Duplicate kms:Decrypt statements per secret: policy bloat that can approach the 10KB inline policy limit

🟠 Worth fixing in this PR
3. Secret values land in argv / shell history via secret set KEY value
4. Default prefix /hosting/secrets is account-global, so two apps in one account collide
5. Plain Error throws in secret-resolve.ts while the rest of hosting uses structured HostingError
6. Pipeline's new dep on "@aws-blocks/hosting": "*" resolves to any version once published
7. Secrets Manager list leaks stage-scoped entries into the shared-namespace listing
8. core's hosting-secrets.ts duplicates the resolve engine as an SSM-only variant with no guard against divergence

🟡 Minor / fast-follow

• No cache TTL in getSecret(): rotation only lands on cold start, which can be hours with provisioned concurrency
• sub_path_exports.test.ts wasn't updated for the new ./secret entry
• No README/docs updates despite the new public API and CLI workflow
• Template secret.ts files use 2-space indent while biome.json mandates tabs; also the hosting/src/index.ts reformat of existing exports inflates the diff a bit
• CLI region mismatch: you already called it out as a follow-up, a --region flag would be cheap insurance
• Worth confirming API.md came from api-extractor and not a hand edit

One thing I checked so nobody else trips on it: requestHandler: { requestTimeout: 5000 } is totally fine 👍 the plain-object short form is officially supported since SDK v3.521.0, so no change needed there.

Overall: really solid feature, and the two blocking items are fixable without touching the architecture. Happy to re-review quickly once they're addressed 🚀

[bobbor]

🔴 Blocking: cross-stage IAM over-grant on the shared fallback

This loop grants the compute role read on both the stage locator and the shared fallback <prefix>/<key>, unconditionally. The two-try fallback is only enforced in application logic; the IAM permission is standing. That means every ephemeral PR/preview deploy holds IAM read access to the shared fallback secret at all times, and a compromised handler in a preview stage can call GetSecretValue on the fallback ARN directly, bypassing the two-try logic.

The docs example (sk_test_shared as fallback) is safe, but nothing stops or warns the inverse (someone putting a prod value in the shared slot and letting previews "inherit" it).

Suggestions: make the fallback grant opt-in per stage, or document loudly that the shared fallback must never hold production values (safe dev defaults only).

[bobbor]

🔴 Blocking: duplicate kms:Decrypt statements per secret

grantSecretRead is called once per locator, and each call appends its own kms:Decrypt statement (Resource: '*' + kms:ViaService condition). CDK doesn't deduplicate addToRolePolicy, so N secrets with stage fallbacks means up to 2N identical kms:Decrypt statements. Beyond the noise, this bloats the inline policy toward the 10KB limit for apps with several secrets.

Suggestion: hoist the KMS grant out of the per-locator path and add it once per store type after the read grants.

(The Resource: '*' + ViaService pattern itself is fine 👍 that's the documented approach for service-default keys and matches the existing AppSetting code.)

[bobbor]

🟠 Secret values land in argv and shell history

secret set STRIPE_KEY sk_live_… puts the value into process.argv, which makes it visible in ps output, /proc/*/cmdline, and shell history files. For a tool whose whole pitch is "secrets never end up in git", this is a bit ironic 😅 and it's exactly the kind of footgun the target audience (external devs) will hit.

Suggestion: support --value-stdin or an interactive prompt, or at minimum document the exposure prominently in the CLI help.

[bobbor]

🟠 Default prefix is account-global

Two standalone apps in the same account using this default share one namespace: same key name means literally the same secret, and secret list enumerates entries across apps. That's a realistic scenario for the target audience (one personal account, several apps).

Suggestion: derive the default from the app/stack name, or document clearly that multi-app accounts must set a unique prefix.

[bobbor]

🟠 Convention: plain Error vs HostingError

hosting_construct.ts uses structured HostingError ({code, message, resolution}) exclusively, 14 instances and zero plain throws, but the throws in this file (partitionEnvironment, resolveSecretsAtSynth, resolveDomainNames) are plain new Error(...). The exposeSecrets path in the construct got it right with HostingError('UnresolvedSecretError', …). Consumers lose the error-code contract for these paths.

[bobbor]

🟠 Bare "*" dependency on a published package

Pipeline previously had no runtime deps. In the workspace this resolves locally, but in the published package "*" accepts any hosting version whatsoever, which will break consumers on the first incompatible hosting release. Suggest pinning to a proper semver range.

[bobbor]

🟠 SM list leaks stage-scoped entries into the shared listing

The SSM path uses Recursive: false to keep the listing flat, but this Secrets Manager name filter is a plain prefix match with no depth control, so stage-scoped secrets show up in the shared-namespace listing as prod/KEY etc.

Suggestion: after slicing the prefix, filter out names containing / (or group them by stage, which would actually be a nice UX).

[bobbor]

🟠 SSM-only duplicate of the hosting resolve engine

This is a reimplementation of hosting/src/secret-resolve.ts's engine, hardcoded to SSM (no _STORE hint, no stage/fallback, SSM-only IAM). That's consistent today because core pins the Blocks SSM namespace, but there's no comment or assertion saying "SSM-only by design", so the two engines can silently diverge (e.g. if someone later threads a store option through core, they'd get SSM grants with a Secrets Manager runtime read → AccessDenied).

Suggestion: a one-line comment/assertion making the SSM-only contract explicit, or share the engine.

[bobbor]

🟡 No TTL: rotation only lands on cold start

The docs say rotated values are picked up "on the next cold start", which is accurate, but with provisioned concurrency or steady traffic a warm sandbox can serve a stale value for hours. Not blocking, but a configurable TTL (even a generous default like 5-15 min) or a prominent note in the rotation docs would save someone a confusing incident.

[bobbor]

🟡 Missing subpath export test

sub_path_exports.test.ts covers ./constructs, ./adapters, and ./error but wasn't updated for this new ./secret entry. Cheap test, catches broken published artifacts.