@aws-blocks/bb-distributed-table 0.1.5 → 0.1.6

package/src/index.cdk.test.ts

@@ -14,7 +14,7 @@ import { test } from 'node:test';
 import assert from 'node:assert';
 import * as cdk from 'aws-cdk-lib';
 import type { Construct } from 'constructs';
-import { Template } from 'aws-cdk-lib/assertions';
+import { Template, Match, Annotations } from 'aws-cdk-lib/assertions';
 import { Scope, DEFAULT_NODE_RUNTIME, BlocksPresets, type BlocksDefaults } from '@aws-blocks/core/cdk';
 import { z } from 'zod';
 import { DistributedTable } from './index.cdk.js';
@@ -27,16 +27,21 @@ const userSchema = z.object({
 
 class StubBlocksStack extends cdk.Stack {
 	public readonly handler: cdk.aws_lambda.Function;
+	public readonly executionRole: cdk.aws_iam.IRole;
 	public readonly id: string;
 	public defaults: BlocksDefaults = BlocksPresets.production;
 	constructor(scope: Construct, id: string) {
 		super(scope, id);
 		this.id = id;
 		(globalThis as any).CURRENT_BLOCKS_STACK = this;
+		this.executionRole = new cdk.aws_iam.Role(this, 'BlocksRole', {
+			assumedBy: new cdk.aws_iam.ServicePrincipal('lambda.amazonaws.com'),
+		});
 		this.handler = new cdk.aws_lambda.Function(this, 'StubHandler', {
 			runtime: DEFAULT_NODE_RUNTIME,
 			handler: 'index.handler',
 			code: cdk.aws_lambda.Code.fromInline('exports.handler = async () => {};'),
+			role: this.executionRole,
 		});
 	}
 }
@@ -59,6 +64,244 @@ test('CDK: default DistributedTable provisions a DynamoDB table', () => {
 	template.resourceCountIs('AWS::DynamoDB::Table', 1);
 });
 
+// ── Secure-by-default durability & encryption (prod) ────────────────────────
+// Regression for the bug bash finding: prod DDB tables shipped with
+// DeletionProtection off, PITR disabled, and SSE (KMS) unset.
+
+test('CDK: prod DistributedTable enables PITR by default', () => {
+	const { stack, parent } = setup();
+	new DistributedTable(parent, 'users', {
+		schema: userSchema,
+		key: { partitionKey: 'userId', sortKey: 'createdAt' },
+	});
+	const template = Template.fromStack(stack);
+	template.hasResourceProperties('AWS::DynamoDB::Table', {
+		PointInTimeRecoverySpecification: { PointInTimeRecoveryEnabled: true },
+	});
+});
+
+test('CDK: default PITR does not pin a recovery window (DynamoDB 35-day default)', () => {
+	const { stack, parent } = setup();
+	new DistributedTable(parent, 'users', {
+		schema: userSchema,
+		key: { partitionKey: 'userId', sortKey: 'createdAt' },
+	});
+	const template = Template.fromStack(stack);
+	template.hasResourceProperties('AWS::DynamoDB::Table', {
+		PointInTimeRecoverySpecification: {
+			PointInTimeRecoveryEnabled: true,
+			RecoveryPeriodInDays: Match.absent(),
+		},
+	});
+});
+
+test('CDK: pointInTimeRecovery { retentionDays } enables PITR and pins the window', () => {
+	const { stack, parent } = setup();
+	new DistributedTable(parent, 'users', {
+		schema: userSchema,
+		key: { partitionKey: 'userId', sortKey: 'createdAt' },
+		pointInTimeRecovery: { retentionDays: 7 },
+	});
+	const template = Template.fromStack(stack);
+	template.hasResourceProperties('AWS::DynamoDB::Table', {
+		PointInTimeRecoverySpecification: {
+			PointInTimeRecoveryEnabled: true,
+			RecoveryPeriodInDays: 7,
+		},
+	});
+});
+
+test('CDK: an out-of-range retentionDays falls back to the default window (still enabled)', () => {
+	const { stack, parent } = setup();
+	new DistributedTable(parent, 'users', {
+		schema: userSchema,
+		key: { partitionKey: 'userId', sortKey: 'createdAt' },
+		pointInTimeRecovery: { retentionDays: 60 },
+	});
+	const template = Template.fromStack(stack);
+	template.hasResourceProperties('AWS::DynamoDB::Table', {
+		PointInTimeRecoverySpecification: {
+			PointInTimeRecoveryEnabled: true,
+			RecoveryPeriodInDays: Match.absent(),
+		},
+	});
+});
+
+test('CDK: pointInTimeRecovery: false disables PITR', () => {
+	const { stack, parent } = setup();
+	new DistributedTable(parent, 'users', {
+		schema: userSchema,
+		key: { partitionKey: 'userId', sortKey: 'createdAt' },
+		pointInTimeRecovery: false,
+	});
+	const template = Template.fromStack(stack);
+	template.hasResourceProperties('AWS::DynamoDB::Table', {
+		PointInTimeRecoverySpecification: Match.absent(),
+	});
+});
+
+test('CDK: prod DistributedTable enables DeletionProtection by default', () => {
+	const { stack, parent } = setup();
+	new DistributedTable(parent, 'users', {
+		schema: userSchema,
+		key: { partitionKey: 'userId', sortKey: 'createdAt' },
+	});
+	const template = Template.fromStack(stack);
+	template.hasResourceProperties('AWS::DynamoDB::Table', {
+		DeletionProtectionEnabled: true,
+	});
+});
+
+test('CDK: prod DistributedTable enables SSE (KMS-managed) by default', () => {
+	const { stack, parent } = setup();
+	new DistributedTable(parent, 'users', {
+		schema: userSchema,
+		key: { partitionKey: 'userId', sortKey: 'createdAt' },
+	});
+	const template = Template.fromStack(stack);
+	// AWS_MANAGED emits SSEEnabled:true with no SSEType (the aws/dynamodb key).
+	// Contrast with the AWS-owned default, which emits no SSESpecification at all,
+	// and customer-managed, which adds SSEType:'KMS' + a KMSMasterKeyId.
+	template.hasResourceProperties('AWS::DynamoDB::Table', {
+		SSESpecification: { SSEEnabled: true, SSEType: Match.absent() },
+	});
+});
+
+test('CDK: prod DistributedTable table is RETAINed on stack delete by default', () => {
+	const { stack, parent } = setup();
+	new DistributedTable(parent, 'users', {
+		schema: userSchema,
+		key: { partitionKey: 'userId', sortKey: 'createdAt' },
+	});
+	const template = Template.fromStack(stack);
+	template.hasResource('AWS::DynamoDB::Table', {
+		DeletionPolicy: 'Retain',
+	});
+});
+
+// (Sandbox-default behavior — DESTROY, deletion protection off, PITR off — is
+// covered by the "adopts sandbox defaults" / "PITR follows the stack defaults"
+// tests above, which drive it through the stack `defaults` rather than the
+// `sandboxMode` context.)
+
+// ── Customer overrides win over the secure defaults ─────────────────────────
+
+test('CDK: customer can opt OUT of PITR + protection in prod', () => {
+	const { stack, parent } = setup();
+	new DistributedTable(parent, 'users', {
+		schema: userSchema,
+		key: { partitionKey: 'userId', sortKey: 'createdAt' },
+		pointInTimeRecovery: false,
+		protection: 'disposable',
+	});
+	const template = Template.fromStack(stack);
+	template.hasResourceProperties('AWS::DynamoDB::Table', {
+		PointInTimeRecoverySpecification: Match.absent(),
+		DeletionProtectionEnabled: false,
+	});
+	template.hasResource('AWS::DynamoDB::Table', { DeletionPolicy: 'Delete' });
+});
+
+test('CDK: customer can opt INTO durable/protected tables even under the sandbox preset', () => {
+	const { stack, parent } = setup(BlocksPresets.sandbox);
+	new DistributedTable(parent, 'users', {
+		schema: userSchema,
+		key: { partitionKey: 'userId', sortKey: 'createdAt' },
+		pointInTimeRecovery: true,
+		protection: 'locked',
+	});
+	const template = Template.fromStack(stack);
+	template.hasResourceProperties('AWS::DynamoDB::Table', {
+		PointInTimeRecoverySpecification: { PointInTimeRecoveryEnabled: true },
+		DeletionProtectionEnabled: true,
+	});
+	template.hasResource('AWS::DynamoDB::Table', { DeletionPolicy: 'Retain' });
+});
+
+test("CDK: protection 'retained' orphans the table without locking deletes", () => {
+	const { stack, parent } = setup();
+	new DistributedTable(parent, 'users', {
+		schema: userSchema,
+		key: { partitionKey: 'userId', sortKey: 'createdAt' },
+		protection: 'retained',
+	});
+	const template = Template.fromStack(stack);
+	// RETAIN on stack delete, but deletion protection OFF (a direct delete works).
+	template.hasResource('AWS::DynamoDB::Table', { DeletionPolicy: 'Retain' });
+	template.hasResourceProperties('AWS::DynamoDB::Table', {
+		DeletionProtectionEnabled: false,
+	});
+});
+
+test('CDK: customer-managed encryption provisions a KMS key', () => {
+	const { stack, parent } = setup();
+	new DistributedTable(parent, 'users', {
+		schema: userSchema,
+		key: { partitionKey: 'userId', sortKey: 'createdAt' },
+		encryption: 'customer-managed',
+	});
+	const template = Template.fromStack(stack);
+	template.resourceCountIs('AWS::KMS::Key', 1);
+	template.hasResourceProperties('AWS::DynamoDB::Table', {
+		SSESpecification: { SSEEnabled: true, SSEType: 'KMS' },
+	});
+});
+
+test('CDK: fromKmsKey encrypts with an existing key and provisions no new KMS key', () => {
+	const { stack, parent } = setup();
+	const keyArn = 'arn:aws:kms:us-east-1:111122223333:key/abcd-1234-ef56';
+	new DistributedTable(parent, 'orders', {
+		schema: userSchema,
+		key: { partitionKey: 'userId', sortKey: 'createdAt' },
+		encryption: DistributedTable.fromKmsKey(keyArn),
+	});
+	const template = Template.fromStack(stack);
+	// Bringing an existing key must NOT mint a new one (the whole point — a
+	// shared key across tables instead of one dedicated key each).
+	template.resourceCountIs('AWS::KMS::Key', 0);
+	template.hasResourceProperties('AWS::DynamoDB::Table', {
+		SSESpecification: { SSEEnabled: true, SSEType: 'KMS', KMSMasterKeyId: keyArn },
+	});
+});
+
+test('CDK: two tables sharing one fromKmsKey ref provision zero KMS keys', () => {
+	const { stack, parent } = setup();
+	const sharedKey = DistributedTable.fromKmsKey('arn:aws:kms:us-east-1:111122223333:key/shared-1');
+	new DistributedTable(parent, 'orders', {
+		schema: userSchema,
+		key: { partitionKey: 'userId', sortKey: 'createdAt' },
+		encryption: sharedKey,
+	});
+	new DistributedTable(parent, 'events', {
+		schema: userSchema,
+		key: { partitionKey: 'userId', sortKey: 'createdAt' },
+		encryption: sharedKey,
+	});
+	const template = Template.fromStack(stack);
+	template.resourceCountIs('AWS::KMS::Key', 0);
+	template.resourceCountIs('AWS::DynamoDB::Table', 2);
+});
+
+test('CDK: fromExisting ignores durability props (customer owns the table)', () => {
+	const { stack, parent } = setup();
+	new DistributedTable(parent, 'users', {
+		schema: userSchema,
+		key: { partitionKey: 'userId', sortKey: 'createdAt' },
+		table: DistributedTable.fromExisting('preexisting-users-table'),
+		// These must be inert when wrapping an existing table.
+		pointInTimeRecovery: true,
+		protection: 'locked',
+		encryption: 'customer-managed',
+	});
+	const template = Template.fromStack(stack);
+	// No table is provisioned, and customer-managed encryption does NOT
+	// provision a CMK — proving the durability options are ignored.
+	template.resourceCountIs('AWS::DynamoDB::Table', 0);
+	template.resourceCountIs('AWS::KMS::Key', 0);
+});
+
+// ── Durability follows the stack `defaults` when no per-block override (#302) ──
+
 test('CDK: table adopts sandbox defaults (DESTROY, deletion protection off)', () => {
 	const { stack, parent } = setup(BlocksPresets.sandbox);
 	new DistributedTable(parent, 'users', {
@@ -81,6 +324,45 @@ test('CDK: table adopts production defaults (RETAIN, deletion protection on)', (
 	template.hasResourceProperties('AWS::DynamoDB::Table', { DeletionProtectionEnabled: true });
 });
 
+test('CDK: PITR follows the stack defaults — off under the sandbox preset', () => {
+	const { stack, parent } = setup(BlocksPresets.sandbox);
+	new DistributedTable(parent, 'users', {
+		schema: userSchema,
+		key: { partitionKey: 'userId', sortKey: 'createdAt' },
+	});
+	const template = Template.fromStack(stack);
+	template.hasResourceProperties('AWS::DynamoDB::Table', {
+		PointInTimeRecoverySpecification: Match.absent(),
+	});
+});
+
+test('CDK: options.pointInTimeRecovery overrides the stack defaults (on under sandbox)', () => {
+	const { stack, parent } = setup(BlocksPresets.sandbox);
+	new DistributedTable(parent, 'users', {
+		schema: userSchema,
+		key: { partitionKey: 'userId', sortKey: 'createdAt' },
+		pointInTimeRecovery: true,
+	});
+	const template = Template.fromStack(stack);
+	template.hasResourceProperties('AWS::DynamoDB::Table', {
+		PointInTimeRecoverySpecification: { PointInTimeRecoveryEnabled: true },
+	});
+});
+
+test('CDK: a per-block protection option overrides the stack defaults', () => {
+	// Sandbox preset would give DESTROY + no protection; `protection: 'locked'`
+	// must win, proving the per-block override sits on top of the #302 defaults.
+	const { stack, parent } = setup(BlocksPresets.sandbox);
+	new DistributedTable(parent, 'users', {
+		schema: userSchema,
+		key: { partitionKey: 'userId', sortKey: 'createdAt' },
+		protection: 'locked',
+	});
+	const template = Template.fromStack(stack);
+	template.hasResource('AWS::DynamoDB::Table', { DeletionPolicy: 'Retain' });
+	template.hasResourceProperties('AWS::DynamoDB::Table', { DeletionProtectionEnabled: true });
+});
+
 test('CDK: DistributedTable.fromExisting does NOT provision a table (regression)', () => {
 	const { stack, parent } = setup();
 	new DistributedTable(parent, 'users', {
@@ -129,3 +411,47 @@ test('CDK: calling a runtime data method throws an actionable error (not a crypt
 		);
 	}
 });
+
+// ── Synth-time warnings actually fire (not just the fallback values) ─────────
+
+test('CDK: an unrecognized protection value warns at synth', () => {
+	const { stack, parent } = setup();
+	new DistributedTable(parent, 'users', {
+		schema: userSchema,
+		key: { partitionKey: 'userId', sortKey: 'createdAt' },
+		protection: 'retian', // intentional typo — exercise the synth guard
+	});
+	Annotations.fromStack(stack).hasWarning('*', Match.stringLikeRegexp('Unrecognized protection'));
+});
+
+test('CDK: an unrecognized encryption value warns at synth', () => {
+	const { stack, parent } = setup();
+	new DistributedTable(parent, 'users', {
+		schema: userSchema,
+		key: { partitionKey: 'userId', sortKey: 'createdAt' },
+		encryption: 'kms', // intentional typo — exercise the synth guard
+	});
+	Annotations.fromStack(stack).hasWarning('*', Match.stringLikeRegexp('Unrecognized encryption'));
+});
+
+test('CDK: an out-of-range retentionDays warns at synth', () => {
+	const { stack, parent } = setup();
+	new DistributedTable(parent, 'users', {
+		schema: userSchema,
+		key: { partitionKey: 'userId', sortKey: 'createdAt' },
+		pointInTimeRecovery: { retentionDays: 60 },
+	});
+	Annotations.fromStack(stack).hasWarning('*', Match.stringLikeRegexp('retentionDays must be an integer'));
+});
+
+test('CDK: durability options passed alongside fromExisting warn at synth', () => {
+	const { stack, parent } = setup();
+	new DistributedTable(parent, 'users', {
+		schema: userSchema,
+		key: { partitionKey: 'userId', sortKey: 'createdAt' },
+		table: DistributedTable.fromExisting('preexisting-users-table'),
+		protection: 'locked',
+		pointInTimeRecovery: { retentionDays: 14 },
+	});
+	Annotations.fromStack(stack).hasWarning('*', Match.stringLikeRegexp('wrapped via fromExisting'));
+});

package/src/index.cdk.ts

@@ -2,20 +2,21 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { Construct } from 'constructs';
-import { Table, type ITable, AttributeType, BillingMode } from 'aws-cdk-lib/aws-dynamodb';
+import { Table, type ITable, AttributeType, BillingMode, TableEncryption } from 'aws-cdk-lib/aws-dynamodb';
 import * as cdk from 'aws-cdk-lib';
-import { CustomResource, Duration } from 'aws-cdk-lib';
+import { Annotations, CustomResource, Duration, RemovalPolicy } from 'aws-cdk-lib';
 import { Code, Function as LambdaFunction } from 'aws-cdk-lib/aws-lambda';
 import { Provider } from 'aws-cdk-lib/custom-resources';
 import { PolicyStatement } from 'aws-cdk-lib/aws-iam';
+import { Key, type IKey } from 'aws-cdk-lib/aws-kms';
 import { Scope, synthGuard, DEFAULT_NODE_RUNTIME } from '@aws-blocks/core/cdk';
 import type { ScopeParent } from '@aws-blocks/core';
-import type { ExternalTableRef } from './types.js';
+import type { ExternalTableRef, ExternalKmsKeyRef } from './types.js';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 
 export { DistributedTableErrors } from './errors.js';
-export type { DistributedTableOptions, ReadValidationMode, TableKeyConfig, TableKey, PutOptions, DeleteOptions, QueryOptions, ScanOptions, ExternalTableRef } from './types.js';
+export type { DistributedTableOptions, ReadValidationMode, TableKeyConfig, TableKey, PutOptions, DeleteOptions, QueryOptions, ScanOptions, ExternalTableRef, ExternalKmsKeyRef } from './types.js';
 
 export class DistributedTable<T = any> extends Scope {
 	private table: ITable;
@@ -31,6 +32,19 @@ export class DistributedTable<T = any> extends Scope {
 		return { __brand: 'ExternalTableRef' as const, tableName };
 	}
 
+	/**
+	 * Reference an existing customer-managed KMS key to encrypt the table,
+	 * instead of letting `encryption: 'customer-managed'` provision a dedicated
+	 * key per table. Pass the result as the `encryption` option so several
+	 * tables can share one key (and one monthly charge).
+	 *
+	 * @param keyArn - ARN of a KMS key you already own. The deploying principal
+	 *   and the DynamoDB service must have the usual grants on it.
+	 */
+	static fromKmsKey(keyArn: string): ExternalKmsKeyRef {
+		return { __brand: 'ExternalKmsKeyRef' as const, keyArn };
+	}
+
 	constructor(scope: ScopeParent, id: string, public options: any) {
 		super(id, { parent: scope });
 
@@ -41,9 +55,23 @@ export class DistributedTable<T = any> extends Scope {
 			// and grant the runtime Lambda read/write + index query access.
 			// We deliberately skip the GSI custom resource — the customer owns the
 			// table's index lifecycle when they bring their own.
+			//
+			// Durability/encryption options don't apply to an existing table (we
+			// never emit a `Table` resource to attach them to). Surface that at
+			// synth so a `protection: 'locked'` on what looks like a fresh
+			// table isn't a silent no-op.
+			const ignoredForExisting = (['pointInTimeRecovery', 'protection', 'encryption'] as const)
+				.filter((key) => config[key] !== undefined);
+			if (ignoredForExisting.length > 0) {
+				Annotations.of(this).addWarningV2(
+					'@aws-blocks/bb-distributed-table:IgnoredOptionsForExistingTable',
+					`Ignoring ${ignoredForExisting.join(', ')} because this table is wrapped via fromExisting() — ` +
+						`the existing table owns its own durability/encryption configuration.`,
+				);
+			}
 			this.table = Table.fromTableName(this, 'table', config.table.tableName);
-			this.table.grantReadWriteData(this.handler);
-			this.handler.addToRolePolicy(new PolicyStatement({
+			this.table.grantReadWriteData(this.executionRole);
+			this.executionRole.addToPrincipalPolicy(new PolicyStatement({
 				actions: ['dynamodb:Query'],
 				resources: [`${this.table.tableArn}/index/*`],
 			}));
@@ -71,6 +99,103 @@ export class DistributedTable<T = any> extends Scope {
 		const getDdbType = (fieldName: string): AttributeType =>
 			isNumericField(fieldName) ? AttributeType.NUMBER : AttributeType.STRING;
 
+		// Secure-by-default durability & encryption.
+		// The posture — removal policy, deletion protection, PITR — comes from the
+		// stack-wide `defaults` (BlocksPresets, #302): production retains + protects
+		// + backs up; sandbox is disposable so `sandbox:destroy` stays a one-command
+		// teardown and throwaway stacks don't accrue backup cost. Blocks read
+		// `this.defaults` rather than the `sandboxMode` context (and rather than the
+		// stack-level SandboxDisableDeletionProtection mixin, which can't reach the
+		// DynamoDB L2 `deletionProtection` prop — the reason that construct-level
+		// mechanism exists). A per-block `protection`/`pointInTimeRecovery`/
+		// `encryption` option always wins.
+		//
+		// `protection` is a single knob (disposable | retained | locked) spanning
+		// removal policy + deletion protection, so the contradictory
+		// "protect + destroy" state can't be expressed. `options` is typed `any`
+		// here, so guard against an unrecognized string (typo) rather than
+		// silently falling through to the stack default.
+		const PROTECTION_VALUES = ['disposable', 'retained', 'locked'] as const;
+		if (config.protection !== undefined && !PROTECTION_VALUES.includes(config.protection)) {
+			Annotations.of(this).addWarningV2(
+				'@aws-blocks/bb-distributed-table:UnknownProtection',
+				`Unrecognized protection '${String(config.protection)}' (expected 'disposable', 'retained', ` +
+					`or 'locked') — falling back to the stack defaults.`,
+			);
+		}
+		// `encryption` accepts two string literals or an ExternalKmsKeyRef
+		// (a `{ __brand: 'ExternalKmsKeyRef', keyArn }` from `fromKmsKey`).
+		// Anything else is a typo — warn rather than silently using the default.
+		const isKmsKeyRef = typeof config.encryption === 'object'
+			&& config.encryption !== null
+			&& config.encryption.__brand === 'ExternalKmsKeyRef';
+		if (
+			config.encryption !== undefined
+			&& config.encryption !== 'aws-managed'
+			&& config.encryption !== 'customer-managed'
+			&& !isKmsKeyRef
+		) {
+			Annotations.of(this).addWarningV2(
+				'@aws-blocks/bb-distributed-table:UnknownEncryption',
+				`Unrecognized encryption '${String(config.encryption)}' (expected 'aws-managed', ` +
+					`'customer-managed', or DistributedTable.fromKmsKey(arn)) — falling back to 'aws-managed'.`,
+			);
+		}
+
+		// PITR is one knob (`boolean | { retentionDays }`) resolved from the
+		// per-block option, else the stack-wide `defaults.pointInTimeRecovery`
+		// (#302 follow-up) — production on, sandbox off. The object form both
+		// enables PITR and pins the window, so "days set but PITR off" can't be
+		// expressed. `retentionDays` must be 1–35; warn and drop back to the
+		// 35-day default on an out-of-range value rather than failing the deploy.
+		const pitrSetting = config.pointInTimeRecovery ?? this.defaults.pointInTimeRecovery;
+		let pitrEnabled: boolean;
+		let pitrDays: number | undefined;
+		if (typeof pitrSetting === 'object' && pitrSetting !== null) {
+			pitrEnabled = true;
+			pitrDays = pitrSetting.retentionDays;
+			if (!Number.isInteger(pitrDays) || (pitrDays as number) < 1 || (pitrDays as number) > 35) {
+				Annotations.of(this).addWarningV2(
+					'@aws-blocks/bb-distributed-table:InvalidPitrDays',
+					`pointInTimeRecovery.retentionDays must be an integer between 1 and 35 (got ${String(pitrDays)}) — ` +
+						`falling back to the 35-day default.`,
+				);
+				pitrDays = undefined;
+			}
+		} else {
+			pitrEnabled = pitrSetting === true;
+			pitrDays = undefined;
+		}
+		// Resolve durability into the two CDK properties. The `protection` option
+		// is the richer per-block override (#282): when set it fully determines
+		// removal policy + deletion protection, and — being one knob — the
+		// contradictory "protect + destroy" state can't be expressed. When
+		// omitted, fall back to the stack-wide `defaults` (BlocksPresets, #302):
+		// production → RETAIN + protected, sandbox → DESTROY + unprotected. Read
+		// `deletionProtection` independently from `defaults`, never derived.
+		let removalPolicy: RemovalPolicy;
+		let deletionProtection: boolean;
+		if (PROTECTION_VALUES.includes(config.protection)) {
+			deletionProtection = config.protection === 'locked';
+			removalPolicy = config.protection === 'disposable' ? RemovalPolicy.DESTROY : RemovalPolicy.RETAIN;
+		} else {
+			removalPolicy = this.defaults.removalPolicy;
+			deletionProtection = this.defaults.deletionProtection;
+		}
+		// `fromKmsKey(arn)` → encrypt with an existing CMK (shareable across
+		// tables). `'customer-managed'` → CDK provisions a fresh dedicated CMK.
+		// Otherwise the AWS-managed `aws/dynamodb` key.
+		let encryptionKey: IKey | undefined;
+		let encryption: TableEncryption;
+		if (isKmsKeyRef) {
+			encryption = TableEncryption.CUSTOMER_MANAGED;
+			encryptionKey = Key.fromKeyArn(this, 'encryption-key', config.encryption.keyArn);
+		} else if (config.encryption === 'customer-managed') {
+			encryption = TableEncryption.CUSTOMER_MANAGED;
+		} else {
+			encryption = TableEncryption.AWS_MANAGED;
+		}
+
 		this.table = new Table(this, 'table', {
 			tableName,
 			partitionKey: {
@@ -83,17 +208,31 @@ export class DistributedTable<T = any> extends Scope {
 			} : undefined,
 			billingMode: BillingMode.PAY_PER_REQUEST,
 			timeToLiveAttribute: config.ttl || undefined,
-			// Durability follows the stack-wide `defaults` (sandbox → DESTROY +
-			// no protection so a teardown is clean; production → RETAIN + protected).
-			// A richer per-block override lands with the `protection` option in #282.
-			removalPolicy: this.defaults.removalPolicy,
-			deletionProtection: this.defaults.deletionProtection,
+			// PITR spec is only emitted when enabled — leaving it undefined keeps
+			// the CloudFormation template clean for sandboxes / opt-outs.
+			// recoveryPeriodInDays is only set when the caller narrows it (an
+			// omitted value keeps DynamoDB's 35-day default without emitting it).
+			pointInTimeRecoverySpecification: pitrEnabled
+				? {
+					pointInTimeRecoveryEnabled: true,
+					...(pitrDays !== undefined ? { recoveryPeriodInDays: pitrDays } : {}),
+				}
+				: undefined,
+			// Resolved above from `protection` (per-block override) or the
+			// stack-wide `defaults` (#302) — supersedes main's placeholder that
+			// read `this.defaults` directly.
+			deletionProtection,
+			removalPolicy,
+			encryption,
+			// Only set when bringing an existing CMK; `CUSTOMER_MANAGED` without a
+			// key lets CDK provision a dedicated one.
+			encryptionKey,
 		});
 
-		this.table.grantReadWriteData(this.handler);
+		this.table.grantReadWriteData(this.executionRole);
 
 		// Explicit index query permissions
-		this.handler.addToRolePolicy(new PolicyStatement({
+		this.executionRole.addToPrincipalPolicy(new PolicyStatement({
 			actions: ['dynamodb:Query'],
 			resources: [`${this.table.tableArn}/index/*`],
 		}));

package/src/index.mock.ts

@@ -15,6 +15,7 @@ export type {
 	DistributedTableOptions,
 	ReadValidationMode,
 	ExternalTableRef,
+	ExternalKmsKeyRef,
 	TableKey,
 	PartitionKeyCondition,
 	SortKeyCondition,
@@ -29,6 +30,7 @@ import type {
 	TableKeyConfig,
 	DistributedTableOptions,
 	ExternalTableRef,
+	ExternalKmsKeyRef,
 	SortKeyCondition,
 	ScanOptions,
 	PutOptions,
@@ -334,6 +336,10 @@ export class DistributedTable<
 		return { __brand: 'ExternalTableRef' as const, tableName };
 	}
 
+	static fromKmsKey(keyArn: string): ExternalKmsKeyRef {
+		return { __brand: 'ExternalKmsKeyRef' as const, keyArn };
+	}
+
 	// ── Internal ────────────────────────────────────────────────────────────
 
 	private checkFieldEquals(keyStr: string, fields: Partial<T>): void {