@learncard/network-brain-service 4.1.3 → 5.0.0

package/src/helpers/managed-status.helpers.ts

@@ -0,0 +1,147 @@
+import { TRPCError } from '@trpc/server';
+import type { Transaction } from 'neo4j-driver';
+import { BitstringStatusListEntryValidator, type BitstringStatusListEntry } from '@learncard/types';
+import { getBitstringStatusListEntries } from '@learncard/helpers';
+
+import { neogma } from '@instance';
+import {
+    allocateStatusListEntry,
+    isNetworkStatusEntry,
+    validateStatusEntries,
+} from './status-list.helpers';
+import { getCredentialRefresh } from '@accesslayer/credential-refresh';
+import { reconcileCredentialStatus } from './credential-status-mutation.helpers';
+
+export const prepareRefreshStatusEntries = async (
+    refreshId: string,
+    ownerProfileId: string,
+    domain: string,
+    purposes: ('revocation' | 'suspension')[] = []
+): Promise<BitstringStatusListEntry[]> => {
+    const refresh = await getCredentialRefresh(refreshId);
+    if (refresh?.statusEntries)
+        return BitstringStatusListEntryValidator.array().parse(JSON.parse(refresh.statusEntries));
+    const entries = await Promise.all(
+        [...new Set(['revocation' as const, ...purposes])].map(purpose =>
+            allocateStatusListEntry(ownerProfileId, domain, purpose)
+        )
+    );
+    await bindRefreshStatusEntries(refreshId, entries, ownerProfileId, domain, undefined, {
+        freshlyAllocated: true,
+    });
+    return entries;
+};
+
+const coordinates = (entries: BitstringStatusListEntry[]): string =>
+    JSON.stringify(
+        entries
+            .map(entry => [entry.statusListCredential, entry.statusListIndex, entry.statusPurpose])
+            .sort()
+    );
+
+/** Bind public coordinates under list locks; an index can belong to only one refresh. */
+export const bindRefreshStatusEntries = async (
+    refreshId: string,
+    entries: BitstringStatusListEntry[],
+    ownerProfileId: string,
+    domain: string,
+    transaction?: Transaction,
+    options: { freshlyAllocated?: boolean } = {}
+): Promise<void> => {
+    await validateStatusEntries(entries, ownerProfileId, domain);
+    await neogma.getTransaction(transaction ?? null, async tx => {
+        const result = await tx.run(
+            `MATCH (refresh:CredentialRefresh {refreshId: $refreshId, issuerProfileId: $ownerProfileId})
+             OPTIONAL MATCH (refresh)-[:ROOT]->(root:Credential)
+             FOREACH (_ IN CASE WHEN root IS NULL THEN [] ELSE [1] END |
+                 SET root._statusMutationLock = true REMOVE root._statusMutationLock)
+             SET refresh._statusBindingLock = true
+             REMOVE refresh._statusBindingLock
+             RETURN refresh.statusEntries AS entries, root.id AS rootId`,
+            { refreshId, ownerProfileId }
+        );
+        const row = result.records[0];
+        if (!row)
+            throw new TRPCError({ code: 'NOT_FOUND', message: 'Credential refresh not found' });
+        const stored: unknown = row.get('entries');
+        if (typeof stored === 'string') {
+            if (
+                coordinates(BitstringStatusListEntryValidator.array().parse(JSON.parse(stored))) !==
+                coordinates(entries)
+            ) {
+                throw new TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: 'Credential status does not match allocated entries',
+                });
+            }
+            return;
+        }
+        // A stable order prevents deadlocks when a credential has multiple lists.
+        for (const entry of [...entries].sort((a, b) =>
+            a.statusListCredential.localeCompare(b.statusListCredential)
+        )) {
+            if (!isNetworkStatusEntry(entry, domain)) continue;
+            const binding = await tx.run(
+                `MATCH (list:BitstringStatusList {statusListCredential: $url})
+                 SET list._statusBindingLock = true
+                 REMOVE list._statusBindingLock
+                 WITH list
+                 OPTIONAL MATCH (list)-[:HAS_STATUS_BINDING]->(binding:CredentialStatusBinding {index: $index})
+                 RETURN binding.refreshId AS refreshId, binding.credentialId AS credentialId`,
+                { url: entry.statusListCredential, index: String(entry.statusListIndex) }
+            );
+            const bound: unknown = binding.records[0]?.get('refreshId');
+            if ((bound && bound !== refreshId) || binding.records[0]?.get('credentialId')) {
+                throw new TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: 'Status list index is already bound to another credential',
+                });
+            }
+            // Legacy ordinary deliveries predate index bindings. Do not let a repair
+            // or low-level managed send take over one of their signed coordinates.
+            const legacy = options.freshlyAllocated
+                ? { records: [] }
+                : await tx.run(
+                      `MATCH (:Profile {profileId: $ownerProfileId})-[:CREDENTIAL_SENT]->(credential:Credential)
+                 WHERE coalesce(credential.refreshId, '') <> $refreshId
+                   AND (credential.statusEntries CONTAINS $url OR credential.credential CONTAINS $url)
+                 RETURN credential.statusEntries AS entries, credential.credential AS body`,
+                      { ownerProfileId, refreshId, url: entry.statusListCredential }
+                  );
+            for (const legacyRow of legacy.records) {
+                const rawEntries: unknown = legacyRow.get('entries');
+                const body: unknown = legacyRow.get('body');
+                const existing: BitstringStatusListEntry[] =
+                    typeof rawEntries === 'string'
+                        ? BitstringStatusListEntryValidator.array().parse(JSON.parse(rawEntries))
+                        : typeof body === 'string'
+                          ? getBitstringStatusListEntries(JSON.parse(body))
+                          : [];
+                if (
+                    existing.some(
+                        candidate =>
+                            candidate.statusListCredential === entry.statusListCredential &&
+                            Number(candidate.statusListIndex) === Number(entry.statusListIndex)
+                    )
+                ) {
+                    throw new TRPCError({
+                        code: 'BAD_REQUEST',
+                        message: 'Status list index is already bound to another credential',
+                    });
+                }
+            }
+            await tx.run(
+                `MATCH (list:BitstringStatusList {statusListCredential: $url})
+                 MERGE (list)-[:HAS_STATUS_BINDING]->(binding:CredentialStatusBinding {index: $index})
+                 SET binding.refreshId = $refreshId`,
+                { url: entry.statusListCredential, index: String(entry.statusListIndex), refreshId }
+            );
+        }
+        await tx.run(
+            `MATCH (refresh:CredentialRefresh {refreshId: $refreshId}) SET refresh.statusEntries = $entries`,
+            { refreshId, entries: JSON.stringify(entries) }
+        );
+        const rootId: unknown = row.get('rootId');
+        if (typeof rootId === 'string') await reconcileCredentialStatus(rootId, tx);
+    });
+};

package/src/helpers/notification-delivery-boundary.helpers.test.ts

@@ -0,0 +1,114 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { Campaign } from '@learncard/types';
+
+const mocks = vi.hoisted(() => ({
+    fetch: vi.fn(),
+    acknowledge: vi.fn(),
+    getCampaign: vi.fn(),
+    recipient: vi.fn(),
+    environment: {
+        NODE_ENV: 'test',
+        IS_OFFLINE: false,
+        DOMAIN_NAME: 'brain.example',
+        NOTIFICATIONS_SERVICE_WEBHOOK_URL: 'https://inbox.example/notifications',
+    },
+}));
+
+vi.mock('@environment', () => ({
+    environment: mocks.environment,
+    getNotificationRuntimeEnvironment: () => mocks.environment,
+}));
+vi.mock('@helpers/learnCard.helpers', () => ({
+    getDidWebLearnCard: async () => ({
+        id: { did: () => 'did:web:brain.example' },
+        invoke: { getDidAuthVp: async () => 'test-jwt' },
+    }),
+}));
+vi.mock('@helpers/did.helpers', () => ({
+    getDidWeb: (domain: string, profileId: string) => `did:web:${domain}:users:${profileId}`,
+}));
+vi.mock('@accesslayer/inbox-credential/relationships/create', () => ({
+    createWebhookSentRelationship: vi.fn(),
+}));
+vi.mock('@cache', () => ({ default: {} }));
+// These suites exercise notification delivery without email transport or a database.
+vi.mock('@helpers/campaign-email.helpers', () => ({ sendCampaignEmail: vi.fn() }));
+vi.mock('@accesslayer/campaign/preferences', () => ({
+    getAnnouncementPreferences: async () => ({
+        announcementEmailOptOut: false,
+        announcementPushOptOut: false,
+    }),
+}));
+vi.mock('@accesslayer/campaign/read', () => ({ getCampaign: mocks.getCampaign }));
+vi.mock('@accesslayer/campaign/test', () => ({ queueCampaignInAppTest: vi.fn() }));
+vi.mock('@accesslayer/campaign/delivery', () => ({
+    getCampaignDeliveryRecipient: mocks.recipient,
+    acknowledgeCampaignNotification: mocks.acknowledge,
+}));
+vi.mock('@helpers/contract-events.helpers', () => ({
+    authorizeContractNotification: async () => true,
+}));
+vi.mock('@helpers/connectionPrompt.helpers', () => ({
+    acknowledgeConnectionPromptNotificationDelivery: vi.fn(),
+}));
+
+import { buildCampaignNotification } from './campaign-notifications.helpers';
+import { sendNotification } from './notifications.helpers';
+import { deliverQueuedNotification } from './notificationQueue.helpers';
+
+const campaign = {
+    id: 'webhook-pilot',
+    createdAt: '2026-01-01T00:00:00Z',
+    status: 'live',
+    channels: ['notify'],
+    notification: { title: 'Explore', body: 'Find your next step' },
+} as Campaign;
+const recipient = {
+    profileId: 'learner',
+    did: 'did:web:brain.example:users:learner',
+    notificationsWebhook: 'https://receiver.example/notifications',
+};
+
+beforeEach(() => {
+    vi.resetAllMocks();
+    vi.stubGlobal('fetch', mocks.fetch);
+    mocks.environment.NOTIFICATIONS_SERVICE_WEBHOOK_URL = 'https://inbox.example/notifications';
+    mocks.getCampaign.mockResolvedValue(campaign);
+    mocks.recipient.mockResolvedValue(recipient);
+});
+
+describe('shared notification delivery boundary', () => {
+    it.each(['ANNOUNCEMENT', 'BOOST_ACCEPTED'] as const)(
+        'blocks a private profile webhook for %s before POST or acknowledgement',
+        async type => {
+            const notification = await buildCampaignNotification(campaign, recipient);
+            notification.type = type;
+            notification.to.notificationsWebhook = 'http://10.0.1.10/internal';
+
+            await expect(
+                sendNotification(notification, {
+                    propagateDirectWebhookTransportErrors: true,
+                })
+            ).rejects.toThrow('public HTTP(S) destination');
+            expect(mocks.fetch).not.toHaveBeenCalled();
+            expect(mocks.acknowledge).not.toHaveBeenCalled();
+        }
+    );
+
+    it('does not trust an explicit queued webhook override', async () => {
+        const notification = await buildCampaignNotification(campaign, recipient);
+        notification.webhookUrl = 'http://169.254.169.254/latest/meta-data/';
+        await expect(deliverQueuedNotification(JSON.stringify(notification))).rejects.toThrow();
+        expect(mocks.fetch).not.toHaveBeenCalled();
+        expect(mocks.acknowledge).not.toHaveBeenCalled();
+    });
+
+    it('also guards the configured default destination', async () => {
+        const notification = await buildCampaignNotification(campaign, recipient);
+        delete notification.to.notificationsWebhook;
+        mocks.environment.NOTIFICATIONS_SERVICE_WEBHOOK_URL = 'http://[::1]/internal';
+        await expect(sendNotification(notification)).resolves.toBe(false);
+        expect(mocks.fetch).not.toHaveBeenCalled();
+    });
+});
+afterEach(() => vi.unstubAllGlobals());

package/src/helpers/notification-webhook-fetch.helpers.test.ts

@@ -0,0 +1,228 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { LookupAddress } from 'node:dns';
+import { EventEmitter } from 'node:events';
+import { PassThrough } from 'node:stream';
+import type { RequestOptions } from 'node:https';
+
+const mocks = vi.hoisted(() => ({ lookup: vi.fn(), request: vi.fn() }));
+vi.mock('node:dns', () => ({ lookup: mocks.lookup }));
+vi.mock('node:http', () => ({ request: mocks.request }));
+vi.mock('node:https', () => ({ request: mocks.request }));
+
+import {
+    fetchNotificationWebhook,
+    isPublicNotificationAddress,
+} from './notification-webhook-fetch.helpers';
+
+const request = (): Parameters<typeof fetchNotificationWebhook>[1] => ({
+    method: 'POST',
+    headers: { Authorization: 'Bearer synthetic', 'Content-Type': 'application/json' },
+    body: '{"type":"ANNOUNCEMENT"}',
+    signal: AbortSignal.timeout(1000),
+});
+const resolve = (addresses: LookupAddress[]): void => {
+    mocks.lookup.mockImplementation((_host, _options, callback) => callback(null, addresses));
+};
+const respond = (status = 200, body = '{"sent":true}'): void => {
+    mocks.request.mockImplementation((_options, callback) => {
+        const outgoing = new EventEmitter() as EventEmitter & { end: (body: string) => void };
+        outgoing.end = () => {
+            const response = Object.assign(new PassThrough(), {
+                statusCode: status,
+                headers: { location: 'http://127.0.0.1/private' },
+            });
+            callback(response);
+            response.end(body);
+        };
+        return outgoing;
+    });
+};
+beforeEach(() => {
+    vi.resetAllMocks();
+    respond();
+});
+afterEach(() => vi.unstubAllGlobals());
+
+describe('notification destination boundary', () => {
+    it.each([
+        '0.0.0.0',
+        '10.0.0.1',
+        '100.64.0.1',
+        '127.0.0.1',
+        '169.254.169.254',
+        '172.16.0.1',
+        '192.0.0.1',
+        '192.0.2.1',
+        '192.88.99.1',
+        '192.168.1.1',
+        '198.18.0.1',
+        '198.51.100.1',
+        '203.0.113.1',
+        '224.0.0.1',
+        '255.255.255.255',
+        '::',
+        '::1',
+        'fc00::1',
+        'fe80::1',
+        'ff02::1',
+        '::ffff:127.0.0.1',
+        '::ffff:8.8.8.8',
+        '64:ff9b::a00:1',
+        '2001::1',
+        '2001:db8::1',
+        '2002:0a00:0001::1',
+        '3fff::1',
+        '4000::1',
+        'not-an-ip',
+    ])('rejects nonpublic or transition address %s', address => {
+        expect(isPublicNotificationAddress(address)).toBe(false);
+    });
+
+    it.each(['8.8.8.8', '1.1.1.1', '93.184.216.34', '2606:4700:4700::1111'])(
+        'accepts public address %s',
+        address => {
+            expect(isPublicNotificationAddress(address)).toBe(true);
+        }
+    );
+
+    it.each([
+        'http://127.0.0.1/',
+        'http://2130706433/',
+        'http://0x7f000001/',
+        'http://127.1/',
+        'http://0177.0.0.1/',
+        'http://10.0.1.10/',
+        'http://169.254.169.254/latest/meta-data/',
+        'https://[::1]/',
+        'http://[::ffff:127.0.0.1]/',
+        'ftp://public.example/',
+        'https://user:password@public.example/',
+        'not a URL',
+    ])('blocks %s before sending the token or body', async destination => {
+        await expect(fetchNotificationWebhook(destination, request(), false)).rejects.toThrow();
+        expect(mocks.request).not.toHaveBeenCalled();
+    });
+
+    it.each([
+        [],
+        [{ address: '10.0.1.10', family: 4 }],
+        [
+            { address: '8.8.8.8', family: 4 },
+            { address: '127.0.0.1', family: 4 },
+        ],
+        [
+            { address: '8.8.8.8', family: 4 },
+            { address: 'fd00::1', family: 6 },
+        ],
+    ])('rejects unsafe DNS answers before opening a connection', async (...addresses) => {
+        resolve(addresses as LookupAddress[]);
+        await expect(
+            fetchNotificationWebhook('http://receiver.example/events', request(), false)
+        ).rejects.toThrow();
+        expect(mocks.lookup).toHaveBeenCalled();
+        expect(mocks.request).not.toHaveBeenCalled();
+    });
+
+    it('pins the validated IP, preserves Host/TLS identity, and checks again on retry', async () => {
+        resolve([{ address: '8.8.8.8', family: 4 }]);
+        const response = await fetchNotificationWebhook(
+            'https://receiver.example:8443/events?q=1',
+            request(),
+            false
+        );
+        expect(await response.text()).toBe('{"sent":true}');
+        expect(mocks.request).toHaveBeenCalledWith(
+            expect.objectContaining({
+                hostname: '8.8.8.8',
+                servername: 'receiver.example',
+                port: '8443',
+                path: '/events?q=1',
+                agent: false,
+                headers: expect.objectContaining({
+                    Host: 'receiver.example:8443',
+                    Authorization: 'Bearer synthetic',
+                }),
+            }),
+            expect.any(Function)
+        );
+        const options = mocks.request.mock.calls[0]![0] as RequestOptions;
+        expect(
+            options.checkServerIdentity!('8.8.8.8', {
+                subjectaltname: 'DNS:receiver.example',
+            } as never)
+        ).toBeUndefined();
+        expect(
+            options.checkServerIdentity!('8.8.8.8', {
+                subjectaltname: 'DNS:other.example',
+            } as never)
+        ).toBeInstanceOf(Error);
+        expect(mocks.lookup).toHaveBeenCalledOnce();
+        resolve([{ address: '10.0.1.10', family: 4 }]);
+        await expect(
+            fetchNotificationWebhook('https://receiver.example:8443/events?q=1', request(), false)
+        ).rejects.toThrow();
+        expect(mocks.lookup).toHaveBeenCalledTimes(2);
+        expect(mocks.request).toHaveBeenCalledOnce();
+    });
+
+    it('pins a public IPv6 DNS result', async () => {
+        resolve([{ address: '2606:4700:4700::1111', family: 6 }]);
+        await fetchNotificationWebhook('https://receiver.example/', request(), false);
+        expect(mocks.request.mock.calls[0]![0].hostname).toBe('2606:4700:4700::1111');
+    });
+
+    it('fails closed on DNS errors and aborts stalled resolution', async () => {
+        mocks.lookup.mockImplementationOnce((_host, _options, callback) =>
+            callback(new Error('DNS failed'))
+        );
+        await expect(
+            fetchNotificationWebhook('http://unresolved.example/', request(), false)
+        ).rejects.toThrow('DNS failed');
+        const controller = new AbortController();
+        const pending = fetchNotificationWebhook(
+            'http://stalled.example/',
+            { ...request(), signal: controller.signal },
+            false
+        );
+        controller.abort(new Error('deadline'));
+        await expect(pending).rejects.toThrow('deadline');
+        expect(mocks.request).not.toHaveBeenCalled();
+    });
+
+    it.each([301, 302, 303, 307, 308])('rejects %i without a second request', async status => {
+        respond(status);
+        await expect(
+            fetchNotificationWebhook('https://8.8.8.8/', request(), false)
+        ).rejects.toThrow('without redirects');
+        expect(mocks.request).toHaveBeenCalledOnce();
+    });
+
+    it('bounds the acknowledgement body', async () => {
+        respond(200, 'x'.repeat(64 * 1024 + 1));
+        await expect(
+            fetchNotificationWebhook('https://8.8.8.8/', request(), false)
+        ).rejects.toThrow('exceeds 64 KiB');
+    });
+
+    it('never relies on the runtime global fetch for hosted delivery', async () => {
+        const globalFetch = vi.fn();
+        vi.stubGlobal('fetch', globalFetch);
+        const response = await fetchNotificationWebhook('https://8.8.8.8/', request(), false);
+        expect(response.ok).toBe(true);
+        expect(globalFetch).not.toHaveBeenCalled();
+    });
+
+    it('permits local development only with the explicit offline runtime flag', async () => {
+        const globalFetch = vi.fn().mockResolvedValue(new Response('{"sent":true}'));
+        vi.stubGlobal('fetch', globalFetch);
+        await expect(
+            fetchNotificationWebhook('http://127.0.0.1:5100/', request(), false)
+        ).rejects.toThrow();
+        expect(globalFetch).not.toHaveBeenCalled();
+        await fetchNotificationWebhook('http://127.0.0.1:5100/', request(), true);
+        expect(globalFetch).toHaveBeenCalledWith(
+            'http://127.0.0.1:5100/',
+            expect.objectContaining({ redirect: 'error' })
+        );
+    });
+});

package/src/helpers/notification-webhook-fetch.helpers.ts

@@ -0,0 +1,166 @@
+import { lookup } from 'node:dns';
+import { BlockList, isIP } from 'node:net';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { checkServerIdentity } from 'node:tls';
+
+const nonpublicV4 = new BlockList();
+for (const [address, prefix] of [
+    ['0.0.0.0', 8],
+    ['10.0.0.0', 8],
+    ['100.64.0.0', 10],
+    ['127.0.0.0', 8],
+    ['169.254.0.0', 16],
+    ['172.16.0.0', 12],
+    ['192.0.0.0', 24],
+    ['192.0.2.0', 24],
+    ['192.88.99.0', 24],
+    ['192.168.0.0', 16],
+    ['198.18.0.0', 15],
+    ['198.51.100.0', 24],
+    ['203.0.113.0', 24],
+    ['224.0.0.0', 4],
+    ['240.0.0.0', 4],
+] as const) {
+    nonpublicV4.addSubnet(address, prefix, 'ipv4');
+}
+
+const globalV6 = new BlockList();
+globalV6.addSubnet('2000::', 3, 'ipv6');
+const nonpublicV6 = new BlockList();
+// Special-purpose space, documentation and 6to4 (which can embed a private IPv4).
+nonpublicV6.addSubnet('2001::', 23, 'ipv6');
+nonpublicV6.addSubnet('2001:db8::', 32, 'ipv6');
+nonpublicV6.addSubnet('2002::', 16, 'ipv6');
+nonpublicV6.addSubnet('3fff::', 20, 'ipv6');
+
+export const isPublicNotificationAddress = (address: string): boolean => {
+    if (isIP(address) === 4) return !nonpublicV4.check(address, 'ipv4');
+    // Fail closed for mapped/translated IPv4, NAT64, local, multicast and reserved IPv6.
+    return (
+        isIP(address) === 6 &&
+        !address.includes('%') &&
+        globalV6.check(address, 'ipv6') &&
+        !nonpublicV6.check(address, 'ipv6')
+    );
+};
+
+export class UnsafeNotificationWebhookError extends Error {
+    constructor() {
+        super('Notification webhook must use a public HTTP(S) destination without redirects');
+        this.name = 'UnsafeNotificationWebhookError';
+    }
+}
+
+/** Resolve once; the HTTP transport receives only a validated literal IP. */
+const resolvePublicAddress = (hostname: string, signal: AbortSignal): Promise<string> => {
+    signal.throwIfAborted();
+    if (isIP(hostname)) {
+        if (!isPublicNotificationAddress(hostname)) throw new UnsafeNotificationWebhookError();
+        return Promise.resolve(hostname);
+    }
+    return new Promise((resolve, reject) => {
+        const abort = (): void => reject(signal.reason);
+        signal.addEventListener('abort', abort, { once: true });
+        lookup(hostname, { all: true, verbatim: true }, (error, addresses) => {
+            signal.removeEventListener('abort', abort);
+            if (error) return reject(error);
+            if (
+                !addresses.length ||
+                addresses.some(({ address }) => !isPublicNotificationAddress(address))
+            ) {
+                return reject(new UnsafeNotificationWebhookError());
+            }
+            resolve(addresses[0]!.address);
+        });
+    });
+};
+
+type WebhookRequest = {
+    method: 'POST';
+    headers: Record<string, string>;
+    body: string;
+    signal: AbortSignal;
+};
+
+export const fetchNotificationWebhook = async (
+    destination: string,
+    request: WebhookRequest,
+    isOffline: boolean
+): Promise<Pick<Response, 'ok' | 'status' | 'text'>> => {
+    let url: URL;
+    try {
+        url = new URL(destination);
+    } catch {
+        throw new UnsafeNotificationWebhookError();
+    }
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) {
+        throw new UnsafeNotificationWebhookError();
+    }
+    const hostname = url.hostname.replace(/^\[|\]$/g, '');
+    // Literal addresses bypass DNS lookup in the transport, so check them here too.
+    if (!isOffline && isIP(hostname) && !isPublicNotificationAddress(hostname)) {
+        throw new UnsafeNotificationWebhookError();
+    }
+    // Only the trusted runtime's explicit local-development mode permits private hosts.
+    // Neither NODE_ENV=test nor notification/profile fields can disable the guard.
+    if (isOffline) return fetch(destination, { ...request, redirect: 'error' });
+    const address = await resolvePublicAddress(hostname, request.signal);
+    request.signal.throwIfAborted();
+    // Pin the connection target instead of relying on a fetch dispatcher/lookup hook:
+    // runtimes can ignore those hooks. Preserve HTTP Host, TLS SNI and certificate identity.
+    return new Promise((resolve, reject) => {
+        const send = url.protocol === 'https:' ? httpsRequest : httpRequest;
+        const outgoing = send(
+            {
+                protocol: url.protocol,
+                hostname: address,
+                port: url.port || (url.protocol === 'https:' ? 443 : 80),
+                path: url.pathname + url.search,
+                method: request.method,
+                headers: {
+                    ...request.headers,
+                    Host: url.host,
+                    'Content-Length': String(Buffer.byteLength(request.body)),
+                },
+                servername: isIP(hostname) ? undefined : hostname,
+                rejectUnauthorized: true,
+                checkServerIdentity: (_server, cert) => checkServerIdentity(hostname, cert),
+                // A fresh pinned connection per attempt; no pooled connection can bypass validation.
+                agent: false,
+                signal: request.signal,
+            },
+            response => {
+                const status = response.statusCode ?? 0;
+                // node:http never follows redirects. Reject them explicitly as failed delivery.
+                if (status >= 300 && status < 400) {
+                    response.destroy();
+                    reject(new UnsafeNotificationWebhookError());
+                    return;
+                }
+                const chunks: Buffer[] = [];
+                let bytes = 0;
+                response.on('error', reject);
+                response.on('data', (chunk: Buffer) => {
+                    bytes += chunk.length;
+                    if (bytes > 64 * 1024) {
+                        response.destroy(
+                            new Error('Notification webhook acknowledgement exceeds 64 KiB')
+                        );
+                        return;
+                    }
+                    chunks.push(chunk);
+                });
+                response.on('end', () =>
+                    resolve({
+                        ok: status >= 200 && status < 300,
+                        status,
+                        text: async () => Buffer.concat(chunks).toString('utf8'),
+                    })
+                );
+            }
+        );
+        outgoing.on('error', reject);
+        outgoing.end(request.body);
+    });
+};

package/src/helpers/notificationQueue.helpers.ts

@@ -2,6 +2,8 @@ import { authorizeContractNotification } from '@helpers/contract-events.helpers'
 import { ConsentFlowWebhookMetadataValidator, LCNNotificationValidator } from '@learncard/types';
 
 import { acknowledgeConnectionPromptNotificationDelivery } from '@helpers/connectionPrompt.helpers';
+import { acknowledgeCampaignNotification } from '@accesslayer/campaign/delivery';
+import { authorizeCampaignNotification } from '@helpers/campaign-notifications.helpers';
 import {
     PermanentNotificationDeliveryError,
     sendNotification,
@@ -10,6 +12,7 @@ import {
 export const deliverQueuedNotification = async (body: string): Promise<void> => {
     const notification = await LCNNotificationValidator.parseAsync(JSON.parse(body));
 
+    if (!(await authorizeCampaignNotification(notification))) return;
     if (!(await authorizeContractNotification(notification))) return;
 
     const isContractEvent = ConsentFlowWebhookMetadataValidator.safeParse(
@@ -30,6 +33,8 @@ export const deliverQueuedNotification = async (body: string): Promise<void> =>
 
     if (!stored) throw new Error('Notification was not durably stored');
 
+    await acknowledgeCampaignNotification(notification);
+
     const connectionPrompt = notification.data?.metadata?.connectionPrompt;
     if (!connectionPrompt) return;