@learncard/cli 3.4.17 → 3.5.1

package/src/token.ts

@@ -0,0 +1,138 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+    connect,
+    ensureIdentity,
+    ensureProfile,
+    loadProject,
+    saveProject,
+    type ProjectOptions,
+    localizeSnippet,
+    resolveServices,
+    withEnvTokenLoader,
+} from './project';
+import { SEND_SH } from './generated/snippets';
+import { out } from './out';
+
+// Route-derived resources documented in auth-grants-and-api-tokens.md (not the stale singular aliases).
+export const SCOPE_RESOURCES = [
+    'boosts',
+    'inbox',
+    'credentials',
+    'presentations',
+    'profiles',
+    'profileManagers',
+    'connections',
+    'contracts',
+    'contracts-data',
+    'signingAuthorities',
+    'authGrants',
+    'didMetadata',
+    'claimHooks',
+    'skills',
+    'app-store',
+    'integrations',
+    'contact-methods',
+    'activity',
+    'storage',
+] as const;
+
+export const validateScope = (scope: string): string => {
+    for (const part of scope.trim().split(/\s+/).filter(Boolean)) {
+        const [resource, action, extra] = part.split(':');
+        if (
+            extra !== undefined ||
+            !resource ||
+            (resource !== '*' && !SCOPE_RESOURCES.some(value => value === resource))
+        ) {
+            throw new Error(
+                `Unknown scope resource in "${part}". Choose: ${SCOPE_RESOURCES.join(', ')}, or *.`
+            );
+        }
+        if (!action || !['read', 'write', 'delete', '*'].includes(action)) {
+            throw new Error(`Invalid action in "${part}". Use read, write, delete, or *.`);
+        }
+    }
+    return scope.trim().split(/\s+/).filter(Boolean).join(' ');
+};
+
+export const runToken = async (
+    options: ProjectOptions & { scope?: string; revoke?: string; expires?: string; list?: boolean }
+): Promise<void> => {
+    const scope = validateScope(options.scope ?? 'boosts:write');
+    const project = await loadProject(process.cwd());
+    const identity = await ensureIdentity(project, { ...options, name: undefined });
+    const learnCard = await connect(project, options);
+    await ensureProfile(learnCard, identity, project);
+    if (options.list) {
+        const grants = (await learnCard.invoke.getAuthGrants()) ?? [];
+        for (const g of grants)
+            out.log(
+                `${g.id}  ${(g.status ?? '').padEnd(8)} ${(g.scope ?? '').padEnd(22)} ${g.name ?? ''}${
+                    g.expiresAt ? `  expires ${g.expiresAt.slice(0, 10)}` : ''
+                }`
+            );
+        if (!grants.length) out.log('No auth grants yet.');
+        out.set({
+            grants: grants.map(g => ({
+                id: g.id,
+                name: g.name,
+                scope: g.scope,
+                status: g.status,
+                expiresAt: g.expiresAt,
+            })),
+        });
+        return;
+    }
+    if (options.revoke) {
+        if (!(await learnCard.invoke.revokeAuthGrant(options.revoke)))
+            throw new Error('Could not revoke auth grant.');
+        out.log(`Revoked auth grant ${options.revoke}.`);
+        out.log('Create a replacement: npx @learncard/cli token');
+        out.set({ grantId: options.revoke });
+        return;
+    }
+    const id = await learnCard.invoke.addAuthGrant({
+        name: options.name ?? `cli-${new Date().toISOString().slice(0, 10)}`,
+        scope,
+        ...(options.expires
+            ? {
+                  expiresAt: new Date(
+                      Date.now() + Number(options.expires) * 86_400_000
+                  ).toISOString(),
+              }
+            : {}),
+    });
+    const token = await learnCard.invoke.getAPITokenForAuthGrant(id);
+    // Tighten existing files before writing the bearer credential.
+    await fs.chmod(project.envPath, 0o600);
+    await saveProject(project, { API_TOKEN: token, API_TOKEN_SCOPE: scope });
+    out.log(`Created auth grant ${id}.`);
+    out.log(
+        "Warning: this token won't be shown again by this command. It is saved in .env; keep it private."
+    );
+    out.log(token);
+    const file = path.join(process.cwd(), 'send.sh');
+    let wroteSendSh = false;
+    try {
+        await fs.writeFile(
+            file,
+            withEnvTokenLoader(
+                localizeSnippet(SEND_SH, resolveServices(project.env, options.network))
+            ),
+            {
+                flag: 'wx',
+                mode: 0o700,
+            }
+        );
+        out.log('Wrote ./send.sh');
+        wroteSendSh = true;
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+        out.log('Kept existing ./send.sh');
+    }
+    out.log(
+        'Next: save your send payload as request.json, then run sh ./send.sh (example: https://docs.learncard.com/start-here/your-first-integration).'
+    );
+    out.set({ grantId: id, scope, token, files: wroteSendSh ? ['./send.sh'] : [] });
+};

package/src/verify.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import { formatVerification, isPresentation, verificationFailed } from './verify';
+
+describe('verification output', () => {
+    it('formats raw checks and errors', () => {
+        const result = {
+            checks: ['expiration'],
+            errors: ['signature error: Bad signature'],
+            warnings: ['Review issuer'],
+        };
+        expect(formatVerification(result)).toEqual([
+            '✓ expiration',
+            '! Review issuer',
+            '✗ proof: Bad signature',
+        ]);
+        expect(verificationFailed(result)).toBe(true);
+    });
+    it('keeps warnings distinct from failures in prettified output', () => {
+        const result = [
+            { status: 'Success' as const, check: 'proof', message: 'Valid' },
+            { status: 'Error' as const, check: 'issuer', message: 'Not checked' },
+        ];
+        expect(formatVerification(result)).toEqual(['✓ proof', '! issuer: Not checked']);
+        expect(verificationFailed(result)).toBe(false);
+        expect(verificationFailed([{ status: 'Failed', check: 'proof', details: 'Invalid' }])).toBe(
+            true
+        );
+    });
+    it('detects presentations by string or array type', () => {
+        expect(isPresentation({ type: ['VerifiablePresentation'] })).toBe(true);
+        expect(isPresentation({ type: 'VerifiablePresentation' })).toBe(true);
+        expect(isPresentation({ type: ['VerifiableCredential'] })).toBe(false);
+        expect(isPresentation(null)).toBe(false);
+    });
+});

package/src/verify.ts

@@ -0,0 +1,66 @@
+import fs from 'node:fs/promises';
+import { initLearnCard } from '@learncard/init';
+import { type VC, type VP, type VerificationCheck, type VerificationItem } from '@learncard/types';
+
+export type VerifyResult = VerificationCheck | VerificationItem[];
+
+export const isPresentation = (value: unknown): boolean => {
+    if (!value || typeof value !== 'object' || !('type' in value)) return false;
+    const types = Array.isArray(value.type) ? value.type : [value.type];
+    return types.includes('VerifiablePresentation');
+};
+
+const checkName = (value: string): string => (value === 'signature' ? 'proof' : value);
+
+export const verificationFailed = (result: VerifyResult): boolean =>
+    Array.isArray(result)
+        ? result.some(item => item.status === 'Failed')
+        : result.errors.length > 0;
+
+export const formatVerification = (result: VerifyResult): string[] => {
+    if (Array.isArray(result))
+        return result.map(item => {
+            const check = checkName(item.check);
+            if (item.status === 'Success') return `✓ ${check}`;
+            return `${item.status === 'Failed' ? '✗' : '!'} ${check}: ${item.details || item.message || 'Check failed'}`;
+        });
+    return [
+        ...result.checks.map(check => `✓ ${checkName(check)}`),
+        ...result.warnings.map(warning => `! ${warning}`),
+        ...result.errors.map(error => {
+            const match = error.match(/^(.+?) error:\s*(.*)$/);
+            return match ? `✗ ${checkName(match[1]!)}: ${match[2]}` : `✗ ${error}`;
+        }),
+    ];
+};
+
+export const runVerify = async (
+    file: string,
+    options: { json?: boolean; didkit?: Promise<Buffer> }
+): Promise<void> => {
+    let text: string;
+    if (file === '-') {
+        const chunks: Buffer[] = [];
+        for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
+        text = Buffer.concat(chunks).toString('utf8');
+    } else text = await fs.readFile(file, 'utf8');
+    const input: unknown = JSON.parse(text);
+    if (!input || typeof input !== 'object' || !('type' in input))
+        throw new Error('Expected a credential or presentation JSON object with a type.');
+    const presentation = isPresentation(input);
+    const types = Array.isArray(input.type) ? input.type : [input.type];
+    if (!presentation && !types.includes('VerifiableCredential'))
+        throw new Error('Expected VerifiableCredential or VerifiablePresentation in type.');
+    const learnCard = await initLearnCard({ ...(options.didkit && { didkit: options.didkit }) });
+    const result = presentation
+        ? await learnCard.invoke.verifyPresentation(input as VP)
+        : options.json
+          ? await learnCard.invoke.verifyCredential(input as VC)
+          : await learnCard.invoke.verifyCredential(input as VC, {}, true);
+    if (options.json) console.log(JSON.stringify(result, null, 2));
+    else {
+        for (const line of formatVerification(result)) console.log(line);
+        console.log('Next: review warnings and issuer trust before accepting this credential.');
+    }
+    if (verificationFailed(result)) process.exitCode = 1;
+};

package/src/webhook.ts

@@ -0,0 +1,247 @@
+import type { Server } from 'node:http';
+import { initLearnCard } from '@learncard/init';
+import {
+    connect,
+    createPrompts,
+    ensureIdentity,
+    ensureProfile,
+    KEYS,
+    loadProject,
+    localizeSnippet,
+    resolveServices,
+    saveProject,
+    type ProjectOptions,
+    PRODUCTION_NETWORK,
+} from './project';
+import { DEFAULT_BADGE, templateCredential } from './send';
+import { WEBHOOK_MJS } from './generated/snippets';
+import { writeSnippet } from './snippet-files';
+import { setupSigning } from './setup-signing';
+import { out } from './out';
+
+interface WebhookModule {
+    extractBearer: (header: unknown) => string | undefined;
+    webhookDedupeKey: (payload: unknown) => string | undefined;
+    createWebhookReceiver: (
+        verifier: {
+            invoke: {
+                verifyPresentation: (
+                    token: string,
+                    options: { proofFormat: 'jwt' }
+                ) => Promise<{ errors: unknown[] }>;
+            };
+        },
+        expectedDid?: string
+    ) => Server;
+}
+
+export const webhookConfig = (
+    env: Record<string, string>,
+    options: { port?: string },
+    runtime: Record<string, string | undefined> = process.env
+): { port: number; expectedDid: string | undefined } => {
+    const port = Number(options.port ?? runtime.PORT ?? env.PORT ?? 8787);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new Error('Port must be 1–65535.');
+    return { port, expectedDid: runtime.EXPECTED_NETWORK_DID ?? env.EXPECTED_NETWORK_DID };
+};
+
+export const closeWebhookReceiver = (server: Server): Promise<void> =>
+    new Promise((resolve, reject) => {
+        // Verification may be waiting on a remote DID. Do not let it block Ctrl+C indefinitely.
+        const timer = setTimeout(() => server.closeAllConnections(), 1000);
+        timer.unref();
+        server.close(error => {
+            clearTimeout(timer);
+            if (error) reject(error);
+            else resolve();
+        });
+    });
+
+/** Execute the embedded, canonical receiver, never a possibly edited file from the cwd. */
+export const loadWebhookModule = async (): Promise<WebhookModule> => {
+    return import(`data:text/javascript;base64,${Buffer.from(WEBHOOK_MJS).toString('base64')}`);
+};
+
+export interface WebhookEvent {
+    type: string;
+    status?: string;
+    issuanceId?: string;
+    recipient?: string;
+}
+
+/** The embedded receiver logs one space-separated line per event: type, status, issuanceId, recipient DID. */
+export const parseWebhookLogLine = (line: string): WebhookEvent | undefined => {
+    const [type, status, issuanceId, recipient] = line.trim().split(/\s+/);
+    if (!type) return undefined;
+    return {
+        type,
+        ...(status && { status }),
+        ...(issuanceId && { issuanceId }),
+        ...(recipient && { recipient }),
+    };
+};
+
+/**
+ * `--json` mode does not stream: intercept the receiver's own console.log lines (never
+ * forwarding them to real stdout) and resolve with everything seen once ISSUANCE_DELIVERED
+ * (and ISSUANCE_CLAIMED, if requested) has arrived, or once the timeout elapses.
+ */
+export const collectWebhookEvents = (
+    timeoutMs: number,
+    waitForClaim: boolean,
+    registerStop?: (stop: () => void) => void
+): Promise<WebhookEvent[]> =>
+    new Promise(resolve => {
+        const events: WebhookEvent[] = [];
+        const originalLog = console.log;
+        const finish = (): void => {
+            clearTimeout(timer);
+            console.log = originalLog;
+            resolve(events);
+        };
+        const timer = setTimeout(finish, Math.max(0, timeoutMs));
+        registerStop?.(finish);
+        console.log = (...args: unknown[]): void => {
+            const [first] = args;
+            const event = typeof first === 'string' ? parseWebhookLogLine(first) : undefined;
+            if (!event) return;
+            events.push(event);
+            const delivered = events.some(e => e.type === 'ISSUANCE_DELIVERED');
+            const claimed = events.some(e => e.type === 'ISSUANCE_CLAIMED');
+            if (delivered && (!waitForClaim || claimed)) finish();
+        };
+    });
+
+export const runWebhook = async (
+    email: string | undefined,
+    options: ProjectOptions & {
+        to?: string;
+        url?: string;
+        port?: string;
+        timeout?: string;
+        waitForClaim?: boolean;
+    }
+): Promise<void> => {
+    const project = await loadProject(process.cwd());
+    const { port, expectedDid } = webhookConfig(project.env, options);
+    const production = resolveServices(project.env, options.network).network === PRODUCTION_NETWORK;
+    if (options.url && production && new URL(options.url).protocol !== 'https:') {
+        throw new Error('--url must be a public HTTPS URL when using the production network.');
+    }
+    const identity = await ensureIdentity(project, options);
+    const learnCard = await connect(project, { ...options, lca: true });
+    await ensureProfile(learnCard, identity, project);
+    const wroteWebhookMjs = await writeSnippet(
+        'webhook.mjs',
+        localizeSnippet(WEBHOOK_MJS, resolveServices(project.env, options.network))
+    );
+    const verifier = await initLearnCard({ ...(options.didkit && { didkit: options.didkit }) });
+    const { createWebhookReceiver } = await loadWebhookModule();
+    const server = createWebhookReceiver(verifier, expectedDid);
+    server.requestTimeout = 5000;
+    await new Promise<void>((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, () => {
+            server.removeListener('error', reject);
+            resolve();
+        });
+    });
+    out.log(`Listening on http://localhost:${port}`);
+    try {
+        if (!options.url) {
+            out.log(
+                `Next: expose port ${port} with ngrok/cloudflared and re-run with --url <publicUrl>. No credential sent.`
+            );
+            out.set({ port, files: wroteWebhookMjs ? ['./webhook.mjs'] : [] });
+            return;
+        }
+        if (!expectedDid) {
+            out.log(
+                'Demo: signatures are verified, but any DID is accepted. Set EXPECTED_NETWORK_DID to your trusted network DID before production.'
+            );
+        }
+        const prompts = createPrompts(options.yes);
+        let recipient: string;
+        try {
+            recipient =
+                email || options.to || (await prompts.ask('Recipient email (--to <email>)', ''));
+        } finally {
+            prompts.close();
+        }
+        if (!recipient) throw new Error('Provide an email argument or --to <email>.');
+        // Template claims need a hosted signer; the demo does not persist signer configuration.
+        await setupSigning(project, learnCard, undefined, { persist: false });
+        if (!project.env[KEYS.TEMPLATE_URI]) {
+            const uri = await learnCard.invoke.createBoost(templateCredential(learnCard.id.did()), {
+                name: DEFAULT_BADGE.name,
+                category: 'Achievement',
+                status: 'LIVE',
+            });
+            await saveProject(project, { [KEYS.TEMPLATE_URI]: uri });
+        }
+        const templateUri = project.env[KEYS.TEMPLATE_URI]!;
+        // Start collecting before send() so an ISSUANCE_DELIVERED that arrives mid-call isn't missed.
+        const timeoutMs = (Number(options.timeout) > 0 ? Number(options.timeout) : 60) * 1000;
+        let stopCollectingEvents: (() => void) | undefined;
+        const eventsPromise = out.json
+            ? collectWebhookEvents(timeoutMs, !!options.waitForClaim, stop => {
+                  stopCollectingEvents = stop;
+              })
+            : undefined;
+        const onServerError = (): void => {};
+        if (eventsPromise) server.on('error', onServerError);
+        const result = await learnCard.invoke
+            .send({
+                type: 'boost',
+                recipient,
+                templateUri,
+                options: { webhookUrl: options.url },
+            })
+            .catch(error => {
+                if (eventsPromise) {
+                    server.removeListener('error', onServerError);
+                    stopCollectingEvents?.();
+                }
+                throw error;
+            });
+        out.log(`Sent. Watch for ISSUANCE_DELIVERED ${result.inbox?.status ?? ''}.`);
+        out.log(
+            result.inbox?.status === 'PENDING'
+                ? `Next: click the claim link in your email to see ISSUANCE_CLAIMED. Ctrl+C to stop.`
+                : 'Next: this recipient already has LearnCard; no claim event is expected. Ctrl+C to stop.'
+        );
+        if (eventsPromise) {
+            const events = await eventsPromise;
+            server.removeListener('error', onServerError);
+            out.set({
+                port,
+                url: options.url,
+                templateUri,
+                issuanceId: result.inbox?.issuanceId,
+                events,
+            });
+            return;
+        }
+        await new Promise<void>((resolve, reject) => {
+            const stop = (): void => {
+                cleanup();
+                resolve();
+            };
+            const fail = (error: Error): void => {
+                cleanup();
+                reject(error);
+            };
+            const cleanup = (): void => {
+                process.removeListener('SIGINT', stop);
+                process.removeListener('SIGTERM', stop);
+                server.removeListener('error', fail);
+            };
+            process.once('SIGINT', stop);
+            process.once('SIGTERM', stop);
+            server.once('error', fail);
+        });
+    } finally {
+        await closeWebhookReceiver(server);
+    }
+};

package/tsconfig.json

@@ -34,5 +34,6 @@
         "skipLibCheck": true,
         "forceConsistentCasingInFileNames": true
     },
+    "include": ["src/**/*", "scripts/**/*.ts"],
     "exclude": ["./dist/**/*", "./node_modules/**/*"]
 }