@aws-blocks/bb-app-setting 0.1.0

package/src/errors.ts

@@ -0,0 +1,27 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Typed error constants for AppSetting. Use with `isBlocksError()` in catch blocks.
+ *
+ * @example
+ * ```typescript
+ * import { isBlocksError } from '@aws-blocks/core';
+ * import { AppSettingErrors } from '@aws-blocks/bb-app-setting';
+ *
+ * try {
+ *   await setting.put(value);
+ * } catch (e: unknown) {
+ *   if (isBlocksError(e, AppSettingErrors.ValidationFailed)) {
+ *     // schema validation failed or value exceeds 4 KB
+ *   }
+ *   throw e;
+ * }
+ * ```
+ */
+export const AppSettingErrors = {
+	/** Thrown when the SSM parameter does not exist. */
+	ParameterNotFound: 'ParameterNotFoundException',
+	/** Thrown when schema validation fails, value exceeds 4 KB, or options are invalid. */
+	ValidationFailed: 'ValidationFailedException',
+} as const;

package/src/index.aws.ts

@@ -0,0 +1,165 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+	SSMClient,
+	GetParameterCommand,
+	PutParameterCommand,
+} from '@aws-sdk/client-ssm';
+import { Scope, registerSdkIdentifiers, getSdkIdentifiers } from '@aws-blocks/core';
+import type { ScopeParent } from '@aws-blocks/core';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { AppSettingErrors } from './errors.js';
+import type { AppSettingOptions, InternalAppSettingOptions } from './types.js';
+import { BB_NAME, BB_VERSION } from './version.js';
+import { Logger } from '@aws-blocks/bb-logger';
+import type { ChildLogger } from '@aws-blocks/bb-logger';
+
+// Re-export public types from types module (canonical source)
+export { AppSettingErrors } from './errors.js';
+export type { AppSettingOptions } from './types.js';
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function blocksError(name: string, message: string): Error {
+	const err = new Error(`${name}: ${message}`);
+	err.name = name;
+	return err;
+}
+
+async function validateSchema<T>(schema: StandardSchemaV1<T> | undefined, value: unknown): Promise<void> {
+	if (!schema) return;
+	const result = schema['~standard'].validate(value);
+	const resolved = result instanceof Promise ? await result : result;
+	if (resolved.issues) {
+		throw blocksError(AppSettingErrors.ValidationFailed, resolved.issues[0].message);
+	}
+}
+
+// ── AppSetting (AWS runtime) ────────────────────────────────────────────────
+
+/**
+ * A single application configuration value backed by SSM Parameter Store.
+ *
+ * **When to use:** You need to store and retrieve a non-secret configuration
+ * value at runtime — a feature flag, API URL, threshold, or structured config
+ * object. For sensitive values, set `secret: true` to use SSM SecureString.
+ *
+ * **When NOT to use:** If you need structured key-value data with conditional
+ * writes and queries, use `KVStore` or `DistributedTable`.
+ *
+ * **Best practices:**
+ * - One AppSetting per logical configuration value
+ * - Use a schema for structured objects to get type safety and runtime validation
+ * - Use `secret: true` for API keys, tokens, and passwords
+ *
+ * **Scaling:** Standard-tier SSM parameters. 40 TPS default for GetParameter
+ * (can be increased). No cost for standard parameters.
+ */
+export class AppSetting<T = string> extends Scope {
+	/**
+	 * Reference an SSM parameter created and owned **outside this stack** (e.g. a
+	 * connection string seeded by `ensureSecrets` before deploy). At runtime this
+	 * reads the value like any other setting; the construct-time behavior (no
+	 * create/seed/tag/delete, read-only grant) is applied by the CDK variant. The
+	 * factory exists on every variant so app code uses one API across dev/deploy.
+	 */
+	static fromExisting<T = string>(
+		scope: ScopeParent,
+		id: string,
+		options: { name: string; secret?: boolean },
+	): AppSetting<T> {
+		const opts: InternalAppSettingOptions<T> = { ...options, external: true };
+		return new AppSetting<T>(scope, id, opts);
+	}
+
+	readonly bbName = BB_NAME;
+	private schema?: StandardSchemaV1<T>;
+	private isSecret: boolean;
+	private client: SSMClient;
+
+	/** @internal Logger for internal operations. Defaults to error-level when not provided. */
+	protected log: ChildLogger;
+
+	constructor(scope: ScopeParent, id: string, options: AppSettingOptions<T>) {
+		super(id, { parent: scope, bbName: BB_NAME, bbVersion: BB_VERSION });
+		this.log = options?.logger ?? new Logger(this, 'logger', { level: 'error' });
+
+		const parameterName = options.name ?? `/${this.fullId}`;
+		this.schema = options.schema;
+		this.isSecret = options.secret ?? false;
+		this.client = new SSMClient({
+			customUserAgent: this.buildUserAgentChain(),
+		});
+		registerSdkIdentifiers(this.fullId, { parameterName });
+	}
+
+	/**
+	 * Retrieve the current value.
+	 *
+	 * Returns the stored SSM parameter value. The parameter is guaranteed
+	 * to exist because the CDK layer creates it with the initial value.
+	 *
+	 * @returns The current value.
+	 * @throws {AppSettingErrors.ParameterNotFound} If the parameter does not exist in SSM (e.g., deleted out-of-band).
+	 *
+	 * @example
+	 * ```typescript
+	 * const retries = await maxRetries.get();
+	 * ```
+	 */
+	async get(): Promise<T> {
+		const result = await this.client.send(new GetParameterCommand({
+			Name: getSdkIdentifiers(this).parameterName,
+			WithDecryption: this.isSecret,
+		}));
+
+		this.client.config.customUserAgent = this.buildUserAgentChain();
+		const raw = result.Parameter?.Value;
+		if (raw === undefined || raw === null) {
+			throw blocksError(AppSettingErrors.ParameterNotFound, `Parameter "${getSdkIdentifiers(this).parameterName}" has no value`);
+		}
+
+		let value: T;
+		try {
+			value = JSON.parse(raw) as T;
+		} catch {
+			// fallback for old-format values
+			value = raw as T;
+		}
+
+		if (this.isSecret && value === ('' as unknown as T)) {
+			throw blocksError(AppSettingErrors.ParameterNotFound, `Secret parameter "${getSdkIdentifiers(this).parameterName}" has an empty value — secrets must not be empty`);
+		}
+
+		return value;
+	}
+
+	/**
+	 * Update the value at runtime.
+	 *
+	 * Overwrites the current SSM parameter value. When a schema is configured,
+	 * the value is validated before writing.
+	 *
+	 * @param value - The new value to store.
+	 * @throws {AppSettingErrors.ValidationFailed} If schema validation fails or value exceeds 4 KB.
+	 *
+	 * @example
+	 * ```typescript
+	 * await maxRetries.put('5');
+	 * await config.put({ maxRetries: 5, timeout: 10000 });
+	 * ```
+	 */
+	async put(value: T): Promise<void> {
+		await validateSchema(this.schema, value);
+
+		const serialized = JSON.stringify(value);
+
+		await this.client.send(new PutParameterCommand({
+			Name: getSdkIdentifiers(this).parameterName,
+			Value: serialized,
+			Type: this.isSecret ? 'SecureString' : 'String',
+			Overwrite: true,
+		}));
+	}
+}

package/src/index.browser.ts

@@ -0,0 +1,10 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+// Browser stub - AppSetting runs server-side only
+export class AppSetting {
+	static fromExisting(...args: any[]): any {
+		return new AppSetting();
+	}
+	constructor(...args: any[]) {}
+}

package/src/index.cdk.test.ts

@@ -0,0 +1,227 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * CDK-side tests for AppSetting.
+ *
+ * Verifies that the Custom Resource Lambda's IAM policy is scoped to specific
+ * parameter ARNs (not a wildcard) — regression test for #598.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert';
+import * as cdk from 'aws-cdk-lib';
+import type { Construct } from 'constructs';
+import { Template, Match } from 'aws-cdk-lib/assertions';
+import { Scope, DEFAULT_NODE_RUNTIME } from '@aws-blocks/core/cdk';
+import { AppSetting } from './index.cdk.js';
+
+class StubBlocksStack extends cdk.Stack {
+	public readonly handler: cdk.aws_lambda.Function;
+	public readonly id: string;
+	constructor(scope: Construct, id: string) {
+		super(scope, id);
+		this.id = id;
+		(globalThis as any).CURRENT_BLOCKS_STACK = this;
+		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 () => {};'),
+		});
+	}
+}
+
+function setup(): { stack: StubBlocksStack; parent: Scope } {
+	const app = new cdk.App();
+	const stack = new StubBlocksStack(app, 'TestStack');
+	const parent = new Scope('app');
+	return { stack, parent };
+}
+
+test('CDK: secret AppSetting SSM policy is scoped to specific parameter ARN (not wildcard)', () => {
+	const { stack, parent } = setup();
+	new AppSetting(parent, 'my-secret', { secret: true, name: '/myapp/secret-key' });
+	const template = Template.fromStack(stack);
+
+	// The KitSecretInitFn should have an IAM policy for ssm:PutParameter/DeleteParameter
+	// scoped to the specific parameter, NOT a wildcard
+	const policies = template.findResources('AWS::IAM::Policy');
+	const policyLogicalIds = Object.keys(policies);
+
+	let foundSsmPolicy = false;
+	for (const logicalId of policyLogicalIds) {
+		const statements = policies[logicalId]?.Properties?.PolicyDocument?.Statement;
+		if (!Array.isArray(statements)) continue;
+
+		for (const stmt of statements) {
+			const actions = stmt.Action;
+			if (!Array.isArray(actions)) continue;
+			if (!actions.includes('ssm:PutParameter') || !actions.includes('ssm:DeleteParameter')) continue;
+
+			foundSsmPolicy = true;
+			// Resource must NOT be a wildcard — it should be a specific ARN
+			const resources = stmt.Resource;
+			if (Array.isArray(resources)) {
+				for (const res of resources) {
+					const arnStr = typeof res === 'string' ? res : JSON.stringify(res);
+					assert.ok(
+						!arnStr.includes('"*"') && arnStr !== '*',
+						`SSM policy resource must not be a wildcard, got: ${arnStr}`
+					);
+				}
+			} else {
+				const arnStr = typeof resources === 'string' ? resources : JSON.stringify(resources);
+				assert.notStrictEqual(arnStr, '*', 'SSM policy resource must not be a wildcard');
+			}
+		}
+	}
+
+	assert.ok(foundSsmPolicy, 'Expected to find an IAM policy with ssm:PutParameter/DeleteParameter');
+});
+
+test('CDK: secret AppSetting SSM policy contains the correct parameter name', () => {
+	const { stack, parent } = setup();
+	new AppSetting(parent, 'db-password', { secret: true, name: '/myapp/db-password' });
+	const template = Template.fromStack(stack);
+
+	// Verify the policy resource ARN references the parameter name
+	const templateJson = JSON.stringify(template.toJSON());
+	assert.ok(
+		templateJson.includes('myapp/db-password'),
+		'Expected the synthesized template to contain the specific parameter name "myapp/db-password"'
+	);
+});
+
+test('CDK: multiple secret AppSettings produce scoped policy with all parameter ARNs', () => {
+	const { stack, parent } = setup();
+	new AppSetting(parent, 'secret-a', { secret: true, name: '/app/secret-a' });
+	new AppSetting(parent, 'secret-b', { secret: true, name: '/app/secret-b' });
+	const template = Template.fromStack(stack);
+
+	const templateJson = JSON.stringify(template.toJSON());
+	assert.ok(templateJson.includes('app/secret-a'), 'Expected template to reference parameter "app/secret-a"');
+	assert.ok(templateJson.includes('app/secret-b'), 'Expected template to reference parameter "app/secret-b"');
+});
+
+test('CDK: non-secret AppSetting creates SSM StringParameter', () => {
+	const { stack, parent } = setup();
+	new AppSetting(parent, 'config', { value: 'hello', name: '/app/config' });
+	const template = Template.fromStack(stack);
+	template.resourceCountIs('AWS::SSM::Parameter', 1);
+});
+
+test('CDK: non-secret AppSetting grants handler scoped SSM access', () => {
+	const { stack, parent } = setup();
+	new AppSetting(parent, 'config', { value: 'hello', name: '/app/config' });
+	const template = Template.fromStack(stack);
+
+	// Should have a policy statement for ssm:GetParameter, ssm:PutParameter
+	// scoped to the specific parameter ARN
+	template.hasResourceProperties('AWS::IAM::Policy', {
+		PolicyDocument: {
+			Statement: Match.arrayWith([
+				Match.objectLike({
+					Action: ['ssm:GetParameter', 'ssm:PutParameter'],
+					Resource: Match.objectLike({
+						'Fn::Join': Match.anyValue(),
+					}),
+				}),
+			]),
+		},
+	});
+});
+
+test('CDK: external secret is NOT enrolled in bulk-init (no KitSecretsBulk / KitSecretInitFn)', () => {
+	const { stack, parent } = setup();
+	AppSetting.fromExisting(parent, 'db-url', { name: '/blocks/sandbox/db-abc-connection-string', secret: true });
+	const template = Template.fromStack(stack);
+
+	// No secret bulk-init custom resource and no init Lambda should be synthesized:
+	// an externally-owned parameter must not be created, tagged, or deleted by us.
+	template.resourceCountIs('AWS::CloudFormation::CustomResource', 0);
+	const lambdas = template.findResources('AWS::Lambda::Function');
+	for (const id of Object.keys(lambdas)) {
+		const code = JSON.stringify(lambdas[id]?.Properties?.Code ?? {});
+		assert.ok(!code.includes('AddTagsToResourceCommand'), `Lambda ${id} should not be the secret-init function`);
+	}
+});
+
+test('CDK: external secret grants READ-ONLY runtime access (GetParameter + Decrypt, scoped, no write)', () => {
+	const { stack, parent } = setup();
+	AppSetting.fromExisting(parent, 'db-url', { name: '/blocks/sandbox/db-abc-connection-string', secret: true });
+	const template = Template.fromStack(stack);
+
+	// ssm:GetParameter, scoped to the specific parameter ARN (not a wildcard).
+	template.hasResourceProperties('AWS::IAM::Policy', {
+		PolicyDocument: {
+			Statement: Match.arrayWith([
+				Match.objectLike({
+					Action: 'ssm:GetParameter',
+					Resource: Match.objectLike({ 'Fn::Join': Match.anyValue() }),
+				}),
+			]),
+		},
+	});
+	// kms:Decrypt for reading the SecureString.
+	template.hasResourceProperties('AWS::IAM::Policy', {
+		PolicyDocument: { Statement: Match.arrayWith([Match.objectLike({ Action: 'kms:Decrypt' })]) },
+	});
+	// Must NOT grant write to an externally-owned secret.
+	const policiesJson = JSON.stringify(template.findResources('AWS::IAM::Policy'));
+	assert.ok(!policiesJson.includes('ssm:PutParameter'), 'external secret must not grant ssm:PutParameter');
+	assert.ok(!policiesJson.includes('kms:Encrypt'), 'external secret must not grant kms:Encrypt');
+});
+
+test('CDK: external non-secret creates no SSM parameter and grants read-only access', () => {
+	const { stack, parent } = setup();
+	AppSetting.fromExisting(parent, 'shared-config', { name: '/some/external/config' });
+	const template = Template.fromStack(stack);
+
+	// The construct does not create the parameter — it's owned externally.
+	template.resourceCountIs('AWS::SSM::Parameter', 0);
+	template.hasResourceProperties('AWS::IAM::Policy', {
+		PolicyDocument: {
+			Statement: Match.arrayWith([
+				Match.objectLike({
+					Action: 'ssm:GetParameter',
+					Resource: Match.objectLike({ 'Fn::Join': Match.anyValue() }),
+				}),
+			]),
+		},
+	});
+	assert.ok(
+		!JSON.stringify(template.findResources('AWS::IAM::Policy')).includes('ssm:PutParameter'),
+		'external non-secret must not grant write',
+	);
+});
+
+test('CDK: the internal external guard requires a name and forbids a value', () => {
+	// fromExisting() is the public API and makes `name` required at the type level;
+	// these assertions cover the runtime guard on the underlying `external` option
+	// (defense for JS callers / direct construction).
+	const { parent } = setup();
+	assert.throws(
+		() => new AppSetting(parent, 'ext-no-name', { secret: true, external: true } as any),
+		/requires an explicit 'name'/,
+	);
+	assert.throws(
+		() => new AppSetting(parent, 'ext-with-value', { external: true, name: '/x', value: 'v' } as any),
+		/must not have a value/,
+	);
+});
+
+test('CDK: fromExisting still registers the runtime config key (BLOCKS_SSM_PARAM_*)', () => {
+	// BLOCKS_SSM_PARAM_DB_URL is the ONLY link between db-pull's runtime resolveConnString()
+	// and the deployed parameter name. If config registration ever moved inside the
+	// non-external branch, every external setting would fail at runtime with
+	// ParameterNotFound — and nothing else would catch it. This pins the contract.
+	const { stack, parent } = setup();
+	AppSetting.fromExisting(parent, 'db-url', { name: '/blocks/sandbox/db-abc-connection-string', secret: true });
+
+	const registry = (stack as any)[Symbol.for('BLOCKS_CONFIG_REGISTRY')] as { entries: Map<string, unknown> } | undefined;
+	assert.ok(registry, 'config registry exists on the stack');
+	assert.ok(
+		registry.entries.has('BLOCKS_SSM_PARAM_DB_URL'),
+		'external setting must register BLOCKS_SSM_PARAM_DB_URL so the runtime can resolve the parameter',
+	);
+	assert.equal(registry.entries.get('BLOCKS_SSM_PARAM_DB_URL'), '/blocks/sandbox/db-abc-connection-string');
+});