@lambda-kata/cdk 0.1.0

package/lib/kata-wrapper.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Kata Wrapper for Lambda Kata CDK Integration
+ *
+ * This module provides the main `kata()` function that transforms Node.js Lambda
+ * functions to run via the Lambda Kata runtime. The transformation includes:
+ * - Changing the runtime to Python 3.12
+ * - Setting the handler to the Lambda Kata handler
+ * - Attaching the customer-specific Lambda Layer
+ * - Preserving the original handler path in a config layer
+ *
+ * Licensing is validated at CDK synthesis/deploy time only—no runtime network calls.
+ *
+ * @module kata-wrapper
+ */
+import { Function as LambdaFunction } from 'aws-cdk-lib/aws-lambda';
+import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
+import { KataProps, LicensingResponse, TransformationConfig } from './types';
+import { LicensingService } from './licensing';
+/**
+ * Options for the kata wrapper, extending KataProps with internal options.
+ */
+export interface KataWrapperOptions extends KataProps {
+    /**
+     * Optional: Custom licensing service for testing.
+     * If not provided, the default HTTP licensing service will be used.
+     * @internal
+     */
+    licensingService?: LicensingService;
+    /**
+     * Custom bundle path.
+     * If not specified, uses the default /opt/js_runtime/bundle.js
+     */
+    bundlePath?: string;
+    /**
+     * Path to middleware TypeScript/JavaScript file.
+     * The file will be compiled with esbuild and included in the config layer.
+     * The middleware must export a function: (bundle, context) => handler
+     */
+    middlewarePath?: string;
+    /**
+     * Inline handler resolver function.
+     * This TypeScript function will be serialized, compiled with esbuild,
+     * and included in the config layer as middleware.js
+     *
+     * The function receives the loaded bundle and context with originalHandler,
+     * and must return the handler function.
+     *
+     * Note: The function must be pure (no closures over external variables)
+     * because it will be serialized via .toString()
+     *
+     * @example
+     * ```typescript
+     * kata(myFunction, {
+     *   handlerResolver: (bundle, ctx) => {
+     *     const handlerName = ctx.originalHandler.split('.').pop();
+     *     return bundle[handlerName];
+     *   }
+     * });
+     * ```
+     */
+    handlerResolver?: (bundle: unknown, context: {
+        originalHandler: string;
+    }) => Function;
+}
+/**
+ * Result of the kata transformation.
+ */
+export interface KataResult {
+    /**
+     * Whether the Lambda was transformed.
+     */
+    transformed: boolean;
+    /**
+     * The licensing response from the licensing service.
+     */
+    licensingResponse: LicensingResponse;
+    /**
+     * The resolved AWS account ID.
+     */
+    accountId: string;
+}
+/**
+ * Transforms a Node.js Lambda function to run via the Lambda Kata runtime.
+ *
+ * This function performs the following steps:
+ * 1. Resolves the target AWS account ID
+ * 2. Calls the licensing service to validate entitlement
+ * 3. If entitled, applies transformations (runtime, handler, layer, env vars)
+ * 4. If not entitled, handles according to unlicensedBehavior option
+ *
+ * @param lambda - The Node.js Lambda function to transform (NodejsFunction or Function)
+ * @param props - Optional configuration for the transformation
+ * @returns The same Lambda construct (modified if licensed)
+ *
+ * @example
+ * ```typescript
+ * import { kata } from '@lambda-kata/cdk';
+ * import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
+ *
+ * const myFunction = new NodejsFunction(this, 'MyFunction', {
+ *   entry: 'src/handler.ts',
+ * });
+ *
+ * // Transform to use Lambda Kata runtime
+ * kata(myFunction);
+ *
+ * // With options
+ * kata(myFunction, {
+ *   unlicensedBehavior: 'fail',
+ * });
+ * ```
+ *
+ * @remarks
+ * Validates: Requirements 2.1, 3.2
+ * - 2.1: WHEN a developer wraps a Node.js Lambda with `kata(lambda)`, THE kata_Wrapper SHALL return a modified Lambda construct
+ * - 3.2: THE kata_Wrapper SHALL call the Licensing_Service to validate the account's entitlement
+ */
+export declare function kata<T extends NodejsFunction | LambdaFunction>(lambda: T, props?: KataWrapperOptions): T;
+/**
+ * Synchronous version of kata for use when account ID is already known.
+ *
+ * This is useful for testing or when the account ID can be determined
+ * without async operations.
+ *
+ * @param lambda - The Node.js Lambda function to transform
+ * @param accountId - The AWS account ID to use for licensing check
+ * @param props - Optional configuration for the transformation
+ * @returns Promise resolving to the transformation result
+ *
+ * @internal
+ */
+export declare function kataWithAccountId<T extends NodejsFunction | LambdaFunction>(lambda: T, accountId: string, props?: KataWrapperOptions): Promise<KataResult>;
+/**
+ * Applies the Lambda Kata transformation to a Lambda function.
+ *
+ * This function modifies the Lambda construct in-place to:
+ * 1. Create and attach a config layer with the original handler path
+ * 2. Change the runtime to Python 3.12
+ * 3. Set the handler to the Lambda Kata handler
+ * 4. Attach the customer-specific Lambda Layer
+ * 5. Add additional environment variables for the Lambda Kata runtime
+ *
+ * @param lambda - The Lambda function to transform
+ * @param config - The transformation configuration
+ *
+ * @remarks
+ * Validates: Requirements 2.2, 2.3, 2.4, 3.3, 3.4, 4.1, 4.2, 5.4
+ * - 2.2: THE kata_Wrapper SHALL change the Lambda runtime from Node.js to Python 3.12
+ * - 2.3: THE kata_Wrapper SHALL set the Lambda handler to `lambdakata.optimized_handler.lambda_handler`
+ * - 2.4: THE kata_Wrapper SHALL attach the customer-specific Lambda_Layer ARN to the Lambda
+ * - 3.3: THE kata_Wrapper SHALL attach the Config_Layer to the transformed Lambda
+ * - 3.4: THE kata_Wrapper SHALL NOT set the `JS_HANDLER_PATH` environment variable
+ * - 4.1: THE kata_Wrapper SHALL NOT add the `JS_HANDLER_PATH` environment variable to transformed Lambdas
+ * - 4.2: WHEN `bundlePath` is specified, THE kata_Wrapper SHALL write it to the Config_Layer JSON as `bundle_path`
+ * - 5.4: THE compiled middleware SHALL be included in the Config_Layer at `/opt/.kata/middleware.js`
+ *
+ * @internal
+ */
+export declare function applyTransformation(lambda: NodejsFunction | LambdaFunction, config: TransformationConfig): void;
+/**
+ * Handles the case when an account is not licensed.
+ *
+ * Depending on the unlicensedBehavior option:
+ * - 'warn' (default): Emit a warning and keep the original Lambda unchanged
+ * - 'fail': Throw an error to fail CDK synthesis
+ *
+ * @param lambda - The Lambda function
+ * @param props - The kata wrapper options
+ * @param licensingResponse - The licensing response
+ *
+ * @remarks
+ * Validates: Requirements 3.5, 3.6, 6.1, 6.2, 6.3, 6.4
+ * - 3.5: IF the account is NOT entitled, THEN THE kata_Wrapper SHALL NOT apply any transformations
+ * - 3.6: IF the account is NOT entitled, THEN THE kata_Wrapper SHALL emit a clear warning message
+ * - 6.1: IF the Licensing_Service returns an unlicensed status, THEN THE kata_Wrapper SHALL keep the original Node.js runtime unchanged
+ * - 6.2: IF the Licensing_Service returns an unlicensed status, THEN THE kata_Wrapper SHALL keep the original handler unchanged
+ * - 6.3: IF the Licensing_Service returns an unlicensed status, THEN THE kata_Wrapper SHALL NOT attach any Lambda_Layer
+ * - 6.4: IF the Licensing_Service returns an unlicensed status, THEN THE kata_Wrapper SHALL emit a warning message
+ *
+ * @internal
+ */
+export declare function handleUnlicensed(lambda: NodejsFunction | LambdaFunction, props: KataWrapperOptions | undefined, licensingResponse: LicensingResponse): void;
+/**
+ * Checks if a Lambda function has been transformed by kata().
+ *
+ * @param lambda - The Lambda function to check
+ * @returns true if the Lambda has been transformed
+ *
+ * @example
+ * ```typescript
+ * const myFunction = new NodejsFunction(this, 'MyFunction', { ... });
+ * kata(myFunction);
+ *
+ * if (isKataTransformed(myFunction)) {
+ *   console.log('Function is using Lambda Kata runtime');
+ * }
+ * ```
+ */
+export declare function isKataTransformed(lambda: NodejsFunction | LambdaFunction): boolean;
+/**
+ * Gets the kata transformation promise for a Lambda function.
+ *
+ * This is useful for testing or when you need to await the transformation result.
+ *
+ * @param lambda - The Lambda function
+ * @returns The transformation promise, or undefined if kata() was not called
+ *
+ * @example
+ * ```typescript
+ * const myFunction = new NodejsFunction(this, 'MyFunction', { ... });
+ * kata(myFunction);
+ *
+ * const result = await getKataPromise(myFunction);
+ * if (result?.transformed) {
+ *   console.log(`Transformed with layer: ${result.licensingResponse.layerArn}`);
+ * }
+ * ```
+ */
+export declare function getKataPromise(lambda: NodejsFunction | LambdaFunction): Promise<KataResult> | undefined;

package/lib/licensing.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Licensing Service for Lambda Kata CDK Integration
+ *
+ * This module provides the interface and implementation for validating
+ * AWS Marketplace entitlements at CDK synthesis/deploy time.
+ *
+ * @module licensing
+ */
+import { LicensingResponse } from './types';
+/**
+ * Interface for the Lambda Kata licensing service.
+ *
+ * Implementations of this interface are responsible for validating
+ * AWS account entitlements and returning customer-specific Layer ARNs.
+ *
+ * @example
+ * ```typescript
+ * const licensingService = new HttpLicensingService();
+ * const response = await licensingService.checkEntitlement('123456789012');
+ * if (response.entitled) {
+ *   console.log(`Layer ARN: ${response.layerArn}`);
+ * }
+ * ```
+ */
+export interface LicensingService {
+    /**
+     * Check if an AWS account is entitled to use Lambda Kata.
+     *
+     * @param accountId - The AWS account ID to check (12-digit string)
+     * @returns Promise resolving to entitlement status and Layer ARN if entitled
+     *
+     * @remarks
+     * - If the account is entitled, the response will include the customer-specific Layer ARN
+     * - If the account is not entitled, the response will have `entitled: false`
+     * - Network errors are handled gracefully and treated as unlicensed (Requirement 6.5)
+     */
+    checkEntitlement(accountId: string): Promise<LicensingResponse>;
+}
+/**
+ * HTTP-based implementation of the LicensingService interface.
+ *
+ * This implementation calls the Lambda Kata licensing backend to validate
+ * AWS Marketplace entitlements. Network errors are handled gracefully
+ * by treating unreachable services as unlicensed (per Requirement 6.5).
+ *
+ * @example
+ * ```typescript
+ * // Use default endpoint
+ * const service = new HttpLicensingService();
+ *
+ * // Use custom endpoint
+ * const customService = new HttpLicensingService('https://custom.endpoint.com');
+ * ```
+ */
+export declare class HttpLicensingService implements LicensingService {
+    private readonly endpoint;
+    private readonly timeoutMs;
+    /**
+     * Creates a new HttpLicensingService instance.
+     *
+     * @param endpoint - Optional custom licensing endpoint URL
+     * @param timeoutMs - Optional request timeout in milliseconds (default: 5000)
+     */
+    constructor(endpoint?: string, timeoutMs?: number);
+    /**
+     * Check if an AWS account is entitled to use Lambda Kata.
+     *
+     * Makes an HTTP request to the licensing service to validate the account's
+     * AWS Marketplace entitlement. If the service is unreachable or returns
+     * an error, the account is treated as unlicensed (Requirement 6.5).
+     *
+     * @param accountId - The AWS account ID to check (12-digit string)
+     * @returns Promise resolving to entitlement status and Layer ARN if entitled
+     *
+     * @remarks
+     * Validates: Requirements 3.2, 3.3, 6.5
+     * - 3.2: Calls the Licensing_Service to validate the account's entitlement
+     * - 3.3: Returns the customer-specific Layer_ARN if entitled
+     * - 6.5: Treats unreachable service as unlicensed with appropriate warning
+     */
+    checkEntitlement(accountId: string): Promise<LicensingResponse>;
+    /**
+     * Makes the HTTP request to the licensing service.
+     *
+     * @param accountId - The AWS account ID to check
+     * @returns Promise resolving to the licensing response
+     * @throws Error if the request fails or times out
+     */
+    private makeRequest;
+}
+/**
+ * Validates that an AWS account ID is in the correct format.
+ *
+ * @param accountId - The account ID to validate
+ * @returns true if the account ID is a valid 12-digit string
+ */
+export declare function isValidAccountId(accountId: string): boolean;
+/**
+ * Creates a default LicensingService instance.
+ *
+ * This factory function provides a convenient way to create a licensing
+ * service with default configuration.
+ *
+ * @param endpoint - Optional custom licensing endpoint URL
+ * @returns A new LicensingService instance
+ *
+ * @example
+ * ```typescript
+ * const service = createLicensingService();
+ * const response = await service.checkEntitlement('123456789012');
+ * ```
+ */
+export declare function createLicensingService(endpoint?: string): LicensingService;

package/lib/mock-licensing.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Mock Licensing Service for Lambda Kata CDK Integration Testing
+ *
+ * This module provides a mock implementation of the LicensingService interface
+ * for testing the kata() wrapper without making real network calls.
+ *
+ * @module mock-licensing
+ */
+import { LicensingService } from './licensing';
+import { LicensingResponse } from './types';
+/**
+ * Mock implementation of the LicensingService interface for testing.
+ *
+ * This class allows programmatic control over entitlement status,
+ * enabling comprehensive testing of the kata() wrapper behavior
+ * for both entitled and non-entitled accounts.
+ *
+ * @example
+ * ```typescript
+ * const mockService = new MockLicensingService();
+ *
+ * // Set up an entitled account
+ * mockService.setEntitled('123456789012', 'arn:aws:lambda:us-east-1:999999999999:layer:LambdaKata:1');
+ *
+ * // Check entitlement
+ * const response = await mockService.checkEntitlement('123456789012');
+ * console.log(response.entitled); // true
+ * console.log(response.layerArn); // 'arn:aws:lambda:us-east-1:999999999999:layer:LambdaKata:1'
+ *
+ * // Non-entitled account
+ * const response2 = await mockService.checkEntitlement('000000000000');
+ * console.log(response2.entitled); // false
+ * ```
+ *
+ * @remarks
+ * Validates: Requirements 3.2, 3.3
+ * - 3.2: Provides mock validation of account entitlements
+ * - 3.3: Returns customer-specific Layer_ARN for entitled accounts
+ */
+export declare class MockLicensingService implements LicensingService {
+    /**
+     * Map of AWS account IDs to their entitled Layer ARNs.
+     * Accounts not in this map are considered non-entitled.
+     */
+    private entitlements;
+    /**
+     * Map of AWS account IDs to custom messages (for non-entitled accounts).
+     */
+    private customMessages;
+    /**
+     * Optional custom message to return for entitled accounts.
+     */
+    private entitledMessage;
+    /**
+     * Optional custom message to return for non-entitled accounts.
+     * Default matches the expected warning message from Requirement 6.4.
+     */
+    private notEntitledMessage;
+    /**
+     * Optional expiration date for entitlements.
+     */
+    private expiresAt?;
+    /**
+     * Flag to simulate service unavailability.
+     */
+    private simulateServiceError;
+    /**
+     * Custom error message when simulating service errors.
+     */
+    private serviceErrorMessage;
+    /**
+     * Sets an account as entitled with a specific Layer ARN.
+     *
+     * @param accountId - The AWS account ID (12-digit string)
+     * @param layerArn - The customer-specific Lambda Layer ARN
+     *
+     * @example
+     * ```typescript
+     * mockService.setEntitled('123456789012', 'arn:aws:lambda:us-east-1:999999999999:layer:LambdaKata:1');
+     * ```
+     */
+    setEntitled(accountId: string, layerArn: string): void;
+    /**
+     * Removes entitlement for an account.
+     *
+     * @param accountId - The AWS account ID to remove entitlement for
+     *
+     * @example
+     * ```typescript
+     * mockService.removeEntitlement('123456789012');
+     * ```
+     */
+    removeEntitlement(accountId: string): void;
+    /**
+     * Clears all entitlements.
+     *
+     * @example
+     * ```typescript
+     * mockService.clearEntitlements();
+     * ```
+     */
+    clearEntitlements(): void;
+    /**
+     * Sets a custom message for entitled accounts.
+     *
+     * @param message - The message to return for entitled accounts
+     */
+    setEntitledMessage(message: string): void;
+    /**
+     * Sets a custom message for non-entitled accounts.
+     *
+     * @param message - The message to return for non-entitled accounts
+     */
+    setNotEntitledMessage(message: string): void;
+    /**
+     * Sets a custom message for a specific non-entitled account.
+     * This allows testing per-account custom error messages from the licensing service.
+     *
+     * @param accountId - The AWS account ID
+     * @param message - The custom message to return for this account
+     *
+     * @example
+     * ```typescript
+     * mockService.setCustomMessage('123456789012', 'Custom licensing error: Account suspended');
+     * ```
+     */
+    setCustomMessage(accountId: string, message: string): void;
+    /**
+     * Sets the expiration date for entitlements.
+     *
+     * @param expiresAt - ISO 8601 formatted expiration date
+     */
+    setExpiresAt(expiresAt: string): void;
+    /**
+     * Configures the mock to simulate service unavailability.
+     *
+     * @param simulate - Whether to simulate service errors
+     * @param errorMessage - Optional custom error message
+     *
+     * @example
+     * ```typescript
+     * // Simulate service being down
+     * mockService.setSimulateServiceError(true);
+     *
+     * // With custom error message
+     * mockService.setSimulateServiceError(true, 'Connection refused');
+     * ```
+     */
+    setSimulateServiceError(simulate: boolean, errorMessage?: string): void;
+    /**
+     * Check if an AWS account is entitled to use Lambda Kata.
+     *
+     * This mock implementation returns entitlement status based on
+     * accounts configured via setEntitled().
+     *
+     * @param accountId - The AWS account ID to check (12-digit string)
+     * @returns Promise resolving to entitlement status and Layer ARN if entitled
+     *
+     * @remarks
+     * Validates: Requirements 3.2, 3.3
+     * - 3.2: Validates the account's entitlement based on configured entitlements
+     * - 3.3: Returns the customer-specific Layer_ARN if entitled
+     */
+    checkEntitlement(accountId: string): Promise<LicensingResponse>;
+    /**
+     * Returns the number of entitled accounts.
+     *
+     * @returns The count of entitled accounts
+     */
+    getEntitlementCount(): number;
+    /**
+     * Checks if a specific account is entitled (without async).
+     *
+     * @param accountId - The AWS account ID to check
+     * @returns true if the account is entitled
+     */
+    isEntitled(accountId: string): boolean;
+    /**
+     * Gets the Layer ARN for an entitled account (without async).
+     *
+     * @param accountId - The AWS account ID
+     * @returns The Layer ARN if entitled, undefined otherwise
+     */
+    getLayerArn(accountId: string): string | undefined;
+}
+/**
+ * Creates a MockLicensingService with pre-configured entitlements.
+ *
+ * @param entitlements - Map of account IDs to Layer ARNs
+ * @returns A new MockLicensingService instance with the specified entitlements
+ *
+ * @example
+ * ```typescript
+ * const mockService = createMockLicensingService({
+ *   '123456789012': 'arn:aws:lambda:us-east-1:999999999999:layer:LambdaKata:1',
+ *   '987654321098': 'arn:aws:lambda:us-west-2:999999999999:layer:LambdaKata:2',
+ * });
+ * ```
+ */
+export declare function createMockLicensingService(entitlements?: Record<string, string>): MockLicensingService;

package/lib/types.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Type definitions for @lambda-kata/cdk
+ *
+ * These interfaces define the core data structures used by the kata() wrapper
+ * for transforming Node.js Lambda functions to use the Lambda Kata runtime.
+ */
+import { Runtime } from 'aws-cdk-lib/aws-lambda';
+/**
+ * Configuration options for the kata() wrapper function.
+ *
+ * @example
+ * ```typescript
+ * kata(myFunction, {
+ *   unlicensedBehavior: 'fail',
+ *   licensingEndpoint: 'https://custom-endpoint.example.com'
+ * });
+ * ```
+ */
+export interface KataProps {
+    /**
+     * Optional: Override the licensing service endpoint
+     * Default: Lambda Kata production licensing endpoint
+     */
+    licensingEndpoint?: string;
+    /**
+     * Optional: Behavior when account is not licensed
+     * 'warn' - Keep original Lambda, emit warning (default)
+     * 'fail' - Throw error and fail synthesis
+     */
+    unlicensedBehavior?: 'warn' | 'fail';
+}
+/**
+ * Response from the Lambda Kata licensing service.
+ *
+ * This interface represents the response returned when checking
+ * an AWS account's entitlement to use Lambda Kata.
+ */
+export interface LicensingResponse {
+    /**
+     * Whether the AWS account is entitled to use Lambda Kata
+     */
+    entitled: boolean;
+    /**
+     * Customer-specific Lambda Layer ARN containing the Lambda Kata runtime.
+     * Only present if the account is entitled.
+     */
+    layerArn?: string;
+    /**
+     * Human-readable status message
+     */
+    message?: string;
+    /**
+     * Entitlement expiration date in ISO 8601 format.
+     * Only present if the account is entitled.
+     */
+    expiresAt?: string;
+}
+/**
+ * Configuration for transforming a Lambda function to use Lambda Kata.
+ *
+ * This interface defines the transformation parameters applied to
+ * an entitled Lambda function.
+ */
+export interface TransformationConfig {
+    /**
+     * The original Node.js handler path (e.g., "index.handler")
+     * This will be stored in the config layer.
+     */
+    originalHandler: string;
+    /**
+     * The target runtime for the transformed Lambda.
+     * Always Runtime.PYTHON_3_12 for Lambda Kata.
+     */
+    targetRuntime: Runtime;
+    /**
+     * The handler path for the Lambda Kata runtime.
+     * Always "lambdakata.optimized_handler.lambda_handler"
+     */
+    targetHandler: string;
+    /**
+     * Customer-specific Lambda Layer ARN containing the Lambda Kata runtime.
+     * Retrieved from the licensing service.
+     */
+    layerArn: string;
+    /**
+     * Custom bundle path.
+     * If not specified, uses the default /opt/js_runtime/bundle.js
+     *
+     * @remarks
+     * Validates: Requirement 4.2
+     */
+    bundlePath?: string;
+    /**
+     * Path to middleware TypeScript/JavaScript file.
+     * The file will be compiled with esbuild and included in the config layer.
+     * The middleware must export a function: (bundle, context) => handler
+     *
+     * @remarks
+     * Validates: Requirement 5.4
+     */
+    middlewarePath?: string;
+    /**
+     * Inline handler resolver function.
+     * This TypeScript function will be serialized, compiled with esbuild,
+     * and included in the config layer as middleware.js
+     *
+     * @remarks
+     * Validates: Requirement for inline handler resolution
+     */
+    handlerResolver?: (bundle: unknown, context: {
+        originalHandler: string;
+    }) => Function;
+}