@aws-blocks/core 0.1.18 → 0.3.0

package/src/cdk/mixins.ts

@@ -6,13 +6,36 @@ import type { IConstruct } from 'constructs';
 import type { IMixin } from 'constructs';
 
 /**
- * Disables deletion protection on any construct that has a `deletionProtection`
- * property (e.g. RDS clusters, RDS instances). Uses duck-typing so it
- * automatically covers current and future resource types.
+ * Property names used across CloudFormation resources to express deletion
+ * protection. L2 constructs and most L1s use `deletionProtection` (e.g. RDS
+ * clusters and instances, ELBv2 load balancers), while others spell it
+ * `deletionProtectionEnabled` (e.g. the DynamoDB `CfnTable` behind an L2
+ * `Table`, Aurora DSQL clusters).
+ */
+const DELETION_PROTECTION_PROPERTIES = ['deletionProtection', 'deletionProtectionEnabled'] as const;
+
+/**
+ * Disables deletion protection on any construct that exposes a deletion
+ * protection property (e.g. RDS clusters, RDS instances, DynamoDB tables).
+ * Uses duck-typing so it automatically covers current and future resource
+ * types, matching both the `deletionProtection` and
+ * `deletionProtectionEnabled` spellings.
+ *
+ * Note that a DynamoDB L2 `Table` only accepts `deletionProtection` as a prop
+ * and does not re-expose it, so tables are matched through their underlying
+ * L1 `CfnTable.deletionProtectionEnabled`.
  *
  * Intended for sandbox teardown — use in the CDK layer alongside
  * `RemovalPolicies.of(stack).destroy()` to ensure `sandbox:destroy` can
- * delete the entire stack without manual cleanup.
+ * delete the entire stack without manual cleanup. DynamoDB refuses
+ * `DeleteTable` while deletion protection is enabled, regardless of the
+ * CloudFormation `DeletionPolicy`.
+ *
+ * @deprecated Prefer the stack-wide `defaults` prop on `BlocksStack`/`BlocksBackend`
+ * (`defaults: BlocksPresets.sandbox` / `.production`, or `sandboxMode ? … : …`).
+ * Amazon-authored Building Blocks now read removal policy + deletion protection
+ * from `defaults`, so this mixin is no longer needed; it is retained only for
+ * backward compatibility.
  *
  * @example
  * ```ts
@@ -27,15 +50,17 @@ import type { IMixin } from 'constructs';
  */
 export class SandboxDisableDeletionProtection extends Mixin implements IMixin {
   supports(construct: any): boolean {
-    return 'deletionProtection' in construct;
+    return DELETION_PROTECTION_PROPERTIES.some((property) => property in construct);
   }
   applyTo(node: IConstruct): void {
     // Only flip explicitly-enabled protection. When undefined (the default),
     // deletion protection is already off — setting it to false would emit the
     // property in the CloudFormation template, which breaks Aurora DB instances
     // (RDS rejects DeletionProtection on cluster members).
-    if ((node as any).deletionProtection === true) {
-      (node as any).deletionProtection = false;
+    for (const property of DELETION_PROTECTION_PROPERTIES) {
+      if ((node as any)[property] === true) {
+        (node as any)[property] = false;
+      }
     }
   }
 }

package/src/common/index.ts

@@ -3,6 +3,7 @@
 
 import type { StackProps } from 'aws-cdk-lib';
 import type { Construct } from 'constructs';
+import type { BlocksDefaults } from '../cdk/blocks-defaults.js';
 import { CORE_VERSION } from '../version.js';
 import { OFFICIAL_BB_NAMES } from './official-bb-names.generated.js';
 export { OFFICIAL_BB_NAMES } from './official-bb-names.generated.js';
@@ -325,6 +326,14 @@ export function computeScopeFullId(scope: { id: string; parent?: any }) {
 export interface BlocksStackProps extends StackProps {
   backendHandlerPath: string;
   backendCDKPath: string;
+  /**
+   * Stack-wide infrastructure defaults applied to every Building Block (removal
+   * policy, deletion protection, …). Start from `BlocksPresets.sandbox` or
+   * `BlocksPresets.production` and override individual fields as needed. Any
+   * field a block also exposes as a per-block option is overridden by that
+   * option. See `BlocksDefaults` in `@aws-blocks/core/cdk`.
+   */
+  defaults: BlocksDefaults;
 }
 
 export class BlocksStack {

package/src/hosting-secrets.test.ts

@@ -0,0 +1,106 @@
+// 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: string[] = [];
+		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: string[] = [];
+		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/src/hosting-secrets.ts

@@ -0,0 +1,106 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * 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,
+	assertMarkersExistAtSynth as leafAssertMarkersExistAtSynth,
+	collectSynthMarkers as leafCollectSynthMarkers,
+	partitionEnvironment as leafPartitionEnvironment,
+	resolveDomainNames as leafResolveDomainNames,
+	resolveSecretsAtSynth as leafResolveSecretsAtSynth,
+	type SecretFetcher,
+	type StoreConfig,
+	wireByo as leafWireByo,
+	wireManagedValue as leafWireManagedValue,
+} from '@aws-blocks/hosting/constructs';
+import type * as cdk from 'aws-cdk-lib';
+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?: StoreConfig): StoreConfig {
+	const base = blocksStoreConfig();
+	if (!override) return base;
+	return {
+		secretStore: { ...base.secretStore, ...override.secretStore },
+		configStore: { ...base.configStore, ...override.configStore },
+	};
+}
+
+/** 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 function partitionEnvironment(environment: Record<string, EnvValue> | undefined): {
+	plain: Record<string, string>;
+	managed: ManagedValue[];
+	byo: ByoBinding[];
+} {
+	return leafPartitionEnvironment(environment);
+}
+
+/** Every managed marker requiring a synth-time fetch (domain markers only). */
+export function collectSynthMarkers(domainName: DomainNameInput | undefined): ManagedValue[] {
+	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: ManagedValue[],
+	fetcher?: SecretFetcher,
+	storeConfig?: StoreConfig,
+): Promise<Map<string, string>> {
+	return leafResolveSecretsAtSynth(markers, { ...mergeBlocksStoreConfig(storeConfig), fetcher });
+}
+
+/** Resolve domain markers to literals using the synth-resolved value map. */
+export function resolveDomainNames(domainName: DomainNameInput, resolved: Map<string, string>): string | string[] {
+	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: ManagedValue[], storeConfig?: StoreConfig): Promise<void> {
+	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: cdk.aws_lambda.Function, marker: ManagedValue, storeConfig?: StoreConfig): void {
+	leafWireManagedValue(fn, marker, mergeBlocksStoreConfig(storeConfig));
+}
+
+/** Wire a runtime BYO handle (grant + inject locator). Honors an optional `storeConfig`. */
+export function wireByo(fn: cdk.aws_lambda.Function, binding: ByoBinding, storeConfig?: StoreConfig): void {
+	leafWireByo(fn, binding, mergeBlocksStoreConfig(storeConfig));
+}