@learncard/cli 3.5.0 → 3.6.0

package/src/demo-refresh-command.test.ts

@@ -0,0 +1,57 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({ direct: vi.fn(), inbox: vi.fn() }));
+
+vi.mock('./demo-refresh', () => ({ runRefreshDemo: mocks.direct }));
+vi.mock('./demo-inbox-refresh', () => ({ runInboxRefreshDemo: mocks.inbox }));
+
+import { runDemoRefreshCommand } from './demo-refresh-command';
+
+beforeEach(() => vi.resetAllMocks());
+
+describe('demo refresh command forwarding', () => {
+    it('routes --inbox to the Universal Inbox demonstration', async () => {
+        mocks.inbox.mockResolvedValue(undefined);
+        const options = { inbox: true, network: 'http://localhost:4000/trpc' };
+        await runDemoRefreshCommand(options);
+        expect(mocks.inbox).toHaveBeenCalledWith(options);
+        expect(mocks.direct).not.toHaveBeenCalled();
+    });
+
+    it('runs the existing direct-send demonstration when --inbox is absent', async () => {
+        mocks.direct.mockResolvedValue(undefined);
+        const options = { network: 'http://localhost:4000/trpc' };
+        await runDemoRefreshCommand(options);
+        expect(mocks.direct).toHaveBeenCalledWith(options);
+        expect(mocks.inbox).not.toHaveBeenCalled();
+    });
+
+    it('rejects --email without --inbox before loading a demo', async () => {
+        await expect(
+            runDemoRefreshCommand({ email: 'owner@example.com', ui: true })
+        ).rejects.toThrow('--email requires --inbox');
+        expect(mocks.inbox).not.toHaveBeenCalled();
+        expect(mocks.direct).not.toHaveBeenCalled();
+    });
+
+    it('rejects --email without --ui', async () => {
+        await expect(
+            runDemoRefreshCommand({ email: 'owner@example.com', inbox: true })
+        ).rejects.toThrow('--email requires --ui');
+        expect(mocks.inbox).not.toHaveBeenCalled();
+        expect(mocks.direct).not.toHaveBeenCalled();
+    });
+
+    it('routes --email with --inbox --ui to the Universal Inbox demonstration', async () => {
+        mocks.inbox.mockResolvedValue(undefined);
+        const options = {
+            inbox: true,
+            ui: true,
+            email: 'owner@example.com',
+            network: 'http://localhost:4000/trpc',
+        };
+        await runDemoRefreshCommand(options);
+        expect(mocks.inbox).toHaveBeenCalledWith(options);
+        expect(mocks.direct).not.toHaveBeenCalled();
+    });
+});

package/src/demo-refresh-command.ts

@@ -0,0 +1,22 @@
+import type { InboxRefreshDemoOptions } from './demo-inbox-refresh';
+
+export type DemoRefreshCommandOptions = InboxRefreshDemoOptions & { inbox?: boolean };
+
+/**
+ * Route `demo refresh` to the direct-send demo, the Universal Inbox demo, or the
+ * opt-in real-email walkthrough. Kept separate so the command-line forwarding is
+ * unit-testable without a live network.
+ */
+export const runDemoRefreshCommand = async (options: DemoRefreshCommandOptions): Promise<void> => {
+    if (options.email !== undefined) {
+        if (!options.inbox) throw new Error('--email requires --inbox.');
+        if (!options.ui) throw new Error('--email requires --ui.');
+    }
+    if (options.inbox) {
+        const { runInboxRefreshDemo } = await import('./demo-inbox-refresh');
+        await runInboxRefreshDemo(options);
+        return;
+    }
+    const { runRefreshDemo } = await import('./demo-refresh');
+    await runRefreshDemo(options);
+};

package/src/demo-refresh-ui.test.ts

@@ -0,0 +1,66 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getRefreshDemoUiConfig } from './demo-refresh-ui';
+
+const apis = {
+    brainService: 'http://localhost:4000/trpc',
+    cloudService: 'http://localhost:4100/trpc',
+    lcaApi: 'http://localhost:5200/trpc',
+    notificationsEndpoint: 'http://localhost:5200/api/notifications/send',
+};
+afterEach(() => vi.unstubAllGlobals());
+const serve = (overrides = {}) => {
+    const fetch = vi
+        .fn()
+        .mockResolvedValue(new Response(JSON.stringify({ apis: { ...apis, ...overrides } })));
+    vi.stubGlobal('fetch', fetch);
+    return fetch;
+};
+describe('UI demo preflight', () => {
+    it('explains how to recover when the app is not running', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('ECONNREFUSED')));
+        await expect(
+            getRefreshDemoUiConfig('http://localhost:3000', apis.brainService)
+        ).rejects.toThrow('Start the LearnCard app in local development mode');
+    });
+    it('uses the running app’s actual cloud and notification ports', async () => {
+        const fetch = serve();
+        expect(
+            await getRefreshDemoUiConfig('http://localhost:3001', 'http://localhost:4000/trpc')
+        ).toEqual({
+            appOrigin: 'http://localhost:3001',
+            cloud: apis.cloudService,
+            lcaApi: apis.lcaApi,
+            notificationsWebhook: apis.notificationsEndpoint,
+        });
+        expect(fetch.mock.calls[0]![0].href).toBe('http://localhost:3001/tenant-config.json');
+        expect(fetch.mock.calls[0]![1]!.redirect).toBe('error');
+    });
+    it.each([
+        'https://learncard.app',
+        'http://localhost.evil.example',
+        'http://user:pass@localhost:3000',
+        'file:///tmp/app',
+    ])('rejects nonlocal or credential-bearing app URL %s before fetching', async app => {
+        const fetch = serve();
+        await expect(getRefreshDemoUiConfig(app, apis.brainService)).rejects.toThrow('loopback');
+        expect(fetch).not.toHaveBeenCalled();
+    });
+    it.each([
+        { brainService: 'http://localhost:9999/trpc' },
+        { cloudService: 'https://cloud.learncard.com/trpc' },
+        { notificationsEndpoint: 'https://api.learncard.app/api/notifications/send' },
+        { notificationsEndpoint: 'http://localhost:5100/api/notifications/send' },
+    ])('rejects mismatched or nonlocal services: %j', async overrides => {
+        serve(overrides);
+        await expect(
+            getRefreshDemoUiConfig('http://localhost:3000', apis.brainService)
+        ).rejects.toThrow();
+    });
+    it('derives the webhook from the app API when no override is present', async () => {
+        serve({ notificationsEndpoint: undefined });
+        expect(
+            (await getRefreshDemoUiConfig('http://localhost:3000', apis.brainService))
+                .notificationsWebhook
+        ).toBe(apis.notificationsEndpoint);
+    });
+});

package/src/demo-refresh-ui.ts

@@ -0,0 +1,65 @@
+export const requireLoopbackUrl = (value: unknown, label: string): URL => {
+    try {
+        if (typeof value !== 'string') throw new Error();
+        const url = new URL(value);
+        if (
+            !['http:', 'https:'].includes(url.protocol) ||
+            !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname) ||
+            url.username ||
+            url.password ||
+            url.search ||
+            url.hash
+        )
+            throw new Error();
+        return url;
+    } catch {
+        throw new Error(
+            `${label} must be an HTTP(S) loopback URL without credentials, query, or fragment.`
+        );
+    }
+};
+
+/** Check the running app before creating accounts or showing a demo sign-in secret. */
+export const getRefreshDemoUiConfig = async (
+    appUrl: string,
+    network: string
+): Promise<{ appOrigin: string; cloud: string; lcaApi: string; notificationsWebhook: string }> => {
+    const app = requireLoopbackUrl(appUrl, '--app-url');
+    const backend = requireLoopbackUrl(network, '--network');
+    let config: { apis?: Record<string, unknown> } | null;
+    try {
+        const response = await fetch(new URL('/tenant-config.json', app), {
+            redirect: 'error',
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+        config = (await response.json()) as { apis?: Record<string, unknown> } | null;
+    } catch {
+        throw new Error(
+            'Could not read the local app configuration. Start the LearnCard app in local development mode and check --app-url.'
+        );
+    }
+    const configuredNetwork = requireLoopbackUrl(config?.apis?.brainService, 'App Brain service');
+    if (configuredNetwork.href.replace(/\/$/, '') !== backend.href.replace(/\/$/, '')) {
+        throw new Error(
+            'The app and CLI must use the same Brain service. Set --network to the app’s local Brain URL.'
+        );
+    }
+    const cloud = requireLoopbackUrl(config?.apis?.cloudService, 'App LearnCloud service');
+    const api = requireLoopbackUrl(config?.apis?.lcaApi, 'App notification API');
+    const notifications = requireLoopbackUrl(
+        config?.apis?.notificationsEndpoint ?? new URL('/api/notifications/send', api).href,
+        'App notifications endpoint'
+    );
+    if (notifications.origin !== api.origin) {
+        throw new Error(
+            'The local app’s notification API and notifications endpoint must use the same origin.'
+        );
+    }
+    return {
+        appOrigin: app.origin,
+        cloud: cloud.href,
+        lcaApi: api.href,
+        notificationsWebhook: notifications.href,
+    };
+};

package/src/demo-refresh.test.ts

@@ -0,0 +1,140 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+const mocks = vi.hoisted(() => ({
+    init: vi.fn(),
+    question: vi.fn(),
+    close: vi.fn(),
+    log: vi.fn(),
+    set: vi.fn(),
+    preflight: vi.fn(),
+}));
+vi.mock('@learncard/init', () => ({ initLearnCard: mocks.init }));
+vi.mock('@learncard/types', () => ({
+    VCValidator: {
+        parse: (v: unknown) => v,
+        safeParse: (v: unknown) => ({ success: true, data: v }),
+    },
+}));
+vi.mock('node:readline/promises', () => ({
+    createInterface: () => ({ question: mocks.question, close: mocks.close }),
+}));
+vi.mock('./out', () => ({ out: { log: mocks.log, set: mocks.set } }));
+vi.mock('./project', () => ({ resolveServices: (_: unknown, network: string) => ({ network }) }));
+vi.mock('./demo-refresh-ui', () => ({ getRefreshDemoUiConfig: mocks.preflight }));
+import { runRefreshDemo } from './demo-refresh';
+const oldTTY = process.stdin.isTTY;
+const oldYes = process.env.LC_YES;
+beforeEach(() => {
+    vi.resetAllMocks();
+    Object.defineProperty(process.stdin, 'isTTY', { value: true, configurable: true });
+    delete process.env.LC_YES;
+});
+afterEach(() => {
+    Object.defineProperty(process.stdin, 'isTTY', { value: oldTTY, configurable: true });
+    if (oldYes === undefined) delete process.env.LC_YES;
+    else process.env.LC_YES = oldYes;
+});
+describe('interactive frontend refresh demonstration', () => {
+    it.each([{ yes: true }, { json: true }])(
+        'rejects auto-advance flags before creating accounts: %j',
+        async flags => {
+            await expect(runRefreshDemo({ ui: true, ...flags })).rejects.toThrow(
+                'interactive terminal'
+            );
+            expect(mocks.init).not.toHaveBeenCalled();
+            expect(mocks.preflight).not.toHaveBeenCalled();
+        }
+    );
+    it('rejects piped input and LC_YES=1', async () => {
+        Object.defineProperty(process.stdin, 'isTTY', { value: false, configurable: true });
+        await expect(runRefreshDemo({ ui: true })).rejects.toThrow('interactive terminal');
+        Object.defineProperty(process.stdin, 'isTTY', { value: true, configurable: true });
+        process.env.LC_YES = '1';
+        await expect(runRefreshDemo({ ui: true })).rejects.toThrow('interactive terminal');
+        expect(mocks.init).not.toHaveBeenCalled();
+    });
+    it('waits for real app saves and never accepts or refreshes on the holder’s behalf', async () => {
+        mocks.preflight.mockResolvedValue({
+            appOrigin: 'http://localhost:3000',
+            cloud: 'http://localhost:4100/trpc',
+            notificationsWebhook: 'http://localhost:5200/api/notifications/send',
+        });
+        let prompts = 0;
+        mocks.question.mockImplementation(async () => {
+            prompts++;
+            return '';
+        });
+        const original = { id: 'urn:uuid:demo', name: 'Provisional Course Certificate' };
+        const final = { ...original, name: 'Final Course Certificate' };
+        const issuer = {
+            id: { did: () => 'did:key:issuer' },
+            invoke: {
+                createProfile: vi.fn(),
+                createBoost: vi.fn().mockResolvedValue('boost:demo'),
+                sendBoost: vi.fn().mockResolvedValue({
+                    credentialUri: 'credential:demo',
+                    refresh: {
+                        credentialId: original.id,
+                        refreshId: 'refresh:demo',
+                        issuerDid: 'did:key:issuer',
+                        holderDid: 'did:key:holder',
+                        refreshService: { id: 'http://localhost:4000/refresh/demo' },
+                    },
+                }),
+                issueCredential: vi.fn(async v => v),
+                publishCredentialRefresh: vi.fn(async () => {
+                    expect(prompts).toBe(4);
+                    return { version: 2 };
+                }),
+            },
+        };
+        const holder = {
+            invoke: {
+                createProfile: vi.fn(),
+                acceptCredential: vi.fn(),
+                refreshCredential: vi.fn(),
+                verifyCredential: vi
+                    .fn()
+                    .mockResolvedValue({ checks: ['proof'], errors: [], warnings: [] }),
+            },
+            index: {
+                LearnCloud: {
+                    get: vi.fn(async () => (prompts < 4 ? [] : [{ uri: 'stored:demo' }])),
+                },
+            },
+            read: {
+                get: vi.fn(async (uri: string) =>
+                    uri === 'stored:demo' && prompts >= 6 ? final : original
+                ),
+            },
+        };
+        mocks.init.mockResolvedValueOnce(issuer).mockResolvedValueOnce(holder);
+        await runRefreshDemo({ ui: true });
+        // Full certificate views render the nested achievement, not the thumbnail title.
+        const sentAchievement =
+            issuer.invoke.createBoost.mock.calls[0]![0].credentialSubject.achievement;
+        const updatedAchievement =
+            issuer.invoke.issueCredential.mock.calls[0]![0].credentialSubject.achievement;
+        expect(sentAchievement.name).toContain('Provisional Results');
+        expect(sentAchievement.description).toContain('Final grade: Pending');
+        expect(sentAchievement.description).not.toContain('Course completed');
+        expect(updatedAchievement.name).toContain('Final Results');
+        expect(updatedAchievement.description).toContain('Final grade: A');
+        expect(updatedAchievement.id).toBe(sentAchievement.id);
+        expect(holder.invoke.acceptCredential).not.toHaveBeenCalled();
+        expect(holder.invoke.refreshCredential).not.toHaveBeenCalled();
+        expect(holder.invoke.verifyCredential).toHaveBeenCalledWith(final);
+        expect(holder.index.LearnCloud.get).toHaveBeenCalledTimes(4);
+        expect(holder.invoke.createProfile).toHaveBeenCalledWith(
+            expect.objectContaining({
+                notificationsWebhook: 'http://localhost:5200/api/notifications/send',
+            })
+        );
+        expect(mocks.log.mock.calls.flat().join('\n')).toMatch(
+            /http:\/\/localhost:3000\/developer\/sign-in\?next=%2Fpassport#seed=[0-9a-f]{64}/
+        );
+        expect(mocks.set).toHaveBeenCalledWith(
+            expect.objectContaining({ ui: true, status: 'updated', sameCredentialId: true })
+        );
+        expect(mocks.close).toHaveBeenCalled();
+    });
+});

package/src/demo-refresh.ts

@@ -0,0 +1,309 @@
+import { randomUUID } from 'node:crypto';
+import { createInterface } from 'node:readline/promises';
+import { initLearnCard } from '@learncard/init';
+import { VCValidator, type UnsignedVC } from '@learncard/types';
+import { generateRandomSeed } from './random';
+import { out } from './out';
+import { resolveServices } from './project';
+import { getRefreshDemoUiConfig } from './demo-refresh-ui';
+
+export interface RefreshDemoOptions {
+    network?: string;
+    yes?: boolean;
+    json?: boolean;
+    didkit?: Promise<Buffer>;
+    ui?: boolean;
+    appUrl?: string;
+}
+
+const LOCAL_NETWORK = 'http://localhost:4000/trpc';
+const BEFORE = 'Provisional Course Certificate';
+const AFTER = 'Final Course Certificate';
+
+/** A real sendBoost lifecycle, narrated for a presenter with no SDK setup required. */
+export const runRefreshDemo = async (options: RefreshDemoOptions): Promise<void> => {
+    // Use fresh demo identities, independent of the presenter's .env and account.
+    const { network } = resolveServices({}, options.network || LOCAL_NETWORK, {});
+    const networkUrl = new URL(network);
+    const local = ['localhost', '127.0.0.1', '[::1]'].includes(networkUrl.hostname);
+    const interactive =
+        !options.yes && !options.json && !!process.stdin.isTTY && process.env.LC_YES !== '1';
+    if (options.ui && !interactive) {
+        throw new Error(
+            '--ui requires an interactive terminal; omit --yes, --json, and LC_YES=1 so you can claim and refresh in the app.'
+        );
+    }
+    if (options.appUrl && !options.ui) throw new Error('--app-url requires --ui.');
+    const ui = options.ui
+        ? await getRefreshDemoUiConfig(options.appUrl ?? 'http://localhost:3000', network)
+        : undefined;
+    const prompts = interactive
+        ? createInterface({ input: process.stdin, output: process.stdout })
+        : undefined;
+    const pause = async (next: string): Promise<void> => {
+        if (prompts) await prompts.question(`\nPress Enter to ${next}... `);
+    };
+    let step = 'connect to the demo network';
+
+    try {
+        out.log('\nLearnCard: watch a credential refresh\n');
+        out.log(`Network: ${network}`);
+        out.log('This creates two demo accounts and a badge on this network.');
+        out.log(
+            ui
+                ? 'The recipient signs into the local app; keep this terminal open until the demo finishes.'
+                : 'Account keys stay in this session; rerunning creates a fresh demonstration.'
+        );
+        await pause('start');
+        out.log('\nSetting up the issuer and recipient...');
+
+        // Trust the explicitly selected demo network for Boost verification.
+        const config = {
+            network,
+            ...(ui && { cloud: { url: ui.cloud } }),
+            ...(options.didkit && { didkit: options.didkit }),
+            trustedBoostRegistry: `data:application/json,${encodeURIComponent(
+                JSON.stringify([
+                    {
+                        id: 'Refresh demo network',
+                        url: networkUrl.origin,
+                        did: `did:web:${encodeURIComponent(networkUrl.host)}`,
+                    },
+                ])
+            )}`,
+        };
+        const issuer = await initLearnCard({ ...config, seed: generateRandomSeed(), network });
+        const holderSeed = generateRandomSeed();
+        const holder = await initLearnCard({ ...config, seed: holderSeed, network });
+        const suffix = randomUUID().slice(0, 8);
+        const recipientProfileId = `refresh-learner-${suffix}`;
+        await issuer.invoke.createProfile({
+            profileId: `refresh-issuer-${suffix}`,
+            displayName: 'Refresh Demo School',
+            bio: '',
+            shortBio: '',
+        });
+        await holder.invoke.createProfile({
+            profileId: recipientProfileId,
+            displayName: 'Refresh Demo Learner',
+            bio: '',
+            shortBio: '',
+            ...(ui && { notificationsWebhook: ui.notificationsWebhook, locale: 'en' }),
+        });
+
+        const template = {
+            '@context': [
+                'https://www.w3.org/ns/credentials/v2',
+                'https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json',
+                'https://ctx.learncard.com/boosts/1.0.1.json',
+            ],
+            type: ['VerifiableCredential', 'OpenBadgeCredential', 'BoostCredential'],
+            name: BEFORE,
+            issuer: issuer.id.did(),
+            credentialSubject: {
+                type: ['AchievementSubject'],
+                achievement: {
+                    id: `urn:uuid:${randomUUID()}`,
+                    type: ['Achievement'],
+                    name: 'Introduction to Biology — Provisional Results',
+                    description:
+                        'Coursework submitted. Final grade: Pending. Results await review.',
+                    criteria: {
+                        narrative:
+                            'Final results require review of coursework and the final assessment.',
+                    },
+                },
+            },
+        } satisfies UnsignedVC;
+
+        if (ui) {
+            const login = new URL('/developer/sign-in', ui.appOrigin);
+            login.searchParams.set('next', '/passport');
+            login.hash = `seed=${holderSeed}`;
+            out.log(`\nOpen this link to sign in as Refresh Demo Learner:\n${login.href}`);
+            out.log(
+                'This link controls a disposable demo account. Keep it private and use it only for test data.'
+            );
+            out.log('If already signed in, choose the demo account switch. Keep the app open.');
+            await pause('send the certificate after signing in');
+        }
+
+        step = 'send the refreshable badge';
+        out.log('\n1 / 3  SEND A BADGE');
+        out.log('Sending through sendBoost with refresh enabled...');
+        const boostUri = await issuer.invoke.createBoost(template, { category: 'Achievement' });
+        const sent = await issuer.invoke.sendBoost(recipientProfileId, boostUri, {
+            enableRefresh: true,
+        });
+        if (!sent?.refresh) throw new Error('The SDK did not return a refresh receipt.');
+        const { credentialUri, refresh } = sent;
+        if (!ui && !(await holder.invoke.acceptCredential(credentialUri))) {
+            throw new Error('The recipient could not accept the badge.');
+        }
+        const original = VCValidator.parse(await holder.read.get(credentialUri));
+        if (original.name !== BEFORE) throw new Error('The delivered badge did not match.');
+        out.log(`Recipient sees: "${original.name}"`);
+
+        const readAppCredential = async () => {
+            const records = await holder.index.LearnCloud.get({});
+            for (const record of records ?? []) {
+                const parsed = VCValidator.safeParse(await holder.read.get(record.uri));
+                if (parsed.success && parsed.data.id === refresh.credentialId) return parsed.data;
+            }
+            return undefined;
+        };
+
+        if (ui) {
+            out.log('\nIn the app: reload if needed, open Alerts, then Claim → Accept.');
+            out.log('Find Provisional Course Certificate under Passport → Achievements.');
+            out.log(
+                'Open it: the full certificate shows Provisional Results and Final grade: Pending.'
+            );
+            let claimed = false;
+            do {
+                await pause('confirm the certificate is saved in the app and publish its update');
+                claimed = Boolean(await readAppCredential());
+                if (!claimed) {
+                    out.log(
+                        'The certificate is not saved in the demo account yet. Finish Claim → Accept in the app first.'
+                    );
+                }
+            } while (!claimed);
+        }
+
+        if (!ui) await pause('publish the final certificate');
+        step = 'publish the updated certificate';
+        out.log('\n2 / 3  PUBLISH AN UPDATE');
+        out.log('The school finalizes the certificate...');
+        // Rebuild solely from the issuer's own claims and the sendBoost receipt.
+        // The issuer cannot read the credential encrypted for the recipient.
+        const updated = await issuer.invoke.issueCredential({
+            ...template,
+            name: AFTER,
+            id: refresh.credentialId,
+            issuer: refresh.issuerDid,
+            boostId: boostUri,
+            validFrom: new Date().toISOString(),
+            refreshService: refresh.refreshService,
+            ...(refresh.credentialStatus && { credentialStatus: refresh.credentialStatus }),
+            credentialSubject: {
+                ...template.credentialSubject,
+                id: refresh.holderDid,
+                achievement: {
+                    ...template.credentialSubject.achievement,
+                    name: 'Introduction to Biology — Final Results',
+                    description:
+                        'Course completed. Final grade: A. Coursework and final assessment reviewed.',
+                },
+            },
+        });
+        const published = await issuer.invoke.publishCredentialRefresh({
+            mode: 'issuer-signed',
+            refreshId: refresh.refreshId,
+            signedCredential: updated,
+            updateSummary: 'Final results are ready. Final grade: A.',
+            idempotencyKey: `demo-final-${suffix}`,
+        });
+        if (published.version !== 2) throw new Error('Expected to publish version 2.');
+        out.log('Version 2 is available. No second badge was sent.');
+        out.log(`Recipient's existing copy still says: "${original.name}"`);
+
+        if (ui) {
+            step = 'confirm the app refreshed the certificate';
+            out.log('\n3 / 3  REFRESH IN THE APP');
+            out.log(
+                'Reload the app, open Alerts, and select “Refresh Demo School updated one of your credentials.”'
+            );
+            out.log(
+                'The app should open Final Course Certificate. Its existing Passport entry is updated.'
+            );
+            out.log('The full certificate now shows Final Results and Final grade: A.');
+            let appUpdated = false;
+            do {
+                await pause('confirm the final certificate is visible');
+                const current = await readAppCredential();
+                if (current?.name !== AFTER) {
+                    out.log(
+                        'The app still has the original copy. Tap the update notification and wait for the final certificate.'
+                    );
+                    continue;
+                }
+                const check = await holder.invoke.verifyCredential(current);
+                if (
+                    check.errors.length ||
+                    check.warnings.length ||
+                    !check.checks.includes('proof')
+                ) {
+                    throw new Error('The app’s updated certificate did not pass verification.');
+                }
+                appUpdated = true;
+            } while (!appUpdated);
+            out.log(
+                '\nVerified: the app saved the final certificate under the same credential identity. Sent once.'
+            );
+            out.log(
+                'You can close this terminal; the recipient stays signed in. Rerun --ui for a fresh demo.'
+            );
+            out.set({
+                network,
+                credentialUri,
+                refreshId: refresh.refreshId,
+                before: BEFORE,
+                after: AFTER,
+                version: published.version,
+                status: 'updated',
+                sameCredentialId: true,
+                ui: true,
+            });
+            return;
+        }
+
+        await pause('refresh the recipient’s copy');
+        step = 'refresh the recipient’s copy';
+        out.log('\n3 / 3  REFRESH THE RECIPIENT’S COPY');
+        out.log('Checking for an update and verifying the new credential...');
+        // Local HTTP is allowed only for this generated credential on the selected
+        // loopback origin. Hosted demos retain the SDK's default transport guards.
+        if (local && new URL(refresh.refreshService.id).origin !== networkUrl.origin) {
+            throw new Error('The refresh service does not match the selected local network.');
+        }
+        const refreshed = await holder.invoke.refreshCredential(
+            original,
+            local
+                ? { allowInsecureHttp: true, allowPrivateAddresses: true, maxRedirects: 0 }
+                : undefined
+        );
+        if (refreshed.status !== 'updated') {
+            throw new Error(`Refresh did not return an update (${refreshed.status}).`);
+        }
+        if (refreshed.credential.name !== AFTER || refreshed.credential.id !== original.id) {
+            throw new Error('The refreshed certificate did not match the published update.');
+        }
+        out.log(`\nBefore: "${original.name}"`);
+        out.log(`After:  "${refreshed.credential.name}"`);
+        out.log('Verified update. Same credential identity. Sent once.');
+        out.log(
+            'The updated copy is shown in this session; this demo does not save it in the app.'
+        );
+        out.set({
+            network,
+            credentialUri,
+            refreshId: refresh.refreshId,
+            before: original.name,
+            after: refreshed.credential.name,
+            version: published.version,
+            status: refreshed.status,
+            sameCredentialId: true,
+        });
+    } catch (error) {
+        const detail = error instanceof Error ? error.message.split('\n')[0] : 'Please try again.';
+        throw Object.assign(
+            new Error(
+                `Could not ${step}: ${detail} Use a running network with managed refresh and LC-2198 deployed.`
+            ),
+            { cause: error }
+        );
+    } finally {
+        prompts?.close();
+    }
+};