@learncard/lca-api-service 1.6.2 → 1.7.0

package/src/routes/keys.ts

@@ -42,6 +42,7 @@ import {
     setRecoveryEmailByAuthProvider,
     markUserKeyMigrationProvisionalByAuthProvider,
     activateUserKeyByAuthProvider,
+    isWeb3AuthLogin,
     purgeExpiredProvisionalMigrationByAuthProvider,
     getSssActivationState,
     hasActivatableRecoveryMethod,
@@ -1058,6 +1059,12 @@ export const keysRouter = t.router({
                      */
                     priorEscrowEnrollment: z.boolean(),
                     sssActivationState: z.enum(['provisional', 'active']),
+                    /**
+                     * Web3Auth, signing in through this login, derives this account's
+                     * key (see `isWeb3AuthLogin`). Web3Auth-mode clients stop any
+                     * existing account where this is false.
+                     */
+                    isWeb3AuthLogin: z.boolean(),
                 })
                 .nullable()
         )
@@ -1133,6 +1140,7 @@ export const keysRouter = t.router({
                     ? maskEmail(userKey.recoveryEmail)
                     : null,
                 sssActivationState: getSssActivationState(userKey),
+                isWeb3AuthLogin: isWeb3AuthLogin(userKey, authProvider),
                 escrowOptedOut: Boolean(userKey.escrowOptedOutAt),
                 escrowPin: getEscrowPinStatus(userKey),
                 escrowStale: userKey.escrowBlob

package/src/routes/notifications.ts

@@ -8,12 +8,17 @@ import { t, didAndChallengeRoute, authorizedDidRoute } from '@routes';
 import cache from '@cache';
 import { createPushNotificationRegistration } from '@accesslayer/pushtokens/create';
 import { deletePushNotificationRegistration } from '@accesslayer/pushtokens/delete';
-import { LCNNotification, LCNNotificationValidator } from '@learncard/types';
+import {
+    ConsentFlowContractNotificationDataValidator,
+    LCNNotification,
+    LCNNotificationValidator,
+} from '@learncard/types';
 import { sendPushNotification } from '@helpers/pushNotifications.helpers';
 import { isDidOwnerOfNotification } from '@helpers/notifications.helpers';
 import {
     createNotification,
     isManagedCredentialRefreshNotification,
+    upsertConsentFlowContractUpdateNotification,
     upsertCredentialRefreshNotification,
 } from '@accesslayer/notifications/create';
 import {
@@ -316,6 +321,34 @@ export const notificationsRouter = t.router({
 
             let sendNotificationResponse: unknown;
 
+            // Quiet revisions belong in the feed as already-read records; access
+            // increases are unread and pushed once per recipient and revision.
+            if (input.type === 'CONSENT_FLOW_CONTRACT_UPDATED') {
+                const updateData = ConsentFlowContractNotificationDataValidator.safeParse(
+                    input.data
+                );
+                if (!updateData.success) return false;
+
+                const updateResult = await upsertConsentFlowContractUpdateNotification(input);
+
+                if (!updateResult) return false;
+
+                if (updateResult.created && updateData.data.kind === 'requires_consent') {
+                    await recordE2ePushAttempt(input);
+
+                    try {
+                        sendNotificationResponse = await sendPushNotification(input);
+                    } catch (error) {
+                        console.error(
+                            'Failed to send push notification after durable storage',
+                            error
+                        );
+                    }
+                }
+
+                return true;
+            }
+
             // Managed credential refresh deliveries (LC-2117/LC-2136) collapse
             // atomically per delivery window: persist first, push only when the
             // upsert inserted a new window record. Other notification types keep

package/src/routes/preferences.test.ts

@@ -0,0 +1,216 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { initTRPC } from '@trpc/server';
+
+const state = vi.hoisted(() => ({
+    saved: {} as Record<string, unknown>,
+    profile: { dob: '1990-01-01', country: 'US', type: 'personal' } as {
+        dob?: string;
+        country?: string;
+        type?: string;
+    },
+    profileUnavailable: false,
+    repairFailure: null as 'throw' | 'return-false' | null,
+}));
+vi.mock('@routes', () => {
+    const t = initTRPC.create();
+    return { t, didAndChallengeRoute: t.procedure };
+});
+vi.mock('@accesslayer/preferences/create', () => ({
+    createPreferences: async (_did: string, theme: string) => {
+        state.saved = { theme };
+        return true;
+    },
+}));
+vi.mock('@accesslayer/preferences/read', () => ({
+    getPreferencesForDid: async () => ({ ...state.saved }),
+}));
+vi.mock('@accesslayer/preferences/update', () => ({
+    updatePreferences: async (_did: string, input: Record<string, unknown>) => {
+        if (state.repairFailure === 'throw') throw new Error('write failed');
+        if (state.repairFailure === 'return-false') return false;
+        Object.assign(state.saved, input);
+        return true;
+    },
+}));
+vi.mock('@helpers/currentProfile', () => ({
+    getCurrentProfile: async () => {
+        if (state.profileUnavailable) return null;
+        return { ...state.profile };
+    },
+}));
+import { preferencesRouter } from './preferences';
+import { ThemeEnum } from '../types/preferences';
+const caller = preferencesRouter.createCaller({
+    user: { did: 'did:example:person', isChallengeValid: true },
+    tenant: { id: 'test-tenant' },
+    authorizationHeader: 'Bearer signed-vp',
+} as never);
+
+beforeEach(() => {
+    vi.useFakeTimers({ toFake: ['Date'] });
+    vi.setSystemTime(new Date('2026-10-29T12:00:00Z'));
+    state.saved = { theme: ThemeEnum.Colorful };
+    state.profile = { dob: '1990-01-01', country: 'US', type: 'personal' };
+    state.profileUnavailable = false;
+    state.repairFailure = null;
+});
+afterEach(() => vi.useRealTimers());
+
+describe('backend analytics age authorization', () => {
+    it.each(['guardian', 'school', 'personal'])(
+        'rejects forged age flags for an underage %s account',
+        async type => {
+            state.profile = { dob: '2012-01-01', country: 'US', type };
+            await caller.updatePreferences({
+                analyticsEnabled: true,
+                isMinor: false,
+                analyticsAutoDisabled: false,
+            });
+            expect(state.saved).toMatchObject({
+                analyticsEnabled: false,
+                isMinor: true,
+                analyticsAutoDisabled: true,
+            });
+            expect(await caller.getPreferencesForDid()).toMatchObject({
+                analyticsEnabled: false,
+                isMinor: true,
+            });
+        }
+    );
+
+    it('permits adult opt-in but derives metadata instead of trusting caller flags', async () => {
+        await caller.updatePreferences({
+            analyticsEnabled: true,
+            isMinor: true,
+            analyticsAutoDisabled: true,
+        });
+        expect(state.saved).toMatchObject({
+            analyticsEnabled: true,
+            isMinor: false,
+            analyticsAutoDisabled: false,
+        });
+        expect((await caller.getPreferencesForDid()).analyticsEnabled).toBe(true);
+    });
+
+    it('repairs incorrect saved consent and keeps it off after the profile becomes eligible', async () => {
+        state.saved.analyticsEnabled = true;
+        state.saved.isMinor = false;
+        state.profile.dob = '2012-01-01';
+        expect((await caller.getPreferencesForDid()).analyticsEnabled).toBe(false);
+        expect(state.saved).toMatchObject({ analyticsEnabled: false, isMinor: true });
+        state.profile.dob = '1990-01-01';
+        expect(await caller.getPreferencesForDid()).toMatchObject({
+            analyticsEnabled: false,
+            isMinor: false,
+        });
+        expect(state.saved.analyticsEnabled).toBe(false);
+    });
+
+    it('re-evaluates trusted country and DOB on every direct API request', async () => {
+        state.profile = { dob: '2010-10-29', country: 'FR' };
+        await caller.updatePreferences({ analyticsEnabled: true });
+        expect((await caller.getPreferencesForDid()).analyticsEnabled).toBe(true);
+        state.profile.country = 'US';
+        expect((await caller.getPreferencesForDid()).analyticsEnabled).toBe(false);
+        expect(state.saved.analyticsEnabled).toBe(false);
+        await caller.updatePreferences({ analyticsEnabled: true });
+        expect(state.saved.analyticsEnabled).toBe(false);
+        state.profile.dob = '2000-01-01';
+        await caller.updatePreferences({ analyticsEnabled: true });
+        expect((await caller.getPreferencesForDid()).analyticsEnabled).toBe(true);
+    });
+
+    it.each([
+        [{ dob: undefined }, true],
+        [{ dob: '' }, true],
+        [{ dob: '1990-01-01', type: 'child' }, false],
+        [{ dob: '2030-01-01' }, false],
+        [{ dob: 'not-a-date' }, false],
+    ])(
+        'honors legacy absent DOB and fails closed for child/invalid/future profiles: %j',
+        async (profile, allowed) => {
+            state.profile = profile;
+            await caller.updatePreferences({ analyticsEnabled: true });
+            expect((await caller.getPreferencesForDid()).analyticsEnabled).toBe(allowed);
+            expect(state.saved.analyticsEnabled).toBe(allowed);
+        }
+    );
+
+    it('keeps preferences available and analytics transiently off when age authority is unknown', async () => {
+        state.saved = {
+            theme: ThemeEnum.Formal,
+            aiEnabled: true,
+            analyticsEnabled: true,
+            isMinor: false,
+        };
+        state.profileUnavailable = true;
+        await expect(caller.getPreferencesForDid()).resolves.toMatchObject({
+            theme: ThemeEnum.Formal,
+            aiEnabled: true,
+            analyticsEnabled: false,
+        });
+        expect(state.saved.analyticsEnabled).toBe(true);
+        await expect(
+            caller.updatePreferences({ theme: ThemeEnum.Colorful, aiEnabled: false })
+        ).resolves.toBe(true);
+        expect(state.saved).toMatchObject({
+            theme: ThemeEnum.Colorful,
+            aiEnabled: false,
+            analyticsEnabled: true,
+        });
+        await caller.updatePreferences({ analyticsEnabled: false, isMinor: true });
+        expect(state.saved).toMatchObject({ analyticsEnabled: false, isMinor: false });
+    });
+    it('rejects opt-in under unknown authority before applying mixed changes', async () => {
+        state.profileUnavailable = true;
+        await expect(
+            caller.updatePreferences({ theme: ThemeEnum.Formal, analyticsEnabled: true })
+        ).rejects.toMatchObject({ code: 'SERVICE_UNAVAILABLE' });
+        expect(state.saved).toEqual({ theme: ThemeEnum.Colorful });
+    });
+
+    it.each(['throw', 'return-false'] as const)(
+        'returns fail-closed preferences on %s repair failure, then retries repair',
+        async failure => {
+            state.profile = { dob: '2012-01-01', country: 'US' };
+            state.saved = { theme: ThemeEnum.Formal, analyticsEnabled: true };
+            state.repairFailure = failure;
+            await expect(caller.getPreferencesForDid()).resolves.toMatchObject({
+                theme: ThemeEnum.Formal,
+                analyticsEnabled: false,
+                isMinor: true,
+            });
+            expect(state.saved.analyticsEnabled).toBe(true);
+            state.repairFailure = null;
+            await caller.getPreferencesForDid();
+            expect(state.saved).toMatchObject({ analyticsEnabled: false, isMinor: true });
+        }
+    );
+
+    it('allows onboarding theme writes without a profile and rejects forged analytics authority', async () => {
+        state.profileUnavailable = true;
+        await expect(caller.createPreferences({ theme: ThemeEnum.Formal })).resolves.toBe(true);
+        await expect(
+            caller.updatePreferences({
+                analyticsEnabled: true,
+                analyticsAutoDisabled: false,
+                isMinor: false,
+            })
+        ).rejects.toMatchObject({ code: 'SERVICE_UNAVAILABLE' });
+        expect(state.saved).toEqual({ theme: ThemeEnum.Formal });
+    });
+
+    it('repairs a known minor and restores adult authorization after authority recovers', async () => {
+        state.saved = { theme: ThemeEnum.Formal, analyticsEnabled: true };
+        state.profile = { dob: '2012-01-01', country: 'US' };
+        await caller.getPreferencesForDid();
+        expect(state.saved).toMatchObject({ analyticsEnabled: false, isMinor: true });
+        state.profileUnavailable = true;
+        await caller.getPreferencesForDid();
+        expect(state.saved.analyticsEnabled).toBe(false);
+        state.profileUnavailable = false;
+        state.profile = { dob: '1990-01-01', country: 'US' };
+        await caller.updatePreferences({ analyticsEnabled: true });
+        expect(state.saved).toMatchObject({ analyticsEnabled: true, isMinor: false });
+    });
+});

package/src/routes/preferences.ts

@@ -1,5 +1,8 @@
 import { z } from 'zod';
 
+import { getCurrentProfile } from '@helpers/currentProfile';
+import { isAnalyticsRestricted } from '@helpers/analyticsEligibility';
+
 import { t, didAndChallengeRoute } from '@routes';
 import { createPreferences } from '@accesslayer/preferences/create';
 import { TRPCError } from '@trpc/server';
@@ -71,7 +74,27 @@ export const preferencesRouter = t.router({
         .input(preferencesInputSchema)
         .output(z.boolean())
         .mutation(async ({ input, ctx }) => {
-            const success = await updatePreferences(ctx.user.did, input);
+            const profile = await getCurrentProfile(ctx);
+            const restricted = profile !== null && isAnalyticsRestricted(profile);
+            // Age-derived metadata is server-owned, not a caller assertion.
+            const safeInput: typeof input = { ...input };
+            if (profile !== null) {
+                safeInput.isMinor = restricted;
+                safeInput.analyticsAutoDisabled = restricted;
+                if (restricted) safeInput.analyticsEnabled = false;
+            } else {
+                // Unknown authority cannot grant opt-in or persist fabricated age metadata.
+                delete safeInput.isMinor;
+                delete safeInput.analyticsAutoDisabled;
+                if (safeInput.analyticsEnabled === true) {
+                    throw new TRPCError({
+                        code: 'SERVICE_UNAVAILABLE',
+                        message:
+                            'Analytics settings are temporarily unavailable. Please try again.',
+                    });
+                }
+            }
+            const success = await updatePreferences(ctx.user.did, safeInput);
 
             if (!success) {
                 throw new TRPCError({
@@ -96,16 +119,43 @@ export const preferencesRouter = t.router({
         .input(z.void())
         .output(preferencesOutputSchema)
         .query(async ({ ctx }) => {
+            const profile = await getCurrentProfile(ctx);
+            const restricted = profile !== null && isAnalyticsRestricted(profile);
             const preferences = await getPreferencesForDid(ctx.user.did);
 
+            if (
+                preferences &&
+                profile !== null &&
+                ((restricted && preferences.analyticsEnabled === true) ||
+                    preferences.isMinor !== restricted ||
+                    (restricted && preferences.analyticsAutoDisabled !== true))
+            ) {
+                try {
+                    const repaired = await updatePreferences(ctx.user.did, {
+                        ...(restricted ? { analyticsEnabled: false } : {}),
+                        isMinor: restricted,
+                        ...(restricted ? { analyticsAutoDisabled: true } : {}),
+                    });
+                    if (!repaired) console.error('Failed to persist age-based preference repair');
+                } catch {
+                    console.error('Failed to persist age-based preference repair');
+                }
+            }
+
             return {
                 theme: preferences?.theme,
                 aiEnabled: preferences?.aiEnabled,
                 aiAutoDisabled: preferences?.aiAutoDisabled,
-                analyticsEnabled: preferences?.analyticsEnabled,
-                analyticsAutoDisabled: preferences?.analyticsAutoDisabled,
+                analyticsEnabled:
+                    profile === null || restricted ? false : preferences?.analyticsEnabled,
+                analyticsAutoDisabled:
+                    profile === null
+                        ? preferences?.analyticsAutoDisabled
+                        : restricted
+                          ? true
+                          : preferences?.analyticsAutoDisabled,
                 bugReportsEnabled: preferences?.bugReportsEnabled,
-                isMinor: preferences?.isMinor,
+                ...(profile === null ? {} : { isMinor: restricted }),
             };
         }),
 });

package/src/services/escrow-enclave/index.ts

@@ -8,6 +8,7 @@ import type { EscrowBlobStaleReason } from '@learncard/types';
 import { SoftwareEnclave } from './softwareEnclave';
 import { createRemoteEnclave } from './remoteEnclave';
 import { pinnedEnclaveCa } from './enclaveTrustAnchors';
+import { emitEnclaveFailureMetric } from './logFailure';
 import { EscrowUnavailableError, type EscrowEnclave } from './types';
 
 export * from './types';
@@ -17,6 +18,27 @@ export * from './notifications';
 
 let enclave: EscrowEnclave | undefined;
 let config: LcaApiEnvironment = environment;
+let remoteConfigMissingReported = false;
+
+/**
+ * Once per container: 'remote' mode without URL/token silently disables escrow
+ * (every escrow call answers 412). On 2026-11-04 a runtime-secrets sync dropped
+ * both keys and nothing said so; this makes it visible in logs and as
+ * `LearnCard/Escrow EnclaveFailure` with `Reason=remote_config_missing`.
+ * Never logs the values, only whether each is present.
+ */
+const reportRemoteConfigMissing = (): void => {
+    if (remoteConfigMissingReported) return;
+    remoteConfigMissingReported = true;
+    console.error(
+        '[escrow] ESCROW_ENCLAVE_MODE=remote but ESCROW_ENCLAVE_REMOTE_URL/TOKEN missing: escrow disabled',
+        {
+            hasUrl: Boolean(config.ESCROW_ENCLAVE_REMOTE_URL),
+            hasToken: Boolean(config.ESCROW_ENCLAVE_REMOTE_TOKEN),
+        }
+    );
+    emitEnclaveFailureMetric('remote_config_missing');
+};
 
 // 'software' config validity is enforced at environment-parse time (see
 // config/environment.ts), so reaching that branch always means it's ready.
@@ -34,15 +56,29 @@ export const isEscrowEnabled = (): boolean => {
         return allowed;
     }
     if (config.ESCROW_ENCLAVE_MODE === 'remote') {
-        return Boolean(config.ESCROW_ENCLAVE_REMOTE_URL && config.ESCROW_ENCLAVE_REMOTE_TOKEN);
+        const ready = Boolean(
+            config.ESCROW_ENCLAVE_REMOTE_URL && config.ESCROW_ENCLAVE_REMOTE_TOKEN
+        );
+        if (!ready) reportRemoteConfigMissing();
+        return ready;
     }
     return false;
 };
+/** Cold-start check so a missing remote config is reported before the first escrow request. */
+export const checkEscrowRemoteConfig = (): void => {
+    if (isEscrowRemoteMode()) isEscrowEnabled();
+};
 export const isEscrowRemoteMode = (): boolean => config.ESCROW_ENCLAVE_MODE === 'remote';
 // The client-facing attestation mode implied by the server's active backend
 // ('remote' mode always attests as 'nitro' — see remoteEnclave.ts).
 export const activeEscrowClientMode = (): 'software' | 'nitro' =>
     isEscrowRemoteMode() ? 'nitro' : 'software';
+/**
+ * The tenant label the (single-tenant) remote enclave signs and requires: server config,
+ * never the request's X-Tenant-Id. App-tenant concerns (hold `tenantId`, email branding,
+ * links) keep using `ctx.tenant`.
+ */
+export const getEscrowAuthorityTenant = (): string => config.ESCROW_AUTHORITY_TENANT;
 export const getEscrowHoldDurationMs = (): number => config.ESCROW_HOLD_DURATION_MS;
 export const getEscrowHoldRestartMinAgeMs = (): number => config.ESCROW_HOLD_RESTART_MIN_AGE_MS;
 export const getEscrowEnclave = (): EscrowEnclave => {
@@ -160,6 +196,7 @@ export const __setEscrowEnclaveForTests = (replacement: EscrowEnclave | undefine
     if (environment.NODE_ENV !== 'test') throw new EscrowUnavailableError();
     config = parseLcaApiEnvironment(process.env);
     enclave = replacement;
+    remoteConfigMissingReported = false;
     attestationCache = undefined;
     attestationRefreshInFlight = undefined;
 };

package/src/services/escrow-enclave/logFailure.ts

@@ -26,7 +26,11 @@ export const logEscrowFailure = (error: unknown): void => {
                     : 'unexpected';
     // lca-api uses structured console warnings rather than the browser logger.
     console.warn('[LCA escrow] enclave operation failed', { reason });
-    // One EMF event alongside the existing warning; no error text, request or identity fields.
+    emitEnclaveFailureMetric(reason);
+};
+
+/** One EMF event per call; `reason` is an allowlisted label, never error text, request or identity fields. */
+export const emitEnclaveFailureMetric = (reason: string): void => {
     console.log(
         JSON.stringify({
             _aws: {

package/src/services/escrow-enclave/production.test.ts

@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import {
     __setEscrowEnclaveForTests,
+    checkEscrowRemoteConfig,
     getEscrowEnclave,
     isEscrowEnabled,
     EscrowUnavailableError,
@@ -32,3 +33,66 @@ describe('software enclave deploy-stage guard', () => {
         }
     );
 });
+
+describe('remote enclave config guard', () => {
+    const metricEvents = (log: { mock: { calls: unknown[][] } }): Record<string, unknown>[] =>
+        log.mock.calls
+            .map(([line]) =>
+                typeof line === 'string' && line.startsWith('{')
+                    ? (JSON.parse(line) as Record<string, unknown>)
+                    : null
+            )
+            .filter((event): event is Record<string, unknown> => event?.EnclaveFailure === 1);
+
+    it.each([
+        ['URL', { ESCROW_ENCLAVE_REMOTE_TOKEN: 'secret-token-value-0123456789abcdef' }],
+        ['token', { ESCROW_ENCLAVE_REMOTE_URL: 'https://escrow.internal:8443' }],
+        ['both', {}],
+    ])('reports a missing %s once per container, without values', (_name, present) => {
+        vi.stubEnv('ESCROW_ENCLAVE_MODE', 'remote');
+        vi.stubEnv('ESCROW_ENCLAVE_REMOTE_URL', '');
+        vi.stubEnv('ESCROW_ENCLAVE_REMOTE_TOKEN', '');
+        for (const [key, value] of Object.entries(present)) vi.stubEnv(key, value);
+        const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+        const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+        __setEscrowEnclaveForTests(undefined);
+
+        checkEscrowRemoteConfig();
+        expect(isEscrowEnabled()).toBe(false);
+        expect(getEscrowEnclave).toThrow(EscrowUnavailableError);
+
+        expect(error).toHaveBeenCalledTimes(1);
+        expect(String(error.mock.calls[0]?.[0])).toContain('ESCROW_ENCLAVE_MODE=remote');
+        expect(JSON.stringify(error.mock.calls)).not.toContain(
+            'secret-token-value-0123456789abcdef'
+        );
+        expect(JSON.stringify(error.mock.calls)).not.toContain('escrow.internal');
+        expect(metricEvents(log)).toEqual([
+            expect.objectContaining({ Reason: 'remote_config_missing', EnclaveFailure: 1 }),
+        ]);
+    });
+
+    it('stays quiet when the remote config is complete', () => {
+        vi.stubEnv('ESCROW_ENCLAVE_MODE', 'remote');
+        vi.stubEnv('ESCROW_ENCLAVE_REMOTE_URL', 'https://escrow.internal:8443');
+        vi.stubEnv('ESCROW_ENCLAVE_REMOTE_TOKEN', 'secret-token-value-0123456789abcdef');
+        const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+        const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+        __setEscrowEnclaveForTests(undefined);
+
+        checkEscrowRemoteConfig();
+        expect(isEscrowEnabled()).toBe(true);
+        expect(error).not.toHaveBeenCalled();
+        expect(metricEvents(log)).toEqual([]);
+    });
+
+    it('does not report when escrow is simply off', () => {
+        vi.stubEnv('ESCROW_ENCLAVE_MODE', '');
+        const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+        __setEscrowEnclaveForTests(undefined);
+
+        checkEscrowRemoteConfig();
+        expect(isEscrowEnabled()).toBe(false);
+        expect(error).not.toHaveBeenCalled();
+    });
+});

package/src/services/escrow-enclave/softwareEnclave.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import {
+    decryptEscrowBlob,
     encryptEscrowBlob,
     generateEscrowKeyPair,
     openEscrowRelease,
@@ -51,7 +52,13 @@ describe('software enclave', () => {
             shareVersion: targetVersion,
             ...(scenario === 'target PIN' ? { pinVerifier } : {}),
         };
-        const targetEnvelope = await encryptEscrowBlob(target, keys.publicKey, 'test');
+        // D21: the owner-sealed email brand must survive the carry re-seal (the
+        // shared parser used to drop unknown plaintext fields).
+        const targetEnvelope = await encryptEscrowBlob(
+            { ...target, recoveryBrand: 'VetPass' },
+            keys.publicKey,
+            'test'
+        );
         const result = enclave.carryPinVerifier({
             sourceEnvelope,
             targetEnvelope,
@@ -68,6 +75,7 @@ describe('software enclave', () => {
         }
         const { envelope } = await result;
         expect(envelope.ciphertext).not.toBe(targetEnvelope.ciphertext);
+        expect((await decryptEscrowBlob(envelope, keys.privateKey)).recoveryBrand).toBe('VetPass');
         expect(
             await enclave.verifyEscrowBlob({ envelope, expectedDid: did, expectedShareVersion: 3 })
         ).toEqual({ ok: true, hasPin: true });
@@ -116,8 +124,9 @@ describe('software enclave', () => {
             const target = { recoveryShare: 'ef'.repeat(33), did, shareVersion: 1 };
             const sourceKeys = scenario === 'current key' ? current : previous;
             const sourceKeyId = scenario === 'current key' ? 'current' : 'previous';
+            // D21: the owner-sealed email brand must survive the rewrap.
             const sourceEnvelope = await encryptEscrowBlob(
-                { ...target, pinVerifier },
+                { ...target, pinVerifier, recoveryBrand: 'VetPass' },
                 sourceKeys.publicKey,
                 sourceKeyId
             );
@@ -141,6 +150,9 @@ describe('software enclave', () => {
             }
             const { envelope } = await result;
             expect(envelope.ciphertext).not.toBe(sourceEnvelope.ciphertext);
+            expect((await decryptEscrowBlob(envelope, current.privateKey)).recoveryBrand).toBe(
+                'VetPass'
+            );
             expect(
                 await enclave.verifyEscrowBlob({
                     envelope,

package/test/jobs/escrowHoldReminders.spec.ts

@@ -209,15 +209,32 @@ describe('runEscrowHoldReminders', () => {
         await runEscrowHoldReminders({ now, limit: 200 });
         const firstRun = await Promise.all(holds.map(hold => findEscrowHoldById(hold._id)));
         expect(firstRun.map(hold => hold?.enclaveCancelAttempts).sort()).toEqual([0, 0, 1, 1]);
-        // UUIDs are ASCII: default string ordering matches Mongo's byte ordering.
-        const unattemptedId = firstRun
+        // UUIDs are ASCII: default string ordering matches Mongo's _id tie-breaker.
+        const unattemptedIds = firstRun
             .filter(hold => hold?.enclaveCancelAttempts === 0)
             .map(hold => hold!._id)
-            .sort()[0]!;
+            .sort();
+        await runEscrowHoldReminders({ now, limit: 1 });
+        const secondRun = await Promise.all(holds.map(hold => findEscrowHoldById(hold._id)));
+        expect((await findEscrowHoldById(unattemptedIds[0]!))?.enclaveCancelAttempts).toBe(1);
+        // Only the first unattempted hold runs; previously attempted holds must not retry.
+        expect(
+            secondRun
+                .filter(hold => unattemptedIds.includes(hold!._id))
+                .map(hold => hold?.enclaveCancelAttempts)
+                .sort()
+        ).toEqual([0, 1]);
+        expect(
+            secondRun
+                .filter(hold => !unattemptedIds.includes(hold!._id))
+                .map(hold => hold?.enclaveCancelAttempts)
+        ).toEqual([1, 1]);
+
+        // The remaining unattempted cancellation must run before any retry, too.
         await runEscrowHoldReminders({ now, limit: 1 });
-        expect((await findEscrowHoldById(unattemptedId))?.enclaveCancelAttempts).toBe(1);
         for (const hold of holds) {
             const stored = await findEscrowHoldById(hold._id);
+            expect(stored?.enclaveCancelAttempts).toBe(1);
             expect(stored?.enclaveCancelPendingAt).toBeInstanceOf(Date);
             expect(stored?.enclaveCancelConfirmedAt).toBeUndefined();
         }