@aws-blocks/core 0.2.0 → 0.4.0

package/dist/errors.d.ts

@@ -70,6 +70,22 @@ export declare class ApiError extends Error {
 export declare function isBlocksError<N extends string>(e: unknown, name: N): e is Error & {
     name: N;
 };
+/**
+ * Build a named `Error` whose `name` is a BB error constant, so it is matchable
+ * with {@link isBlocksError} on both server and client. The name is also
+ * prefixed into the message for readable logs.
+ *
+ * This is the producer half of the {@link isBlocksError} contract: throw via
+ * this helper so the `name` a consumer matches on is set consistently. It has
+ * no runtime dependencies, so it is safe to use in every bundle — mock,
+ * aws-runtime, and CDK synth.
+ *
+ * @example
+ * ```typescript
+ * throw blocksError(KVStoreErrors.ConditionalCheckFailed, 'Key already exists');
+ * ```
+ */
+export declare function blocksError(name: string, message: string): Error;
 /**
  * Type guard for branching on a failed `AuthState` (the recommended
  * `setAuthState` client path) by its structured `errorName`.

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,aAAa,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,QAAS,SAAQ,KAAK;IAClC,wBAAwB;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;gBAEhB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE;CAM9G;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,IAAI,KAAK,GAAG;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,CAE7F;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,CAAC,SAAS,MAAM,EAC9E,KAAK,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EAC3B,IAAI,EAAE,CAAC,GACL,KAAK,IAAI,CAAC,GAAG;IAAE,SAAS,EAAE,CAAC,CAAA;CAAE,CAE/B"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,aAAa,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,QAAS,SAAQ,KAAK;IAClC,wBAAwB;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;gBAEhB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE;CAM9G;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,IAAI,KAAK,GAAG;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,CAE7F;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,CAIhE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,CAAC,SAAS,MAAM,EAC9E,KAAK,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EAC3B,IAAI,EAAE,CAAC,GACL,KAAK,IAAI,CAAC,GAAG;IAAE,SAAS,EAAE,CAAC,CAAA;CAAE,CAE/B"}

package/dist/errors.js

@@ -73,6 +73,26 @@ export class ApiError extends Error {
 export function isBlocksError(e, name) {
     return e instanceof Error && e.name === name;
 }
+/**
+ * Build a named `Error` whose `name` is a BB error constant, so it is matchable
+ * with {@link isBlocksError} on both server and client. The name is also
+ * prefixed into the message for readable logs.
+ *
+ * This is the producer half of the {@link isBlocksError} contract: throw via
+ * this helper so the `name` a consumer matches on is set consistently. It has
+ * no runtime dependencies, so it is safe to use in every bundle — mock,
+ * aws-runtime, and CDK synth.
+ *
+ * @example
+ * ```typescript
+ * throw blocksError(KVStoreErrors.ConditionalCheckFailed, 'Key already exists');
+ * ```
+ */
+export function blocksError(name, message) {
+    const err = new Error(`${name}: ${message}`);
+    err.name = name;
+    return err;
+}
 /**
  * Type guard for branching on a failed `AuthState` (the recommended
  * `setAuthState` client path) by its structured `errorName`.

package/dist/hosting-secrets.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Resolution glue between the dependency-free `secret()` / `config()` markers
+ * (defined in `@aws-blocks/hosting`) and the `Hosting` CDK block.
+ *
+ * Delegates to the shared `@aws-blocks/hosting` engine, pinning only the Blocks
+ * namespaces (`/blocks/secrets`, `/blocks/config`). The store is derived from the
+ * marker's kind (`secret` → Secrets Manager, `config` → SSM), and BYO
+ * `ISecret`/`IParameter` handles are wired identically.
+ *
+ * @module
+ */
+import type { ManagedValue } from '@aws-blocks/hosting';
+import { type ByoBinding, type DomainNameInput as LeafDomainNameInput, type EnvValue as LeafEnvValue, type SecretFetcher, type StoreConfig } from '@aws-blocks/hosting/constructs';
+import type * as cdk from 'aws-cdk-lib';
+/** A `compute.environment` value: a literal, a managed marker, or a BYO CDK handle. */
+export type EnvValue = LeafEnvValue;
+/** A custom-domain name: a literal, a managed marker, or a mix in an array. */
+export type DomainNameInput = LeafDomainNameInput;
+/** Split an environment map into plain literals, managed markers, and BYO handles. */
+export declare function partitionEnvironment(environment: Record<string, EnvValue> | undefined): {
+    plain: Record<string, string>;
+    managed: ManagedValue[];
+    byo: ByoBinding[];
+};
+/** Every managed marker requiring a synth-time fetch (domain markers only). */
+export declare function collectSynthMarkers(domainName: DomainNameInput | undefined): ManagedValue[];
+/**
+ * Resolve managed markers to plaintext at synth time under the Blocks namespaces.
+ * Throws a clear, actionable error if a referenced value was never set. An optional
+ * `storeConfig` overrides the pinned Blocks prefix/stage per kind.
+ */
+export declare function resolveSecretsAtSynth(markers: ManagedValue[], fetcher?: SecretFetcher, storeConfig?: StoreConfig): Promise<Map<string, string>>;
+/** Resolve domain markers to literals using the synth-resolved value map. */
+export declare function resolveDomainNames(domainName: DomainNameInput, resolved: Map<string, string>): string | string[];
+/**
+ * Fail synth (deploy) when a referenced `environment` marker has no value set —
+ * existence only, never fetching the value. Uses the Blocks namespaces (with an
+ * optional per-kind `storeConfig` override), matching how the values are wired.
+ */
+export declare function assertMarkersExistAtSynth(markers: ManagedValue[], storeConfig?: StoreConfig): Promise<void>;
+/**
+ * Wire a runtime managed marker under the Blocks namespace (store from kind). An
+ * optional `storeConfig` overrides the pinned prefix/stage/cacheTtlSeconds per kind.
+ */
+export declare function wireManagedValue(fn: cdk.aws_lambda.Function, marker: ManagedValue, storeConfig?: StoreConfig): void;
+/** Wire a runtime BYO handle (grant + inject locator). Honors an optional `storeConfig`. */
+export declare function wireByo(fn: cdk.aws_lambda.Function, binding: ByoBinding, storeConfig?: StoreConfig): void;
+//# sourceMappingURL=hosting-secrets.d.ts.map

package/dist/hosting-secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosting-secrets.d.ts","sourceRoot":"","sources":["../src/hosting-secrets.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EACN,KAAK,UAAU,EACf,KAAK,eAAe,IAAI,mBAAmB,EAC3C,KAAK,QAAQ,IAAI,YAAY,EAM7B,KAAK,aAAa,EAClB,KAAK,WAAW,EAGhB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,KAAK,GAAG,MAAM,aAAa,CAAC;AAiBxC,uFAAuF;AACvF,MAAM,MAAM,QAAQ,GAAG,YAAY,CAAC;AAEpC,+EAA+E;AAC/E,MAAM,MAAM,eAAe,GAAG,mBAAmB,CAAC;AAElD,sFAAsF;AACtF,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,SAAS,GAAG;IACxF,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,GAAG,EAAE,UAAU,EAAE,CAAC;CAClB,CAEA;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,eAAe,GAAG,SAAS,GAAG,YAAY,EAAE,CAE3F;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAC1C,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,CAAC,EAAE,aAAa,EACvB,WAAW,CAAC,EAAE,WAAW,GACvB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAE9B;AAED,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,eAAe,EAAE,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,MAAM,EAAE,CAEhH;AAED;;;;GAIG;AACH,wBAAsB,yBAAyB,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,WAAW,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAEjH;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,GAAG,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,CAEnH;AAED,4FAA4F;AAC5F,wBAAgB,OAAO,CAAC,EAAE,EAAE,GAAG,CAAC,UAAU,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,CAEzG"}

package/dist/hosting-secrets.js

@@ -0,0 +1,57 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { assertMarkersExistAtSynth as leafAssertMarkersExistAtSynth, collectSynthMarkers as leafCollectSynthMarkers, partitionEnvironment as leafPartitionEnvironment, resolveDomainNames as leafResolveDomainNames, resolveSecretsAtSynth as leafResolveSecretsAtSynth, wireByo as leafWireByo, wireManagedValue as leafWireManagedValue, } from '@aws-blocks/hosting/constructs';
+import { blocksStoreConfig } from './secret-naming.js';
+/**
+ * Layer a caller's per-kind store config over the pinned Blocks defaults. Shallow
+ * and per-kind: the Blocks `/blocks/*` prefix stays the default, but any field the
+ * app sets (`prefix`, `stage`, `cacheTtlSeconds`) wins.
+ */
+function mergeBlocksStoreConfig(override) {
+    const base = blocksStoreConfig();
+    if (!override)
+        return base;
+    return {
+        secretStore: { ...base.secretStore, ...override.secretStore },
+        configStore: { ...base.configStore, ...override.configStore },
+    };
+}
+/** Split an environment map into plain literals, managed markers, and BYO handles. */
+export function partitionEnvironment(environment) {
+    return leafPartitionEnvironment(environment);
+}
+/** Every managed marker requiring a synth-time fetch (domain markers only). */
+export function collectSynthMarkers(domainName) {
+    return leafCollectSynthMarkers(domainName);
+}
+/**
+ * Resolve managed markers to plaintext at synth time under the Blocks namespaces.
+ * Throws a clear, actionable error if a referenced value was never set. An optional
+ * `storeConfig` overrides the pinned Blocks prefix/stage per kind.
+ */
+export async function resolveSecretsAtSynth(markers, fetcher, storeConfig) {
+    return leafResolveSecretsAtSynth(markers, { ...mergeBlocksStoreConfig(storeConfig), fetcher });
+}
+/** Resolve domain markers to literals using the synth-resolved value map. */
+export function resolveDomainNames(domainName, resolved) {
+    return leafResolveDomainNames(domainName, resolved);
+}
+/**
+ * Fail synth (deploy) when a referenced `environment` marker has no value set —
+ * existence only, never fetching the value. Uses the Blocks namespaces (with an
+ * optional per-kind `storeConfig` override), matching how the values are wired.
+ */
+export async function assertMarkersExistAtSynth(markers, storeConfig) {
+    return leafAssertMarkersExistAtSynth(markers, mergeBlocksStoreConfig(storeConfig));
+}
+/**
+ * Wire a runtime managed marker under the Blocks namespace (store from kind). An
+ * optional `storeConfig` overrides the pinned prefix/stage/cacheTtlSeconds per kind.
+ */
+export function wireManagedValue(fn, marker, storeConfig) {
+    leafWireManagedValue(fn, marker, mergeBlocksStoreConfig(storeConfig));
+}
+/** Wire a runtime BYO handle (grant + inject locator). Honors an optional `storeConfig`. */
+export function wireByo(fn, binding, storeConfig) {
+    leafWireByo(fn, binding, mergeBlocksStoreConfig(storeConfig));
+}

package/dist/hosting-secrets.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=hosting-secrets.test.d.ts.map

package/dist/hosting-secrets.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosting-secrets.test.d.ts","sourceRoot":"","sources":["../src/hosting-secrets.test.ts"],"names":[],"mappings":""}

package/dist/hosting-secrets.test.js

@@ -0,0 +1,81 @@
+// 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 { config, secret } from '@aws-blocks/hosting';
+import { collectSynthMarkers, partitionEnvironment, resolveDomainNames, resolveSecretsAtSynth, } from './hosting-secrets.js';
+void describe('partitionEnvironment()', () => {
+    void it('splits plain / managed (secret+config)', () => {
+        const { plain, managed } = partitionEnvironment({
+            FLAG: 'on',
+            STRIPE_KEY: secret('STRIPE_KEY'),
+            FEATURE_FLAGS: config('FEATURE_FLAGS'),
+        });
+        assert.deepStrictEqual(plain, { FLAG: 'on' });
+        assert.deepStrictEqual(managed.map((m) => `${m.key}:${m.kind}`).sort(), [
+            'FEATURE_FLAGS:config',
+            'STRIPE_KEY:secret',
+        ]);
+    });
+    void it('rejects env key / marker key mismatch', () => {
+        assert.throws(() => partitionEnvironment({ STRIPE_KEY: secret('OTHER') }), /must match the environment variable name/);
+    });
+    void it('handles undefined', () => {
+        const { plain, managed, byo } = partitionEnvironment(undefined);
+        assert.deepStrictEqual(plain, {});
+        assert.strictEqual(managed.length, 0);
+        assert.strictEqual(byo.length, 0);
+    });
+});
+void describe('collectSynthMarkers()', () => {
+    void it('gathers domain markers, deduped by key', () => {
+        const markers = collectSynthMarkers(['example.com', config('DOMAIN_PROD'), config('DOMAIN_PROD')]);
+        assert.deepStrictEqual(markers.map((m) => m.key), ['DOMAIN_PROD']);
+    });
+    void it('returns nothing when no markers', () => {
+        assert.deepStrictEqual(collectSynthMarkers('example.com'), []);
+        assert.deepStrictEqual(collectSynthMarkers(undefined), []);
+    });
+});
+void describe('resolveSecretsAtSynth() — Blocks namespaces', () => {
+    void it('config marker resolves under /blocks/config (SSM leading-slash)', async () => {
+        const seen = [];
+        const resolved = await resolveSecretsAtSynth([config('DOMAIN_PROD')], async (name) => {
+            seen.push(name);
+            return 'prod.example.com';
+        });
+        assert.deepStrictEqual(seen, ['/blocks/config/DOMAIN_PROD']);
+        assert.strictEqual(resolved.get('DOMAIN_PROD'), 'prod.example.com');
+    });
+    void it('secret marker resolves under /blocks/secrets (Secrets Manager slash-free)', async () => {
+        const seen = [];
+        await resolveSecretsAtSynth([secret('API_KEY')], async (name) => {
+            seen.push(name);
+            return 'k';
+        });
+        assert.deepStrictEqual(seen, ['blocks/secrets/API_KEY']);
+    });
+    void it('throws an actionable error when a value is not set', async () => {
+        await assert.rejects(resolveSecretsAtSynth([config('DOMAIN_PROD')], async () => {
+            const e = new Error('not found');
+            e.name = 'ParameterNotFound';
+            throw e;
+        }), /config 'DOMAIN_PROD' is referenced/);
+    });
+});
+void describe('resolveDomainNames()', () => {
+    void it('replaces markers with resolved literals, preserving shape', () => {
+        const resolved = new Map([['DOMAIN_PROD', 'prod.example.com']]);
+        assert.strictEqual(resolveDomainNames(config('DOMAIN_PROD'), resolved), 'prod.example.com');
+        assert.deepStrictEqual(resolveDomainNames(['www.example.com', config('DOMAIN_PROD')], resolved), [
+            'www.example.com',
+            'prod.example.com',
+        ]);
+    });
+    void it('throws if a marker reached the sync path unresolved', () => {
+        assert.throws(() => resolveDomainNames(config('DOMAIN_PROD'), new Map()), /requires async resolution/);
+    });
+    void it('passes literal domains through untouched', () => {
+        assert.strictEqual(resolveDomainNames('example.com', new Map()), 'example.com');
+    });
+});

package/dist/hosting.d.ts

@@ -1,8 +1,9 @@
+import type { FrameworkType, KindStoreOptions } from '@aws-blocks/hosting/constructs';
+import { type FrameworkAdapterFn } from '@aws-blocks/hosting/adapters';
+import { type HostingDomainConfig, type HostingWafConfig, type SkewProtectionConfig } from '@aws-blocks/hosting/constructs';
 import * as cdk from 'aws-cdk-lib';
 import { Construct } from 'constructs';
-import { type HostingDomainConfig, type HostingWafConfig, type SkewProtectionConfig } from '@aws-blocks/hosting/constructs';
-import { type FrameworkAdapterFn } from '@aws-blocks/hosting/adapters';
-import type { FrameworkType } from '@aws-blocks/hosting';
+import { type DomainNameInput, type EnvValue } from './hosting-secrets.js';
 /**
  * Lambda compute configuration for SSR frameworks.
  *
@@ -62,6 +63,18 @@ export type ComputeConfig = {
     logRetention?: cdk.aws_logs.RetentionDays;
 };
 export type { FrameworkType, HostingDomainConfig, HostingWafConfig, SkewProtectionConfig };
+/**
+ * Custom-domain config for the Blocks {@link Hosting} block — the leaf
+ * {@link HostingDomainConfig} with `domainName` widened to also accept a
+ * `config()` marker (resolved to a literal at synth). Only `config()` or a plain
+ * string is accepted here, never `secret()` (a synth-inlined value would leak into
+ * the template). All other fields (`hostedZone`, `certificate`, `wwwRedirect`, …)
+ * are inherited unchanged from {@link HostingDomainConfig}.
+ */
+export interface HostingDomain extends Omit<HostingDomainConfig, 'domainName'> {
+    /** Domain name(s): a plain string / string[] and/or a `config()` marker resolved at synth. */
+    domainName: DomainNameInput;
+}
 /**
  * Structural interface for the Blocks backend stack.
  *
@@ -146,12 +159,65 @@ export interface HostingProps {
     backendConfig?: Record<string, unknown>;
     /** Lambda compute configuration for SSR frameworks. */
     compute?: ComputeConfig;
-    /** Custom domain configuration. */
-    domain?: HostingDomainConfig;
+    /**
+     * Custom environment variables injected into all compute Lambda functions.
+     *
+     * Values are either plain strings or {@link secret} references:
+     *
+     * ```ts
+     * environment: {
+     *   FEATURE_FLAG: 'on',                 // plaintext (in CFN template + Lambda config)
+     *   STRIPE_KEY: secret('STRIPE_KEY'),   // encrypted; read at runtime via getSecret()
+     * }
+     * ```
+     *
+     * A plain string is injected verbatim (visible in the CloudFormation
+     * template — safe for non-sensitive literals). A `secret('K')` value (AWS
+     * Secrets Manager) or `config('K')` value (SSM Parameter Store) injects only
+     * the store LOCATOR — never the value — and grants the compute role scoped
+     * read + decrypt; fetch it at runtime with `await getSecret('K')` /
+     * `await getConfig('K')`. A bring-your-own CDK `ISecret` / `IParameter` handle
+     * is accepted too and resolves identically.
+     *
+     * The env-var name must equal the key: `STRIPE_KEY: secret('STRIPE_KEY')`.
+     */
+    environment?: Record<string, EnvValue>;
+    /**
+     * Custom domain configuration. `domainName` accepts plain strings and/or
+     * {@link config} references (e.g. `domain: { domainName: config('DOMAIN_PROD') }`).
+     * A domain is resolved at synth time and inlined as a literal into the template,
+     * so only `config()` (non-sensitive → SSM) is allowed here, never `secret()`
+     * (which would leak into the template). Any domain marker requires constructing
+     * via the async {@link Hosting.create}.
+     */
+    domain?: HostingDomain;
+    /**
+     * Namespace/cache config for `secret()` values (AWS Secrets Manager). Defaults
+     * to the Blocks `/blocks/secrets` prefix; set `prefix` to namespace per app,
+     * `stage` for per-stage values with a shared fallback, or `cacheTtlSeconds` to
+     * refresh a rotated value on a warm compute without a cold start. Any field the
+     * app sets overrides the Blocks default.
+     */
+    secretStore?: KindStoreOptions;
+    /**
+     * Namespace/cache config for `config()` values (SSM Parameter Store). Defaults
+     * to the Blocks `/blocks/config` prefix; same override semantics as
+     * {@link HostingProps.secretStore}.
+     */
+    configStore?: KindStoreOptions;
     /** WAF protection configuration. */
     waf?: HostingWafConfig;
     /** Retain the S3 bucket when the stack is deleted. Default: false. */
     retainOnDelete?: boolean;
+    /**
+     * Days to retain SUPERSEDED build artifacts in S3 before they are expired.
+     * Default: 30. The build currently referenced by CloudFront KVS (`meta.b`)
+     * is NEVER expired regardless of this value — only builds that have been
+     * replaced by a newer deploy are cleaned up (issue #480). Raise this to keep
+     * a longer rollback window. Must be at least `skewProtection.maxAge`
+     * (converted to days), or synth throws `InvalidSkewProtectionMaxAgeError`.
+     */
+    buildRetentionDays?: number;
     /** Custom Content-Security-Policy header value. */
     contentSecurityPolicy?: string;
     /** CloudFront price class. Default: PRICE_CLASS_100. */
@@ -322,7 +388,32 @@ export declare class Hosting extends Construct {
     readonly buildCacheBucket?: cdk.aws_s3.Bucket;
     /** SNS topic for hosting CloudWatch alarms (present when `monitoring.enabled` is true). */
     readonly monitoringTopic?: cdk.aws_sns.ITopic;
-    constructor(scope: Construct, id: string, props: HostingProps);
+    /**
+     * Async constructor. Required when a `secret()` / `config()` value resolves at
+     * **synth time** — i.e. a `domain.domainName` marker — because that value is
+     * fetched from its store (Secrets Manager / SSM) during synthesis. Returns a
+     * fully-constructed {@link Hosting}.
+     *
+     * For runtime `environment` markers (read via `getSecret`/`getConfig`) and
+     * plain literals, `new Hosting(...)` works directly; `create()` is also safe
+     * to use uniformly.
+     *
+     * @example
+     * ```ts
+     * await Hosting.create(stack, 'Web', {
+     *   root: '.', framework: 'nextjs', api: blocksStack,
+     *   domain: { domainName: config('DOMAIN_PROD') },
+     * });
+     * ```
+     */
+    static create(scope: Construct, id: string, props: HostingProps): Promise<Hosting>;
+    /**
+     * @param resolvedSecrets - Synth-time-resolved secret values, keyed by secret
+     *   key. Populated by {@link Hosting.create}; empty for the direct
+     *   `new Hosting()` path (which then rejects any synth-time secret with a
+     *   clear "use Hosting.create()" error).
+     */
+    constructor(scope: Construct, id: string, props: HostingProps, resolvedSecrets?: Map<string, string>);
     /**
      * Build the config.json payload from props.
      *

package/dist/hosting.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hosting.d.ts","sourceRoot":"","sources":["../src/hosting.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hosting.d.ts","sourceRoot":"","sources":["../src/hosting.ts"],"names":[],"mappings":"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"}

package/dist/hosting.js

@@ -1,18 +1,19 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
+import { execSync } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { detectFramework, getAdapter, normalizeBasePath } from '@aws-blocks/hosting/adapters';
+import { generateBuildId, HostingConstruct, } from '@aws-blocks/hosting/constructs';
 import * as cdk from 'aws-cdk-lib';
-import { AllowedMethods, CachePolicy, OriginRequestPolicy, ViewerProtocolPolicy, } from 'aws-cdk-lib/aws-cloudfront';
+import { AllowedMethods, CachePolicy, OriginRequestPolicy, ViewerProtocolPolicy } from 'aws-cdk-lib/aws-cloudfront';
 import { HttpOrigin } from 'aws-cdk-lib/aws-cloudfront-origins';
 import * as s3deploy from 'aws-cdk-lib/aws-s3-deployment';
 import { Construct } from 'constructs';
-import { execSync } from 'node:child_process';
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-import { HostingConstruct, generateBuildId, } from '@aws-blocks/hosting/constructs';
-import { detectFramework, getAdapter, normalizeBasePath, } from '@aws-blocks/hosting/adapters';
-import { BLOCKS_RPC_PREFIX, BLOCKS_AUTH_PREFIX } from './constants.js';
-import { BLOCKS_SANDBOX_DIR } from './common/constants.js';
 import { registerConfig } from './cdk/config-registry.js';
+import { BLOCKS_SANDBOX_DIR } from './common/constants.js';
+import { BLOCKS_AUTH_PREFIX, BLOCKS_RPC_PREFIX } from './constants.js';
+import { assertMarkersExistAtSynth, collectSynthMarkers, partitionEnvironment, resolveDomainNames, resolveSecretsAtSynth, wireByo, wireManagedValue, } from './hosting-secrets.js';
 import { getRegisteredRoutes } from './raw-route.js';
 // ─── Default build output directories per framework ──────────────
 const DEFAULT_BUILD_DIRS = {
@@ -71,7 +72,43 @@ export class Hosting extends Construct {
     buildCacheBucket;
     /** SNS topic for hosting CloudWatch alarms (present when `monitoring.enabled` is true). */
     monitoringTopic;
-    constructor(scope, id, props) {
+    /**
+     * Async constructor. Required when a `secret()` / `config()` value resolves at
+     * **synth time** — i.e. a `domain.domainName` marker — because that value is
+     * fetched from its store (Secrets Manager / SSM) during synthesis. Returns a
+     * fully-constructed {@link Hosting}.
+     *
+     * For runtime `environment` markers (read via `getSecret`/`getConfig`) and
+     * plain literals, `new Hosting(...)` works directly; `create()` is also safe
+     * to use uniformly.
+     *
+     * @example
+     * ```ts
+     * await Hosting.create(stack, 'Web', {
+     *   root: '.', framework: 'nextjs', api: blocksStack,
+     *   domain: { domainName: config('DOMAIN_PROD') },
+     * });
+     * ```
+     */
+    static async create(scope, id, props) {
+        const storeConfig = { secretStore: props.secretStore, configStore: props.configStore };
+        const synthMarkers = collectSynthMarkers(props.domain?.domainName);
+        const resolved = synthMarkers.length
+            ? await resolveSecretsAtSynth(synthMarkers, undefined, storeConfig)
+            : new Map();
+        // Fail the deploy early if a declared `environment` secret/config has no value
+        // set — existence only, never fetching the value. (Domain markers above already
+        // fail this way; this extends it to runtime markers.)
+        await assertMarkersExistAtSynth(partitionEnvironment(props.environment).managed, storeConfig);
+        return new Hosting(scope, id, props, resolved);
+    }
+    /**
+     * @param resolvedSecrets - Synth-time-resolved secret values, keyed by secret
+     *   key. Populated by {@link Hosting.create}; empty for the direct
+     *   `new Hosting()` path (which then rejects any synth-time secret with a
+     *   clear "use Hosting.create()" error).
+     */
+    constructor(scope, id, props, resolvedSecrets = new Map()) {
         super(scope, id);
         const root = resolve(props.root);
         // ── 1. Detect framework ──────────────────────────────────────
@@ -84,7 +121,7 @@ export class Hosting extends Construct {
             // from breaking frontend builds (e.g., Next.js webpack module resolution).
             const nodeOptions = (process.env.NODE_OPTIONS || '')
                 .split(/\s+/)
-                .filter(opt => opt !== '--conditions=cdk')
+                .filter((opt) => opt !== '--conditions=cdk')
                 .join(' ');
             const buildEnv = { ...process.env, NODE_OPTIONS: nodeOptions };
             try {
@@ -154,8 +191,7 @@ export class Hosting extends Construct {
         //    errorPages will drive the CloudFront configuration correctly,
         //    and the HTML files are already in the static assets directory
         //    (copied by the adapter).
-        const manifestHasErrorPages = manifest.errorPages !== undefined &&
-            Object.keys(manifest.errorPages).length > 0;
+        const manifestHasErrorPages = manifest.errorPages !== undefined && Object.keys(manifest.errorPages).length > 0;
         const skipPropsErrorPages = !!(props.errorPages && manifestHasErrorPages);
         // ── 5. Write placeholder config.json into static assets ─────────
         //    A placeholder is needed so the L3 construct sees
@@ -208,15 +244,40 @@ export class Hosting extends Construct {
                     : props.compute.timeout,
             }
             : undefined;
+        // ── 6b. Resolve secret() markers ─────────────────────────────
+        //    Env values split into plain / runtime-secret / deploy-time buckets;
+        //    domain names may contain markers resolved at synth time. See
+        //    ./hosting-secrets.ts for the two-strategy rationale.
+        const { plain: plainEnv, managed, byo } = partitionEnvironment(props.environment);
+        // Resolved domain (markers → literals); falls back to the raw config when
+        // no domain is set. resolveDomainNames throws a "use Hosting.create()"
+        // error if a domain marker reached the sync path unresolved.
+        const resolvedDomain = props.domain
+            ? {
+                ...props.domain,
+                domainName: resolveDomainNames(props.domain.domainName, resolvedSecrets),
+            }
+            : undefined;
         const hostingProps = {
             manifest,
             compute: normalizedCompute,
-            domain: props.domain,
+            // Plain env + deploy-time literals go straight to the L3 (which stays
+            // secret-agnostic: it only ever sees plain strings). Runtime secrets are
+            // wired separately below so we can attach IAM grants per function.
+            environment: Object.keys(plainEnv).length ? plainEnv : undefined,
+            domain: resolvedDomain,
             waf: props.waf,
-            storage: props.retainOnDelete != null
-                ? { retainOnDelete: props.retainOnDelete }
+            storage: props.retainOnDelete != null || props.buildRetentionDays != null
+                ? {
+                    ...(props.retainOnDelete != null
+                        ? { retainOnDelete: props.retainOnDelete }
+                        : {}),
+                    ...(props.buildRetentionDays != null
+                        ? { buildRetentionDays: props.buildRetentionDays }
+                        : {}),
+                }
                 : undefined,
-            cdn: (props.contentSecurityPolicy || props.priceClass || props.geoRestriction || props.quotas)
+            cdn: props.contentSecurityPolicy || props.priceClass || props.geoRestriction || props.quotas
                 ? {
                     contentSecurityPolicy: props.contentSecurityPolicy,
                     priceClass: props.priceClass,
@@ -251,14 +312,24 @@ export class Hosting extends Construct {
             if (props.backendConfig) {
                 fn.addEnvironment('BLOCKS_CONFIG', JSON.stringify(props.backendConfig));
             }
+            // Runtime managed markers (secret|config): inject the store locator
+            // (never the value) + grant read/decrypt; read via getSecret()/getConfig().
+            // The app's secretStore/configStore (prefix, stage, cacheTtlSeconds) layer
+            // over the Blocks defaults.
+            const storeConfig = { secretStore: props.secretStore, configStore: props.configStore };
+            for (const marker of managed) {
+                wireManagedValue(fn, marker, storeConfig);
+            }
+            // BYO handles (ISecret|IParameter): grant via the handle + inject its locator.
+            for (const binding of byo) {
+                wireByo(fn, binding, storeConfig);
+            }
         }
         // ── 8. Deploy config.json with resolved CDK tokens ───────────
         const buildId = manifest.buildId;
         if (buildId) {
             const configDeployment = new s3deploy.BucketDeployment(this, 'BlocksConfigDeployment', {
-                sources: [
-                    s3deploy.Source.jsonData('config.json', this.buildConfigJson(props)),
-                ],
+                sources: [s3deploy.Source.jsonData('config.json', this.buildConfigJson(props))],
                 destinationBucket: hosting.bucket,
                 destinationKeyPrefix: `builds/${buildId}/.blocks-sandbox`,
                 prune: false,
@@ -271,10 +342,7 @@ export class Hosting extends Construct {
                 // primary guard against staleness is step 5a's no-cache placeholder;
                 // this is defense-in-depth so a post-deploy invalidation actually
                 // clears any edge entry at its real key.)
-                distributionPaths: [
-                    `/builds/${buildId}/.blocks-sandbox/*`,
-                    '/.blocks-sandbox/*',
-                ],
+                distributionPaths: [`/builds/${buildId}/.blocks-sandbox/*`, '/.blocks-sandbox/*'],
                 cacheControl: [s3deploy.CacheControl.fromString('public, max-age=60, must-revalidate')],
             });
             // Ensure the config deployment runs AFTER the hosting construct's