@aws-blocks/core 0.1.0

package/src/common/config.ts

@@ -0,0 +1,169 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Runtime config loader for Building Blocks.
+ *
+ * At deploy time, BB resource mappings (ARNs, URLs, paths) are stored in an
+ * S3 JSON file instead of Lambda environment variables (which have a 4KB limit).
+ * This module loads that config file once at cold start and caches it.
+ *
+ * Lookup order for each key:
+ * 1. `process.env[key]` — local dev where env vars are set directly
+ * 2. Cached S3 config — loaded once per cold start
+ *
+ * @module
+ */
+
+let configCache: Record<string, string> | null = null;
+let configLoadPromise: Promise<Record<string, string>> | null = null;
+
+type S3Fetcher = (bucket: string, key: string) => Promise<string>;
+let s3FetcherOverride: S3Fetcher | null = null;
+
+async function defaultS3Fetcher(bucket: string, key: string): Promise<string> {
+	const { S3Client, GetObjectCommand } = await import('@aws-sdk/client-s3');
+	const client = new S3Client({
+		region: process.env.AWS_REGION,
+		requestHandler: { requestTimeout: 5000 },
+		maxAttempts: 3,
+	});
+	const response = await client.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
+	const body = await response.Body?.transformToString('utf-8');
+	if (!body) throw new Error('Empty config file');
+	return body;
+}
+
+/**
+ * Load the config JSON from S3. Fetches once and caches forever (Lambda lifetime).
+ * Skips S3 entirely if BLOCKS_CONFIG_BUCKET/BLOCKS_CONFIG_KEY are not set (local dev).
+ * Throws if the env vars ARE set but the S3 fetch fails.
+ */
+async function loadConfigFromS3(): Promise<Record<string, string>> {
+	if (configCache) return configCache;
+
+	const bucket = process.env.BLOCKS_CONFIG_BUCKET;
+	const key = process.env.BLOCKS_CONFIG_KEY;
+
+	if (!bucket || !key) {
+		configCache = {};
+		return configCache;
+	}
+
+	const fetcher = s3FetcherOverride ?? defaultS3Fetcher;
+
+	try {
+		const body = await fetcher(bucket, key);
+		configCache = JSON.parse(body);
+	} catch (error: any) {
+		const isNotFound = error?.name === 'NoSuchKey'
+			|| error?.Code === 'NoSuchKey'
+			|| error?.$metadata?.httpStatusCode === 404;
+		if (isNotFound) {
+			console.warn(`[Blocks] Config file not found in S3 (${bucket}/${key}), proceeding with empty config`);
+			configCache = {};
+			return configCache;
+		}
+		const msg = error instanceof Error ? error.message : String(error);
+		throw new Error(`[Blocks] Failed to load config from S3 (${bucket}/${key}): ${msg}`);
+	}
+
+	if (typeof configCache !== 'object' || configCache === null || Array.isArray(configCache)) {
+		throw new Error('[Blocks] Config file must be a JSON object');
+	}
+
+	console.log(`[Blocks] Config loaded: ${Object.keys(configCache).length} keys`);
+	return configCache!;
+}
+
+/**
+ * Ensure only one S3 fetch is in flight at a time.
+ * Multiple BB constructors calling getConfig() concurrently will share the same promise.
+ */
+function ensureConfigLoaded(): Promise<Record<string, string>> {
+	if (configCache) return Promise.resolve(configCache);
+	if (!configLoadPromise) {
+		configLoadPromise = loadConfigFromS3().finally(() => {
+			configLoadPromise = null;
+		});
+	}
+	return configLoadPromise;
+}
+
+/**
+ * Get a config value by key.
+ *
+ * Checks `process.env[key]` first (local dev where env vars are set directly).
+ * If not found, reads from the cached S3 config file.
+ *
+ * @param key - The config key (e.g., `BLOCKS_AUTH_COGNITO_MYAPP_AUTHC_USER_POOL_ID`)
+ * @returns The config value, or empty string if not found anywhere
+ */
+export async function getConfig(key: string): Promise<string> {
+	const envValue = process.env[key];
+	if (envValue !== undefined) return envValue;
+
+	const config = await ensureConfigLoaded();
+	return config[key] ?? '';
+}
+
+/**
+ * Synchronous config access — returns the value if already cached, otherwise
+ * returns the process.env fallback. Use this only when you're certain the
+ * config has already been loaded (e.g., after an initial await getConfig() call).
+ *
+ * @param key - The config key
+ * @returns The config value, or empty string if not found
+ */
+export function getConfigSync(key: string): string {
+	const envValue = process.env[key];
+	if (envValue !== undefined) return envValue;
+
+	if (configCache) return configCache[key] ?? '';
+
+	return '';
+}
+
+/**
+ * Preload the S3 config. Call this early in Lambda cold start to ensure
+ * the config is cached before any BB constructors need it.
+ *
+ * This is a no-op if the config is already loaded or if S3 env vars aren't set.
+ */
+export async function preloadConfig(): Promise<void> {
+	await ensureConfigLoaded();
+}
+
+/**
+ * Load S3 config and inject all values into `process.env`.
+ *
+ * This enables the lazy-init handler pattern: the handler loads config into
+ * process.env BEFORE importing the backend module, so BB constructors can
+ * read their config via `process.env[key]` as before — no BB code changes needed.
+ *
+ * Only sets env vars that aren't already set (won't override explicit env vars).
+ */
+export async function loadConfigToProcessEnv(): Promise<void> {
+	const config = await ensureConfigLoaded();
+	for (const [key, value] of Object.entries(config)) {
+		if (process.env[key] === undefined) {
+			process.env[key] = value;
+		}
+	}
+}
+
+/**
+ * Reset the config cache. **For testing only.**
+ */
+export function _resetConfigCache(): void {
+	configCache = null;
+	configLoadPromise = null;
+	s3FetcherOverride = null;
+}
+
+/**
+ * Override the S3 fetcher function. **For testing only.**
+ */
+export function _setS3Fetcher(fetcher: ((bucket: string, key: string) => Promise<string>) | null): void {
+	s3FetcherOverride = fetcher;
+}

package/src/common/constants.ts

@@ -0,0 +1,15 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Shared constants used across the Blocks framework.
+ *
+ * Centralizes magic strings so directory names and conventions
+ * can be updated in one place.
+ */
+
+/** Directory where sandbox/deploy config is written (relative to project root). */
+export const BLOCKS_SANDBOX_DIR = '.blocks-sandbox';
+
+/** Default backend entry point directory name. */
+export const BLOCKS_BACKEND_DIR = 'aws-blocks';

package/src/common/crypto.ts

@@ -0,0 +1,15 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { timingSafeEqual } from 'node:crypto';
+
+/**
+ * Compares two strings in constant time to prevent timing side-channel attacks.
+ * Use this for HMAC signature validation — never use === or !== for crypto comparisons.
+ */
+export function constantTimeEquals(a: string, b: string): boolean {
+	const ab = Buffer.from(a, 'utf8');
+	const bb = Buffer.from(b, 'utf8');
+	if (ab.length !== bb.length) return false;
+	return timingSafeEqual(ab, bb);
+}

package/src/common/index.test.ts

@@ -0,0 +1,242 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { test, describe } from 'node:test';
+import assert from 'node:assert';
+import { Scope } from './index.js';
+import type { ScopeParent } from './index.js';
+import { CORE_VERSION } from '../version.js';
+
+/**
+ * Test subclass that exposes the protected buildUserAgentChain method.
+ */
+class TestBB extends Scope {
+	override readonly bbName?: string;
+	override readonly bbVersion?: string;
+
+	constructor(
+		id: string,
+		opts?: { parent?: ScopeParent; bbName?: string; bbVersion?: string },
+	) {
+		super(id, { parent: opts?.parent });
+		this.bbName = opts?.bbName;
+		this.bbVersion = opts?.bbVersion;
+	}
+
+	/** Expose protected method for testing */
+	public testBuildUserAgentChain(): [string, string][] {
+		return this.buildUserAgentChain();
+	}
+}
+
+// ── buildUserAgentChain: standalone BB (no BB parent) ───────────────────────
+
+describe('buildUserAgentChain', () => {
+	test('standalone BB returns [aws-blocks, bb] pair', () => {
+		const root = { id: 'my-app' };
+		const bb = new TestBB('store', {
+			parent: root,
+			bbName: 'KVStore',
+			bbVersion: '0.4.0',
+		});
+
+		const chain = bb.testBuildUserAgentChain();
+
+		assert.deepStrictEqual(chain, [
+			['aws-blocks', CORE_VERSION],
+			['bb', 'KVStore/0.4.0'],
+		]);
+	});
+
+	// ── Nested BB (one level) ─────────────────────────────────────────────
+
+	test('BB nested inside another BB includes parent BB in chain', () => {
+		const root = { id: 'my-app' };
+		const parentBB = new TestBB('auth', {
+			parent: root,
+			bbName: 'AuthBasic',
+			bbVersion: '1.0.1',
+		});
+		const childBB = new TestBB('store', {
+			parent: parentBB,
+			bbName: 'KVStore',
+			bbVersion: '0.4.0',
+		});
+
+		const chain = childBB.testBuildUserAgentChain();
+
+		assert.deepStrictEqual(chain, [
+			['aws-blocks', CORE_VERSION],
+			['bb', 'AuthBasic/1.0.1'],
+			['bb', 'KVStore/0.4.0'],
+		]);
+	});
+
+	// ── Deeply nested BB (2+ levels) ──────────────────────────────────────
+
+	test('BB nested 2+ levels deep builds the full chain in root-to-leaf order', () => {
+		const root = { id: 'my-app' };
+		const grandparentBB = new TestBB('dashboard', {
+			parent: root,
+			bbName: 'Dashboard',
+			bbVersion: '2.0.0',
+		});
+		const parentBB = new TestBB('auth', {
+			parent: grandparentBB,
+			bbName: 'AuthBasic',
+			bbVersion: '1.0.1',
+		});
+		const childBB = new TestBB('store', {
+			parent: parentBB,
+			bbName: 'KVStore',
+			bbVersion: '0.4.0',
+		});
+
+		const chain = childBB.testBuildUserAgentChain();
+
+		assert.deepStrictEqual(chain, [
+			['aws-blocks', CORE_VERSION],
+			['bb', 'Dashboard/2.0.0'],
+			['bb', 'AuthBasic/1.0.1'],
+			['bb', 'KVStore/0.4.0'],
+		]);
+	});
+
+	// ── Parent without BB metadata (non-BB scope in the chain) ────────────
+
+	test('parent scope without bbName/bbVersion is skipped in chain', () => {
+		const root = { id: 'my-app' };
+		// A plain Scope (not a BB) in between
+		const middleScope = new TestBB('middleware', {
+			parent: root,
+			// no bbName/bbVersion
+		});
+		const childBB = new TestBB('store', {
+			parent: middleScope,
+			bbName: 'KVStore',
+			bbVersion: '0.4.0',
+		});
+
+		const chain = childBB.testBuildUserAgentChain();
+
+		assert.deepStrictEqual(chain, [
+			['aws-blocks', CORE_VERSION],
+			['bb', 'KVStore/0.4.0'],
+		]);
+	});
+
+	test('non-BB parent between two BBs is skipped', () => {
+		const root = { id: 'my-app' };
+		const parentBB = new TestBB('auth', {
+			parent: root,
+			bbName: 'AuthBasic',
+			bbVersion: '1.0.1',
+		});
+		// Plain scope between parent BB and child BB
+		const middleScope = new TestBB('internal', {
+			parent: parentBB,
+			// no bbName/bbVersion
+		});
+		const childBB = new TestBB('store', {
+			parent: middleScope,
+			bbName: 'KVStore',
+			bbVersion: '0.4.0',
+		});
+
+		const chain = childBB.testBuildUserAgentChain();
+
+		assert.deepStrictEqual(chain, [
+			['aws-blocks', CORE_VERSION],
+			['bb', 'AuthBasic/1.0.1'],
+			['bb', 'KVStore/0.4.0'],
+		]);
+	});
+
+	// ── Edge case: bbName set but bbVersion missing ───────────────────────
+
+	test('self not added to chain when bbVersion is missing', () => {
+		const root = { id: 'my-app' };
+		const bb = new TestBB('store', {
+			parent: root,
+			bbName: 'KVStore',
+			// bbVersion missing
+		});
+
+		const chain = bb.testBuildUserAgentChain();
+
+		assert.deepStrictEqual(chain, [
+			['aws-blocks', CORE_VERSION],
+		]);
+	});
+
+	// ── Edge case: bbVersion set but bbName missing ───────────────────────
+
+	test('self not added to chain when bbName is missing', () => {
+		const root = { id: 'my-app' };
+		const bb = new TestBB('store', {
+			parent: root,
+			// bbName missing
+			bbVersion: '0.4.0',
+		});
+
+		const chain = bb.testBuildUserAgentChain();
+
+		assert.deepStrictEqual(chain, [
+			['aws-blocks', CORE_VERSION],
+		]);
+	});
+
+	// ── Edge case: neither bbName nor bbVersion set ───────────────────────
+
+	test('self not added to chain when neither bbName nor bbVersion is set', () => {
+		const root = { id: 'my-app' };
+		const bb = new TestBB('store', {
+			parent: root,
+		});
+
+		const chain = bb.testBuildUserAgentChain();
+
+		assert.deepStrictEqual(chain, [
+			['aws-blocks', CORE_VERSION],
+		]);
+	});
+
+	// ── Edge case: parent with only bbName (no bbVersion) is skipped ──────
+
+	test('parent with bbName but no bbVersion is skipped', () => {
+		const root = { id: 'my-app' };
+		const parentPartial = new TestBB('partial', {
+			parent: root,
+			bbName: 'PartialBB',
+			// bbVersion missing
+		});
+		const childBB = new TestBB('store', {
+			parent: parentPartial,
+			bbName: 'KVStore',
+			bbVersion: '0.4.0',
+		});
+
+		const chain = childBB.testBuildUserAgentChain();
+
+		assert.deepStrictEqual(chain, [
+			['aws-blocks', CORE_VERSION],
+			['bb', 'KVStore/0.4.0'],
+		]);
+	});
+
+	// ── Verifies CORE_VERSION is used as the aws-blocks version ───────────
+
+	test('CORE_VERSION is used as the aws-blocks version', () => {
+		const root = { id: 'my-app' };
+		const bb = new TestBB('store', {
+			parent: root,
+			bbName: 'KVStore',
+			bbVersion: '1.0.0',
+		});
+
+		const chain = bb.testBuildUserAgentChain();
+
+		assert.strictEqual(chain[0][0], 'aws-blocks');
+		assert.strictEqual(chain[0][1], CORE_VERSION);
+	});
+});