@learncard/network-brain-service 3.17.0 → 3.19.0

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']);
+    });
+});

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

@@ -0,0 +1,155 @@
+/**
+ * Pure content/recipient decisions for the managed credential-refresh update
+ * email (LC-2198).
+ *
+ * Kept dependency-free (no database, delivery, or model imports) so the
+ * privacy-sensitive decisions — what minimal context is rendered and which
+ * verified contact method is targeted — are exhaustively unit testable.
+ *
+ * Rendering and delivery live in `credential-refresh-email.helpers.ts`.
+ */
+
+/** Upper bound on a persisted credential display title, in characters. */
+export const MAX_CREDENTIAL_DISPLAY_TITLE_LENGTH = 120;
+
+/**
+ * Normalizes an issuer-supplied credential title into a bounded, single-line
+ * string safe to persist and render. Control characters (including newlines)
+ * become spaces, runs of whitespace collapse, and the result is truncated to
+ * `maxLength`. Returns `undefined` for non-strings or values that normalize to
+ * nothing, so callers can fall back to generic copy.
+ */
+export const extractBoundedCredentialDisplayTitle = (
+    value: unknown,
+    maxLength: number = MAX_CREDENTIAL_DISPLAY_TITLE_LENGTH
+): string | undefined => {
+    if (typeof value !== 'string') return undefined;
+
+    // Control characters (C0, DEL, C1) become spaces rather than being dropped.
+    const withoutControlCharacters = Array.from(value, character => {
+        const code = character.charCodeAt(0);
+
+        return code <= 0x1f || (code >= 0x7f && code <= 0x9f) ? ' ' : character;
+    }).join('');
+
+    const sanitized = withoutControlCharacters
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, maxLength)
+        .trim();
+
+    return sanitized.length > 0 ? sanitized : undefined;
+};
+
+/** Minimal shape of a contact method used by the pure selection logic. */
+export type CredentialRefreshEmailContactMethod = {
+    type: string;
+    value: string;
+    isVerified: boolean;
+    isPrimary?: boolean;
+};
+
+/** A profile that may manage the holder, plus its verified contact methods. */
+export type CredentialRefreshEmailManager = {
+    locale?: string;
+    contactMethods: CredentialRefreshEmailContactMethod[];
+};
+
+export type CredentialRefreshEmailTargetParams = {
+    holder: { locale?: string };
+    holderContactMethods: CredentialRefreshEmailContactMethod[];
+    /** Profiles that manage the holder (guardians/managers). Empty = unmanaged. */
+    managers: CredentialRefreshEmailManager[];
+};
+
+export type CredentialRefreshEmailTarget =
+    | {
+          status: 'resolved';
+          kind: 'holder' | 'guardian';
+          locale?: string;
+          contactMethod: { type: 'email'; value: string };
+      }
+    | {
+          status: 'skipped';
+          reason: 'no-verified-holder-email' | 'no-verified-guardian-email';
+      };
+
+const isUsableVerifiedEmail = (contactMethod: CredentialRefreshEmailContactMethod): boolean =>
+    contactMethod.type === 'email' &&
+    contactMethod.isVerified === true &&
+    typeof contactMethod.value === 'string' &&
+    contactMethod.value.trim().length > 0;
+
+const pickVerifiedEmail = (
+    contactMethods: CredentialRefreshEmailContactMethod[]
+): CredentialRefreshEmailContactMethod | undefined => {
+    const verified = contactMethods.filter(isUsableVerifiedEmail);
+
+    return verified.find(contactMethod => contactMethod.isPrimary) ?? verified[0];
+};
+
+/**
+ * Chooses the single verified email that should receive an update notice.
+ *
+ * - Unmanaged holders are emailed at their own verified email (primary preferred).
+ * - Managed holders are NEVER emailed directly: the notice goes to a verified
+ *   manager's email, or is skipped when none is available. Falling back to the
+ *   child's address is intentionally impossible.
+ * - Callers always resolve contact methods from the bound holder profile — the
+ *   original inbox address and any caller-supplied address are never used.
+ */
+export const chooseCredentialRefreshEmailTarget = (
+    params: CredentialRefreshEmailTargetParams
+): CredentialRefreshEmailTarget => {
+    const { holder, holderContactMethods, managers } = params;
+
+    if (managers.length > 0) {
+        const candidates = managers.flatMap(manager =>
+            manager.contactMethods
+                .filter(isUsableVerifiedEmail)
+                .map(contactMethod => ({ manager, contactMethod }))
+        );
+        const chosen =
+            candidates.find(candidate => candidate.contactMethod.isPrimary) ?? candidates[0];
+
+        if (!chosen) return { status: 'skipped', reason: 'no-verified-guardian-email' };
+
+        return {
+            status: 'resolved',
+            kind: 'guardian',
+            locale: chosen.manager.locale,
+            contactMethod: { type: 'email', value: chosen.contactMethod.value },
+        };
+    }
+
+    const contactMethod = pickVerifiedEmail(holderContactMethods);
+
+    if (!contactMethod) return { status: 'skipped', reason: 'no-verified-holder-email' };
+
+    return {
+        status: 'resolved',
+        kind: 'holder',
+        locale: holder.locale,
+        contactMethod: { type: 'email', value: contactMethod.value },
+    };
+};
+
+/**
+ * Builds the minimal template model for `credential-updated`.
+ *
+ * Exactly two optional values are allowed: the issuer display name and the
+ * bounded credential title. No summary, subject, recipient, grade, evidence, or
+ * credential body content can be expressed by this shape.
+ */
+export const buildCredentialUpdatedEmailModel = (params: {
+    issuerDisplayName?: string;
+    credentialTitle?: string;
+}): { issuer?: { name?: string }; credential?: { name?: string } } => {
+    const model: { issuer?: { name?: string }; credential?: { name?: string } } = {};
+    const title = extractBoundedCredentialDisplayTitle(params.credentialTitle);
+
+    if (params.issuerDisplayName) model.issuer = { name: params.issuerDisplayName };
+    if (title) model.credential = { name: title };
+
+    return model;
+};

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

@@ -0,0 +1,201 @@
+import { environment } from '@environment';
+import { generateClaimUrl } from './contact-method.helpers';
+import type { BoostInstance } from '@models';
+import { getBoostById } from '@accesslayer/boost/read';
+import { getContactMethodsForProfile } from '@accesslayer/contact-method/read';
+import {
+    claimCredentialRefreshEmailDelivery,
+    finalizeCredentialRefreshEmailDelivery,
+    getCredentialRefresh,
+} from '@accesslayer/credential-refresh';
+import { getProfilesThatManageAProfile } from '@accesslayer/profile/relationships/read';
+import type { TenantBranding } from '@learncard/email-templates';
+
+import type { CredentialRefreshVersionNode } from 'types/credential-refresh';
+import type { ProfileType } from 'types/profile';
+
+import { ensureCredentialRefreshConstraints } from '../models/credential-refresh-constraints';
+import { getDeliveryService } from '@services/delivery/delivery.factory';
+import {
+    buildCredentialUpdatedEmailModel,
+    chooseCredentialRefreshEmailTarget,
+    extractBoundedCredentialDisplayTitle,
+    type CredentialRefreshEmailContactMethod,
+    type CredentialRefreshEmailManager,
+    type CredentialRefreshEmailTarget,
+} from './credential-refresh-email-content.helpers';
+import { computeCredentialRefreshDeliveryKey } from './credential-refresh-materiality.helpers';
+import { resolveRecipientLocale } from './getRecipientLocale.helpers';
+
+/**
+ * Managed credential-refresh update email (LC-2198).
+ *
+ * Runs independently of the durable in-app/push notification: an email failure
+ * never changes the publication result and never re-enqueues the push event. The
+ * email carries only the minimal context the user approved — issuer display name
+ * and a bounded credential display title — and routes to a verified email of the
+ * bound holder (or a verified guardian when the holder is managed).
+ *
+ * Delivery is at-most-once per configured delivery window, backed by a unique
+ * `CredentialRefreshEmailDelivery` node (see the access layer). A send that fails
+ * after the claim is recorded as `failed`; it is not retried inside the same
+ * window. A later material update in a new window produces a new claim and is the
+ * retry boundary. The window claim is intentionally attempted even when the in-app
+ * notification was already delivered, so the two channels do not share failure.
+ */
+
+export type CredentialRefreshEmailDeliveryOutcome =
+    'sent' | 'duplicate-window' | 'skipped-no-recipient' | 'failed';
+
+/** Resolves the verified email target for the bound holder. Never caller-supplied. */
+export const resolveCredentialRefreshEmailTarget = async (
+    holderProfile: ProfileType
+): Promise<CredentialRefreshEmailTarget> => {
+    const managers = await getProfilesThatManageAProfile(holderProfile.profileId);
+
+    if (managers.length > 0) {
+        const managerContacts: CredentialRefreshEmailManager[] = await Promise.all(
+            managers.map(async manager => ({
+                locale: manager.locale,
+                contactMethods: (await getContactMethodsForProfile(
+                    manager.did
+                )) as CredentialRefreshEmailContactMethod[],
+            }))
+        );
+
+        // Managed holder: only verified guardian emails are eligible. The child's
+        // own address is deliberately not resolved, so it can never be emailed.
+        return chooseCredentialRefreshEmailTarget({
+            holder: { locale: holderProfile.locale },
+            holderContactMethods: [],
+            managers: managerContacts,
+        });
+    }
+
+    const holderContactMethods = (await getContactMethodsForProfile(
+        holderProfile.did
+    )) as CredentialRefreshEmailContactMethod[];
+
+    return chooseCredentialRefreshEmailTarget({
+        holder: { locale: holderProfile.locale },
+        holderContactMethods,
+        managers: [],
+    });
+};
+
+/**
+ * Resolves the bounded email-only title: the persisted publish-input title first,
+ * then the aggregate's coalesced title, then the original boost template name.
+ * The holder-encrypted payload is never decrypted to recover a title.
+ */
+export const resolveCredentialRefreshEmailDisplayTitle = async (params: {
+    version: CredentialRefreshVersionNode;
+    refreshId: string;
+}): Promise<string | undefined> => {
+    const { version, refreshId } = params;
+    const fromVersion = extractBoundedCredentialDisplayTitle(version.credentialDisplayName);
+
+    if (fromVersion) return fromVersion;
+
+    const aggregate = await getCredentialRefresh(refreshId);
+    const fromAggregate = extractBoundedCredentialDisplayTitle(aggregate?.credentialDisplayName);
+
+    if (fromAggregate) return fromAggregate;
+
+    if (!aggregate?.boostId) return undefined;
+
+    const boost: BoostInstance | null = await getBoostById(aggregate.boostId);
+
+    return extractBoundedCredentialDisplayTitle(boost?.name);
+};
+
+/**
+ * Best-effort email delivery for one published version. Never throws: the caller
+ * uses the outcome for observability only, so email can neither undo a
+ * publication nor block the in-app notification path.
+ */
+export const deliverCredentialRefreshEmailNotification = async (params: {
+    version: CredentialRefreshVersionNode;
+    issuerProfile: ProfileType;
+    holderProfile: ProfileType;
+    branding?: Partial<TenantBranding>;
+}): Promise<CredentialRefreshEmailDeliveryOutcome> => {
+    const { version, issuerProfile, holderProfile, branding } = params;
+    const refreshId = version.refreshId;
+
+    try {
+        const target = await resolveCredentialRefreshEmailTarget(holderProfile);
+
+        if (target.status === 'skipped') return 'skipped-no-recipient';
+
+        // Replay the publication's original window, even if the caller retries
+        // tomorrow. Recomputing from the current clock would send duplicate mail.
+        const windowKey =
+            version.notificationDeliveryKey ??
+            computeCredentialRefreshDeliveryKey(
+                refreshId,
+                new Date(version.notificationCreatedAt ?? version.publishedAt)
+            );
+
+        // The email-delivery unique constraint is created on demand: the accept
+        // path can reach this helper without passing through the publish route
+        // middleware that normally ensures credential-refresh constraints.
+        await ensureCredentialRefreshConstraints();
+
+        const claim = await claimCredentialRefreshEmailDelivery({ refreshId, windowKey });
+
+        if (claim === 'duplicate') return 'duplicate-window';
+
+        try {
+            const credentialTitle = await resolveCredentialRefreshEmailDisplayTitle({
+                version,
+                refreshId,
+            });
+
+            await getDeliveryService(target.contactMethod).send({
+                contactMethod: target.contactMethod,
+                templateId: 'credential-updated',
+                templateModel: buildCredentialUpdatedEmailModel({
+                    issuerDisplayName: issuerProfile.displayName,
+                    credentialTitle,
+                }),
+                branding: environment.IS_OFFLINE
+                    ? { ...branding, appUrl: new URL(generateClaimUrl('')).origin }
+                    : branding,
+                locale: target.locale ?? resolveRecipientLocale(holderProfile),
+                messageStream: 'universal-inbox',
+            });
+
+            await finalizeCredentialRefreshEmailDelivery({
+                refreshId,
+                windowKey,
+                state: 'delivered',
+            });
+
+            return 'sent';
+        } catch (error) {
+            console.error('Credential Refresh Email - Failed to deliver update email:', error);
+
+            try {
+                await finalizeCredentialRefreshEmailDelivery({
+                    refreshId,
+                    windowKey,
+                    state: 'failed',
+                });
+            } catch (recordError) {
+                console.error(
+                    'Credential Refresh Email - Failed to record delivery failure:',
+                    recordError
+                );
+            }
+
+            return 'failed';
+        }
+    } catch (error) {
+        // Recipient resolution / claim setup failed. Nothing was sent and no window
+        // was claimed, so a later attempt in the same window may still succeed.
+        console.error('Credential Refresh Email - Delivery setup failed:', error);
+
+        return 'failed';
+    }
+};

package/src/helpers/credential-refresh-proof.helpers.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { VC } from '@learncard/types';
+
+import { verifyManagedRefreshProof } from './credential-refresh-proof.helpers';
+
+const issuer = 'did:web:network.example:users:issuer';
+const credential = {
+    '@context': ['https://www.w3.org/ns/credentials/v2'],
+    type: ['VerifiableCredential'],
+    issuer,
+    credentialSubject: { id: 'did:key:holder' },
+} as VC;
+const valid = { checks: ['proof'], warnings: [], errors: [] };
+const stale = { checks: [], warnings: [], errors: ['No applicable proof'] };
+const makeVerifier = () => ({
+    verifyCredential: vi.fn().mockResolvedValue(valid),
+    resolveDid: vi.fn().mockResolvedValue({ id: issuer }),
+});
+
+describe('managed refresh proof verification', () => {
+    it('keeps the successful path to one proof check without refreshing the resolver', async () => {
+        const verifier = makeVerifier();
+        await verifyManagedRefreshProof(verifier, credential, issuer);
+        expect(verifier.verifyCredential).toHaveBeenCalledExactlyOnceWith(credential, {
+            checks: ['proof'],
+        });
+        expect(verifier.resolveDid).not.toHaveBeenCalled();
+    });
+
+    it('refreshes a stale local issuer document once and re-verifies the same credential', async () => {
+        const verifier = makeVerifier();
+        verifier.verifyCredential.mockResolvedValueOnce(stale).mockResolvedValueOnce(valid);
+        const original = JSON.stringify(credential);
+        await verifyManagedRefreshProof(verifier, credential, issuer);
+        expect(verifier.resolveDid).toHaveBeenCalledExactlyOnceWith(issuer, { noCache: true });
+        expect(verifier.verifyCredential).toHaveBeenCalledTimes(2);
+        expect(verifier.verifyCredential).toHaveBeenNthCalledWith(2, credential, {
+            checks: ['proof'],
+        });
+        expect(verifier.resolveDid.mock.invocationCallOrder[0]).toBeLessThan(
+            verifier.verifyCredential.mock.invocationCallOrder[1]!
+        );
+        expect(JSON.stringify(credential)).toBe(original);
+    });
+
+    it.each([
+        stale,
+        { checks: ['proof'], warnings: ['untrusted proof'], errors: [] },
+        { checks: [], warnings: [], errors: [] },
+        { checks: ['proof'], warnings: [], errors: ['invalid signature'] },
+    ])('still rejects an invalid result after fresh resolution: %j', async failure => {
+        const verifier = makeVerifier();
+        verifier.verifyCredential.mockResolvedValueOnce(stale).mockResolvedValueOnce(failure);
+        await expect(verifyManagedRefreshProof(verifier, credential, issuer)).rejects.toMatchObject(
+            {
+                code: 'BAD_REQUEST',
+            }
+        );
+        expect(verifier.verifyCredential).toHaveBeenCalledTimes(2);
+        expect(verifier.resolveDid).toHaveBeenCalledTimes(1);
+    });
+
+    it.each(['did:key:issuer', 'did:web:elsewhere.example:users:issuer', `${issuer}-other`])(
+        'does not force-resolve an issuer other than the exact local profile: %s',
+        async other => {
+            const verifier = makeVerifier();
+            verifier.verifyCredential.mockResolvedValue(stale);
+            await expect(
+                verifyManagedRefreshProof(verifier, { ...credential, issuer: other }, issuer)
+            ).rejects.toMatchObject({ code: 'BAD_REQUEST' });
+            expect(verifier.resolveDid).not.toHaveBeenCalled();
+            expect(verifier.verifyCredential).toHaveBeenCalledTimes(1);
+        }
+    );
+
+    it.each([false, true])('maps verifier exceptions consistently (retry: %s)', async retry => {
+        const verifier = makeVerifier();
+        const cause = new Error('DIDKit verification failed');
+        if (retry) verifier.verifyCredential.mockResolvedValueOnce(stale);
+        verifier.verifyCredential.mockRejectedValueOnce(cause);
+        await expect(verifyManagedRefreshProof(verifier, credential, issuer)).rejects.toMatchObject(
+            {
+                code: 'BAD_REQUEST',
+                message: 'Credential proof could not be verified',
+                cause,
+            }
+        );
+        expect(verifier.verifyCredential).toHaveBeenCalledTimes(retry ? 2 : 1);
+        expect(verifier.resolveDid).toHaveBeenCalledTimes(retry ? 1 : 0);
+    });
+
+    it('fails closed when the authoritative document cannot be fetched', async () => {
+        const verifier = makeVerifier();
+        verifier.verifyCredential.mockResolvedValue(stale);
+        verifier.resolveDid.mockRejectedValue(new Error('network unavailable'));
+        await expect(verifyManagedRefreshProof(verifier, credential, issuer)).rejects.toMatchObject(
+            {
+                code: 'BAD_REQUEST',
+            }
+        );
+        expect(verifier.verifyCredential).toHaveBeenCalledTimes(1);
+    });
+});