@learncard/lca-api-service 1.6.3 → 1.7.0

package/src/accesslayer/notifications/create.test.ts

@@ -12,6 +12,7 @@ vi.mock('.', () => ({
 }));
 
 import {
+    createNotification,
     isManagedCredentialRefreshNotification,
     upsertCredentialRefreshNotification,
 } from './create';
@@ -103,3 +104,82 @@ describe('managed credential refresh notification persistence', () => {
         expect(update.$setOnInsert).toMatchObject({ archived: false });
     });
 });
+
+describe('campaign notification persistence', () => {
+    const campaignNotification = {
+        type: 'ANNOUNCEMENT' as const,
+        to: { did: 'did:web:brain.example:users:learner' },
+        from: 'did:web:brain.example',
+        message: { title: 'Welcome', body: 'Explore your next step' },
+        data: { metadata: { campaignId: 'pilot-clr', campaignCreatedAt: '2026-01-01T00:00:00Z' } },
+    };
+    beforeEach(() => {
+        mocks.updateOne.mockReset();
+    });
+
+    it('collapses concurrent retries into one insertion without changing read state or copy', async () => {
+        const stored = new Map<string, unknown>();
+        mocks.updateOne.mockImplementation(async (filter, update) => {
+            if (stored.has(filter._id)) return { upsertedCount: 0 };
+            stored.set(filter._id, update.$setOnInsert);
+            return { upsertedCount: 1 };
+        });
+        const results = await Promise.all(
+            Array.from({ length: 10 }, () => createNotification(campaignNotification))
+        );
+        expect(results.filter(result => result && result.created)).toHaveLength(1);
+        expect(stored.size).toBe(1);
+        await createNotification({ ...campaignNotification, message: { title: 'Edited' } });
+        expect([...stored.values()][0]).toMatchObject({ message: campaignNotification.message });
+        for (const [filter, update, options] of mocks.updateOne.mock.calls) {
+            expect(filter._id).toMatch(/^campaign:[a-f0-9]{64}$/);
+            expect(update.$set).toBeUndefined();
+            expect(options).toEqual({ upsert: true });
+        }
+    });
+
+    it('keeps separate recipients, recreated campaigns and explicit tests independent', async () => {
+        mocks.updateOne.mockResolvedValue({ upsertedCount: 1 });
+        await createNotification(campaignNotification);
+        await createNotification({ ...campaignNotification, to: { did: 'did:key:other' } });
+        await createNotification({
+            ...campaignNotification,
+            data: {
+                metadata: {
+                    ...campaignNotification.data.metadata,
+                    campaignCreatedAt: '2026-02-01T00:00:00Z',
+                },
+            },
+        });
+        await createNotification({
+            ...campaignNotification,
+            data: {
+                metadata: {
+                    ...campaignNotification.data.metadata,
+                    campaignTestId: 'aaaaaaaa-aaaa-4aaa-aaaa-aaaaaaaaaaaa',
+                },
+            },
+        });
+        expect(new Set(mocks.updateOne.mock.calls.map(([filter]) => filter._id)).size).toBe(4);
+    });
+
+    it('does not turn ambiguous storage errors into a successful delivery', async () => {
+        const error = Object.assign(new Error('lost response'), { name: 'MongoNetworkError' });
+        mocks.updateOne.mockRejectedValue(error);
+        await expect(createNotification(campaignNotification)).rejects.toBe(error);
+        mocks.updateOne.mockResolvedValue({ upsertedCount: 0 });
+        await expect(createNotification(campaignNotification)).resolves.toEqual({ created: false });
+    });
+
+    it('treats an atomic duplicate-key race as an existing delivery', async () => {
+        mocks.updateOne.mockRejectedValue({ code: 11000 });
+        await expect(createNotification(campaignNotification)).resolves.toEqual({ created: false });
+    });
+
+    it('rejects missing campaign identity before storing or pushing', async () => {
+        await expect(
+            createNotification({ ...campaignNotification, data: undefined })
+        ).resolves.toBe(false);
+        expect(mocks.updateOne).not.toHaveBeenCalled();
+    });
+});

package/src/accesslayer/notifications/create.ts

@@ -1,7 +1,11 @@
-import { Notifications, ensureManagedCredentialRefreshNotificationIndex } from '.';
-import { LCNNotification } from '@learncard/types';
+import {
+    ConsentFlowContractNotificationDataValidator,
+    type ConsentFlowContractNotificationData,
+    type LCNNotification,
+} from '@learncard/types';
 import { createHash } from 'crypto';
 import { v4 as uuidv4 } from 'uuid';
+import { Notifications, ensureManagedCredentialRefreshNotificationIndex } from '.';
 
 export type NotificationCreationResult = {
     created: boolean;
@@ -53,6 +57,66 @@ const getCredentialRefreshNotificationId = (
     return `credential-refresh:${digest}`;
 };
 
+const getContractUpdateNotificationData = (
+    notification: LCNNotification
+): ConsentFlowContractNotificationData | undefined => {
+    const parsed = ConsentFlowContractNotificationDataValidator.safeParse(notification.data);
+    return parsed.success ? parsed.data : undefined;
+};
+
+const getContractUpdateNotificationId = (
+    notification: LCNNotification,
+    update: ConsentFlowContractNotificationData
+): string => {
+    const digest = createHash('sha256')
+        .update(JSON.stringify([notification.to.did, update.contractUri, update.toVersion]))
+        .digest('hex');
+
+    return `consent-flow-contract-update:${digest}`;
+};
+
+/** Persist each revision once so queue retries cannot duplicate its push. */
+export const upsertConsentFlowContractUpdateNotification = async (
+    notification: LCNNotification
+): Promise<NotificationCreationResult | false> => {
+    const update = getContractUpdateNotificationData(notification);
+    if (!update) return false;
+
+    const notificationId = getContractUpdateNotificationId(notification, update);
+
+    try {
+        const result = await Notifications.updateOne(
+            { _id: notificationId },
+            {
+                $setOnInsert: {
+                    _id: notificationId,
+                    read: update.kind !== 'requires_consent',
+                    archived: false,
+                    sent: new Date().toISOString(),
+                    ...notification,
+                },
+            },
+            { upsert: true }
+        );
+
+        return { created: result.upsertedCount === 1 };
+    } catch (e) {
+        if (
+            typeof e === 'object' &&
+            e !== null &&
+            'code' in e &&
+            (e as { code?: unknown }).code === 11000
+        ) {
+            return { created: false };
+        }
+
+        if (isAmbiguousMongoWriteError(e)) throw e;
+
+        console.error(e);
+        return false;
+    }
+};
+
 const isAmbiguousMongoWriteError = (error: unknown): boolean => {
     if (typeof error !== 'object' || error === null) return false;
 
@@ -79,6 +143,37 @@ export const createNotification = async (
     notification: LCNNotification
 ): Promise<NotificationCreationResult | false> => {
     try {
+        if (notification.type === 'ANNOUNCEMENT') {
+            const metadata = notification.data?.metadata;
+            if (!metadata?.campaignId || !metadata.campaignCreatedAt) return false;
+            // The Mongo _id index arbitrates concurrent deliveries. A dispatch/retry
+            // never changes this identity; explicit test sends get their own identity.
+            const digest = createHash('sha256')
+                .update(
+                    JSON.stringify([
+                        notification.from,
+                        notification.to.did,
+                        metadata.campaignId,
+                        metadata.campaignCreatedAt,
+                        metadata.campaignTestId ?? null,
+                    ])
+                )
+                .digest('hex');
+            const result = await Notifications.updateOne(
+                { _id: `campaign:${digest}` },
+                {
+                    $setOnInsert: {
+                        ...notification,
+                        _id: `campaign:${digest}`,
+                        read: false,
+                        archived: false,
+                        sent: new Date().toISOString(),
+                    },
+                },
+                { upsert: true }
+            );
+            return { created: result.upsertedCount === 1 };
+        }
         const promptId = getConnectionPromptId(notification);
 
         if (!promptId) {

package/src/config/environment.test.ts

@@ -1,5 +1,10 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import { isEscrowReleaseKillSwitchEnabled, parseLcaApiEnvironment } from './environment';
+import { ESCROW_AUTHORITY_TENANT_PATTERN } from '@learncard/sss-key-manager';
+import {
+    ESCROW_AUTHORITY_TENANT_LABEL,
+    isEscrowReleaseKillSwitchEnabled,
+    parseLcaApiEnvironment,
+} from './environment';
 
 afterEach(() => vi.unstubAllEnvs());
 
@@ -157,3 +162,24 @@ describe('Keycloak startup configuration', () => {
         ).not.toThrow();
     });
 });
+
+describe('escrow authority tenant', () => {
+    it('validates the label exactly like the SDK', () => {
+        expect(ESCROW_AUTHORITY_TENANT_LABEL.source).toBe(ESCROW_AUTHORITY_TENANT_PATTERN.source);
+        expect(ESCROW_AUTHORITY_TENANT_LABEL.flags).toBe(ESCROW_AUTHORITY_TENANT_PATTERN.flags);
+    });
+
+    const offline = { ...production, IS_OFFLINE: 'true' };
+    it('defaults to the learncard enclave label (no infra change)', () => {
+        expect(parseLcaApiEnvironment(offline).ESCROW_AUTHORITY_TENANT).toBe('learncard');
+    });
+    it('accepts an explicit label and rejects a malformed one', () => {
+        expect(
+            parseLcaApiEnvironment({ ...offline, ESCROW_AUTHORITY_TENANT: 'scouts' })
+                .ESCROW_AUTHORITY_TENANT
+        ).toBe('scouts');
+        expect(() =>
+            parseLcaApiEnvironment({ ...offline, ESCROW_AUTHORITY_TENANT: 'learn card' })
+        ).toThrow();
+    });
+});

package/src/config/environment.ts

@@ -11,6 +11,12 @@ import {
     requiredEnvironmentString,
 } from '@learncard/helpers';
 
+/**
+ * Same as `ESCROW_AUTHORITY_TENANT_PATTERN` in `@learncard/sss-key-manager`; copied so loading
+ * the environment doesn't import the SDK. `environment.test.ts` asserts the two stay identical.
+ */
+export const ESCROW_AUTHORITY_TENANT_LABEL = /^[A-Za-z0-9_-]{1,128}$/;
+
 export const lcaApiEnvironmentShape = {
     NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
     LAMBDA_STAGE: optionalEnvironmentString,
@@ -72,6 +78,16 @@ export const lcaApiEnvironmentShape = {
     ESCROW_ENCLAVE_ACTIVE_KEY_ID: optionalEnvironmentString,
     ESCROW_ENCLAVE_REMOTE_URL: optionalEnvironmentUrl,
     ESCROW_ENCLAVE_REMOTE_TOKEN: optionalEnvironmentString,
+    /** The remote enclave's measured authority tenant label (ESCROW_AUTHORITY_TENANT in its
+     *  image). Every app tenant's escrow intents and authority state are checked against it,
+     *  never against the client-supplied X-Tenant-Id: the enclave is single-tenant, so
+     *  VetPass and LearnCard both use "learncard". Defaults to "learncard" (no infra change).
+     *  The default also applies to the ScoutPass deployment (CONFIG_TENANT=scouts), whose app
+     *  has escrow off: enabling ScoutPass escrow on its own enclave must set this in
+     *  config.scouts.<stage>.json, or its escrow routes fail closed. */
+    ESCROW_AUTHORITY_TENANT: optionalEnvironmentString
+        .transform(value => value ?? 'learncard')
+        .pipe(z.string().regex(ESCROW_AUTHORITY_TENANT_LABEL)),
     /** Operator-flipped, manual-only kill switch (P7.1). When true, startRecovery/completeRecovery
      *  refuse with a friendly message; hold cancellation and notifications keep working. Never
      *  auto-flipped by the escrow-ledger-monitor — a compromised monitor must not be able to

package/src/config/escrowDeployment.test.ts

@@ -32,6 +32,7 @@ const SOURCES = {
         'ESCROW_HOLD_DURATION_MS',
         'ESCROW_HOLD_RESTART_MIN_AGE_MS',
         'ESCROW_ENCLAVE_REMOTE_TIMEOUT_MS',
+        'ESCROW_AUTHORITY_TENANT',
     ],
 };
 const SECRETS = new Set([

package/src/docker-entry.ts

@@ -11,7 +11,7 @@ import { fastifyTRPCOpenApiPlugin, CreateOpenApiFastifyPluginOptions } from 'trp
 import { appRouter, type AppRouter, createContext } from './app';
 import { openApiDocument } from './openapi';
 import { didFastifyPlugin } from './dids';
-import { ensureUserKeysIndexes, createEscrowHoldsIndexes } from './models';
+import { ensureUserKeysIndexes } from './models';
 import { oidcFastifyPlugin } from './oidc';
 import { ensureAuthSubjectIndexes } from './models/AuthSubject';
 
@@ -116,7 +116,6 @@ server.register(oidcFastifyPlugin);
         });
         console.log('Server starting on port ', environment.PORT || 3000);
         await ensureUserKeysIndexes();
-        await createEscrowHoldsIndexes();
         await server.listen({ host: '0.0.0.0', port: Number(environment.PORT || 3000) });
     } catch (err) {
         console.error(err);

package/src/helpers/analyticsEligibility.ts

@@ -0,0 +1,15 @@
+import { calculateAgeFromISODate, getMinorAgeThreshold } from '@learncard/helpers';
+
+export type TrustedProfileAge = {
+    dob?: string | null;
+    country?: string | null;
+    type?: string | null;
+};
+
+/** Missing DOB preserves legacy adult eligibility; malformed/future DOB fails closed. */
+export const isAnalyticsRestricted = (profile: TrustedProfileAge, now = new Date()): boolean => {
+    if (profile.type === 'child') return true;
+    if (!profile.dob) return false;
+    const age = calculateAgeFromISODate(profile.dob, now);
+    return Number.isNaN(age) || age < getMinorAgeThreshold(profile.country ?? undefined);
+};

package/src/helpers/brainUrl.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest';
+import { getBrainOpenApiBase } from './brainUrl';
+
+describe('getBrainOpenApiBase', () => {
+    it.each(['', '/', '/api', '/api/', '/trpc', '/trpc/'])(
+        'normalizes the endpoint suffix %j',
+        suffix => {
+            expect(getBrainOpenApiBase(`https://brain.test${suffix}`)).toBe(
+                'https://brain.test/api'
+            );
+        }
+    );
+});

package/src/helpers/brainUrl.ts

@@ -0,0 +1,3 @@
+/** The shared Brain endpoint may name tRPC; OpenAPI is served alongside it. */
+export const getBrainOpenApiBase = (serviceUrl: string): string =>
+    `${serviceUrl.replace(/\/(?:trpc|api)\/?$/, '').replace(/\/$/, '')}/api`;

package/src/helpers/currentProfile.test.ts

@@ -0,0 +1,55 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({ get: vi.fn() }));
+vi.mock('axios', async importOriginal => {
+    const actual = await importOriginal<typeof import('axios')>();
+    return { ...actual, default: { ...actual.default, get: mocks.get } };
+});
+vi.mock('@environment', () => ({
+    environment: { NETWORK_BRAIN_SERVICE_URL: 'http://brain.test/api' },
+}));
+
+import { getCurrentProfile } from './currentProfile';
+import { isAnalyticsRestricted } from './analyticsEligibility';
+
+const ctx = {
+    authorizationHeader: 'Bearer signed-did-vp',
+    tenant: { id: 'tenant-a' },
+    user: { did: 'did:example:person' },
+} as never;
+
+describe('getCurrentProfile', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        vi.useFakeTimers({ toFake: ['Date'] });
+        vi.setSystemTime(new Date('2026-10-29T12:00:00Z'));
+    });
+    afterEach(() => vi.useRealTimers());
+
+    it('keeps age authority when Brain rewrites the authenticated profile DID', async () => {
+        mocks.get.mockResolvedValueOnce({
+            data: { did: 'did:web:network.learncard.com:users:person', dob: '2010-01-01' },
+        });
+        expect(isAnalyticsRestricted((await getCurrentProfile(ctx))!)).toBe(true);
+    });
+
+    it('treats malformed profile authority as unknown rather than adult authority', async () => {
+        mocks.get.mockResolvedValueOnce({ data: { dob: 2010, country: 'US' } });
+        await expect(getCurrentProfile(ctx)).resolves.toBeNull();
+    });
+
+    it('fails closed when brain-service cannot resolve the profile without exposing transport details', async () => {
+        mocks.get.mockRejectedValueOnce(new Error('private transport detail'));
+        await expect(getCurrentProfile(ctx)).resolves.toBeNull();
+    });
+
+    it('accepts a self-profile without a DID field', async () => {
+        mocks.get.mockResolvedValueOnce({ data: { dob: '1990-01-01' } });
+        expect(isAnalyticsRestricted((await getCurrentProfile(ctx))!)).toBe(false);
+    });
+
+    it('treats an absent network profile as unknown rather than an adult', async () => {
+        mocks.get.mockResolvedValueOnce({ data: undefined });
+        await expect(getCurrentProfile(ctx)).resolves.toBeNull();
+    });
+});

package/src/helpers/currentProfile.ts

@@ -0,0 +1,58 @@
+import axios from 'axios';
+import { z } from 'zod';
+
+import { environment } from '@environment';
+import type { Context } from '@routes';
+import { getBrainOpenApiBase } from './brainUrl';
+
+const brainServiceUrl = environment.NETWORK_BRAIN_SERVICE_URL;
+// The shared service endpoint is normally the tRPC base. OpenAPI is served
+// alongside it, not beneath /trpc.
+const profileUrl = brainServiceUrl ? `${getBrainOpenApiBase(brainServiceUrl)}/profile` : null;
+
+const currentProfileSchema = z.object({
+    dob: z.string().nullish(),
+    country: z.string().nullish(),
+    type: z.string().nullish(),
+});
+
+/** Resolve the authenticated holder's persisted profile; null means unknown age authority. */
+// Brain's self-profile uses didRoute and verifies this same signed VP without
+// consuming a second challenge. A challenge-consuming route would need a new
+// service-auth contract. Brain may rewrite profile DIDs; the VP establishes identity.
+export const getCurrentProfile = async (
+    ctx: Pick<Context, 'authorizationHeader' | 'tenant' | 'user'>
+) => {
+    if (!ctx.authorizationHeader || !ctx.user?.did) return null;
+    if (!profileUrl) {
+        console.warn('Current profile authority unavailable: endpoint not configured');
+        return null;
+    }
+
+    try {
+        const { data } = await axios.get(profileUrl, {
+            timeout: 3000,
+            maxRedirects: 0,
+            headers: {
+                Authorization: ctx.authorizationHeader,
+                'X-Tenant-Id': ctx.tenant.id,
+            },
+        });
+        // The self-profile endpoint returns an empty body when no profile exists.
+        if (data == null || data === '') return null;
+        const parsed = currentProfileSchema.safeParse(data);
+        if (!parsed.success) {
+            console.warn('Current profile authority unavailable: malformed response');
+            return null;
+        }
+        return parsed.data;
+    } catch (error) {
+        const status = axios.isAxiosError(error) ? error.response?.status : undefined;
+        console.warn(
+            status
+                ? `Current profile authority unavailable: HTTP ${status}`
+                : 'Current profile authority unavailable: request failed'
+        );
+        return null;
+    }
+};

package/src/helpers/locale.helpers.test.ts

@@ -5,6 +5,9 @@ import cache from '@cache';
 
 import { resolveLocaleByEmail } from './locale.helpers';
 
+vi.mock('@environment', () => ({
+    environment: { NETWORK_BRAIN_SERVICE_URL: 'http://brain.test/trpc' },
+}));
 vi.mock('axios');
 vi.mock('@cache', () => ({
     default: {
@@ -44,7 +47,7 @@ describe('resolveLocaleByEmail', () => {
         await expect(resolveLocaleByEmail('Jane@Example.com')).resolves.toBe('es');
 
         expect(mockedPost).toHaveBeenCalledWith(
-            expect.stringContaining('/utilities/resolve-email-locale'),
+            'http://brain.test/api/utilities/resolve-email-locale',
             { email: 'Jane@Example.com' },
             expect.objectContaining({ timeout: expect.any(Number) })
         );

package/src/helpers/locale.helpers.ts

@@ -2,14 +2,16 @@ import { environment } from '@environment';
 import axios from 'axios';
 
 import cache from '@cache';
+import { getBrainOpenApiBase } from './brainUrl';
 
 /**
  * Base URL for the LearnCard Network (brain-service) OpenAPI, used to resolve a
  * recipient's saved locale by email before they authenticate. Overridable via
  * `NETWORK_BRAIN_SERVICE_URL`; defaults to production.
  */
-const BRAIN_SERVICE_URL =
-    environment.NETWORK_BRAIN_SERVICE_URL || 'https://network.learncard.com/api';
+const BRAIN_SERVICE_URL = getBrainOpenApiBase(
+    environment.NETWORK_BRAIN_SERVICE_URL || 'https://network.learncard.com/api'
+);
 
 /** Max time we'll wait on the locale lookup before falling back. Login must not block on it. */
 const LOOKUP_TIMEOUT_MS = 1500;

package/src/helpers/retryingOnce.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { createRetryingOnce } from './retryingOnce';
+
+describe('createRetryingOnce', () => {
+    it('runs the task once and shares the result', async () => {
+        const task = vi.fn().mockResolvedValue('ready');
+        const ensure = createRetryingOnce(task);
+
+        await expect(Promise.all([ensure(), ensure()])).resolves.toEqual(['ready', 'ready']);
+        await expect(ensure()).resolves.toBe('ready');
+        expect(task).toHaveBeenCalledTimes(1);
+    });
+
+    it('shares an in-flight failure, then retries on the next call', async () => {
+        const task = vi
+            .fn()
+            .mockRejectedValueOnce(new Error('Escrow hold index initialization failed'))
+            .mockResolvedValue('ready');
+        const ensure = createRetryingOnce(task);
+
+        const first = ensure();
+        const concurrent = ensure();
+        await expect(first).rejects.toThrow('Escrow hold index initialization failed');
+        await expect(concurrent).rejects.toThrow('Escrow hold index initialization failed');
+        expect(task).toHaveBeenCalledTimes(1);
+
+        await expect(ensure()).resolves.toBe('ready');
+        expect(task).toHaveBeenCalledTimes(2);
+        await expect(ensure()).resolves.toBe('ready');
+        expect(task).toHaveBeenCalledTimes(2);
+    });
+});

package/src/helpers/retryingOnce.ts

@@ -0,0 +1,18 @@
+/**
+ * Run `task` at most once at a time and share its result. A rejection is not
+ * cached: the next call starts the task again. Used for Lambda cold-start work,
+ * where caching a failure turns one transient error (e.g. a slow Mongo call)
+ * into a container that fails every request until it is recycled.
+ */
+export const createRetryingOnce = <T>(task: () => Promise<T>): (() => Promise<T>) => {
+    let pending: Promise<T> | undefined;
+
+    return () => {
+        pending ??= task().catch((error: unknown) => {
+            pending = undefined;
+            throw error;
+        });
+
+        return pending;
+    };
+};