@mettlecast/domain-cdk-packer 0.2.60 → 0.2.62

package/dist/DomainStack.d.ts

@@ -82,6 +82,11 @@ export interface DomainStackProps extends cdk.StackProps {
      * Defaults to the second segment of the stack name; falls back to `dev` when not derivable.
      */
     envCode?: string;
+    /**
+     * When true, disables the auto-generated per-domain CloudWatch dashboard.
+     * Existing dashboards will be removed on the next CDK deploy.
+     */
+    disableCloudWatchDashboards?: boolean;
 }
 export declare class DomainStack extends cdk.Stack {
     /** Shared HTTP API for routing API and webhook requests. */

package/dist/DomainStack.js

@@ -1,7 +1,5 @@
 import * as cdk from 'aws-cdk-lib';
 import * as apigwv2 from 'aws-cdk-lib/aws-apigatewayv2';
-import * as apigwv2integrations from 'aws-cdk-lib/aws-apigatewayv2-integrations';
-import * as apigwv2Authorizers from 'aws-cdk-lib/aws-apigatewayv2-authorizers';
 import * as events from 'aws-cdk-lib/aws-events';
 import * as eventsTargets from 'aws-cdk-lib/aws-events-targets';
 import * as sqs from 'aws-cdk-lib/aws-sqs';
@@ -20,12 +18,9 @@ import { WafConstruct } from './constructs/waf-construct.js';
 import { AlarmConstruct } from './constructs/alarm-construct.js';
 import { CanaryConstruct } from './constructs/canary-construct.js';
 import { domainResourceName } from './naming.js';
-/**
- * Top-level CDK Stack that composes all domain constructs from a single DomainRegistry input.
- * Uses grouped Lambdas for each primitive type to reduce deployment artifact size.
- */
+import { SecurityAssertionAspect } from './aspects/security-assertion-aspect.js';
 /** L1 helper: adds a CfnRoute + CfnIntegration to an existing HTTP API. */
-function addRouteToApi(scope, fn, path, methods, apiId) {
+function addRouteToApi(scope, fn, path, methods, apiId, auth) {
     const id = path.replace(/[^a-zA-Z0-9]/g, '_').replace(/^_/, 'api') + '_' + methods[0].toLowerCase();
     const integ = new apigwv2.CfnIntegration(scope, 'Integ_' + id, {
         apiId,
@@ -37,12 +32,24 @@ function addRouteToApi(scope, fn, path, methods, apiId) {
         principal: new iam.ServicePrincipal('apigateway.amazonaws.com'),
         sourceArn: 'arn:aws:execute-api:' + cdk.Aws.REGION + ':' + cdk.Aws.ACCOUNT_ID + ':' + apiId + '/*',
     });
-    const routeKey = methods[0] === apigwv2.HttpMethod.GET ? 'GET ' + path : 'POST ' + path;
-    new apigwv2.CfnRoute(scope, 'Route_' + id, {
-        apiId,
-        routeKey,
-        target: 'integrations/' + integ.ref,
-    });
+    // Use the actual HTTP method (supports GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS/ANY).
+    // Previous implementation only handled GET vs POST and silently coerced every
+    // other method to POST, breaking PUT/PATCH/DELETE routes.
+    const routeKey = `${methods[0]} ${path}`;
+    const routeProps = auth
+        ? {
+            apiId,
+            routeKey,
+            target: 'integrations/' + integ.ref,
+            authorizationType: auth.authorizationType,
+            authorizerId: auth.authorizerId,
+        }
+        : {
+            apiId,
+            routeKey,
+            target: 'integrations/' + integ.ref,
+        };
+    new apigwv2.CfnRoute(scope, 'Route_' + id, routeProps);
 }
 export class DomainStack extends cdk.Stack {
     /** Shared HTTP API for routing API and webhook requests. */
@@ -57,7 +64,7 @@ export class DomainStack extends cdk.Stack {
      */
     constructor(scope, id, props) {
         super(scope, id, props);
-        const { registry, eventBusArn, eventBusName, databaseUrl, dbSecretArn, userPoolArn, userPoolId, userPoolClientId, internalSubnetSelection, internetSubnetSelection, enableCmk, enableWaf, enableAlarms, alarmSnsTopicArn, enableCanaryDeploy, reservedConcurrency, logRetentionDays, corsAllowedOrigins, allowCredentials } = props;
+        const { registry, eventBusArn, eventBusName, databaseUrl, dbSecretArn, userPoolArn, userPoolId, userPoolClientId, internalSubnetSelection, internetSubnetSelection, enableCmk, enableWaf, enableAlarms, alarmSnsTopicArn, enableCanaryDeploy, reservedConcurrency, logRetentionDays, corsAllowedOrigins, allowCredentials, disableCloudWatchDashboards } = props;
         const vpc = props.vpc ?? (props.vpcId
             ? ec2.Vpc.fromVpcAttributes(this, 'SharedVpc', {
                 vpcId: props.vpcId,
@@ -88,15 +95,53 @@ export class DomainStack extends cdk.Stack {
                 ...(allowCredentials ? { allowCredentials: true } : {}),
             },
         });
-        // Wire Cognito JWT authorizer when user pool is provided
+        // Wire Cognito JWT authorizer when user pool is provided.
+        //
+        // We use the L2 `HttpAuthorizer` (not `HttpJwtAuthorizer`) because it eagerly
+        // creates the underlying `CfnAuthorizer` and exposes `authorizerId` as a
+        // concrete string. `HttpJwtAuthorizer` lazily binds through `bind()` and
+        // throws if `authorizerId` is read before binding — that prevented the
+        // existing L1 `addRouteToApi` from ever attaching an authorizer, which is
+        // the bug Wave 4 Task 4.1 fixes.
         let jwtAuthorizer;
         if ((userPoolId || userPoolArn) && userPoolClientId) {
             const region = cdk.Stack.of(this).region;
             const resolvedUserPoolId = userPoolId ?? cdk.Fn.select(1, cdk.Fn.split('/', userPoolArn));
-            jwtAuthorizer = new apigwv2Authorizers.HttpJwtAuthorizer('CognitoAuthorizer', `https://cognito-idp.${region}.amazonaws.com/${resolvedUserPoolId}`, {
+            jwtAuthorizer = new apigwv2.HttpAuthorizer(this, 'CognitoAuthorizer', {
+                httpApi: this.httpApi,
+                authorizerName: 'CognitoAuthorizer',
+                type: apigwv2.HttpAuthorizerType.JWT,
+                identitySource: ['$request.header.Authorization'],
                 jwtAudience: [userPoolClientId],
+                jwtIssuer: `https://cognito-idp.${region}.amazonaws.com/${resolvedUserPoolId}`,
             });
         }
+        // Pre-resolve authorizer metadata for `addRouteToApi` — `CfnRoute` consumes
+        // a concrete `{ authorizerId, authorizationType }` tuple, not the L2 authorizer.
+        const jwtAuth = jwtAuthorizer
+            ? { authorizerId: jwtAuthorizer.authorizerId, authorizationType: apigwv2.HttpAuthorizerType.JWT }
+            : undefined;
+        // Determine whether any route in this domain requires a JWT authorizer.
+        // If so and `jwtAuth` is undefined, emit a synth-time error so missing Cognito
+        // configuration fails fast instead of producing an unauthenticated route.
+        //
+        // Issue #4689: only API-exposed actions (`exposure.auth === 'required'`)
+        // contribute to this check. Legacy `registry.apis` rows are always
+        // empty in fresh registries, so checking them would never fire.
+        const actionNeedsJwt = registry.actions.some(a => a.exposure?.type === 'api' && a.exposure.auth === 'required');
+        const anyRouteRequiresJwt = actionNeedsJwt;
+        if (anyRouteRequiresJwt && !jwtAuth) {
+            cdk.Annotations.of(this).addError(`[DomainStack] Domain "${domainId}" declares one or more JWT-protected routes ` +
+                `(action.exposure.auth='required') but no Cognito user pool is ` +
+                `configured. Provide userPoolArn/userPoolId AND userPoolClientId to DomainStackProps.`);
+        }
+        // Issue #4662 Task D — deployment-time security assertions. The aspect
+        // walks the synthesised tree after the stack has been assembled and
+        // re-validates the same invariants the CLI checks at build time. It
+        // catches regressions where a route was silently synthesised without
+        // an authorizer (e.g. a feature flag skipped the wiring), or where an
+        // action Lambda was attached to a Function URL outside the registry.
+        cdk.Aspects.of(this).add(new SecurityAssertionAspect({ registry }));
         // Optional WAF
         if (enableWaf) {
             new WafConstruct(this, 'Waf', { domainId, namePrefix: resourceBaseName, httpApi: this.httpApi });
@@ -138,12 +183,30 @@ export class DomainStack extends cdk.Stack {
             const lambdas = [];
             const byId = new Map();
             for (const group of splitByOutboundAccess(entries)) {
-                const dedicated = group.entries.some(entry => entry.deployment?.isolation === 'dedicated') || primitiveType === 'api';
+                // Force dedicated mode for action groups that contain any API-exposed
+                // action — the per-entry adapter override only takes effect in
+                // dedicated mode (grouped mode uses a single TIB_HANDLER_MAP dispatcher
+                // which assumes a uniform adapter across all entries). We detect
+                // api-exposed actions by their `adapter` override (set by the caller
+                // in the action block below), since the entry shape is intentionally
+                // primitive-agnostic.
+                const hasApiExposedAction = primitiveType === 'action'
+                    && group.entries.some(e => e.adapter === 'createExposedActionApiHandler');
+                const dedicated = group.entries.some(entry => entry.deployment?.isolation === 'dedicated')
+                    || hasApiExposedAction;
                 const groupLambdas = createGroupedLambdas(this, {
                     domainId,
                     domainRoot: registry.domainRoot,
                     primitiveType,
-                    handlerEntries: group.entries.map(entry => ({ id: entry.id, handlerFile: entry.handlerFile })),
+                    handlerEntries: group.entries.map(entry => {
+                        const handlerEntry = {
+                            id: entry.id,
+                            handlerFile: entry.handlerFile,
+                        };
+                        if (entry.adapter)
+                            handlerEntry.adapter = entry.adapter;
+                        return handlerEntry;
+                    }),
                     environment,
                     eventBusArn,
                     dedicated,
@@ -205,7 +268,6 @@ export class DomainStack extends cdk.Stack {
         });
         environment['DOMAIN_TENANT_ROLE_ARN'] = tenantScopedRole.roleArn;
         // Pre-declare lambda group variables
-        let apiLambdas = [];
         let webhookLambdas = [];
         let subscriberLambdas = [];
         let scheduleLambdas = [];
@@ -214,45 +276,18 @@ export class DomainStack extends cdk.Stack {
         // Track all DLQs for alarm construct
         const allDlqs = [];
         // Deploy API endpoints as grouped Lambdas
-        if (registry.apis.length > 0) {
-            const apiHandlers = createPrimitiveHandlers(registry.apis, 'api');
-            const apiLambdaById = apiHandlers.byId;
-            apiLambdas = apiHandlers.lambdas;
-            this.lambdaArns[`${domainId}-api`] = apiLambdas[0].functionArn;
-            // Wire each API Lambda to the HttpApi
-            const iamPolicies = iamBuilder.forApi();
-            apiLambdas.forEach((fn) => {
-                iamPolicies.forEach(statement => fn.addToRolePolicy(statement));
-            });
-            // Add dbSecretArn grant if provided
-            if (dbSecretArn) {
-                apiLambdas.forEach(fn => fn.addToRolePolicy(new iam.PolicyStatement({
-                    actions: ['secretsmanager:GetSecretValue'],
-                    resources: [dbSecretArn],
-                })));
-            }
-            // Add routes for each API entry
-            for (const api of registry.apis) {
-                const fn = apiLambdaById.get(api.id);
-                const apiRouteBase = {
-                    path: api.path,
-                    methods: [toHttpMethod(api.method)],
-                    integration: new apigwv2integrations.HttpLambdaIntegration(`Apis${toPascalCase(api.id)}Integration`, fn),
-                };
-                let apiRoute;
-                if (api.authType === 'jwt' && jwtAuthorizer) {
-                    apiRoute = { ...apiRouteBase, authorizer: jwtAuthorizer };
-                }
-                else if (api.authType === 'api-key') {
-                    cdk.Annotations.of(this).addWarning(`[DomainStack] API "${api.id}" uses authType "api-key" which is not supported on HTTP API v2 — route is UNAUTHENTICATED. Switch to "jwt" or implement a Lambda authorizer.`);
-                    apiRoute = apiRouteBase;
-                }
-                else {
-                    apiRoute = apiRouteBase;
-                }
-                addRouteToApi(this, fn, `/${domainId}${api.path}`, [toHttpMethod(api.method)], this.httpApi.httpApiId);
-            }
-        }
+        //
+        // Issue #4689: the legacy `defineApi` primitive was removed. The
+        // canonical HTTP endpoint surface is `actions[]` with
+        // `exposure.type === 'api'`. Each API-exposed action is wrapped with
+        // `createExposedActionApiHandler` (see grouped-lambda-factory) and
+        // mounted on the HTTP API in the action-routing loop below. The
+        // legacy `registry.apis` block has been removed because the builder
+        // no longer populates that slot in fresh registries.
+        //
+        // We intentionally do NOT iterate `registry.apis` here; doing so
+        // would re-introduce legacy routing that is no longer reachable
+        // from the action-first source-of-truth.
         // Deploy webhooks as grouped Lambdas
         if (registry.webhooks.length > 0) {
             // Create shared dedupe table for webhooks
@@ -420,7 +455,27 @@ export class DomainStack extends cdk.Stack {
         }
         // Deploy callable actions as grouped Lambdas
         if (registry.actions.length > 0) {
-            const actionHandlers = createPrimitiveHandlers(registry.actions, 'action');
+            // Map action entries to NetworkedRegistryEntry so we can attach a per-entry
+            // adapter override. API-exposed actions must use `createExposedActionApiHandler`
+            // because they receive raw HTTP API v2 events; internal actions use the
+            // default `createActionLambdaHandler` (envelope-based invocation through
+            // `ctx.actions`).
+            const actionEntries = registry.actions.map((action) => {
+                const entry = {
+                    id: action.id,
+                    handlerFile: action.handlerFile,
+                };
+                if (action.outboundAccess !== undefined)
+                    entry.outboundAccess = action.outboundAccess;
+                if (action.deployment !== undefined)
+                    entry.deployment = action.deployment;
+                if (action.exposure?.type === 'api') {
+                    entry.adapter = 'createExposedActionApiHandler';
+                }
+                return entry;
+            });
+            const actionHandlers = createPrimitiveHandlers(actionEntries, 'action');
+            const actionLambdaById = actionHandlers.byId;
             actionLambdas = actionHandlers.lambdas;
             this.lambdaArns[`${domainId}-action`] = actionLambdas[0].functionArn;
             const iamPolicies = iamBuilder.forAction([
@@ -436,10 +491,22 @@ export class DomainStack extends cdk.Stack {
                     resources: [dbSecretArn],
                 })));
             }
+            // Generate API Gateway routes for actions whose exposure is `api`.
+            //
+            // `exposure.type === 'internal'` actions are intentionally NOT routed —
+            // they are reachable only through `ctx.actions` and exposing them would
+            // silently bypass the `backendAccess` permission gate.
+            for (const action of registry.actions) {
+                if (action.exposure?.type !== 'api')
+                    continue;
+                const fn = actionLambdaById.get(action.id);
+                const routeAuth = action.exposure.auth === 'required' ? jwtAuth : undefined;
+                addRouteToApi(this, fn, `/${domainId}${action.exposure.path}`, [toHttpMethod(action.exposure.method)], this.httpApi.httpApiId, routeAuth);
+            }
         }
         // Grant all domain Lambdas read/write access to the per-domain table and bucket
         const allDomainLambdas = [
-            ...apiLambdas, ...webhookLambdas, ...subscriberLambdas,
+            ...webhookLambdas, ...subscriberLambdas,
             ...scheduleLambdas, ...jobLambdas, ...actionLambdas,
         ];
         for (const fn of allDomainLambdas) {
@@ -509,19 +576,30 @@ export class DomainStack extends cdk.Stack {
         addRouteToApi(this, healthConstruct.healthFn, `/${domainId}/_health`, [apigwv2.HttpMethod.GET], this.httpApi.httpApiId);
         addRouteToApi(this, healthConstruct.readyFn, `/${domainId}/_ready`, [apigwv2.HttpMethod.GET], this.httpApi.httpApiId);
         // Create CloudWatch dashboard for all primitives
+        //
+        // Issue #4689: HTTP endpoints are now action entries with
+        // `exposure.type === 'api'`. We tag those actions with the
+        // `primitiveClass: 'api'` so the dashboard can still group them
+        // separately from internal-only actions.
         const allEndpoints = [
-            ...registry.apis.map(a => ({ id: a.id, primitiveClass: 'api' })),
-            ...registry.actions.map(a => ({ id: a.id, primitiveClass: 'action' })),
+            ...registry.actions
+                .filter(a => a.exposure?.type === 'api')
+                .map(a => ({ id: a.id, primitiveClass: 'api' })),
+            ...registry.actions
+                .filter(a => a.exposure?.type !== 'api')
+                .map(a => ({ id: a.id, primitiveClass: 'action' })),
             ...registry.subscribers.map(s => ({ id: s.id, primitiveClass: 'subscriber' })),
             ...registry.jobs.map(j => ({ id: j.id, primitiveClass: 'job' })),
             ...registry.webhooks.map(w => ({ id: w.id, primitiveClass: 'webhook' })),
             ...registry.schedules.map(sc => ({ id: sc.id, primitiveClass: 'schedule' })),
         ];
-        new DashboardConstruct(this, 'Dashboard', {
-            domainId,
-            envCode: this.stackName.split('-')[1] ?? 'dev',
-            endpoints: allEndpoints,
-        });
+        if (!disableCloudWatchDashboards) {
+            new DashboardConstruct(this, 'Dashboard', {
+                domainId,
+                envCode: this.stackName.split('-')[1] ?? 'dev',
+                endpoints: allEndpoints,
+            });
+        }
         new cdk.CfnOutput(this, 'DomainTableName', {
             value: domainTable.tableName,
             description: 'Per-domain DynamoDB table name',

package/dist/__tests__/action-construct.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/action-construct.test.js

@@ -0,0 +1,159 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import * as cdk from 'aws-cdk-lib';
+import { Template } from 'aws-cdk-lib/assertions';
+import fs from 'node:fs';
+import path from 'node:path';
+import { ActionConstruct } from '../constructs/action-construct.js';
+import { LambdaFactory } from '../lambda-factory.js';
+import { IamPolicyBuilder } from '../iam/iam-policy-builder.js';
+const DOMAIN_ROOT = path.join(process.cwd(), '.test-action-construct');
+const baseRegistry = {
+    schemaVersion: '1',
+    domainRoot: DOMAIN_ROOT,
+    domain: { id: 'test-domain', kind: 'domain', name: 'Test Domain', tenancy: 'none' },
+    webhooks: [], subscribers: [], schedules: [], jobs: [],
+    actions: [], integrations: [], events: [],
+};
+beforeAll(() => {
+    const handlerDir = path.join(DOMAIN_ROOT, 'src', 'actions');
+    fs.mkdirSync(handlerDir, { recursive: true });
+    fs.writeFileSync(path.join(handlerDir, 'noop.ts'), 'export const handler = async () => ({ statusCode: 200 });\n');
+    fs.writeFileSync(path.join(handlerDir, 'workspace.ts'), 'export const handler = async () => ({ statusCode: 200 });\n');
+});
+afterAll(() => {
+    fs.rmSync(DOMAIN_ROOT, { recursive: true, force: true });
+});
+/**
+ * Wave 4 Task 4.2 (#4619):
+ *   Action Lambdas must never be exposed directly through a Lambda Function URL.
+ *   External reachability is granted ONLY via API Gateway routes synthesized from
+ *   the action's `exposure` field. Function URLs with `authType: NONE` would
+ *   create public, unauthenticated endpoints that bypass auth and tenancy.
+ */
+describe('ActionConstruct (Wave 4 Task 4.2 — no public Function URLs)', () => {
+    const buildStack = (actions) => {
+        const app = new cdk.App();
+        const stack = new cdk.Stack(app, 'TestActionStack');
+        const registry = { ...baseRegistry, actions };
+        const factory = new LambdaFactory({ scope: stack, registry, domainRoot: registry.domainRoot });
+        const iamBuilder = new IamPolicyBuilder();
+        const construct = new ActionConstruct(stack, 'Actions', { registry, lambdaFactory: factory, iamBuilder });
+        return { stack, template: Template.fromStack(stack), construct };
+    };
+    it('synthesises one Lambda per action', () => {
+        const { template } = buildStack([
+            { id: 'noop', kind: 'action', handlerFile: 'src/actions/noop.ts', backendAccess: 'domain', exposure: { type: 'internal' }, idempotent: false },
+        ]);
+        const lambdas = Object.entries(template.findResources('AWS::Lambda::Function'))
+            .filter(([id]) => !id.startsWith('LogRetention'));
+        expect(lambdas).toHaveLength(1);
+        expect(lambdas[0][0]).toContain('NoopFn');
+    });
+    it('does NOT create a Lambda::Url resource for any action', () => {
+        const { template } = buildStack([
+            { id: 'noop', kind: 'action', handlerFile: 'src/actions/noop.ts', backendAccess: 'domain', exposure: { type: 'internal' }, idempotent: false },
+        ]);
+        template.resourceCountIs('AWS::Lambda::Url', 0);
+    });
+    it('does NOT create a Lambda::Url even when legacy visibility === "workspace"', () => {
+        // Legacy entries with the deprecated `visibility: 'workspace'` must NOT
+        // resurrect Function URL exposure now that the action-first migration is in place.
+        const { template } = buildStack([
+            {
+                id: 'workspace-action',
+                kind: 'action',
+                handlerFile: 'src/actions/workspace.ts',
+                backendAccess: 'domain',
+                exposure: { type: 'internal' },
+                idempotent: false,
+                visibility: 'workspace',
+            },
+        ]);
+        template.resourceCountIs('AWS::Lambda::Url', 0);
+        const lambdas = Object.entries(template.findResources('AWS::Lambda::Function'))
+            .filter(([id]) => !id.startsWith('LogRetention'));
+        expect(lambdas).toHaveLength(1);
+        expect(lambdas[0][0]).toContain('WorkspaceActionFn');
+    });
+    it('does NOT create a Lambda::Url when an action exposes via API Gateway (exposure.type === "api")', () => {
+        // API-exposed actions are routed by DomainStack via API Gateway, not by Function URL.
+        const { template } = buildStack([
+            {
+                id: 'api-action',
+                kind: 'action',
+                handlerFile: 'src/actions/noop.ts',
+                backendAccess: 'domain',
+                exposure: { type: 'api', path: '/v1/example', method: 'POST', auth: 'required', tenancy: 'required' },
+                idempotent: false,
+            },
+        ]);
+        template.resourceCountIs('AWS::Lambda::Url', 0);
+    });
+    it('does NOT attach any Lambda::Permission that allows public (apigateway) principal invocation', () => {
+        // Defensive: even without a Function URL, the construct must not add
+        // resource-based Lambda permissions that would let API Gateway invoke
+        // the function without going through the synthesized routes in DomainStack.
+        const { template, construct } = buildStack([
+            { id: 'noop', kind: 'action', handlerFile: 'src/actions/noop.ts', backendAccess: 'domain', exposure: { type: 'internal' }, idempotent: false },
+        ]);
+        expect(construct.functions.size).toBe(1);
+        template.resourceCountIs('AWS::Lambda::Url', 0);
+        const permissions = Object.values(template.findResources('AWS::Lambda::Permission'));
+        // No Function URL permission allowed
+        const hasUrlPermission = permissions.some(p => p.Properties.FunctionUrlAuthType !== undefined);
+        expect(hasUrlPermission).toBe(false);
+    });
+});
+/**
+ * Tenant-scoped storage IAM (defence-in-depth, Wave 4 Task 4.2).
+ *
+ * Verifies the IamPolicyBuilder.forTenantScopedStorage output uses
+ * PrincipalTag conditions to restrict DynamoDB LeadingKeys and S3 object
+ * prefixes to the calling session's tenantId.
+ */
+describe('IamPolicyBuilder.forTenantScopedStorage (defence-in-depth)', () => {
+    const params = {
+        tableArn: 'arn:aws:dynamodb:eu-north-1:123456789012:table/test-domain',
+        bucketArn: 'arn:aws:s3:::test-domain',
+    };
+    it('restricts DynamoDB LeadingKeys to ${aws:PrincipalTag/tenantId}', () => {
+        const builder = new IamPolicyBuilder();
+        const statements = builder.forTenantScopedStorage(params);
+        const ddb = statements.find(s => (s.actions ?? []).some(a => a.startsWith('dynamodb:')));
+        expect(ddb).toBeDefined();
+        expect(ddb.resources).toContain(params.tableArn);
+        const leadingKeys = ddb.conditions?.['ForAllValues:StringEquals']?.['dynamodb:LeadingKeys'];
+        expect(leadingKeys).toEqual(['${aws:PrincipalTag/tenantId}']);
+    });
+    it('restricts S3 object operations to ${aws:PrincipalTag/tenantId}/* prefix', () => {
+        const builder = new IamPolicyBuilder();
+        const statements = builder.forTenantScopedStorage(params);
+        const s3Objects = statements.find(s => (s.actions ?? []).some(a => a === 's3:GetObject' || a === 's3:PutObject' || a === 's3:DeleteObject'));
+        expect(s3Objects).toBeDefined();
+        expect(s3Objects.resources).toEqual([
+            `${params.bucketArn}/\${aws:PrincipalTag/tenantId}/*`,
+        ]);
+    });
+    it('restricts S3:ListBucket to the current tenant prefix via s3:prefix condition', () => {
+        const builder = new IamPolicyBuilder();
+        const statements = builder.forTenantScopedStorage(params);
+        const listBucket = statements.find(s => (s.actions ?? []).includes('s3:ListBucket'));
+        expect(listBucket).toBeDefined();
+        expect(listBucket.resources).toEqual([params.bucketArn]);
+        const prefixCondition = listBucket.conditions
+            ?.StringLike?.['s3:prefix'];
+        expect(prefixCondition).toEqual(['${aws:PrincipalTag/tenantId}/*']);
+    });
+    it('does NOT grant bucket-wide S3 access (no unconditional ${bucketArn} resource for object ops)', () => {
+        const builder = new IamPolicyBuilder();
+        const statements = builder.forTenantScopedStorage(params);
+        for (const s of statements) {
+            const acts = (s.actions ?? []);
+            const isObjectOp = acts.some(a => a === 's3:GetObject' || a === 's3:PutObject' || a === 's3:DeleteObject');
+            if (isObjectOp) {
+                // The only resource granted must be the tenant-scoped prefix, not the bare bucket.
+                expect(s.resources).not.toContain(params.bucketArn);
+            }
+        }
+    });
+});