@mettlecast/domain-cdk-packer 0.2.104 → 0.2.106

package/dist/DomainStack.js

@@ -9,6 +9,9 @@ import * as iam from 'aws-cdk-lib/aws-iam';
 import * as scheduler from 'aws-cdk-lib/aws-scheduler';
 import * as ec2 from 'aws-cdk-lib/aws-ec2';
 import * as s3 from 'aws-cdk-lib/aws-s3';
+import * as cloudwatch from 'aws-cdk-lib/aws-cloudwatch';
+import * as cloudwatchActions from 'aws-cdk-lib/aws-cloudwatch-actions';
+import * as sns from 'aws-cdk-lib/aws-sns';
 import { createGroupedLambdas, createGroupedApiActionLambda } from './grouped-lambda-factory.js';
 import { IamPolicyBuilder } from './iam/iam-policy-builder.js';
 import { HealthConstruct } from './constructs/health-construct.js';
@@ -204,6 +207,56 @@ export class DomainStack extends cdk.Stack {
         if (Object.keys(crossDomainActionArns).length > 0) {
             environment.TIB_ACTION_LAMBDA_ARNS = JSON.stringify(crossDomainActionArns);
         }
+        // Transactional outbox (issue #5294): when the domain declares an outbox
+        // table in defineDomain, the runtime hydrates a real ctx.outbox backed by
+        // Postgres + SQS. The table itself is created by the domain's
+        // `outbox-table` migration.
+        if (registry.domain.outboxTableName) {
+            environment.TIB_OUTBOX_TABLE = registry.domain.outboxTableName;
+        }
+        // ── Job queues (issue #5294) ────────────────────────────────────────────
+        // Pre-create every declared job's SQS queue + DLQ BEFORE any producer
+        // Lambda so TIB_JOB_QUEUE_URLS / TIB_JOB_DLQ_ARNS can be injected into
+        // the shared environment. The runtime's ctx.jobs.enqueue resolves queue
+        // URLs from that map at hydrate time, so every handler that receives ctx
+        // can enqueue declared jobs. Queues are encrypted (KMS when enableCmk,
+        // else SQS-managed), redrive honors defineJob.maxRetries as RETRY
+        // ATTEMPTS AFTER THE FIRST DELIVERY (maxReceiveCount = maxRetries + 1,
+        // minimum 1 so zero retries is valid), and the configured visibility
+        // timeout is preserved.
+        const jobQueues = new Map();
+        const jobDlqs = new Map();
+        const jobQueueUrlMap = {};
+        const jobDlqArnMap = {};
+        for (const job of registry.jobs) {
+            const pascalId = toPascalCase(job.id);
+            const dlq = new sqs.Queue(this, `${pascalId}JobDlq`, {
+                retentionPeriod: cdk.Duration.days(14),
+                encryption: enableCmk ? sqs.QueueEncryption.KMS : sqs.QueueEncryption.SQS_MANAGED,
+                encryptionMasterKey: enableCmk ? cmkKey : undefined,
+            });
+            jobDlqs.set(job.id, dlq);
+            const queue = new sqs.Queue(this, `${pascalId}JobQueue`, {
+                visibilityTimeout: cdk.Duration.seconds(job.visibilityTimeoutSeconds ?? 30),
+                deadLetterQueue: {
+                    queue: dlq,
+                    maxReceiveCount: maxReceiveCountForJob(job.maxRetries),
+                },
+                encryption: enableCmk ? sqs.QueueEncryption.KMS : sqs.QueueEncryption.SQS_MANAGED,
+                encryptionMasterKey: enableCmk ? cmkKey : undefined,
+            });
+            jobQueues.set(job.id, queue);
+            jobQueueUrlMap[job.id] = queue.queueUrl;
+            jobDlqArnMap[job.id] = dlq.queueArn;
+        }
+        if (Object.keys(jobQueueUrlMap).length > 0) {
+            // Fn::ToJsonString resolves the queue URL tokens at deploy time so the
+            // Lambda env var carries the real per-job URLs.
+            environment.TIB_JOB_QUEUE_URLS = cdk.Fn.toJsonString(jobQueueUrlMap);
+            // Per-job DLQ ARNs back ctx.jobs.replayDlq (operator DLQ redrive via
+            // SQS StartMessageMoveTask). Scoped IAM is granted below.
+            environment.TIB_JOB_DLQ_ARNS = cdk.Fn.toJsonString(jobDlqArnMap);
+        }
         // Deterministic physical name for THIS domain's internal-action grouped
         // Lambda so other stacks can construct its ARN for cross-domain calls.
         const actionLambdaName = `${resourceBaseName}-action`;
@@ -555,30 +608,55 @@ export class DomainStack extends cdk.Stack {
             const jobLambdaById = jobHandlers.byId;
             jobLambdas = jobHandlers.lambdas;
             this.lambdaArns[`${domainId}-job`] = jobLambdas[0].functionArn;
-            // Wire SQS → Lambda for each job
+            // Wire SQS → Lambda for each job. Queues/DLQs were pre-created above so
+            // TIB_JOB_QUEUE_URLS could be injected before any Lambda existed.
+            const alarmTopic = alarmSnsTopicArn
+                ? sns.Topic.fromTopicArn(this, 'JobDlqAlarmTopic', alarmSnsTopicArn)
+                : undefined;
+            const alarmAction = alarmTopic ? [new cloudwatchActions.SnsAction(alarmTopic)] : [];
             for (const job of registry.jobs) {
                 const pascalId = toPascalCase(job.id);
-                // Create dead-letter queue
-                const dlq = new sqs.Queue(this, `${pascalId}JobDlq`, {
-                    retentionPeriod: cdk.Duration.days(14),
-                    encryption: enableCmk ? sqs.QueueEncryption.KMS : sqs.QueueEncryption.SQS_MANAGED,
-                    encryptionMasterKey: enableCmk ? cmkKey : undefined,
+                const dlq = jobDlqs.get(job.id);
+                const queue = jobQueues.get(job.id);
+                // Standard per-job DLQ alarms (issue #5294): fire when any message
+                // lands in the DLQ, and when the oldest message ages past 15 minutes.
+                // Both are wired to the project SNS topic when one is configured.
+                const dlqDepthAlarm = new cloudwatch.Alarm(this, `${pascalId}JobDlqDepthAlarm`, {
+                    alarmName: `${resourceBaseName}-job-${job.id}-dlq-depth`,
+                    alarmDescription: `Job ${job.id} DLQ has visible messages — investigate failed job processing`,
+                    metric: dlq.metricApproximateNumberOfMessagesVisible({
+                        period: cdk.Duration.minutes(1),
+                        statistic: 'Maximum',
+                    }),
+                    threshold: 0,
+                    evaluationPeriods: 1,
+                    comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_THRESHOLD,
+                    treatMissingData: cloudwatch.TreatMissingData.NOT_BREACHING,
                 });
-                allDlqs.push(dlq);
-                // Create main queue with dead-letter queue configuration
-                const queue = new sqs.Queue(this, `${pascalId}JobQueue`, {
-                    visibilityTimeout: cdk.Duration.seconds(job.visibilityTimeoutSeconds),
-                    deadLetterQueue: {
-                        queue: dlq,
-                        maxReceiveCount: 5,
-                    },
-                    encryption: enableCmk ? sqs.QueueEncryption.KMS : sqs.QueueEncryption.SQS_MANAGED,
-                    encryptionMasterKey: enableCmk ? cmkKey : undefined,
+                if (alarmAction.length > 0)
+                    dlqDepthAlarm.addAlarmAction(...alarmAction);
+                const dlqAgeAlarm = new cloudwatch.Alarm(this, `${pascalId}JobDlqAgeAlarm`, {
+                    alarmName: `${resourceBaseName}-job-${job.id}-dlq-oldest-age`,
+                    alarmDescription: `Job ${job.id} DLQ oldest message exceeded 15 minutes — investigate failed job processing`,
+                    metric: dlq.metricApproximateAgeOfOldestMessage({
+                        period: cdk.Duration.minutes(5),
+                        statistic: 'Maximum',
+                    }),
+                    threshold: 900,
+                    evaluationPeriods: 1,
+                    comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_THRESHOLD,
+                    treatMissingData: cloudwatch.TreatMissingData.NOT_BREACHING,
                 });
-                // Add SQS as event source for the first grouped Lambda
+                if (alarmAction.length > 0)
+                    dlqAgeAlarm.addAlarmAction(...alarmAction);
+                // Add SQS as event source for the first grouped Lambda. Batch size
+                // stays 1 (one message per invocation), but partial-batch failure
+                // reporting is enabled so a future batch-size increase degrades
+                // safely: only failed messages are retried/redriven (issue #5294).
                 const fn = jobLambdaById.get(job.id);
                 fn.addEventSource(new lambdaEventSources.SqsEventSource(queue, {
                     batchSize: 1,
+                    reportBatchItemFailures: true,
                 }));
                 // Grant IAM permissions for this queue
                 const queuePolicies = iamBuilder.forJob({ queueArn: queue.queueArn, dlqArn: dlq.queueArn });
@@ -654,6 +732,44 @@ export class DomainStack extends cdk.Stack {
                 addRouteToApi(this, fn, `/${domainId}${action.exposure.path}`, [toHttpMethod(action.exposure.method)], this.httpApi.httpApiId, routeAuth);
             }
         }
+        // Producer SQS grant (issue #5294): every producer handler — actions,
+        // subscribers, schedules, jobs, and webhooks — receives ctx.jobs, so each
+        // gets sqs:SendMessage scoped to THIS domain's declared job queue ARNs.
+        // Never a wildcard; producers cannot touch other domains' queues.
+        if (jobQueues.size > 0) {
+            const producerQueueArns = [...jobQueues.values()].map(q => q.queueArn);
+            const producerStatements = iamBuilder.forJobProducer(producerQueueArns);
+            const producerLambdas = [
+                ...actionLambdas,
+                ...subscriberLambdas,
+                ...scheduleLambdas,
+                ...jobLambdas,
+                ...webhookLambdas,
+            ];
+            for (const fn of producerLambdas) {
+                producerStatements.forEach(statement => fn.addToRolePolicy(statement));
+            }
+        }
+        // DLQ redrive grant (issue #5294): the runtime's ctx.jobs.replayDlq
+        // starts an SQS StartMessageMoveTask on a declared job's DLQ. Every
+        // domain Lambda that receives ctx.jobs can invoke it, so grant
+        // sqs:StartMessageMoveTask scoped to THIS domain's exact DLQ ARNs — the
+        // destination is derived by SQS from the DLQ's redrive policy, so no
+        // broader resource is needed.
+        if (jobDlqs.size > 0) {
+            const dlqArns = [...jobDlqs.values()].map(q => q.queueArn);
+            const replayStatements = iamBuilder.forDlqReplay(dlqArns);
+            const replayLambdas = [
+                ...actionLambdas,
+                ...subscriberLambdas,
+                ...scheduleLambdas,
+                ...jobLambdas,
+                ...webhookLambdas,
+            ];
+            for (const fn of replayLambdas) {
+                replayStatements.forEach(statement => fn.addToRolePolicy(statement));
+            }
+        }
         // Grant all domain Lambdas read/write access to the per-domain table and bucket
         const allDomainLambdas = [
             ...webhookLambdas, ...subscriberLambdas,
@@ -663,6 +779,18 @@ export class DomainStack extends cdk.Stack {
             domainTable.grantReadWriteData(fn);
             domainBucket.grantReadWrite(fn);
         }
+        // SQS KMS grants (issue #5294): with enableCmk every queue/DLQ — job
+        // queues, subscriber queues — is encrypted with the domain CMK. SQS
+        // producers need kms:GenerateDataKey (envelope encrypt) and consumers
+        // need kms:Decrypt + kms:GenerateDataKey (envelope decrypt). Grant the
+        // exact operations on the exact queue key to every Lambda that touches
+        // SQS (producers enqueue, subscribers/jobs consume).
+        if (enableCmk && cmkKey) {
+            const sqsKmsStatements = iamBuilder.forSqsKmsEncryption(cmkKey.keyArn);
+            for (const fn of allDomainLambdas) {
+                sqsKmsStatements.forEach(statement => fn.addToRolePolicy(statement));
+            }
+        }
         // Grant Cognito Admin permissions when a user pool is configured.
         // The auth domain's provision-cognito-user internal action needs
         // AdminCreateUser, AdminSetUserPassword, and AdminGetUser to
@@ -692,14 +820,16 @@ export class DomainStack extends cdk.Stack {
             }
         }
         // Grant SES SendEmail permission when a verified sending address is configured.
-        // Scoped to the SES identity ARN derived from SES_FROM_EMAIL (e.g. an
-        // address or domain identity) — least-privilege. Falls back to 'arn:aws:ses:*:*:*'
-        // only when the address is not address-shaped (tests/local).
+        // Scoped to the SES identity ARN derived from SES_FROM_EMAIL — least-privilege.
+        // SES_FROM_EMAIL may be address-shaped (noreply@example.com) or a bare domain
+        // (example.com). The Email Domain settings tab always creates a *domain*
+        // identity, so an address-shaped value must be reduced to its domain part:
+        // scoping to `identity/noreply@example.com` would not match the created
+        // `identity/example.com` and ses:SendEmail would be denied at runtime.
         if (process.env['SES_FROM_EMAIL']) {
             const sesFrom = process.env['SES_FROM_EMAIL'];
-            const sesIdentity = sesFrom.includes('@')
-                ? `arn:aws:ses:${this.region}:${this.account}:identity/${sesFrom}`
-                : `arn:aws:ses:${this.region}:${this.account}:identity/${sesFrom}`;
+            const sesIdentityDomain = (sesFrom.includes('@') ? sesFrom.split('@')[1] : sesFrom).toLowerCase();
+            const sesIdentity = `arn:aws:ses:${this.region}:${this.account}:identity/${sesIdentityDomain}`;
             for (const fn of allDomainLambdas) {
                 fn.addToRolePolicy(new iam.PolicyStatement({
                     actions: ['ses:SendEmail', 'ses:SendRawEmail'],
@@ -823,6 +953,19 @@ function toPascalCase(s) {
         .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
         .join('');
 }
+/**
+ * Map `defineJob.maxRetries` to the SQS redrive policy `maxReceiveCount`.
+ *
+ * `maxRetries` is documented as the number of RETRY ATTEMPTS AFTER THE FIRST
+ * DELIVERY, so the receive count is `maxRetries + 1`. Zero retries is valid
+ * (exactly one delivery) and the receive count is clamped to a minimum of 1
+ * (SQS rejects 0). This mirrors the domain-runtime `defineJob` contract
+ * (issue #5294).
+ */
+function maxReceiveCountForJob(maxRetries) {
+    const retries = Number.isFinite(maxRetries) && maxRetries !== undefined ? maxRetries : 3;
+    return Math.max(1, retries + 1);
+}
 /**
  * Convert HTTP method string to ApiGatewayV2 HttpMethod enum.
  * @param method - HTTP method string (e.g., 'GET', 'POST').

package/dist/__tests__/domain-stack.test.js

@@ -1,4 +1,4 @@
-import { describe, it, expect, afterAll } from 'vitest';
+import { describe, it, expect, afterAll, afterEach } from 'vitest';
 import * as cdk from 'aws-cdk-lib';
 import { Template } from 'aws-cdk-lib/assertions';
 import fs from 'node:fs';
@@ -633,4 +633,68 @@ describe('DomainStack', () => {
             expect(hasScopedPutEvents).toBe(true);
         });
     });
+    /**
+     * Review finding H1 (#5292): the ses:SendEmail/ses:SendRawEmail grant must
+     * scope to the *domain* SES identity that the Email Domain settings tab
+     * creates. SES_FROM_EMAIL is address-shaped (`noreply@example.com`) after
+     * sender activation — building `identity/noreply@example.com` would never
+     * match the created `identity/example.com` and email would be denied.
+     */
+    describe('SES send grant scoped to the domain identity (#5292 H1)', () => {
+        const originalSesFromEmail = process.env.SES_FROM_EMAIL;
+        afterEach(() => {
+            if (originalSesFromEmail === undefined)
+                delete process.env.SES_FROM_EMAIL;
+            else
+                process.env.SES_FROM_EMAIL = originalSesFromEmail;
+        });
+        const sesResourceStrings = (template) => Object.values(template.findResources('AWS::IAM::Policy')).flatMap(p => p.Properties.PolicyDocument.Statement
+            .filter(s => s.Action?.includes('ses:SendEmail'))
+            .map(s => JSON.stringify(s.Resource)));
+        it('scopes an address-shaped SES_FROM_EMAIL to identity/example.com, never identity/noreply@example.com', () => {
+            process.env.SES_FROM_EMAIL = 'noreply@example.com';
+            const app = new cdk.App();
+            const stack = new DomainStack(app, 'TestDomainStackSesAddress', {
+                registry: minimalRegistry,
+                eventBusArn,
+                projectId: 'Test',
+                envCode: 'Dev',
+            });
+            const template = Template.fromStack(stack);
+            const resources = sesResourceStrings(template);
+            expect(resources.length).toBeGreaterThan(0);
+            for (const resource of resources) {
+                expect(resource).toContain('identity/example.com');
+                expect(resource).not.toContain('identity/noreply@example.com');
+            }
+        });
+        it('keeps plain-domain behavior: a bare domain SES_FROM_EMAIL scopes to identity/example.com', () => {
+            process.env.SES_FROM_EMAIL = 'example.com';
+            const app = new cdk.App();
+            const stack = new DomainStack(app, 'TestDomainStackSesDomain', {
+                registry: minimalRegistry,
+                eventBusArn,
+                projectId: 'Test',
+                envCode: 'Dev',
+            });
+            const template = Template.fromStack(stack);
+            const resources = sesResourceStrings(template);
+            expect(resources.length).toBeGreaterThan(0);
+            for (const resource of resources) {
+                expect(resource).toContain('identity/example.com');
+            }
+        });
+        it('omits the SES grant when SES_FROM_EMAIL is not set', () => {
+            delete process.env.SES_FROM_EMAIL;
+            const app = new cdk.App();
+            const stack = new DomainStack(app, 'TestDomainStackSesUnset', {
+                registry: minimalRegistry,
+                eventBusArn,
+                projectId: 'Test',
+                envCode: 'Dev',
+            });
+            const template = Template.fromStack(stack);
+            expect(sesResourceStrings(template)).toHaveLength(0);
+        });
+    });
 });

package/dist/__tests__/jobs-outbox-cmk.test.d.ts

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

package/dist/__tests__/jobs-outbox-cmk.test.js

@@ -0,0 +1,108 @@
+import { describe, it, expect, 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 { DomainStack } from '../DomainStack.js';
+const DOMAIN_ROOT = path.join(process.cwd(), '.test-domain-cdk-packer-cmk');
+const handlerDir = path.join(DOMAIN_ROOT, 'src', 'handlers');
+fs.mkdirSync(handlerDir, { recursive: true });
+fs.writeFileSync(path.join(handlerDir, 'send-email.ts'), `export const sendEmail = { id: "send-email", _kind: "job", maxRetries: 2, visibilityTimeoutSeconds: 60, handler: async () => undefined };\n`);
+fs.writeFileSync(path.join(handlerDir, 'on-user-created.ts'), `export const onUserCreated = { id: "on-user-created", _kind: "subscriber", event: "auth.user.created", semverRange: ">=1", handler: async () => undefined };\n`);
+// Grouped Lambdas need stub asset dirs to synth.
+const assetDirs = ['subscriber', 'job'].map(type => path.join(process.cwd(), 'dist', 'domains', 'email', type));
+for (const dir of assetDirs) {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'index.js'), 'exports.handler = async () => ({});\n');
+}
+afterAll(() => {
+    fs.rmSync(DOMAIN_ROOT, { recursive: true, force: true });
+    for (const dir of assetDirs) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+});
+const eventBusArn = 'arn:aws:events:eu-north-1:123456789012:event-bus/tib-event-bus';
+const cmkRegistry = {
+    schemaVersion: '1',
+    domainRoot: DOMAIN_ROOT,
+    domain: { id: 'email', kind: 'domain', name: 'Email', tenancy: 'required', outboxTableName: 'email.outbox' },
+    webhooks: [],
+    subscribers: [
+        {
+            id: 'on-user-created', kind: 'subscriber', handlerFile: 'src/handlers/on-user-created.ts',
+            event: 'auth.user.created', semverRange: '>=1',
+        },
+    ],
+    schedules: [],
+    jobs: [
+        { id: 'send-email', kind: 'job', handlerFile: 'src/handlers/send-email.ts', maxRetries: 2, visibilityTimeoutSeconds: 60 },
+    ],
+    actions: [],
+    integrations: [],
+    events: [],
+};
+describe('DomainStack enableCmk SQS KMS grants (#5294)', () => {
+    const app = new cdk.App();
+    const stack = new DomainStack(app, 'CmkTestDomainStack', {
+        registry: cmkRegistry,
+        eventBusArn,
+        projectId: 'Test',
+        envCode: 'Dev',
+        enableCmk: true,
+    });
+    const template = Template.fromStack(stack);
+    it('encrypts job queues and DLQs with the customer-managed key', () => {
+        const queues = Object.values(template.findResources('AWS::SQS::Queue'));
+        expect(queues.length).toBeGreaterThan(0);
+        for (const q of queues) {
+            expect(q.Properties.KmsMasterKeyId).toBeDefined();
+        }
+    });
+    it('grants the exact KMS operations (kms:Decrypt + kms:GenerateDataKey) on the queue key to SQS producers and consumers', () => {
+        const policies = Object.values(template.findResources('AWS::IAM::Policy'));
+        const kmsStatements = policies.flatMap(p => p.Properties.PolicyDocument.Statement
+            .filter(s => {
+            const actions = Array.isArray(s.Action) ? s.Action : [s.Action];
+            return actions.some(a => a === 'kms:Decrypt' || a === 'kms:GenerateDataKey');
+        }));
+        expect(kmsStatements.length).toBeGreaterThan(0);
+        // The SQS grant is the statement that carries BOTH exact operations on
+        // the domain CMK (S3/DDB grants carry narrower single-operation grants on
+        // the same key — do not conflate them).
+        const sqsKmsStatement = kmsStatements.find(s => {
+            const actions = Array.isArray(s.Action) ? s.Action : [s.Action];
+            return actions.includes('kms:Decrypt') && actions.includes('kms:GenerateDataKey');
+        });
+        expect(sqsKmsStatement).toBeDefined();
+        // Scoped to the domain CMK ARN (references the DomainKey resource).
+        expect(JSON.stringify(sqsKmsStatement.Resource ?? '')).toContain('DomainKey');
+        // No broader kms:* wildcard anywhere.
+        for (const s of kmsStatements) {
+            const actions = Array.isArray(s.Action) ? s.Action : [s.Action];
+            for (const a of actions) {
+                expect(String(a)).not.toBe('kms:*');
+            }
+        }
+    });
+    it('grants the KMS operations to both job consumers and subscriber consumers (SQS receive paths)', () => {
+        // The subscriber and job lambdas consume from KMS-encrypted queues; at
+        // least one policy must be attached to a role used by each group. The
+        // check is intentionally coarse: every domain Lambda policy that carries
+        // SQS actions also carries the KMS decrypt grant.
+        const policies = Object.values(template.findResources('AWS::IAM::Policy'));
+        const sqsKmsPolicies = policies.filter(p => p.Properties.PolicyDocument.Statement
+            .some(s => {
+            const actions = Array.isArray(s.Action) ? s.Action : [s.Action];
+            return actions.includes('sqs:ReceiveMessage') || actions.includes('sqs:SendMessage');
+        }));
+        expect(sqsKmsPolicies.length).toBeGreaterThan(0);
+        for (const p of sqsKmsPolicies) {
+            const statements = p.Properties.PolicyDocument.Statement;
+            const hasKms = statements.some(s => {
+                const actions = Array.isArray(s.Action) ? s.Action : [s.Action];
+                return actions.includes('kms:Decrypt') || actions.includes('kms:GenerateDataKey');
+            });
+            expect(hasKms).toBe(true);
+        }
+    });
+});

package/dist/__tests__/jobs-outbox-wiring.test.d.ts

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

package/dist/__tests__/jobs-outbox-wiring.test.js

@@ -0,0 +1,228 @@
+import { describe, it, expect, 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 { DomainStack } from '../DomainStack.js';
+const DOMAIN_ROOT = path.join(process.cwd(), '.test-domain-cdk-packer-jobs');
+const handlerDir = path.join(DOMAIN_ROOT, 'src', 'handlers');
+fs.mkdirSync(handlerDir, { recursive: true });
+fs.writeFileSync(path.join(handlerDir, 'get-users.ts'), `export const getUsers = { id: "get-users", backendAccess: "domain", exposure: { type: "api", path: "/v1/tenants/{tenantId}/users", method: "GET", auth: "required", tenancy: "required" }, input: { parse: (x) => x }, output: { parse: (x) => x }, idempotent: false, handler: async () => ({ ok: true }) };\n`);
+fs.writeFileSync(path.join(handlerDir, 'send-email.ts'), `export const sendEmail = { id: "send-email", _kind: "job", maxRetries: 4, visibilityTimeoutSeconds: 120, handler: async () => undefined };\n`);
+fs.writeFileSync(path.join(handlerDir, 'sync-users.ts'), `export const syncUsers = { id: "sync-users", _kind: "job", handler: async () => undefined };\n`);
+fs.writeFileSync(path.join(handlerDir, 'no-retry.ts'), `export const noRetry = { id: "no-retry", _kind: "job", maxRetries: 0, handler: async () => undefined };\n`);
+fs.writeFileSync(path.join(handlerDir, 'daily-digest.ts'), `export const dailyDigest = { id: "daily-digest", _kind: "schedule", cron: "rate(1 day)", enabled: true, handler: async () => undefined };\n`);
+fs.writeFileSync(path.join(handlerDir, 'on-user-created.ts'), `export const onUserCreated = { id: "on-user-created", _kind: "subscriber", event: "auth.user.created", semverRange: ">=1", handler: async () => undefined };\n`);
+fs.writeFileSync(path.join(handlerDir, 'github-push.ts'), `export const githubPush = { id: "github-push", _kind: "webhook", path: "/github/push", provider: "github", handler: async () => undefined };\n`);
+// Grouped (non-dedicated) Lambdas use Code.fromAsset('dist/domains/{domain}/{type}').
+// Create stub asset dirs so `Template.fromStack` can synth without a real build.
+const assetDirs = ['webhook', 'subscriber', 'schedule', 'job'].map(type => path.join(process.cwd(), 'dist', 'domains', 'email', type));
+for (const dir of assetDirs) {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'index.js'), 'exports.handler = async () => ({});\n');
+}
+afterAll(() => {
+    fs.rmSync(DOMAIN_ROOT, { recursive: true, force: true });
+    for (const dir of assetDirs) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+});
+const eventBusArn = 'arn:aws:events:eu-north-1:123456789012:event-bus/tib-event-bus';
+const jobsRegistry = {
+    schemaVersion: '1',
+    domainRoot: DOMAIN_ROOT,
+    domain: {
+        id: 'email',
+        kind: 'domain',
+        name: 'Email',
+        tenancy: 'required',
+        outboxTableName: 'email.outbox',
+    },
+    webhooks: [
+        {
+            id: 'github-push', kind: 'webhook', handlerFile: 'src/handlers/github-push.ts',
+            path: '/github/push', provider: 'github',
+        },
+    ],
+    subscribers: [
+        {
+            id: 'on-user-created', kind: 'subscriber', handlerFile: 'src/handlers/on-user-created.ts',
+            event: 'auth.user.created', semverRange: '>=1',
+        },
+    ],
+    schedules: [
+        {
+            id: 'daily-digest', kind: 'schedule', handlerFile: 'src/handlers/daily-digest.ts',
+            cron: 'rate(1 day)', enabled: true,
+        },
+    ],
+    jobs: [
+        {
+            id: 'send-email', kind: 'job', handlerFile: 'src/handlers/send-email.ts',
+            maxRetries: 4, visibilityTimeoutSeconds: 120,
+        },
+        {
+            id: 'sync-users', kind: 'job', handlerFile: 'src/handlers/sync-users.ts',
+            maxRetries: 3, visibilityTimeoutSeconds: 30,
+        },
+        {
+            id: 'no-retry', kind: 'job', handlerFile: 'src/handlers/no-retry.ts',
+            maxRetries: 0, visibilityTimeoutSeconds: 30,
+        },
+    ],
+    actions: [
+        {
+            id: 'get-users', kind: 'action', handlerFile: 'src/handlers/get-users.ts',
+            backendAccess: 'domain',
+            exposure: { type: 'api', path: '/v1/tenants/{tenantId}/users', method: 'GET', auth: 'required', tenancy: 'required' },
+            idempotent: false,
+            inputSchema: { type: 'object', properties: {} },
+            outputSchema: { type: 'object', properties: {} },
+        },
+    ],
+    integrations: [],
+    events: [],
+};
+describe('DomainStack jobs/outbox wiring (#5294)', () => {
+    const app = new cdk.App();
+    const stack = new DomainStack(app, 'JobsTestDomainStack', {
+        registry: jobsRegistry,
+        eventBusArn,
+        projectId: 'Test',
+        envCode: 'Dev',
+        alarmSnsTopicArn: 'arn:aws:sns:eu-north-1:123456789012:alerts',
+    });
+    const template = Template.fromStack(stack);
+    function domainLambdaEnvVars() {
+        const lambdas = template.findResources('AWS::Lambda::Function');
+        return Object.entries(lambdas)
+            .filter(([id]) => !id.includes('Health') && !id.includes('Ready') && !id.includes('LogRetention'))
+            .map(([, res]) => res.Properties.Environment?.Variables ?? {});
+    }
+    it('injects TIB_JOB_QUEUE_URLS into every producer Lambda environment', () => {
+        const envs = domainLambdaEnvVars();
+        expect(envs.length).toBeGreaterThan(0);
+        for (const env of envs) {
+            expect(env.TIB_JOB_QUEUE_URLS).toBeDefined();
+            expect(JSON.stringify(env.TIB_JOB_QUEUE_URLS)).toContain('send-email');
+            expect(JSON.stringify(env.TIB_JOB_QUEUE_URLS)).toContain('sync-users');
+        }
+    });
+    it('injects TIB_OUTBOX_TABLE when the domain declares an outbox', () => {
+        const envs = domainLambdaEnvVars();
+        for (const env of envs) {
+            expect(env.TIB_OUTBOX_TABLE).toBe('email.outbox');
+        }
+    });
+    it('maps defineJob.maxRetries to maxReceiveCount = maxRetries + 1 (retries AFTER first delivery)', () => {
+        const queues = template.findResources('AWS::SQS::Queue');
+        const redriveCounts = Object.values(queues)
+            .map(q => q.Properties.RedrivePolicy?.maxReceiveCount)
+            .filter((v) => v !== undefined)
+            .map(v => String(v));
+        // send-email maxRetries: 4 → 5 deliveries total
+        expect(redriveCounts).toContain('5');
+        // sync-users default maxRetries: 3 → 4 deliveries total
+        expect(redriveCounts).toContain('4');
+        // no-retry maxRetries: 0 → exactly 1 delivery (zero retries is valid)
+        expect(redriveCounts).toContain('1');
+        // No queue can carry a receive count of 0 (SQS rejects it)
+        expect(redriveCounts).not.toContain('0');
+    });
+    it('enables SQS partial-batch failure reporting on JOB event-source mappings (batch stays 1)', () => {
+        const mappings = Object.values(template.findResources('AWS::Lambda::EventSourceMapping'));
+        // Filter to JOB mappings only (the subscriber mapping legitimately uses
+        // batchSize 10 — job mappings are the #5294 contract).
+        const jobMappings = mappings.filter(m => JSON.stringify(m.Properties.EventSourceArn ?? '').includes('JobQueue'));
+        expect(jobMappings.length).toBeGreaterThan(0);
+        for (const m of jobMappings) {
+            const props = m.Properties;
+            expect(props.BatchSize).toBe(1);
+            // FunctionResponseTypes 'ReportBatchItemFailures' — safe future batch growth
+            expect(props.FunctionResponseTypes).toContain('ReportBatchItemFailures');
+        }
+    });
+    it('injects TIB_JOB_DLQ_ARNS (jobId → DLQ ARN) for the ctx.jobs.replayDlq operator path', () => {
+        const envs = domainLambdaEnvVars();
+        for (const env of envs) {
+            expect(env.TIB_JOB_DLQ_ARNS).toBeDefined();
+            const raw = JSON.stringify(env.TIB_JOB_DLQ_ARNS);
+            // Fn::ToJsonString synthesizes to an Fn::Join token — assert the
+            // resolved literals (job ids + the DLQ logical-id references) are present.
+            expect(raw).toContain('no-retry');
+            expect(raw).toContain('send-email');
+            expect(raw).toContain('sync-users');
+            expect(raw).toContain('JobDlq');
+        }
+    });
+    it('grants sqs:StartMessageMoveTask scoped to the domain DLQ ARNs (operator replay, no wildcard)', () => {
+        const policies = Object.values(template.findResources('AWS::IAM::Policy'));
+        const replayStatements = policies.flatMap(p => p.Properties.PolicyDocument.Statement
+            .filter(s => (Array.isArray(s.Action) ? s.Action : [s.Action]).includes('sqs:StartMessageMoveTask')));
+        expect(replayStatements.length).toBeGreaterThan(0);
+        for (const s of replayStatements) {
+            const res = JSON.stringify(s.Resource ?? '');
+            expect(res).not.toBe('"*"');
+            expect(res).toContain('JobDlq'); // scoped to the job DLQ logical ids
+        }
+    });
+    it('includes webhook handlers in the producer sqs:SendMessage grant (ctx.jobs is hydrated for webhooks)', () => {
+        const policies = Object.values(template.findResources('AWS::IAM::Policy'));
+        const webhookPolicy = policies.find(p => p.Properties.PolicyDocument.Statement
+            .some(s => (Array.isArray(s.Action) ? s.Action : [s.Action]).includes('sqs:SendMessage')));
+        expect(webhookPolicy).toBeDefined();
+    });
+    it('preserves the configured visibility timeout and keeps encryption enabled', () => {
+        const queues = template.findResources('AWS::SQS::Queue');
+        const mainQueues = Object.values(queues).filter(q => !String(q.Properties.QueueName ?? '').includes('dlq'));
+        expect(mainQueues.some(q => q.Properties.VisibilityTimeout === 120)).toBe(true);
+        // SQS-managed encryption is the default — every queue must declare it (no plaintext queues).
+        for (const q of Object.values(queues)) {
+            expect(q.Properties.SqsManagedSseEnabled).toBe(true);
+        }
+    });
+    it('grants producers sqs:SendMessage scoped to the domain queue ARNs (no wildcard SQS)', () => {
+        const policies = Object.values(template.findResources('AWS::IAM::Policy'));
+        const sendStatements = policies.flatMap(p => p.Properties.PolicyDocument.Statement
+            .filter(s => (Array.isArray(s.Action) ? s.Action : [s.Action]).includes('sqs:SendMessage')));
+        expect(sendStatements.length).toBeGreaterThan(0);
+        // The producer grant targets THIS domain's job queue ARNs (logical ids
+        // contain "JobQueue"), not the per-handler DLQ grants.
+        const producerStatement = sendStatements.find(s => JSON.stringify(s.Resource ?? '').includes('JobQueue'));
+        expect(producerStatement).toBeDefined();
+        // Never a wildcard — every sqs:SendMessage resource is an exact queue ARN.
+        for (const s of sendStatements) {
+            const res = JSON.stringify(s.Resource ?? '');
+            expect(res).not.toBe('"*"');
+            expect(res).not.toContain('*');
+        }
+    });
+    it('creates standard DLQ depth + oldest-age alarms for each job', () => {
+        const alarms = Object.values(template.findResources('AWS::CloudWatch::Alarm'))
+            .map(a => a.Properties.AlarmName);
+        expect(alarms.some(name => name.includes('-job-send-email-dlq-depth'))).toBe(true);
+        expect(alarms.some(name => name.includes('-job-send-email-dlq-oldest-age'))).toBe(true);
+        expect(alarms.some(name => name.includes('-job-sync-users-dlq-depth'))).toBe(true);
+        expect(alarms.some(name => name.includes('-job-sync-users-dlq-oldest-age'))).toBe(true);
+    });
+    it('wires DLQ alarms to the SNS topic when one is provided', () => {
+        const alarms = template.findResources('AWS::CloudWatch::Alarm');
+        const depthAlarm = Object.entries(alarms).find(([, a]) => a.Properties.AlarmName.includes('-job-send-email-dlq-depth'));
+        expect(depthAlarm).toBeDefined();
+        expect(JSON.stringify(depthAlarm[1].Properties.AlarmActions)).toContain('alerts');
+    });
+    it('does not expose any wildcard SQS policy action', () => {
+        const policies = Object.values(template.findResources('AWS::IAM::Policy'));
+        const sqsStatements = policies.flatMap(p => p.Properties.PolicyDocument.Statement
+            .filter(s => {
+            const actions = Array.isArray(s.Action) ? s.Action : [s.Action];
+            return actions.some(a => typeof a === 'string' && a.startsWith('sqs:'));
+        }));
+        for (const s of sqsStatements) {
+            const actions = Array.isArray(s.Action) ? s.Action : [s.Action];
+            for (const action of actions) {
+                expect(action).not.toBe('sqs:*');
+            }
+        }
+    });
+});

package/dist/constructs/job-construct.d.ts

@@ -1,3 +1,4 @@
+import * as cdk from 'aws-cdk-lib';
 import * as sqs from 'aws-cdk-lib/aws-sqs';
 import { Construct } from 'constructs';
 import { LambdaFactory } from '../lambda-factory.js';
@@ -13,10 +14,21 @@ export interface JobConstructProps {
     lambdaFactory: LambdaFactory;
     /** Builder for generating IAM policies. */
     iamBuilder: IamPolicyBuilder;
+    /** Whether queues/DLQs use a customer-managed KMS key. Defaults to SQS-managed encryption. */
+    enableCmk?: boolean;
+    /** KMS key used when enableCmk is true. */
+    encryptionKey?: cdk.aws_kms.IKey;
 }
 /**
  * CDK Construct that synthesizes Lambda functions with SQS queues, dead-letter queues,
  * and event source mappings for background jobs defined in the domain registry.
+ *
+ * Issue #5294: each job's SQS redrive policy honors `defineJob.maxRetries` as
+ * RETRY ATTEMPTS AFTER THE FIRST DELIVERY (`maxReceiveCount = maxRetries + 1`,
+ * minimum 1 so zero retries is valid), the configured `visibilityTimeoutSeconds`
+ * is preserved, queue/DLQ encryption is always enabled (KMS when `enableCmk`,
+ * otherwise SQS-managed), and job event-source mappings report partial batch
+ * failures so a future batch-size increase stays safe.
  */
 export declare class JobConstruct extends Construct {
     /**

package/dist/constructs/job-construct.js

@@ -5,6 +5,13 @@ import { Construct } from 'constructs';
 /**
  * CDK Construct that synthesizes Lambda functions with SQS queues, dead-letter queues,
  * and event source mappings for background jobs defined in the domain registry.
+ *
+ * Issue #5294: each job's SQS redrive policy honors `defineJob.maxRetries` as
+ * RETRY ATTEMPTS AFTER THE FIRST DELIVERY (`maxReceiveCount = maxRetries + 1`,
+ * minimum 1 so zero retries is valid), the configured `visibilityTimeoutSeconds`
+ * is preserved, queue/DLQ encryption is always enabled (KMS when `enableCmk`,
+ * otherwise SQS-managed), and job event-source mappings report partial batch
+ * failures so a future batch-size increase stays safe.
  */
 export class JobConstruct extends Construct {
     /**
@@ -24,23 +31,40 @@ export class JobConstruct extends Construct {
             const pascalId = toPascalCase(entry.id);
             const dlq = new sqs.Queue(this, `${pascalId}Dlq`, {
                 retentionPeriod: cdk.Duration.days(14),
+                encryption: props.enableCmk ? sqs.QueueEncryption.KMS : sqs.QueueEncryption.SQS_MANAGED,
+                encryptionMasterKey: props.enableCmk ? props.encryptionKey : undefined,
             });
             const queue = new sqs.Queue(this, `${pascalId}Queue`, {
-                visibilityTimeout: cdk.Duration.seconds(entry.visibilityTimeoutSeconds),
+                visibilityTimeout: cdk.Duration.seconds(entry.visibilityTimeoutSeconds ?? 30),
                 deadLetterQueue: {
                     queue: dlq,
-                    maxReceiveCount: entry.maxRetries,
+                    maxReceiveCount: maxReceiveCountForJob(entry.maxRetries),
                 },
+                encryption: props.enableCmk ? sqs.QueueEncryption.KMS : sqs.QueueEncryption.SQS_MANAGED,
+                encryptionMasterKey: props.enableCmk ? props.encryptionKey : undefined,
             });
             this.queues.set(entry.id, queue);
             const fn = props.lambdaFactory.createFunction(entry, entry.deployment);
             props.iamBuilder
                 .forJob({ queueArn: queue.queueArn, dlqArn: dlq.queueArn })
                 .forEach((s) => fn.addToRolePolicy(s));
-            fn.addEventSource(new lambdaEventSources.SqsEventSource(queue, { batchSize: 1 }));
+            fn.addEventSource(new lambdaEventSources.SqsEventSource(queue, {
+                batchSize: 1,
+                reportBatchItemFailures: true,
+            }));
         }
     }
 }
+/**
+ * Map `defineJob.maxRetries` to the SQS redrive policy `maxReceiveCount`.
+ *
+ * `maxRetries` is the number of retry attempts AFTER the first delivery, so
+ * the receive count is `maxRetries + 1` (minimum 1 — zero retries is valid).
+ */
+function maxReceiveCountForJob(maxRetries) {
+    const retries = Number.isFinite(maxRetries) && maxRetries !== undefined ? maxRetries : 3;
+    return Math.max(1, retries + 1);
+}
 /**
  * Convert a kebab-case or snake_case string to PascalCase.
  * @param s - Input string to convert

package/dist/iam/iam-policy-builder.d.ts

@@ -58,6 +58,35 @@ export declare class IamPolicyBuilder {
      * @returns Array of policy statements for SQS message receive/delete and DLQ send access.
      */
     forJob(params: QueuePolicyParams): iam.PolicyStatement[];
+    /**
+     * Returns IAM policy statements for PRODUCER handlers that enqueue jobs via
+     * `ctx.jobs.enqueue(...)`. Grants `sqs:SendMessage` scoped to the exact
+     * queue ARNs of THIS domain's declared `defineJob` queues — never a
+     * wildcard. Applies to action, subscriber, schedule, job, and webhook roles
+     * because the runtime exposes `ctx.jobs` to all of them.
+     * @param queueArns - Exact ARNs of the domain's declared job queues.
+     * @returns Array of policy statements (empty when there are no queues).
+     */
+    forJobProducer(queueArns: string[]): iam.PolicyStatement[];
+    /**
+     * Returns IAM policy statements for the operator DLQ redrive operation
+     * (`ctx.jobs.replayDlq`, SQS `StartMessageMoveTask`). Scoped to the exact
+     * DLQ ARNs of THIS domain's declared `defineJob` queues — never a wildcard.
+     * The move-task destination is derived by SQS from the DLQ's redrive
+     * policy, so no destination grant is needed.
+     * @param dlqArns - Exact ARNs of the domain's job DLQs.
+     * @returns Array of policy statements (empty when there are no DLQs).
+     */
+    forDlqReplay(dlqArns: string[]): iam.PolicyStatement[];
+    /**
+     * Returns IAM policy statements for SQS KMS envelope encryption on the
+     * domain CMK (enableCmk mode). Producers need `kms:GenerateDataKey` to
+     * encrypt a message; consumers need `kms:Decrypt` + `kms:GenerateDataKey`
+     * to decrypt it. Both are granted on the exact queue key ARN.
+     * @param keyArn - ARN of the domain CMK used to encrypt the queues.
+     * @returns Array of policy statements (exact KMS operations on the key).
+     */
+    forSqsKmsEncryption(keyArn: string): iam.PolicyStatement[];
     /**
      * Returns IAM policy statements for callable action handlers.
      * @param crossDomainActionArns - Optional ARNs of other domain action Lambdas to invoke.

package/dist/iam/iam-policy-builder.js

@@ -91,6 +91,60 @@ export class IamPolicyBuilder {
             }),
         ];
     }
+    /**
+     * Returns IAM policy statements for PRODUCER handlers that enqueue jobs via
+     * `ctx.jobs.enqueue(...)`. Grants `sqs:SendMessage` scoped to the exact
+     * queue ARNs of THIS domain's declared `defineJob` queues — never a
+     * wildcard. Applies to action, subscriber, schedule, job, and webhook roles
+     * because the runtime exposes `ctx.jobs` to all of them.
+     * @param queueArns - Exact ARNs of the domain's declared job queues.
+     * @returns Array of policy statements (empty when there are no queues).
+     */
+    forJobProducer(queueArns) {
+        if (queueArns.length === 0)
+            return [];
+        return [
+            new iam.PolicyStatement({
+                actions: ['sqs:SendMessage'],
+                resources: queueArns,
+            }),
+        ];
+    }
+    /**
+     * Returns IAM policy statements for the operator DLQ redrive operation
+     * (`ctx.jobs.replayDlq`, SQS `StartMessageMoveTask`). Scoped to the exact
+     * DLQ ARNs of THIS domain's declared `defineJob` queues — never a wildcard.
+     * The move-task destination is derived by SQS from the DLQ's redrive
+     * policy, so no destination grant is needed.
+     * @param dlqArns - Exact ARNs of the domain's job DLQs.
+     * @returns Array of policy statements (empty when there are no DLQs).
+     */
+    forDlqReplay(dlqArns) {
+        if (dlqArns.length === 0)
+            return [];
+        return [
+            new iam.PolicyStatement({
+                actions: ['sqs:StartMessageMoveTask'],
+                resources: dlqArns,
+            }),
+        ];
+    }
+    /**
+     * Returns IAM policy statements for SQS KMS envelope encryption on the
+     * domain CMK (enableCmk mode). Producers need `kms:GenerateDataKey` to
+     * encrypt a message; consumers need `kms:Decrypt` + `kms:GenerateDataKey`
+     * to decrypt it. Both are granted on the exact queue key ARN.
+     * @param keyArn - ARN of the domain CMK used to encrypt the queues.
+     * @returns Array of policy statements (exact KMS operations on the key).
+     */
+    forSqsKmsEncryption(keyArn) {
+        return [
+            new iam.PolicyStatement({
+                actions: ['kms:Decrypt', 'kms:GenerateDataKey'],
+                resources: [keyArn],
+            }),
+        ];
+    }
     /**
      * Returns IAM policy statements for callable action handlers.
      * @param crossDomainActionArns - Optional ARNs of other domain action Lambdas to invoke.

package/dist/registry.d.ts

@@ -262,6 +262,13 @@ export interface DomainRegistryEntry extends BaseRegistryEntry {
     tenancy: string;
     /** Optional default deployment configuration for the domain. */
     defaultDeployment?: SerialDeploymentConfig;
+    /**
+     * Optional transactional outbox table (schema-qualified, e.g. `email.outbox`).
+     * When declared, the CDK packer injects `TIB_OUTBOX_TABLE` so the runtime
+     * hydrates a real `ctx.outbox` (append/dispatch) for this domain (#5294).
+     * The table must be created by the domain's `outbox-table` migration.
+     */
+    outboxTableName?: string;
 }
 /**
  * Union type of all registry entry kinds.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mettlecast/domain-cdk-packer",
-  "version": "0.2.104",
+  "version": "0.2.106",
   "type": "module",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",