@learncard/network-brain-service 4.1.2 → 5.0.0

package/src/campaign-unsubscribe.test.ts

@@ -0,0 +1,158 @@
+import Fastify from 'fastify';
+import { readFileSync } from 'node:fs';
+import { parse } from 'yaml';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { TRPCError } from '@trpc/server';
+const unsubscribe = vi.hoisted(() => vi.fn());
+vi.mock('@helpers/campaign-unsubscribe.helpers', () => ({
+    unsubscribeFromCampaignEmails: unsubscribe,
+}));
+import { campaignUnsubscribeFastifyPlugin } from './campaign-unsubscribe';
+beforeEach(() => {
+    unsubscribe.mockReset();
+});
+describe('one-click unsubscribe HTTP', () => {
+    it.each(['serverless.yml', 'serverless-local.yml', 'serverless.local.yml'])(
+        'exposes the browser and provider routes in %s',
+        manifest => {
+            const config = parse(readFileSync(new URL(`../${manifest}`, import.meta.url), 'utf8'));
+            expect(config.functions.campaignUnsubscribe.handler).toBe(
+                'lambda.campaignUnsubscribeHandler'
+            );
+            expect(config.functions.campaignUnsubscribe.events).toEqual(
+                expect.arrayContaining([
+                    { httpApi: 'GET /campaigns/unsubscribe/browser' },
+                    { httpApi: 'POST /campaigns/unsubscribe/browser' },
+                    { httpApi: 'POST /campaigns/unsubscribe' },
+                ])
+            );
+        }
+    );
+
+    it.each([
+        ['es-MX', 'es', 'ltr', 'Cancelar suscripción'],
+        ['fr-FR', 'fr', 'ltr', 'Se désinscrire'],
+        ['ar-EG', 'ar', 'rtl', 'إلغاء الاشتراك'],
+    ])('localizes the browser page for %s', async (language, locale, direction, label) => {
+        const app = Fastify();
+        await app.register(campaignUnsubscribeFastifyPlugin);
+        try {
+            const page = await app.inject({
+                url: '/campaigns/unsubscribe/browser?token=signed',
+                headers: { 'accept-language': language },
+            });
+            expect(page.body).toContain(`lang="${locale}" dir="${direction}"`);
+            expect(page.body).toContain(`${label}</button>`);
+            expect(unsubscribe).not.toHaveBeenCalled();
+        } finally {
+            await app.close();
+        }
+    });
+
+    it('serves an anonymous browser confirmation and applies only explicit form submissions', async () => {
+        const app = Fastify();
+        await app.register(campaignUnsubscribeFastifyPlugin);
+        try {
+            unsubscribe.mockResolvedValue(true);
+            const page = await app.inject('/campaigns/unsubscribe/browser?token=signed');
+            expect(page.statusCode).toBe(200);
+            expect(page.headers['content-type']).toContain('text/html');
+            expect(page.headers['cache-control']).toBe('no-store');
+            expect(page.headers['referrer-policy']).toBe('no-referrer');
+            expect(page.headers['content-security-policy']).toContain("form-action 'self'");
+            expect(page.body).toContain('action="/campaigns/unsubscribe/browser"');
+            expect(page.body).toContain('name="token" value="signed"');
+            expect(page.body).toContain('Unsubscribe</button>');
+            expect(unsubscribe).not.toHaveBeenCalled();
+            const submitted = await app.inject({
+                method: 'POST',
+                url: '/campaigns/unsubscribe/browser',
+                headers: { 'content-type': 'application/x-www-form-urlencoded' },
+                payload: 'token=signed',
+            });
+            expect(submitted.statusCode).toBe(200);
+            expect(submitted.body).toContain('You’re unsubscribed');
+            expect(submitted.body).not.toContain('signed');
+            expect(unsubscribe).toHaveBeenCalledExactlyOnceWith('signed');
+        } finally {
+            await app.close();
+        }
+    });
+
+    it('renders invalid and transient errors without leaking provider errors or unsafe markup', async () => {
+        const app = Fastify();
+        await app.register(campaignUnsubscribeFastifyPlugin);
+        try {
+            const attack = await app.inject(
+                '/campaigns/unsubscribe/browser?token=%22%3E%3Cscript%3E'
+            );
+            expect(attack.statusCode).toBe(400);
+            expect(attack.body).not.toContain('<script>');
+            expect(unsubscribe).not.toHaveBeenCalled();
+            for (const error of [
+                new TRPCError({ code: 'BAD_REQUEST' }),
+                new Error('private details'),
+            ]) {
+                unsubscribe.mockRejectedValueOnce(error);
+                const response = await app.inject({
+                    method: 'POST',
+                    url: '/campaigns/unsubscribe/browser',
+                    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+                    payload: 'token=signed',
+                });
+                expect(response.statusCode).toBe(error instanceof TRPCError ? 400 : 503);
+                expect(response.body).toContain('role="alert"');
+                expect(response.body).not.toContain('private details');
+                expect(response.body.includes('Try Again')).toBe(!(error instanceof TRPCError));
+            }
+        } finally {
+            await app.close();
+        }
+    });
+
+    it('handles actual form POSTs without auth and does not mutate on GET', async () => {
+        const app = Fastify();
+        await app.register(campaignUnsubscribeFastifyPlugin);
+        try {
+            unsubscribe.mockResolvedValue(true);
+            const response = await app.inject({
+                method: 'POST',
+                url: '/campaigns/unsubscribe?token=signed',
+                headers: { 'content-type': 'application/x-www-form-urlencoded' },
+                payload: 'List-Unsubscribe=One-Click',
+            });
+            expect(response.statusCode).toBe(200);
+            expect(response.headers['cache-control']).toBe('no-store');
+            expect(unsubscribe).toHaveBeenCalledWith('signed');
+            unsubscribe.mockClear();
+            expect(
+                (await app.inject({ method: 'GET', url: '/campaigns/unsubscribe?token=signed' }))
+                    .statusCode
+            ).toBe(404);
+            expect(
+                (
+                    await app.inject({
+                        method: 'POST',
+                        url: '/campaigns/unsubscribe?token=signed',
+                        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+                        payload: 'other=value',
+                    })
+                ).statusCode
+            ).toBe(400);
+            expect(unsubscribe).not.toHaveBeenCalled();
+            unsubscribe.mockRejectedValue(new TRPCError({ code: 'BAD_REQUEST' }));
+            expect(
+                (
+                    await app.inject({
+                        method: 'POST',
+                        url: '/campaigns/unsubscribe?token=tampered',
+                        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+                        payload: 'List-Unsubscribe=One-Click',
+                    })
+                ).statusCode
+            ).toBe(400);
+        } finally {
+            await app.close();
+        }
+    });
+});

package/src/campaign-unsubscribe.ts

@@ -0,0 +1,86 @@
+import Fastify, { type FastifyPluginAsync } from 'fastify';
+import { TRPCError } from '@trpc/server';
+import { unsubscribeFromCampaignEmails } from '@helpers/campaign-unsubscribe.helpers';
+import { renderCampaignUnsubscribePage } from '@helpers/campaign-unsubscribe-page';
+
+/** RFC 8058 endpoint: form POSTs work without cookies, redirects, or a JavaScript client. */
+export const campaignUnsubscribeFastifyPlugin: FastifyPluginAsync = async app => {
+    app.addContentTypeParser(
+        'application/x-www-form-urlencoded',
+        { parseAs: 'string', bodyLimit: 1024 },
+        (_request, body, done) => {
+            done(null, new URLSearchParams(String(body)));
+        }
+    );
+    app.route<{ Querystring: { token?: string } }>({
+        method: ['GET', 'POST'],
+        url: '/campaigns/unsubscribe/browser',
+        bodyLimit: 4096,
+        logLevel: 'silent',
+        handler: async (request, reply) => {
+            const language = request.headers['accept-language'];
+            reply
+                .type('text/html; charset=utf-8')
+                .header('Cache-Control', 'no-store')
+                .header('Referrer-Policy', 'no-referrer')
+                .header('X-Content-Type-Options', 'nosniff')
+                .header(
+                    'Content-Security-Policy',
+                    "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'"
+                );
+            const token =
+                request.method === 'GET'
+                    ? request.query.token
+                    : request.body instanceof URLSearchParams
+                      ? request.body.get('token')
+                      : undefined;
+            if (typeof token !== 'string' || !/^[A-Za-z0-9_-]{1,2048}$/.test(token))
+                return reply
+                    .code(400)
+                    .send(renderCampaignUnsubscribePage('invalid', undefined, language));
+            if (request.method === 'GET')
+                return reply.send(renderCampaignUnsubscribePage('confirm', token, language));
+            try {
+                await unsubscribeFromCampaignEmails(token);
+                return reply.send(renderCampaignUnsubscribePage('success', undefined, language));
+            } catch (error) {
+                const invalid = error instanceof TRPCError && error.code === 'BAD_REQUEST';
+                return reply
+                    .code(invalid ? 400 : 503)
+                    .send(
+                        renderCampaignUnsubscribePage(
+                            invalid ? 'invalid' : 'error',
+                            invalid ? undefined : token,
+                            language
+                        )
+                    );
+            }
+        },
+    });
+    app.post<{ Querystring: { token?: string } }>(
+        '/campaigns/unsubscribe',
+        { bodyLimit: 1024, logLevel: 'silent' },
+        async (request, reply) => {
+            reply.header('Cache-Control', 'no-store').header('Referrer-Policy', 'no-referrer');
+            if (
+                !(request.body instanceof URLSearchParams) ||
+                request.body.get('List-Unsubscribe') !== 'One-Click' ||
+                typeof request.query.token !== 'string'
+            ) {
+                return reply.code(400).send({ success: false });
+            }
+            try {
+                await unsubscribeFromCampaignEmails(request.query.token);
+                return reply.send({ success: true });
+            } catch (error) {
+                return reply
+                    .code(error instanceof TRPCError && error.code === 'BAD_REQUEST' ? 400 : 503)
+                    .send({ success: false });
+            }
+        }
+    );
+};
+
+export const app = Fastify({ logger: false, bodyLimit: 1024 });
+app.register(campaignUnsubscribeFastifyPlugin);
+export default app;

package/src/config/environment.test.ts

@@ -21,6 +21,29 @@ const REQUIRED_ENVIRONMENT = {
 };
 
 describe('credential refresh configuration', () => {
+    it.each(['invalid-json', '[]', 'null', '{"v1":123}'])(
+        'rejects invalid previous digest keys at startup: %s',
+        value => {
+            expect(() =>
+                parseBrainServiceEnvironment({
+                    ...REQUIRED_ENVIRONMENT,
+                    NODE_ENV: 'test',
+                    CREDENTIAL_REFRESH_DIGEST_PREVIOUS_KEYS: value,
+                })
+            ).toThrow(/Must be a JSON object mapping digest versions to string keys/);
+        }
+    );
+
+    it('transforms previous digest keys into a typed record at startup', () => {
+        expect(
+            parseBrainServiceEnvironment({
+                ...REQUIRED_ENVIRONMENT,
+                NODE_ENV: 'test',
+                CREDENTIAL_REFRESH_DIGEST_PREVIOUS_KEYS: '{"v1":"previous-test-key"}',
+            }).CREDENTIAL_REFRESH_DIGEST_PREVIOUS_KEYS
+        ).toEqual({ v1: 'previous-test-key' });
+    });
+
     it('parses typed defaults and explicit runtime values at call time', () => {
         const previousEnabled = process.env.CREDENTIAL_REFRESH_ENABLED;
         const previousSecret = process.env.CREDENTIAL_REFRESH_DIGEST_SECRET;
@@ -311,3 +334,32 @@ describe('LC-2206 skill embedding configuration', () => {
         }
     );
 });
+
+describe('campaign dispatch configuration', () => {
+    it('defaults to 1000 recipients and 60 seconds, accepting an explicit zero delay', () => {
+        expect(
+            parseBrainServiceEnvironment({ ...REQUIRED_ENVIRONMENT, NODE_ENV: 'test' })
+        ).toMatchObject({
+            CAMPAIGN_DISPATCH_PAGE_SIZE: 1000,
+            CAMPAIGN_DISPATCH_DELAY_SECONDS: 60,
+        });
+        expect(
+            parseBrainServiceEnvironment({
+                ...REQUIRED_ENVIRONMENT,
+                NODE_ENV: 'test',
+                CAMPAIGN_DISPATCH_PAGE_SIZE: '25',
+                CAMPAIGN_DISPATCH_DELAY_SECONDS: '0',
+            })
+        ).toMatchObject({ CAMPAIGN_DISPATCH_PAGE_SIZE: 25, CAMPAIGN_DISPATCH_DELAY_SECONDS: 0 });
+    });
+    it.each([
+        { CAMPAIGN_DISPATCH_PAGE_SIZE: '0' },
+        { CAMPAIGN_DISPATCH_PAGE_SIZE: '1001' },
+        { CAMPAIGN_DISPATCH_DELAY_SECONDS: '901' },
+        { CAMPAIGN_DISPATCH_DELAY_SECONDS: '-1' },
+    ])('rejects unsupported queue settings %j', settings => {
+        expect(() =>
+            parseBrainServiceEnvironment({ ...REQUIRED_ENVIRONMENT, NODE_ENV: 'test', ...settings })
+        ).toThrow();
+    });
+});

package/src/config/environment.ts

@@ -31,6 +31,31 @@ const credentialRefreshNotificationWindowHours = z.preprocess(
     z.coerce.number().finite().positive().default(24)
 );
 
+const credentialRefreshPreviousDigestKeys = z
+    .string()
+    .default('{}')
+    .transform((value, context) => {
+        let parsed: unknown;
+        try {
+            parsed = JSON.parse(value);
+        } catch {
+            context.addIssue({
+                code: 'custom',
+                message: 'Must be a JSON object mapping digest versions to string keys',
+            });
+            return z.NEVER;
+        }
+        const result = z.record(z.string(), z.string()).safeParse(parsed);
+        if (!result.success) {
+            context.addIssue({
+                code: 'custom',
+                message: 'Must be a JSON object mapping digest versions to string keys',
+            });
+            return z.NEVER;
+        }
+        return result.data;
+    });
+
 export const brainServiceEnvironmentShape = {
     NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
     PORT: environmentPort.default(3000),
@@ -45,6 +70,22 @@ export const brainServiceEnvironmentShape = {
     SIGNING_AUTHORITY_ENDPOINT: optionalEnvironmentUrl,
     APP_STORE_ADMIN_PROFILE_IDS: optionalEnvironmentString,
     CAMPAIGN_ADMIN_PROFILE_IDS: optionalEnvironmentString,
+    CAMPAIGN_QUEUE_URL: optionalEnvironmentUrl,
+    CAMPAIGN_UNSUBSCRIBE_SECRET: optionalEnvironmentString,
+    CAMPAIGN_APP_ORIGINS: optionalEnvironmentString,
+    POSTMARK_BROADCAST_STREAM: z.string().trim().min(1).default('broadcast'),
+    CAMPAIGN_EMAIL_PAGE_SIZE: z.preprocess(
+        value => (value === '' ? undefined : value),
+        z.coerce.number().int().min(1).max(1000).default(500)
+    ),
+    CAMPAIGN_DISPATCH_PAGE_SIZE: z.preprocess(
+        value => (value === '' ? undefined : value),
+        z.coerce.number().int().min(1).max(1000).default(1000)
+    ),
+    CAMPAIGN_DISPATCH_DELAY_SECONDS: z.preprocess(
+        value => (value === '' ? undefined : value),
+        z.coerce.number().int().min(0).max(900).default(60)
+    ),
     SKILL_FRAMEWORK_ADMIN_PROFILE_IDS: optionalEnvironmentString,
     SKILL_FRAMEWORK_SEED_OWNER_PROFILE_ID: optionalEnvironmentString,
     TRUSTED_BRAIN_SERVICES: optionalEnvironmentString,
@@ -111,6 +152,7 @@ export const brainServiceEnvironmentShape = {
     SKILL_SEMANTIC_SEARCH_RATE_LIMIT_PER_MIN: optionalEnvironmentPort,
     BITSTRING_STATUS_LIST_SIZE: optionalEnvironmentPort,
     CREDENTIAL_REFRESH_DIGEST_SECRET: optionalEnvironmentString,
+    CREDENTIAL_REFRESH_DIGEST_PREVIOUS_KEYS: credentialRefreshPreviousDigestKeys,
     SHARE_LINK_REQUEST_HASH_SECRET: optionalEnvironmentString,
     CREDENTIAL_REFRESH_ENABLED: optionalEnvironmentBoolean.default(false),
     CREDENTIAL_REFRESH_NOTIFICATION_WINDOW_HOURS: credentialRefreshNotificationWindowHours,
@@ -334,6 +376,10 @@ export const getNotificationRuntimeEnvironment = (): NotificationRuntimeEnvironm
 
 const credentialRefreshRuntimeEnvironmentSchema = z
     .object({
+        CREDENTIAL_REFRESH_DIGEST_KEY_VERSION: z
+            .string()
+            .regex(/^[A-Za-z0-9_-]+$/)
+            .default('v1'),
         NODE_ENV: brainServiceEnvironmentShape.NODE_ENV,
         DOMAIN_NAME: brainServiceEnvironmentShape.DOMAIN_NAME,
         CREDENTIAL_REFRESH_DIGEST_SECRET:
@@ -360,6 +406,18 @@ export type CredentialRefreshRuntimeEnvironment = z.output<
     typeof credentialRefreshRuntimeEnvironmentSchema
 >;
 
+/** Previous keys are startup-validated and only read again when matching an older digest. */
+export const getCredentialRefreshPreviousDigestKeys = (): Record<string, string> =>
+    parseEnvironment(
+        z.object({ CREDENTIAL_REFRESH_DIGEST_PREVIOUS_KEYS: credentialRefreshPreviousDigestKeys }),
+        process.env,
+        {
+            project: 'brain-service credential refresh',
+            source: 'process environment',
+            examplePath: 'services/learn-card-network/brain-service/.env.example',
+        }
+    ).CREDENTIAL_REFRESH_DIGEST_PREVIOUS_KEYS;
+
 /** Reads refresh settings at call time so tests and local route registration can override them. */
 export const getCredentialRefreshRuntimeEnvironment = (): CredentialRefreshRuntimeEnvironment =>
     parseEnvironment(credentialRefreshRuntimeEnvironmentSchema, process.env, {

package/src/config/serverlessFunctionEnv.test.ts

@@ -1,7 +1,9 @@
 import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 const require = createRequire(import.meta.url);
+const { load } = require('js-yaml');
 const functions: {
     provider: (input?: {
         options?: Record<string, unknown>;
@@ -16,12 +18,15 @@ const INFRA_KEYS = {
     REDIS_PORT: { 'Fn::GetAtt': ['ElasticCacheCluster', 'RedisEndpoint.Port'] },
     NOTIFICATIONS_QUEUE_URL: '${construct:notifications-queue.queueUrl}',
     INBOX_QUEUE_URL: '${construct:inbox-queue.queueUrl}',
+    CAMPAIGN_QUEUE_URL: '${construct:campaign-queue.queueUrl}',
 };
 
 beforeEach(() => {
     vi.stubEnv('RUNTIME_SECRETS_ID', '');
     vi.stubEnv('GIT_SHA', '');
     vi.stubEnv('SEED', 'seed');
+    vi.stubEnv('CAMPAIGN_UNSUBSCRIBE_SECRET', 'synthetic-campaign-unsubscribe-secret');
+    vi.stubEnv('POSTMARK_BROADCAST_STREAM', 'deploy-time-stream');
     vi.stubEnv('NEO4J_PASSWORD', 'neo4j-password');
     vi.stubEnv('SHARE_LINK_REQUEST_HASH_SECRET', 'hash-secret');
     vi.stubEnv('SENTRY_AUTH_TOKEN', 'build-token');
@@ -30,6 +35,58 @@ beforeEach(() => {
 afterEach(() => vi.unstubAllEnvs());
 
 describe('brain-service serverless provider environment', () => {
+    it('routes the shared notifications worker through NAT to the internet', () => {
+        const service = load(
+            readFileSync(new URL('../../serverless.yml', import.meta.url), 'utf8')
+        );
+        const resources = service.resources.Resources;
+        const properties = (name: string) => resources[name].Properties;
+
+        // All notifications use this worker, including third-party profile webhooks.
+        expect(service.constructs['notifications-queue'].worker.vpc).toEqual({
+            securityGroupIds: [{ 'Fn::GetAtt': ['ServerlessSecurityGroup', 'GroupId'] }],
+            subnetIds: [{ Ref: 'PrivateSubnetA' }],
+        });
+        expect(properties('SubnetRouteTableAssociationLambdaPrivateA')).toEqual({
+            SubnetId: { Ref: 'PrivateSubnetA' },
+            RouteTableId: { Ref: 'PrivateRouteTable' },
+        });
+        expect(properties('PrivateRoute')).toEqual({
+            RouteTableId: { Ref: 'PrivateRouteTable' },
+            DestinationCidrBlock: '0.0.0.0/0',
+            NatGatewayId: { Ref: 'NatGateway' },
+        });
+        expect(properties('NatGateway')).toEqual({
+            AllocationId: { 'Fn::GetAtt': ['IP', 'AllocationId'] },
+            SubnetId: { Ref: 'PublicSubnetA' },
+        });
+        expect(properties('IP').Domain).toBe('vpc');
+        expect(properties('SubnetRouteTableAssociationLambdaPublicA')).toEqual({
+            SubnetId: { Ref: 'PublicSubnetA' },
+            RouteTableId: { Ref: 'PublicRouteTable' },
+        });
+        expect(properties('PublicRoute')).toEqual({
+            RouteTableId: { Ref: 'PublicRouteTable' },
+            DestinationCidrBlock: '0.0.0.0/0',
+            GatewayId: { Ref: 'InternetGateway' },
+        });
+        expect(properties('VPCGatewayAttachment')).toEqual({
+            VpcId: { Ref: 'VPC' },
+            InternetGatewayId: { Ref: 'InternetGateway' },
+        });
+        for (const name of [
+            'PrivateSubnetA',
+            'PublicSubnetA',
+            'PrivateRouteTable',
+            'PublicRouteTable',
+            'ServerlessSecurityGroup',
+        ]) {
+            expect(properties(name).VpcId).toEqual({ Ref: 'VPC' });
+        }
+        // With no explicit egress rules, AWS supplies the default allow-all outbound rule.
+        expect(properties('ServerlessSecurityGroup')).not.toHaveProperty('SecurityGroupEgress');
+    });
+
     it('always emits Redis and queue infrastructure as unresolved references', () => {
         expect(functions.provider({ options: { stage: 'dev' } })).toMatchObject(INFRA_KEYS);
     });
@@ -60,6 +117,8 @@ describe('brain-service serverless provider environment', () => {
             RUNTIME_SECRETS_ID: 'brain-service/dev/runtime-secrets',
         });
         expect(result).not.toHaveProperty('SEED');
+        expect(result).not.toHaveProperty('CAMPAIGN_UNSUBSCRIBE_SECRET');
+        expect(result).not.toHaveProperty('POSTMARK_BROADCAST_STREAM');
         expect(result).not.toHaveProperty('NEO4J_PASSWORD');
         expect(result).not.toHaveProperty('SHARE_LINK_REQUEST_HASH_SECRET');
     });

package/src/credential-refresh.ts

@@ -369,6 +369,7 @@ export const credentialRefreshFastifyPlugin: FastifyPluginAsync<
                         ...(record.etag ? { etag: record.etag } : {}),
                         ...(record.signingMode ? { signingMode: record.signingMode } : {}),
                         ...(record.updateSummary ? { updateSummary: record.updateSummary } : {}),
+                        ...(record.updateReason ? { updateReason: record.updateReason } : {}),
                     })),
                     hasMore,
                     ...(nextCursor ? { cursor: nextCursor } : {}),

package/src/docker-entry.ts

@@ -1,6 +1,7 @@
 import './config/applyDockerStageConfig';
 
 import { dispatchContractEvents } from '@helpers/contract-events.helpers';
+import { suspendExpiredConsentFlowTerms } from '@helpers/consentflow-deadline.helpers';
 import { configureInboxBatchBodyLimit } from '@helpers/inbox-batch-http.helpers';
 import { environment } from '@environment';
 import Fastify from 'fastify';
@@ -16,6 +17,7 @@ import {
     DeleteMessageCommand,
 } from '@aws-sdk/client-sqs';
 
+import { migrateLegacyConsentFlowContracts } from '@helpers/consentflow-legacy-migration.helpers';
 import { neogma } from '@instance';
 import { appRouter, type AppRouter, createContext } from './app';
 import { publicShareLinkCacheControlHeaders } from './routes';
@@ -25,6 +27,7 @@ import { inboxBatchResponseMeta } from './helpers/inbox-batch-http.helpers';
 import { didFastifyPlugin } from './dids';
 import { skillsViewerFastifyPlugin } from './skills-viewer';
 import { statusListsFastifyPlugin } from './status-lists';
+import { campaignUnsubscribeFastifyPlugin } from './campaign-unsubscribe';
 import { credentialRefreshFastifyPlugin } from './credential-refresh';
 import { deliverQueuedNotification } from '@helpers/notificationQueue.helpers';
 import { startSkillEmbeddingBackfill } from '@helpers/skill-embedding.helpers';
@@ -47,6 +50,9 @@ let shareLinkMaintenanceScheduler: ShareLinkMaintenanceScheduler | null = null;
 let contractEventTimer: ReturnType<typeof setTimeout> | null = null;
 let contractEventPass: Promise<unknown> | null = null;
 let contractEventsStopped = false;
+let consentDeadlineTimer: NodeJS.Timeout | undefined;
+let consentDeadlinePass: Promise<unknown> | null = null;
+let consentDeadlineStopped = false;
 
 const runContractEventPass = (): void => {
     if (contractEventsStopped) return;
@@ -60,12 +66,27 @@ const runContractEventPass = (): void => {
                 contractEventTimer = setTimeout(runContractEventPass, 60_000);
         });
 };
+const runConsentDeadlinePass = (): void => {
+    if (consentDeadlineStopped) return;
+    consentDeadlinePass = suspendExpiredConsentFlowTerms()
+        .catch(() => {
+            console.warn('consent_deadline: recovery_pending');
+        })
+        .finally(() => {
+            consentDeadlinePass = null;
+            if (!consentDeadlineStopped)
+                consentDeadlineTimer = setTimeout(runConsentDeadlinePass, 60_000);
+        });
+};
 
 server.addHook('onClose', async () => {
     contractEventsStopped = true;
     if (contractEventTimer) clearTimeout(contractEventTimer);
     await contractEventPass;
     await shareLinkMaintenanceScheduler?.stop();
+    consentDeadlineStopped = true;
+    clearTimeout(consentDeadlineTimer);
+    await consentDeadlinePass;
 });
 // Register before either OpenAPI or tRPC registers its wildcard route. The hook raises the
 // parser ceiling for those shared routes, then narrows it back to 4 MiB only for batch issuance.
@@ -169,10 +190,13 @@ server.register(didFastifyPlugin);
 server.register(skillsViewerFastifyPlugin);
 server.register(statusListsFastifyPlugin);
 server.register(credentialRefreshFastifyPlugin);
+server.register(campaignUnsubscribeFastifyPlugin);
 
 (async () => {
     try {
-        console.log('Server starting on port ', environment.PORT || 3000);
+        // Complete the idempotent legacy backfill before accepting traffic. Every
+        // replica can safely run it; Neo4j node locks serialize first-time writes.
+        await migrateLegacyConsentFlowContracts();
         await server.listen({ host: '0.0.0.0', port: Number(environment.PORT || 3000) });
 
         try {
@@ -190,6 +214,7 @@ server.register(credentialRefreshFastifyPlugin);
         }
 
         contractEventTimer = setTimeout(runContractEventPass, 60_000);
+        consentDeadlineTimer = setTimeout(runConsentDeadlinePass, 60_000);
 
         // Explicit startup after readiness. Disabled/invalid config stays inert.
         const maintenanceRuntime = createShareLinkMaintenanceRuntime();