@learncard/network-plugin 2.13.17 → 2.14.0

package/src/test/index.test.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-explicit-any -- plugin integration mocks intentionally expose dynamic method bags */
 import { generateLearnCard } from '@learncard/core';
 import { getDidKitPlugin } from '@learncard/didkit-plugin';
 import { getDidKeyPlugin } from '@learncard/didkey-plugin';
@@ -16,8 +17,30 @@ vi.mock('@learncard/core', () => ({ generateLearnCard: vi.fn() }));
 vi.mock('@learncard/didkit-plugin', () => ({ getDidKitPlugin: vi.fn() }));
 vi.mock('@learncard/didkey-plugin', () => ({ getDidKeyPlugin: vi.fn() }));
 vi.mock('@learncard/vc-plugin', () => ({ getVCPlugin: vi.fn() }));
-vi.mock('@learncard/helpers', () => ({}));
-vi.mock('@learncard/types', () => ({}));
+vi.mock('@learncard/helpers', () => ({
+    isVC2Format: (credential: any) => {
+        const contexts = credential?.['@context'];
+        const list = Array.isArray(contexts) ? contexts : [contexts];
+
+        return list.includes('https://www.w3.org/ns/credentials/v2');
+    },
+    getCredentialStatusArray: () => [],
+    resolveStorageReadResult: (value: any) => value,
+}));
+vi.mock('@learncard/types', () => ({
+    VCValidator: {
+        parse: (value: any) => {
+            if (!value?.type) throw new Error('Invalid credential');
+            return value;
+        },
+    },
+    UnsignedVCValidator: {
+        spa: async (value: any) => ({
+            success: true,
+            data: typeof value === 'string' ? JSON.parse(value) : value,
+        }),
+    },
+}));
 
 const PROFILE = {
     profileId: 'usera',
@@ -34,12 +57,33 @@ const PROFILE = {
 
 const PROMPT_ID = '00000000-0000-4000-8000-000000000001';
 
+const REFRESH_ID = 'cnVsbGFiZWxseXVuZ3Vlc3NhYmxlcmVmcmVzaGlkMTIzNDU2Nzg';
+const TARGET_DID = 'did:web:network.example:users:userb';
+
+const ALLOCATION = {
+    refreshId: REFRESH_ID,
+    refreshService: {
+        id: `https://network.example/refresh/${REFRESH_ID}`,
+        type: 'LearnCardCredentialRefresh2026',
+        authorization: { type: 'LearnCardDIDAuth' },
+    },
+};
+
+const getUnsignedBoostTemplate = (overrides: Record<string, unknown> = {}) => ({
+    '@context': ['https://www.w3.org/ns/credentials/v2'],
+    type: ['VerifiableCredential', 'BoostCredential'],
+    issuer: 'did:example:template-issuer',
+    validFrom: '2020-01-01T00:00:00.000Z',
+    credentialSubject: { id: 'did:example:template-subject' },
+    ...overrides,
+});
+
 const getMockLearnCard = () =>
     ({
         id: { did: () => PROFILE.did },
         invoke: { getDidAuthVp: vi.fn() },
         debug: vi.fn(),
-    } as any);
+    }) as any;
 
 const getMockClient = (profile: typeof PROFILE | null = PROFILE) => ({
     profile: {
@@ -67,9 +111,59 @@ const getMockClient = (profile: typeof PROFILE | null = PROFILE) => ({
             mutate: vi.fn().mockResolvedValue({ promptId: PROMPT_ID, status: 'CONNECTED' }),
         },
     },
+    boost: {
+        getBoost: { query: vi.fn().mockResolvedValue({ boost: getUnsignedBoostTemplate() }) },
+        sendBoost: { mutate: vi.fn().mockResolvedValue('boost-credential-uri') },
+        allocateCredentialStatus: { mutate: vi.fn().mockResolvedValue([]) },
+    },
+    utilities: {
+        getDid: { query: vi.fn().mockResolvedValue('did:web:network.example') },
+    },
+    credentialRefresh: {
+        allocateCredentialRefresh: { mutate: vi.fn().mockResolvedValue(ALLOCATION) },
+        sendRefreshableCredential: { mutate: vi.fn().mockResolvedValue('managed-credential-uri') },
+        publishCredentialRefresh: {
+            mutate: vi.fn().mockResolvedValue({
+                refreshId: REFRESH_ID,
+                version: 2,
+                publishedAt: '2026-09-02T00:00:00.000Z',
+                notification: 'queued',
+            }),
+        },
+        getCredentialRefreshHistory: {
+            query: vi.fn().mockResolvedValue({
+                records: [
+                    { version: 2, publishedAt: '2026-09-02T00:00:00.000Z' },
+                    { version: 1, publishedAt: '2026-09-01T00:00:00.000Z' },
+                ],
+                hasMore: false,
+            }),
+        },
+    },
 });
 
-let learnCards: Record<string, { learnCard: any }> = {};
+const getMockIssuingLearnCard = () => {
+    const issuedCredentials: any[] = [];
+
+    const learnCard = {
+        id: { did: () => PROFILE.did },
+        invoke: {
+            getDidAuthVp: vi.fn(),
+            getProfile: vi.fn().mockResolvedValue({ profileId: 'userb', did: TARGET_DID }),
+            issueCredential: vi.fn(async (credential: any) => {
+                issuedCredentials.push(credential);
+
+                return { ...credential, proof: { type: 'DataIntegrityProof' } };
+            }),
+            createDagJwe: vi.fn().mockResolvedValue({ ciphertext: 'encrypted' }),
+        },
+        debug: vi.fn(),
+    } as any;
+
+    return { learnCard, issuedCredentials };
+};
+
+const learnCards: Record<string, { learnCard: any }> = {};
 
 const getLearnCard = async (seed = 'a'.repeat(64)) => {
     if (!learnCards[seed]) {
@@ -152,6 +246,313 @@ describe('connection prompt methods', () => {
     });
 });
 
+describe('credential refresh methods', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+
+    it('forwards allocateCredentialRefresh input to the credentialRefresh procedure', async () => {
+        const client = getMockClient();
+        vi.mocked(getBrainClient).mockResolvedValue(client as never);
+        const learnCard = getMockLearnCard();
+        const plugin = await getLearnCardNetworkPlugin(learnCard, 'https://network.example/trpc');
+
+        const input = {
+            holder: { profileId: 'userb', did: TARGET_DID },
+            credentialId: 'urn:uuid:credential-1',
+        };
+
+        await expect(plugin.methods?.allocateCredentialRefresh(learnCard, input)).resolves.toEqual(
+            ALLOCATION
+        );
+        expect(client.credentialRefresh.allocateCredentialRefresh.mutate).toHaveBeenCalledWith(
+            input
+        );
+    });
+
+    it('forwards sendRefreshableCredential to the managed send procedure', async () => {
+        const client = getMockClient();
+        vi.mocked(getBrainClient).mockResolvedValue(client as never);
+        const learnCard = getMockLearnCard();
+        const plugin = await getLearnCardNetworkPlugin(learnCard, 'https://network.example/trpc');
+
+        const signedCredential = {
+            ...getUnsignedBoostTemplate({ id: 'urn:uuid:credential-1' }),
+            proof: { type: 'DataIntegrityProof' },
+        };
+
+        await expect(
+            plugin.methods?.sendRefreshableCredential(
+                learnCard,
+                REFRESH_ID,
+                signedCredential as any
+            )
+        ).resolves.toEqual('managed-credential-uri');
+        expect(client.credentialRefresh.sendRefreshableCredential.mutate).toHaveBeenCalledWith({
+            refreshId: REFRESH_ID,
+            credential: signedCredential,
+            boostUri: undefined,
+        });
+    });
+
+    it('forwards optional boostUri and notification suppression to the managed send procedure', async () => {
+        const client = getMockClient();
+        vi.mocked(getBrainClient).mockResolvedValue(client as never);
+        const learnCard = getMockLearnCard();
+        const plugin = await getLearnCardNetworkPlugin(learnCard, 'https://network.example/trpc');
+
+        const signedCredential = {
+            ...getUnsignedBoostTemplate({ id: 'urn:uuid:credential-1' }),
+            proof: { type: 'DataIntegrityProof' },
+        };
+
+        await plugin.methods?.sendRefreshableCredential(
+            learnCard,
+            REFRESH_ID,
+            signedCredential as any,
+            'did:example:boost:9',
+            true
+        );
+
+        expect(client.credentialRefresh.sendRefreshableCredential.mutate).toHaveBeenCalledWith({
+            refreshId: REFRESH_ID,
+            credential: signedCredential,
+            boostUri: 'did:example:boost:9',
+            skipNotification: true,
+        });
+    });
+
+    it.each([
+        [
+            'issuer-signed',
+            {
+                mode: 'issuer-signed',
+                refreshId: REFRESH_ID,
+                signedCredential: {
+                    ...getUnsignedBoostTemplate({ id: 'urn:uuid:credential-1' }),
+                    proof: { type: 'DataIntegrityProof' },
+                },
+            },
+        ],
+        [
+            'signing-authority',
+            {
+                mode: 'signing-authority',
+                refreshId: REFRESH_ID,
+                credential: getUnsignedBoostTemplate({ id: 'urn:uuid:credential-1' }),
+                signingAuthority: { type: 'http', endpoint: 'https://sa.example', name: 'sa' },
+                updateSummary: 'Updated employer name',
+                idempotencyKey: 'publish-attempt-1',
+            },
+        ],
+    ] as const)(
+        'forwards publishCredentialRefresh %s input and returns the typed result',
+        async (_mode, input) => {
+            const client = getMockClient();
+            vi.mocked(getBrainClient).mockResolvedValue(client as never);
+            const learnCard = getMockLearnCard();
+            const plugin = await getLearnCardNetworkPlugin(
+                learnCard,
+                'https://network.example/trpc'
+            );
+
+            await expect(
+                plugin.methods?.publishCredentialRefresh(learnCard, input as any)
+            ).resolves.toEqual({
+                refreshId: REFRESH_ID,
+                version: 2,
+                publishedAt: '2026-09-02T00:00:00.000Z',
+                notification: 'queued',
+            });
+            expect(client.credentialRefresh.publishCredentialRefresh.mutate).toHaveBeenCalledWith(
+                input
+            );
+        }
+    );
+
+    it('forwards getCredentialRefreshHistory input to the history query', async () => {
+        const client = getMockClient();
+        vi.mocked(getBrainClient).mockResolvedValue(client as never);
+        const learnCard = getMockLearnCard();
+        const plugin = await getLearnCardNetworkPlugin(learnCard, 'https://network.example/trpc');
+
+        const input = { refreshId: REFRESH_ID, cursor: 'cursor-1', limit: 10 };
+
+        await expect(
+            plugin.methods?.getCredentialRefreshHistory(learnCard, input)
+        ).resolves.toEqual({
+            records: [
+                { version: 2, publishedAt: '2026-09-02T00:00:00.000Z' },
+                { version: 1, publishedAt: '2026-09-01T00:00:00.000Z' },
+            ],
+            hasMore: false,
+        });
+        expect(client.credentialRefresh.getCredentialRefreshHistory.query).toHaveBeenCalledWith(
+            input
+        );
+    });
+
+    it.each([
+        [
+            'allocateCredentialRefresh',
+            [{ holder: { did: TARGET_DID }, credentialId: 'urn:uuid:credential-1' }],
+        ],
+        ['sendRefreshableCredential', [REFRESH_ID, getUnsignedBoostTemplate()]],
+        [
+            'publishCredentialRefresh',
+            [
+                {
+                    mode: 'issuer-signed',
+                    refreshId: REFRESH_ID,
+                    signedCredential: getUnsignedBoostTemplate(),
+                },
+            ],
+        ],
+        ['getCredentialRefreshHistory', [{ refreshId: REFRESH_ID }]],
+    ] as const)('runs ensureUser before %s', async (method, args) => {
+        const client = getMockClient(null);
+        vi.mocked(getBrainClient).mockResolvedValue(client as never);
+        const learnCard = getMockLearnCard();
+        const plugin = await getLearnCardNetworkPlugin(learnCard, 'https://network.example/trpc');
+
+        await expect((plugin.methods?.[method] as any)(learnCard, ...args)).rejects.toThrow(
+            'Please make an account first!'
+        );
+
+        const operation = {
+            allocateCredentialRefresh: client.credentialRefresh.allocateCredentialRefresh.mutate,
+            sendRefreshableCredential: client.credentialRefresh.sendRefreshableCredential.mutate,
+            publishCredentialRefresh: client.credentialRefresh.publishCredentialRefresh.mutate,
+            getCredentialRefreshHistory: client.credentialRefresh.getCredentialRefreshHistory.query,
+        }[method];
+        expect(operation).not.toHaveBeenCalled();
+    });
+
+    it('sendBoost with enableRefresh allocates before signing, injects the service, and uses managed storage', async () => {
+        const client = getMockClient();
+        vi.mocked(getBrainClient).mockResolvedValue(client as never);
+        const { learnCard, issuedCredentials } = getMockIssuingLearnCard();
+        const plugin = await getLearnCardNetworkPlugin(learnCard, 'https://network.example/trpc');
+
+        const uri = await plugin.methods?.sendBoost(learnCard, 'userb', 'did:example:boost:1', {
+            enableRefresh: true,
+            skipNotification: true,
+        });
+
+        expect(uri).toEqual('managed-credential-uri');
+
+        // A stable UUID credential ID is generated when the template has none
+        expect(client.credentialRefresh.allocateCredentialRefresh.mutate).toHaveBeenCalledTimes(1);
+        const allocateInput = client.credentialRefresh.allocateCredentialRefresh.mutate.mock
+            .calls[0]?.[0] as any;
+        expect(allocateInput.holder).toEqual({ profileId: 'userb', did: TARGET_DID });
+        expect(allocateInput.credentialId).toMatch(
+            /^urn:uuid:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
+        );
+
+        // Allocation happens before signing so the service lands in the signed payload
+        const allocateOrder =
+            client.credentialRefresh.allocateCredentialRefresh.mutate.mock.invocationCallOrder[0]!;
+        const signOrder = learnCard.invoke.issueCredential.mock.invocationCallOrder[0]!;
+        expect(allocateOrder).toBeLessThan(signOrder);
+
+        // The allocated service and its inline context are injected into the signed credential
+        const signedInput = issuedCredentials[0];
+        expect(signedInput.id).toEqual(allocateInput.credentialId);
+        expect(signedInput.refreshService).toEqual(ALLOCATION.refreshService);
+        expect(signedInput['@context']).toContainEqual(
+            expect.objectContaining({ 'LearnCardCredentialRefresh2026': expect.any(String) })
+        );
+
+        // Dedicated managed-send procedure is used instead of legacy credential storage,
+        // with holder-only server-side encryption (no client-side JWE, no LCN recipient).
+        // The boost URI is forwarded so the issued credential stays linked INSTANCE_OF
+        // the boost for canonical recipient management (including revocation).
+        expect(client.credentialRefresh.sendRefreshableCredential.mutate).toHaveBeenCalledWith({
+            refreshId: REFRESH_ID,
+            credential: expect.objectContaining({
+                id: allocateInput.credentialId,
+                refreshService: ALLOCATION.refreshService,
+                proof: { type: 'DataIntegrityProof' },
+            }),
+            boostUri: 'did:example:boost:1',
+            skipNotification: true,
+        });
+        expect(client.boost.sendBoost.mutate).not.toHaveBeenCalled();
+        expect(learnCard.invoke.createDagJwe).not.toHaveBeenCalled();
+        expect(client.utilities.getDid.query).not.toHaveBeenCalled();
+    });
+
+    it('sendBoost with enableRefresh reuses an existing credential ID', async () => {
+        const client = getMockClient();
+        vi.mocked(getBrainClient).mockResolvedValue(client as never);
+        client.boost.getBoost.query.mockResolvedValue({
+            boost: getUnsignedBoostTemplate({ id: 'urn:uuid:existing-credential-id' }),
+        });
+        const { learnCard } = getMockIssuingLearnCard();
+        const plugin = await getLearnCardNetworkPlugin(learnCard, 'https://network.example/trpc');
+
+        await plugin.methods?.sendBoost(learnCard, 'userb', 'did:example:boost:1', {
+            enableRefresh: true,
+        });
+
+        expect(client.credentialRefresh.allocateCredentialRefresh.mutate).toHaveBeenCalledWith({
+            holder: { profileId: 'userb', did: TARGET_DID },
+            credentialId: 'urn:uuid:existing-credential-id',
+        });
+    });
+
+    it.each([[{ encrypt: true }], [{ encrypt: false }], [true], [false], [undefined]] as const)(
+        'sendBoost without enableRefresh keeps the legacy storage path (options=%j)',
+        async options => {
+            const client = getMockClient();
+            vi.mocked(getBrainClient).mockResolvedValue(client as never);
+            const { learnCard } = getMockIssuingLearnCard();
+            const plugin = await getLearnCardNetworkPlugin(
+                learnCard,
+                'https://network.example/trpc'
+            );
+
+            const uri = await plugin.methods?.sendBoost(
+                learnCard,
+                'userb',
+                'did:example:boost:1',
+                options as any
+            );
+
+            expect(uri).toEqual('boost-credential-uri');
+            expect(client.boost.sendBoost.mutate).toHaveBeenCalledTimes(1);
+            expect(
+                client.credentialRefresh.allocateCredentialRefresh.mutate
+            ).not.toHaveBeenCalled();
+            expect(
+                client.credentialRefresh.sendRefreshableCredential.mutate
+            ).not.toHaveBeenCalled();
+
+            const sentCredential = (client.boost.sendBoost.mutate.mock.calls[0]?.[0] as any)
+                ?.credential;
+            const encrypts =
+                options === undefined ||
+                options === true ||
+                (typeof options === 'object' && options.encrypt);
+
+            if (encrypts) {
+                expect(learnCard.invoke.createDagJwe).toHaveBeenCalledWith(expect.anything(), [
+                    PROFILE.did,
+                    TARGET_DID,
+                    'did:web:network.example',
+                ]);
+                expect(sentCredential).toEqual({ ciphertext: 'encrypted' });
+            } else {
+                expect(learnCard.invoke.createDagJwe).not.toHaveBeenCalled();
+                expect(sentCredential).toEqual(
+                    expect.objectContaining({ proof: { type: 'DataIntegrityProof' } })
+                );
+            }
+        }
+    );
+});
+
 // Skipping until LCN has the updated function and vc-templates can be updated with resolveable VCs.
 describe.skip('LearnCard Network Plugin', () => {
     describe('NetworkLearnCard', () => {
@@ -205,3 +606,36 @@ describe.skip('LearnCard Network Plugin', () => {
         });
     });
 });
+
+it('recovers valid deliveries despite decryption and validation failures on the page', async () => {
+    const client = {
+        ...getMockClient(),
+        inbox: {
+            getMyInboxDeliveries: {
+                query: vi.fn().mockResolvedValue({
+                    records: [
+                        { id: 'bad-decrypt', credential: 'broken' },
+                        { id: 'bad-vc', credential: {} },
+                        { id: 'good', credential: { type: ['VerifiableCredential'] } },
+                    ],
+                    hasMore: true,
+                    cursor: 'good',
+                }),
+            },
+        },
+    };
+    vi.mocked(getBrainClient).mockResolvedValue(client as any);
+    const wallet = getMockLearnCard();
+    wallet.id.keypair = () => ({ publicKey: 'key' });
+    wallet.invoke.decryptDagJwe = vi.fn(async (credential: any) => {
+        if (credential === 'broken') throw new Error('Cannot decrypt');
+        return credential;
+    });
+    const plugin = await getLearnCardNetworkPlugin(wallet, 'https://network.example');
+    expect(await plugin.methods?.recoverInboxCredentials(wallet, {})).toEqual({
+        records: [{ id: 'good', credential: { type: ['VerifiableCredential'] } }],
+        failed: 2,
+        hasMore: true,
+        cursor: 'good',
+    });
+});

package/src/types.ts

@@ -111,6 +111,12 @@ import {
     CredentialActivityStats,
     BitstringCredentialStatusPurpose,
     BitstringCredentialStatusEntry,
+    AllocateCredentialRefreshInput,
+    AllocateCredentialRefreshResult,
+    PublishCredentialRefreshInput,
+    PublishCredentialRefreshResult,
+    GetCredentialRefreshHistoryInput,
+    GetCredentialRefreshHistoryResult,
 } from '@learncard/types';
 import { Plugin } from '@learncard/core';
 import { ProofOptions } from '@learncard/didkit-plugin';
@@ -411,6 +417,47 @@ export type LearnCardNetworkPluginMethods = {
         statusPurposes?: BitstringCredentialStatusPurpose[];
         listSize?: number;
     }) => Promise<BitstringCredentialStatusEntry[]>;
+
+    // Managed Credential Refresh (LC-2117 / LC-2135 / LC-2136)
+
+    /**
+     * Allocates an unguessable managed refresh service for a credential BEFORE it is
+     * signed. The returned `refreshService` descriptor must be injected into the
+     * unsigned credential so it becomes part of the signed payload; `credentialId`
+     * binds the allocation to the credential's stable ID.
+     */
+    allocateCredentialRefresh: (
+        input: AllocateCredentialRefreshInput
+    ) => Promise<AllocateCredentialRefreshResult>;
+    /**
+     * Binds a signed credential to its allocated refresh aggregate. The plaintext VC is
+     * verified server-side and persisted only as a holder-encrypted JWE — the issuer
+     * and the service never retain a readable copy. When the credential was issued from
+     * a boost, pass `boostUri` so the stored instance stays linked INSTANCE_OF the
+     * boost for canonical recipient management (including revocation).
+     */
+    sendRefreshableCredential: (
+        refreshId: string,
+        credential: VC,
+        boostUri?: string,
+        skipNotification?: boolean
+    ) => Promise<string>;
+    /**
+     * Publishes a new immutable version of a refreshable credential and atomically
+     * advances the refresh head. Issuer-signed mode takes a fully signed VC;
+     * signing-authority mode takes updated unsigned claims plus an authorized signing
+     * authority.
+     */
+    publishCredentialRefresh: (
+        input: PublishCredentialRefreshInput
+    ) => Promise<PublishCredentialRefreshResult>;
+    /**
+     * Cursor-paginated, metadata-only issuer audit history for a managed refresh.
+     * Never includes credential bodies or encrypted payloads.
+     */
+    getCredentialRefreshHistory: (
+        input: GetCredentialRefreshHistoryInput
+    ) => Promise<GetCredentialRefreshHistoryResult>;
     revokeBoostRecipient: (
         boostUri: string,
         recipientProfileId: string,
@@ -437,6 +484,16 @@ export type LearnCardNetworkPluginMethods = {
                   skipNotification?: boolean;
                   templateData?: Record<string, unknown>;
                   statusPurposes?: BitstringCredentialStatusPurpose[];
+                  /**
+                   * Opt into a managed refresh service. When true, a stable UUID
+                   * credential ID is generated if the boost template has none, a
+                   * refresh service is allocated BEFORE signing and injected into the
+                   * signed credential, and the credential is sent via the dedicated
+                   * managed-send procedure (holder-encrypted storage only) instead of
+                   * legacy credential storage. The `encrypt` option is ignored in this
+                   * mode — managed storage is always holder-only.
+                   */
+                  enableRefresh?: boolean;
               }
     ) => Promise<string>;
 
@@ -630,12 +687,21 @@ export type LearnCardNetworkPluginMethods = {
     ) => Promise<PaginatedInboxCredentialsType>;
 
     getInboxCredential: (id: string) => Promise<InboxCredentialType | null>;
+    /** Recover and locally decrypt claims for seven days; deduplicate by the stable inbox id. */
+    recoverInboxCredentials: (options?: { limit?: number; cursor?: string }) => Promise<{
+        records: { id: string; credential: VC; expiresAt: string }[];
+        /** Deliveries that could not be decrypted or validated on this page. */
+        failed: number;
+        hasMore: boolean;
+        cursor?: string;
+    }>;
     finalizeInboxCredentials: () => Promise<{
         processed: number;
         claimed: number;
         errors: number;
         guardianPending: number;
         verifiableCredentials: VC[];
+        deliveries: { id: string; credential: VC }[];
     }>;
 
     // Guardian Approval