@learncard/network-brain-service 3.18.0 → 3.19.1

package/src/cache/index.ts

@@ -85,11 +85,11 @@ export type Cache = {
     lrange: (key: RedisKey, start: number, stop: number) => Promise<string[] | undefined>;
 
     /**
-     * Atomically increments a key by 1 and returns the new value.
-     * If the key does not exist it is created with value 1.
-     * When ttl is provided and this is the first increment (result === 1), EXPIRE is set.
+     * Atomically increments a key by amount (default 1) and returns the new value.
+     * If the key does not exist it is created with value amount.
+     * When ttl is provided, increment and missing-expiry repair happen atomically.
      */
-    incr: (key: RedisKey, ttl?: number) => Promise<number | undefined>;
+    incr: (key: RedisKey, ttl?: number, amount?: number) => Promise<number | undefined>;
 };
 
 /** Evict all keys after one hour by default */
@@ -239,19 +239,31 @@ export const getCache = (): Cache => {
 
             return undefined;
         },
-        incr: async (key, ttl) => {
+        incr: async (key, ttl, amount = 1) => {
             try {
                 const redis = cache?.redis ?? cache?.node;
                 if (!redis) return undefined;
 
-                const newVal = await redis.incr(key);
-
-                // Set TTL on first increment so the window auto-expires
-                if (newVal === 1 && ttl) {
-                    await redis.expire(key, ttl);
-                }
-
-                return newVal;
+                if (!Number.isSafeInteger(amount) || amount <= 0) return undefined;
+                // Increment and expiry must be atomic: a crash between commands must not
+                // leave a permanent quota. Also repair counters created without an expiry.
+                if (ttl)
+                    return Number(
+                        await redis.eval(
+                            `
+                    local count = redis.call('INCRBY', KEYS[1], ARGV[1])
+                    if redis.call('TTL', KEYS[1]) < 0 then
+                        redis.call('EXPIRE', KEYS[1], ARGV[2])
+                    end
+                    return count
+                `,
+                            1,
+                            key,
+                            amount,
+                            ttl
+                        )
+                    );
+                return await redis.incrby(key, amount);
             } catch (e) {
                 console.error('Cache incr error', e);
             }

package/src/config/environment.ts

@@ -36,6 +36,9 @@ export const brainServiceEnvironmentShape = {
     OIDC_EXPECTED_AUDIENCE: optionalEnvironmentString,
     AWS_REGION: optionalEnvironmentString,
     NOTIFICATIONS_QUEUE_URL: optionalEnvironmentUrl,
+    INBOX_QUEUE_URL: optionalEnvironmentUrl,
+    INBOX_DEAD_LETTER_QUEUE_URL: optionalEnvironmentUrl,
+    INBOX_QUEUE_ENDPOINT: optionalEnvironmentUrl,
     NOTIFICATIONS_QUEUE_POLL_URL: optionalEnvironmentUrl,
     NOTIFICATIONS_SERVICE_WEBHOOK_URL: optionalEnvironmentUrl.or(z.literal('false')),
     NOTIFICATIONS_SERVICE_PORT: optionalEnvironmentPort,
@@ -74,12 +77,15 @@ export const brainServiceEnvironmentShape = {
     SKILL_SEMANTIC_SEARCH_RATE_LIMIT_PER_MIN: optionalEnvironmentPort,
     BITSTRING_STATUS_LIST_SIZE: optionalEnvironmentPort,
     CREDENTIAL_REFRESH_DIGEST_SECRET: optionalEnvironmentString,
+    SHARE_LINK_REQUEST_HASH_SECRET: optionalEnvironmentString,
     CREDENTIAL_REFRESH_ENABLED: optionalEnvironmentBoolean.default(false),
     CREDENTIAL_REFRESH_NOTIFICATION_WINDOW_HOURS: credentialRefreshNotificationWindowHours,
     IS_OFFLINE: optionalEnvironmentBoolean.default(false),
     IS_CI: optionalEnvironmentBoolean.default(false),
     IS_E2E_TEST: optionalEnvironmentBoolean.default(false),
     INBOX_DELETE_EXPIRED_RECORDS: optionalEnvironmentBoolean.default(false),
+    INBOX_BATCH_ITEMS_PER_HOUR: optionalEnvironmentString,
+    AWS_LAMBDA_FUNCTION_NAME: optionalEnvironmentString,
     ENABLE_BENCH_ROUTES: optionalEnvironmentBoolean.default(false),
     ENABLE_SEND_CREDENTIAL_TELEMETRY: optionalEnvironmentBoolean.default(false),
     LC_PERF_LOG: optionalEnvironmentBoolean.default(false),
@@ -206,6 +212,40 @@ export const getCredentialRefreshRuntimeEnvironment = (): CredentialRefreshRunti
         examplePath: 'services/learn-card-network/brain-service/.env.example',
     });
 
+const shareLinkRequestHashRuntimeEnvironmentSchema = z.object({
+    NODE_ENV: brainServiceEnvironmentShape.NODE_ENV,
+    SHARE_LINK_REQUEST_HASH_SECRET: brainServiceEnvironmentShape.SHARE_LINK_REQUEST_HASH_SECRET,
+});
+
+/** Reads the dedicated fingerprint secret at call time for enabled share-link APIs. */
+export const getShareLinkRequestHashRuntimeEnvironment = () =>
+    parseEnvironment(shareLinkRequestHashRuntimeEnvironmentSchema, process.env, {
+        project: 'brain-service share links',
+        source: 'process environment',
+        examplePath: 'services/learn-card-network/brain-service/.env.example',
+    });
+
+const inboxBatchRuntimeEnvironmentSchema = z.object({
+    INBOX_QUEUE_URL: brainServiceEnvironmentShape.INBOX_QUEUE_URL,
+    INBOX_DEAD_LETTER_QUEUE_URL: brainServiceEnvironmentShape.INBOX_DEAD_LETTER_QUEUE_URL,
+    INBOX_QUEUE_ENDPOINT: brainServiceEnvironmentShape.INBOX_QUEUE_ENDPOINT,
+    AWS_REGION: brainServiceEnvironmentShape.AWS_REGION,
+    NODE_ENV: brainServiceEnvironmentShape.NODE_ENV,
+    IS_OFFLINE: brainServiceEnvironmentShape.IS_OFFLINE,
+    AWS_LAMBDA_FUNCTION_NAME: brainServiceEnvironmentShape.AWS_LAMBDA_FUNCTION_NAME,
+    INBOX_BATCH_ITEMS_PER_HOUR: brainServiceEnvironmentShape.INBOX_BATCH_ITEMS_PER_HOUR,
+});
+
+export type InboxBatchRuntimeEnvironment = z.output<typeof inboxBatchRuntimeEnvironmentSchema>;
+
+/** Reads batch settings at call time so local invocations and tests can override them safely. */
+export const getInboxBatchRuntimeEnvironment = (): InboxBatchRuntimeEnvironment =>
+    parseEnvironment(inboxBatchRuntimeEnvironmentSchema, process.env, {
+        project: 'brain-service inbox batch',
+        source: 'process environment',
+        examplePath: 'services/learn-card-network/brain-service/.env.example',
+    });
+
 export type BrainServiceEnvironment = z.output<typeof brainServiceEnvironmentSchema>;
 
 export const parseBrainServiceEnvironment = (

package/src/constants/auth-grant.ts

@@ -45,3 +45,8 @@ export const AUTH_GRANT_CREDENTIAL_MANAGEMENT_SCOPE = 'credential:* presentation
 export const AUTH_GRANT_CONTRACTS_SCOPE = 'contracts:*';
 export const AUTH_GRANT_DID_METADATA_SCOPE = 'didMetadata:*';
 export const AUTH_GRANT_AUTH_GRANTS_SCOPE = 'authGrants:*';
+
+// LC-2187 owner share-link APIs. Least privilege: owner metadata/recovery reads
+// use `shareLinks:read`; create/update/revoke/retry use `shareLinks:write`.
+export const AUTH_GRANT_SHARE_LINKS_READ_SCOPE = 'shareLinks:read';
+export const AUTH_GRANT_SHARE_LINKS_WRITE_SCOPE = 'shareLinks:write';

package/src/credential-refresh.ts

@@ -172,7 +172,11 @@ const authenticateRefreshRequest = async (
 
     // Missing aggregates, wrong holders, and awaiting-claim aggregates deliberately
     // share one response so a valid DID cannot use the endpoint as an existence oracle.
-    if (aggregate.holderDid !== auth.holderDid) {
+    if (
+        !aggregate.holderDid ||
+        aggregate.state === 'pending_holder' ||
+        aggregate.holderDid !== auth.holderDid
+    ) {
         logRefreshRequest(refreshId, 'unauthorized', startedAt);
         await reply.status(403).send({ code: 'CREDENTIAL_REFRESH_UNAUTHORIZED' });
         return null;

package/src/docker-entry.ts

@@ -1,3 +1,4 @@
+import { configureInboxBatchBodyLimit } from '@helpers/inbox-batch-http.helpers';
 import { environment } from '@environment';
 import Fastify from 'fastify';
 import fastifyCors from '@fastify/cors';
@@ -14,17 +15,41 @@ import {
 
 import { neogma } from '@instance';
 import { appRouter, type AppRouter, createContext } from './app';
+import { publicShareLinkCacheControlHeaders } from './routes';
+import { registerPublicShareLinkNoStore } from './public-share-link-http';
 import { openApiDocument } from './openapi';
+import { inboxBatchResponseMeta } from './helpers/inbox-batch-http.helpers';
 import { didFastifyPlugin } from './dids';
 import { skillsViewerFastifyPlugin } from './skills-viewer';
 import { statusListsFastifyPlugin } from './status-lists';
 import { credentialRefreshFastifyPlugin } from './credential-refresh';
 import { deliverQueuedNotification } from '@helpers/notificationQueue.helpers';
 import { startSkillEmbeddingBackfill } from '@helpers/skill-embedding.helpers';
+import {
+    createConsoleMaintenanceLogger,
+    createShareLinkMaintenanceRuntime,
+    createShareLinkMaintenanceScheduler,
+    type ShareLinkMaintenanceScheduler,
+} from '@helpers/share-link-maintenance';
 import { maybeAutoSeedSkillFrameworks } from './seed/seedSkillFrameworks';
 
 const server = Fastify({ routerOptions: { maxParamLength: 5000 } });
 
+/**
+ * The scheduled maintenance runtime is created only after the server is ready.
+ * When its config is disabled/invalid it is inert, so no interval and no
+ * graph/remote/signing dependency is initialized at all.
+ */
+let shareLinkMaintenanceScheduler: ShareLinkMaintenanceScheduler | null = null;
+
+server.addHook('onClose', async () => {
+    await shareLinkMaintenanceScheduler?.stop();
+});
+// 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.
+// Registering this later would leave the already-created adapter routes at Fastify's 1 MiB limit.
+configureInboxBatchBodyLimit(server);
+
 server.addHook('onRequest', (request, _reply, done) => {
     type RawWithEmitter = typeof request.raw & {
         on?: (...args: unknown[]) => unknown;
@@ -71,6 +96,9 @@ server.register(fastifyTRPCPlugin, {
         allowMethodOverride: true,
         router: appRouter,
         createContext,
+        responseMeta: ({ paths }) => ({
+            headers: publicShareLinkCacheControlHeaders(paths),
+        }),
         onError({ path, error }) {
             // report to error monitoring
             console.error(`Error in tRPC handler on path '${path}':`, error);
@@ -79,6 +107,7 @@ server.register(fastifyTRPCPlugin, {
 });
 
 server.register(fastifyTRPCOpenApiPlugin, {
+    responseMeta: inboxBatchResponseMeta,
     basePath: '/api',
     router: appRouter,
     createContext,
@@ -88,6 +117,13 @@ server.register(fastifyTRPCOpenApiPlugin, {
     },
 } satisfies CreateOpenApiFastifyPluginOptions<AppRouter>);
 
+/**
+ * LC-2187: the Fastify OpenAPI adapter has no `responseMeta` hook, so the
+ * no-store contract for the anonymous public share-link routes is applied at
+ * the adapter boundary itself. It never depends on a cache layer above.
+ */
+registerPublicShareLinkNoStore(server);
+
 server.get('/docs/openapi.json', () => openApiDocument);
 
 const SCALAR_HTML = `<!DOCTYPE html>
@@ -130,12 +166,41 @@ server.register(credentialRefreshFastifyPlugin);
         } catch (error) {
             console.error('Skill embedding backfill failed', error);
         }
+
+        // Explicit startup after readiness. Disabled/invalid config stays inert.
+        const maintenanceRuntime = createShareLinkMaintenanceRuntime();
+
+        if (maintenanceRuntime.resolution.status === 'enabled') {
+            shareLinkMaintenanceScheduler = createShareLinkMaintenanceScheduler({
+                runOnce: () => maintenanceRuntime.runOnce(),
+                intervalMs: maintenanceRuntime.resolution.config.intervalMs,
+                logger: createConsoleMaintenanceLogger(),
+            });
+            shareLinkMaintenanceScheduler.start();
+        }
     } catch (err) {
         console.error(err);
         process.exit(1);
     }
 })();
 
+const shutdown = async (signal: NodeJS.Signals): Promise<void> => {
+    console.log(`Received ${signal}; closing server and draining maintenance`);
+    try {
+        await server.close();
+    } catch (error) {
+        console.error('Server shutdown failed', error);
+    }
+    process.exit(0);
+};
+
+process.once('SIGTERM', () => {
+    void shutdown('SIGTERM');
+});
+process.once('SIGINT', () => {
+    void shutdown('SIGINT');
+});
+
 const pollUrl = environment.NOTIFICATIONS_QUEUE_POLL_URL;
 
 if (pollUrl) {

package/src/helpers/activity.helpers.ts

@@ -20,6 +20,7 @@ export const logCredentialActivity = async (
 };
 
 export const logCredentialSent = async (params: {
+    onBehalfOf?: string;
     actorProfileId?: string;
     recipientType: CredentialActivityRecipientType;
     recipientIdentifier: string;
@@ -45,6 +46,7 @@ export const logCredentialSent = async (params: {
 };
 
 export const logCredentialDelivered = async (params: {
+    onBehalfOf?: string;
     activityId: string;
     actorProfileId: string;
     recipientType: CredentialActivityRecipientType;
@@ -64,6 +66,7 @@ export const logCredentialDelivered = async (params: {
 };
 
 export const logCredentialClaimed = async (params: {
+    onBehalfOf?: string;
     activityId?: string;
     actorProfileId: string;
     recipientType: CredentialActivityRecipientType;
@@ -98,6 +101,7 @@ export const logCredentialExpired = async (params: {
 };
 
 export const logCredentialFailed = async (params: {
+    onBehalfOf?: string;
     activityId?: string;
     actorProfileId: string;
     recipientType: CredentialActivityRecipientType;

package/src/helpers/app-counter.helpers.ts

@@ -44,7 +44,7 @@ export const handleIncrementCounterEvent = async (
         // tRPC does not support HTTP 429 natively, so we cast to BAD_REQUEST
         // while keeping the semantic code in the message for clients.
         throw new TRPCError({
-            code: 'TOO_MANY_REQUESTS' as 'BAD_REQUEST',
+            code: 'TOO_MANY_REQUESTS',
             message: 'Rate limit exceeded: max 100 counter writes per user per app per minute',
         });
     }

package/src/helpers/boost.helpers.ts

@@ -22,6 +22,7 @@ import {
     parseRenderedTemplate,
     shouldAutoAppendTemplateEvidence,
 } from '@helpers/template.helpers';
+import { setCredentialSubjectIds } from '@helpers/credentialSubject.helpers';
 
 import { getBoostOwner } from '@accesslayer/boost/relationships/read';
 import { BoostInstance } from '@models';
@@ -95,15 +96,7 @@ export const convertCredentialToBoostTemplateJSON = (
     delete template.proof;
     template.issuer = defaultIssuerDid ?? 'did:example:123';
 
-    if (Array.isArray(template.credentialSubject)) {
-        template.credentialSubject = template.credentialSubject.map(subject => {
-            subject.id = 'did:example:123';
-
-            return subject;
-        });
-    } else {
-        template.credentialSubject.id = 'did:example:123';
-    }
+    setCredentialSubjectIds(template, 'did:example:123');
     return JSON.stringify(template);
 };
 
@@ -262,14 +255,7 @@ export const issueClaimLinkBoost = async (
 
     boostCredential.issuer = signingAuthorityForUser.relationship.did;
 
-    if (Array.isArray(boostCredential.credentialSubject)) {
-        boostCredential.credentialSubject = boostCredential.credentialSubject.map(subject => ({
-            ...subject,
-            id: getDidWeb(domain, to.profileId),
-        }));
-    } else {
-        boostCredential.credentialSubject.id = getDidWeb(domain, to.profileId);
-    }
+    setCredentialSubjectIds(boostCredential, getDidWeb(domain, to.profileId));
 
     // Embed the boostURI into the boost credential for verification purposes.
     if (boostCredential.type.includes('BoostCredential')) {
@@ -362,20 +348,7 @@ export const prepareCredentialFromBoost = async (
         credential.issuer = issuerDid;
     }
 
-    // Set recipient DID in credentialSubject if provided
-    if (recipientDid) {
-        if (Array.isArray(credential.credentialSubject)) {
-            credential.credentialSubject = credential.credentialSubject.map(subject => ({
-                ...subject,
-                id: recipientDid,
-            }));
-        } else {
-            credential.credentialSubject = {
-                ...(credential.credentialSubject || {}),
-                id: recipientDid,
-            };
-        }
-    }
+    if (recipientDid) setCredentialSubjectIds(credential, recipientDid);
 
     // Embed boostId for BoostCredential types
     if (credential?.type?.includes('BoostCredential')) {

package/src/helpers/contact-method.helpers.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it, vi } from 'vitest';
+
+const environment = vi.hoisted(() => ({
+    CLIENT_APP_DOMAIN_NAME: undefined as string | undefined,
+    CLIENT_APP_PORT: undefined as number | undefined,
+    PORT: 4000,
+    IS_OFFLINE: true,
+}));
+vi.mock('@environment', () => ({ environment }));
+vi.mock('@cache', () => ({ default: {} }));
+
+import { generateClaimUrl } from './contact-method.helpers';
+
+describe('inbox claim links', () => {
+    it('opens the default frontend instead of the backend port', () => {
+        expect(generateClaimUrl('test-token')).toBe(
+            'http://localhost:3000/interactions/inbox-claim/test-token?iuv=1'
+        );
+    });
+
+    it('uses the configured frontend port locally', () => {
+        environment.CLIENT_APP_PORT = 3100;
+        try {
+            expect(generateClaimUrl('test-token')).toContain('http://localhost:3100/');
+        } finally {
+            environment.CLIENT_APP_PORT = undefined;
+        }
+    });
+
+    it('honors a configured app domain locally and keeps production HTTPS', () => {
+        environment.CLIENT_APP_DOMAIN_NAME = 'app.example.org';
+        try {
+            expect(generateClaimUrl('test-token')).toContain('http://app.example.org/');
+            environment.IS_OFFLINE = false;
+            expect(generateClaimUrl('test-token')).toBe(
+                'https://app.example.org/interactions/inbox-claim/test-token?iuv=1'
+            );
+        } finally {
+            environment.IS_OFFLINE = true;
+            environment.CLIENT_APP_DOMAIN_NAME = undefined;
+        }
+    });
+});

package/src/helpers/contact-method.helpers.ts

@@ -110,10 +110,9 @@ export const markInboxClaimTokenAsUsed = async (token: string): Promise<boolean>
 
 export const generateClaimUrl = (token: string): string => {
     const domainName = environment.CLIENT_APP_DOMAIN_NAME;
-    const domain =
-        !domainName || environment.IS_OFFLINE
-            ? `localhost:${environment.PORT || 3000}`
-            : domainName;
+    // Claim links open the frontend, not the brain-service HTTP port. Honor an
+    // explicitly configured app domain in local development as well.
+    const domain = domainName || `localhost:${environment.CLIENT_APP_PORT || 3000}`;
 
     const protocol = environment.IS_OFFLINE ? 'http' : 'https';
 

package/src/helpers/credential-refresh-email-content.helpers.test.ts

@@ -0,0 +1,222 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+    buildCredentialUpdatedEmailModel,
+    chooseCredentialRefreshEmailTarget,
+    extractBoundedCredentialDisplayTitle,
+    MAX_CREDENTIAL_DISPLAY_TITLE_LENGTH,
+} from './credential-refresh-email-content.helpers';
+
+const email = (value: string, { verified = true, primary = false } = {}) => ({
+    type: 'email',
+    value,
+    isVerified: verified,
+    isPrimary: primary,
+});
+
+const phone = (value: string) => ({
+    type: 'phone',
+    value,
+    isVerified: true,
+    isPrimary: true,
+});
+
+describe('extractBoundedCredentialDisplayTitle', () => {
+    it('returns a trimmed, whitespace-collapsed title', () => {
+        expect(extractBoundedCredentialDisplayTitle('  Introduction \n to\tBiology  ')).toBe(
+            'Introduction to Biology'
+        );
+    });
+
+    it('removes control characters', () => {
+        expect(extractBoundedCredentialDisplayTitle('Biology\u0000\u0007 101')).toBe('Biology 101');
+    });
+
+    it('truncates to the bounded maximum length', () => {
+        const long = 'x'.repeat(MAX_CREDENTIAL_DISPLAY_TITLE_LENGTH + 50);
+        const result = extractBoundedCredentialDisplayTitle(long);
+
+        expect(result).toHaveLength(MAX_CREDENTIAL_DISPLAY_TITLE_LENGTH);
+    });
+
+    it('honors an explicit maximum length', () => {
+        expect(extractBoundedCredentialDisplayTitle('abcdef', 3)).toBe('abc');
+    });
+
+    it.each([undefined, null, '', '   ', 42, {}, []])(
+        'returns undefined for a non-title value (%s)',
+        value => {
+            expect(extractBoundedCredentialDisplayTitle(value)).toBeUndefined();
+        }
+    );
+
+    it('returns undefined when only whitespace remains after sanitization', () => {
+        expect(extractBoundedCredentialDisplayTitle('\u0000 \n\u0007')).toBeUndefined();
+    });
+});
+
+describe('chooseCredentialRefreshEmailTarget', () => {
+    it('resolves a verified holder email for an unmanaged holder', () => {
+        const result = chooseCredentialRefreshEmailTarget({
+            holder: { locale: 'es' },
+            holderContactMethods: [email('holder@example.com')],
+            managers: [],
+        });
+
+        expect(result).toEqual({
+            status: 'resolved',
+            kind: 'holder',
+            locale: 'es',
+            contactMethod: { type: 'email', value: 'holder@example.com' },
+        });
+    });
+
+    it('prefers the verified primary holder email', () => {
+        const result = chooseCredentialRefreshEmailTarget({
+            holder: {},
+            holderContactMethods: [
+                email('secondary@example.com'),
+                email('primary@example.com', { primary: true }),
+            ],
+            managers: [],
+        });
+
+        expect(result).toMatchObject({
+            status: 'resolved',
+            contactMethod: { value: 'primary@example.com' },
+        });
+    });
+
+    it('never uses an unverified holder email', () => {
+        const result = chooseCredentialRefreshEmailTarget({
+            holder: {},
+            holderContactMethods: [
+                email('unverified@example.com', { verified: false }),
+                email('verified@example.com'),
+            ],
+            managers: [],
+        });
+
+        expect(result).toMatchObject({
+            status: 'resolved',
+            contactMethod: { value: 'verified@example.com' },
+        });
+    });
+
+    it('ignores non-email contact methods', () => {
+        const result = chooseCredentialRefreshEmailTarget({
+            holder: {},
+            holderContactMethods: [phone('+15555550100')],
+            managers: [],
+        });
+
+        expect(result).toEqual({ status: 'skipped', reason: 'no-verified-holder-email' });
+    });
+
+    it('skips an unmanaged holder with no verified email', () => {
+        const result = chooseCredentialRefreshEmailTarget({
+            holder: {},
+            holderContactMethods: [],
+            managers: [],
+        });
+
+        expect(result).toEqual({ status: 'skipped', reason: 'no-verified-holder-email' });
+    });
+
+    it('routes a managed child to the verified guardian email, never the child', () => {
+        const result = chooseCredentialRefreshEmailTarget({
+            holder: { locale: 'en' },
+            holderContactMethods: [email('child@example.com')],
+            managers: [
+                {
+                    locale: 'fr',
+                    contactMethods: [email('guardian@example.com')],
+                },
+            ],
+        });
+
+        expect(result).toEqual({
+            status: 'resolved',
+            kind: 'guardian',
+            locale: 'fr',
+            contactMethod: { type: 'email', value: 'guardian@example.com' },
+        });
+        expect(JSON.stringify(result)).not.toContain('child@example.com');
+    });
+
+    it('skips a managed child when no guardian has a verified email', () => {
+        const result = chooseCredentialRefreshEmailTarget({
+            holder: {},
+            holderContactMethods: [email('child@example.com')],
+            managers: [
+                { contactMethods: [email('guardian@example.com', { verified: false })] },
+                { contactMethods: [] },
+            ],
+        });
+
+        expect(result).toEqual({ status: 'skipped', reason: 'no-verified-guardian-email' });
+    });
+
+    it('skips a managed child even when the child has a verified email', () => {
+        const result = chooseCredentialRefreshEmailTarget({
+            holder: {},
+            holderContactMethods: [email('child@example.com')],
+            managers: [{ contactMethods: [] }],
+        });
+
+        expect(result).toEqual({ status: 'skipped', reason: 'no-verified-guardian-email' });
+    });
+
+    it('prefers a primary verified guardian email across managers', () => {
+        const result = chooseCredentialRefreshEmailTarget({
+            holder: {},
+            holderContactMethods: [],
+            managers: [
+                { contactMethods: [email('guardian-a@example.com')] },
+                {
+                    contactMethods: [
+                        email('guardian-b@example.com', { primary: true }),
+                        email('guardian-b2@example.com'),
+                    ],
+                },
+            ],
+        });
+
+        expect(result).toMatchObject({
+            status: 'resolved',
+            kind: 'guardian',
+            contactMethod: { value: 'guardian-b@example.com' },
+        });
+    });
+});
+
+describe('buildCredentialUpdatedEmailModel', () => {
+    it('includes the issuer display name and credential title', () => {
+        expect(
+            buildCredentialUpdatedEmailModel({
+                issuerDisplayName: 'Inbox Demo School',
+                credentialTitle: 'Introduction to Biology',
+            })
+        ).toEqual({
+            issuer: { name: 'Inbox Demo School' },
+            credential: { name: 'Introduction to Biology' },
+        });
+    });
+
+    it('omits the credential title when unavailable', () => {
+        expect(
+            buildCredentialUpdatedEmailModel({
+                issuerDisplayName: 'Inbox Demo School',
+            })
+        ).toEqual({ issuer: { name: 'Inbox Demo School' } });
+    });
+
+    it('does not include any other credential content', () => {
+        const model = buildCredentialUpdatedEmailModel({
+            issuerDisplayName: 'Inbox Demo School',
+            credentialTitle: 'Introduction to Biology',
+        });
+
+        expect(Object.keys(model).sort()).toEqual(['credential', 'issuer']);
+    });
+});