@learncard/cli 3.6.7 → 4.0.0

package/src/org.ts

@@ -1,124 +0,0 @@
-import type { Command } from 'commander';
-import {
-    connect,
-    connectAsDidWeb,
-    connectAsDidWebSigner,
-    ensureIdentity,
-    loadProject,
-    type Project,
-    type ProjectOptions,
-} from './project';
-import { loadOrgSpec } from './org/load';
-import { applyOrg } from './org/apply';
-import { formatChanges, hasChanges } from './org/diff';
-import { out } from './out';
-import { generateRandomSeed } from './random';
-
-export type OrgApplyOptions = ProjectOptions & {
-    dryRun?: boolean;
-    secretsOut?: string;
-    cwd?: string;
-    /** Operate on this in-memory project instead of loading .env from cwd (dry-run previews). */
-    project?: Project;
-};
-
-export const runOrgApply = async (file: string, options: OrgApplyOptions): Promise<void> => {
-    const spec = await loadOrgSpec(file);
-    const project = options.project ?? (await loadProject(options.cwd ?? process.cwd()));
-
-    if (options.profileId && options.profileId !== spec.issuer.profileId)
-        throw new Error(
-            `--profile-id "${options.profileId}" does not match the spec's issuer.profileId "${spec.issuer.profileId}". Remove the flag or update the spec.`
-        );
-
-    if (project.env.PROFILE_ID && project.env.PROFILE_ID !== spec.issuer.profileId)
-        throw new Error(
-            `This project's .env is already set up for profile "${project.env.PROFILE_ID}", but the spec declares "${spec.issuer.profileId}". Use a separate folder for a different issuer.`
-        );
-
-    if (options.dryRun) {
-        if (!project.env.SECURE_SEED) {
-            out.log(
-                'Dry run: no identity in this folder yet — using a throwaway seed, nothing written.'
-            );
-            project.env.SECURE_SEED = generateRandomSeed();
-        }
-        project.env.PROFILE_ID ??= spec.issuer.profileId;
-    } else {
-        await ensureIdentity(project, {
-            ...options,
-            profileId: spec.issuer.profileId,
-            name: spec.issuer.displayName,
-        });
-    }
-    const learnCard = await connect(project, {
-        ...options,
-        lca: true,
-        readOnly: !!options.dryRun,
-    });
-
-    const result = await applyOrg(spec, learnCard, project, {
-        dryRun: options.dryRun,
-        secretsOut: options.secretsOut,
-        connectAsManager: managerDid => connectAsDidWeb(project, options, managerDid),
-        connectAsManaged: managedDid => connectAsDidWeb(project, options, managedDid),
-        connectAsManagedSigner: managedDid => connectAsDidWebSigner(project, options, managedDid),
-    });
-
-    if (options.dryRun) out.log('Dry run: no changes were made.');
-    if (hasChanges(result.changes)) {
-        for (const line of formatChanges(result.changes)) out.log(line);
-    } else {
-        out.log('No changes.');
-    }
-    out.log(`Issuer DID: ${result.outputs.issuerDid}`);
-
-    out.set({ changes: result.changes, outputs: result.outputs });
-};
-
-export const registerOrgCommand = (
-    program: Command,
-    run: (
-        command: string,
-        options: { json?: boolean },
-        action: (didkit: Promise<Buffer>) => Promise<void>
-    ) => Promise<void>
-): void => {
-    const orgCommand = program
-        .command('org')
-        .description('Manage an issuer organization declaratively.');
-
-    orgCommand
-        .command('apply <file>')
-        .description(
-            'Reconcile a YAML/JSON org spec (issuer, signing authority, districts, service accounts) against the network.'
-        )
-        .option('-y, --yes', 'accept defaults without prompting')
-        .option(
-            '--profile-id <id>',
-            'public handle for your issuer profile (default: from the spec)'
-        )
-        .option('--network <url>', 'network tRPC URL or staging (default: production)')
-        .option('--json', 'print a single JSON result on stdout')
-        .option('--dry-run', 'preview changes without applying them')
-        .option(
-            '--secrets-out <path>',
-            'write created service-account tokens to this file, e.g. ./secrets.env (mode 0600; keep it next to .env and out of git)'
-        )
-        .action(
-            (
-                file: string,
-                options: {
-                    yes?: boolean;
-                    profileId?: string;
-                    network?: string;
-                    json?: boolean;
-                    dryRun?: boolean;
-                    secretsOut?: string;
-                }
-            ) =>
-                run('org apply', options, async didkit => {
-                    await runOrgApply(file, { ...options, didkit });
-                })
-        );
-};

package/src/out.test.ts

@@ -1,40 +0,0 @@
-import { afterEach, describe, expect, it, vi } from 'vitest';
-import { out } from './out';
-
-afterEach(() => {
-    out.json = false;
-    out.result = {};
-    vi.restoreAllMocks();
-});
-
-describe('out', () => {
-    it('routes log to console.log in human mode', () => {
-        const log = vi.spyOn(console, 'log').mockImplementation(() => {});
-        const error = vi.spyOn(console, 'error').mockImplementation(() => {});
-
-        out.json = false;
-        out.log('hello', 1);
-
-        expect(log).toHaveBeenCalledWith('hello', 1);
-        expect(error).not.toHaveBeenCalled();
-    });
-
-    it('routes log to console.error in json mode, keeping stdout free for the result', () => {
-        const log = vi.spyOn(console, 'log').mockImplementation(() => {});
-        const error = vi.spyOn(console, 'error').mockImplementation(() => {});
-
-        out.json = true;
-        out.log('hidden from stdout');
-
-        expect(error).toHaveBeenCalledWith('hidden from stdout');
-        expect(log).not.toHaveBeenCalled();
-    });
-
-    it('accumulates result patches, later keys winning on conflict', () => {
-        out.result = {};
-        out.set({ a: 1, b: 2 });
-        out.set({ b: 3 });
-
-        expect(out.result).toEqual({ a: 1, b: 3 });
-    });
-});

package/src/out.ts

@@ -1,16 +0,0 @@
-/**
- * Shared output router for every CLI command.
- *
- * Human mode: `out.log(...)` behaves exactly like `console.log(...)`.
- * `--json` mode: `out.log(...)` is redirected to stderr (so stdout stays reserved
- * for the single JSON result line) and each command accumulates its result via
- * `out.set(...)`. `index.tsx`'s `runCommand` prints the final `out.result` object
- * as one JSON line on stdout after the command succeeds (or an error envelope on
- * failure) and sets `out.json` before running the command's action.
- */
-export const out = {
-    json: false,
-    log: (...a: unknown[]) => (out.json ? console.error(...a) : console.log(...a)),
-    result: {} as Record<string, unknown>,
-    set: (patch: Record<string, unknown>) => Object.assign(out.result, patch),
-};

package/src/phase-two.test.ts

@@ -1,154 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-import { consentUrl } from './consent-contract';
-import { personalizeClaimButton, validateDomains } from './embed';
-import { PRODUCTION_NETWORK, STAGING_NETWORK } from './project';
-import { closeWebhookReceiver, loadWebhookModule, webhookConfig } from './webhook';
-
-describe('consent URL', () => {
-    it('encodes both parameters and selects the app for the network', () => {
-        for (const [network, origin] of [
-            [PRODUCTION_NETWORK, 'https://learncard.app'],
-            [STAGING_NETWORK, 'https://staging.learncard.ai'],
-            ['http://localhost:4000/trpc', 'https://learncard.app'],
-        ]) {
-            const url = new URL(
-                consentUrl('lc:network:contract?a&b', 'https://example.com/cb?a=1&b=2', network!)
-            );
-            expect(url.origin).toBe(origin);
-            expect(url.searchParams.get('uri')).toBe('lc:network:contract?a&b');
-            expect(url.searchParams.get('returnTo')).toBe('https://example.com/cb?a=1&b=2');
-        }
-    });
-});
-
-describe('embed helpers', () => {
-    it('uses the network domain/origin validator, including its error message', () => {
-        expect(validateDomains('http://localhost:3000, example.com')).toEqual([
-            'http://localhost:3000',
-            'example.com',
-        ]);
-        for (const invalid of [
-            '',
-            'https://example.com/path',
-            'file://example.com',
-            'https://*.example.com',
-        ]) {
-            expect(() => validateDomains(invalid)).toThrow(/Must be a valid/);
-        }
-    });
-    it('substitutes keys safely, including replacement and script-closing characters', () => {
-        const html = personalizeClaimButton("pk_$&'</script>", 'http://localhost:4000/api');
-        expect(html).not.toContain('PUBLISHABLE_KEY_PLACEHOLDER');
-        expect(html).toContain("pk_$&'\\u003c/script>");
-        expect(html).toContain('http://localhost:4000/api');
-        expect(html).toContain('LearnCard.init(');
-    });
-});
-
-describe('canonical webhook helpers', () => {
-    it('resolves trusted DID and port from the project with explicit overrides', () => {
-        const env = { PORT: '9000', EXPECTED_NETWORK_DID: 'did:key:project' };
-        expect(webhookConfig(env, {}, {})).toEqual({ port: 9000, expectedDid: 'did:key:project' });
-        expect(
-            webhookConfig(
-                env,
-                { port: '9001' },
-                { PORT: '9002', EXPECTED_NETWORK_DID: 'did:key:runtime' }
-            )
-        ).toEqual({ port: 9001, expectedDid: 'did:key:runtime' });
-        expect(() => webhookConfig({}, { port: '0' }, {})).toThrow('Port must be');
-    });
-    it('closes connections even when verification never completes', async () => {
-        const { createWebhookReceiver } = await loadWebhookModule();
-        let started!: () => void;
-        const verifying = new Promise<void>(resolve => {
-            started = resolve;
-        });
-        const server = createWebhookReceiver({
-            invoke: {
-                verifyPresentation: () => {
-                    started();
-                    return new Promise(() => {});
-                },
-            },
-        });
-        await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve));
-        const address = server.address();
-        if (!address || typeof address === 'string') throw new Error('Expected TCP address');
-        const request = fetch(`http://127.0.0.1:${address.port}`, {
-            method: 'POST',
-            headers: { Authorization: 'Bearer pending' },
-            body: '{}',
-        }).catch(() => undefined);
-        await verifying;
-        await closeWebhookReceiver(server);
-        await request;
-        expect(server.listening).toBe(false);
-    });
-    it('rejects invalid authentication and payloads, and acknowledges duplicate events once', async () => {
-        const { createWebhookReceiver } = await loadWebhookModule();
-        const verifyPresentation = vi.fn().mockResolvedValue({ errors: [] });
-        const server = createWebhookReceiver({ invoke: { verifyPresentation } }, 'did:key:trusted');
-        const log = vi.spyOn(console, 'log').mockImplementation(() => {});
-        await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve));
-        const address = server.address();
-        if (!address || typeof address === 'string') throw new Error('Expected TCP address');
-        const url = `http://127.0.0.1:${address.port}`;
-        const token = (iss: string): string =>
-            `header.${Buffer.from(JSON.stringify({ iss })).toString('base64url')}.signature`;
-        const post = (body: string, bearer = token('did:key:trusted')) =>
-            fetch(url, {
-                method: 'POST',
-                headers: { Authorization: `Bearer ${bearer}` },
-                body,
-            });
-        try {
-            expect((await fetch(url, { method: 'POST' })).status).toBe(401);
-            expect((await post('{}', token('did:key:other'))).status).toBe(403);
-            verifyPresentation.mockResolvedValueOnce({ errors: ['invalid signature'] });
-            expect((await post('{}')).status).toBe(401);
-            expect((await post('{')).status).toBe(400);
-            expect((await post('{}')).status).toBe(400);
-            const data = { inbox: { issuanceId: 'same-id', status: 'PENDING' } };
-            const delivered = JSON.stringify({ type: 'ISSUANCE_DELIVERED', data });
-            expect((await post(delivered)).status).toBe(200);
-            expect((await post(delivered)).status).toBe(200);
-            expect((await post(JSON.stringify({ type: 'ISSUANCE_CLAIMED', data }))).status).toBe(
-                200
-            );
-            expect(log).toHaveBeenCalledTimes(2);
-            expect(verifyPresentation).toHaveBeenCalledWith(expect.any(String), {
-                proofFormat: 'jwt',
-            });
-        } finally {
-            log.mockRestore();
-            await new Promise<void>((resolve, reject) =>
-                server.close(error => (error ? reject(error) : resolve()))
-            );
-        }
-    });
-    it('extracts only bearer credentials', async () => {
-        const { extractBearer } = await loadWebhookModule();
-        expect(extractBearer('Bearer abc.def.ghi')).toBe('abc.def.ghi');
-        expect(extractBearer('bearer   token')).toBe('token');
-        for (const invalid of [undefined, null, [], 'Basic abc', 'Bearer', 'Bearer a b']) {
-            expect(extractBearer(invalid)).toBeUndefined();
-        }
-    });
-    it('deduplicates retries without conflating delivered and claimed', async () => {
-        const { webhookDedupeKey } = await loadWebhookModule();
-        const data = { inbox: { issuanceId: 'abc' } };
-        expect(webhookDedupeKey({ type: 'ISSUANCE_DELIVERED', data })).toBe(
-            'ISSUANCE_DELIVERED:abc'
-        );
-        expect(webhookDedupeKey({ type: 'ISSUANCE_CLAIMED', data })).toBe('ISSUANCE_CLAIMED:abc');
-        for (const invalid of [
-            null,
-            {},
-            { type: 'OTHER', data },
-            { type: 'ISSUANCE_DELIVERED', data: { inbox: {} } },
-        ]) {
-            expect(webhookDedupeKey(invalid)).toBeUndefined();
-        }
-    });
-});

package/src/project.test.ts

@@ -1,232 +0,0 @@
-import { afterEach, describe, expect, it, vi } from 'vitest';
-import fs from 'node:fs/promises';
-import os from 'node:os';
-import path from 'node:path';
-import {
-    assertProjectNetwork,
-    KEYS,
-    createPrompts,
-    ensureIdentity,
-    loadProject,
-    parseEnv,
-    resolveServices,
-    saveProject,
-    upsertEnv,
-} from './project';
-
-afterEach(() => vi.restoreAllMocks());
-
-describe('createPrompts non-interactive behavior', () => {
-    const originalIsTTY = process.stdin.isTTY;
-    const originalLcYes = process.env.LC_YES;
-
-    afterEach(() => {
-        Object.defineProperty(process.stdin, 'isTTY', { value: originalIsTTY, configurable: true });
-        if (originalLcYes === undefined) delete process.env.LC_YES;
-        else process.env.LC_YES = originalLcYes;
-    });
-
-    it('returns the fallback without opening a prompt when yes is true', async () => {
-        const prompts = createPrompts(true);
-        await expect(prompts.ask('Display name', 'My Organization')).resolves.toBe(
-            'My Organization'
-        );
-        prompts.close();
-    });
-
-    it('returns the fallback when stdin is not a TTY, even without --yes', async () => {
-        Object.defineProperty(process.stdin, 'isTTY', { value: false, configurable: true });
-        const prompts = createPrompts(undefined);
-        await expect(prompts.ask('Display name', 'My Organization')).resolves.toBe(
-            'My Organization'
-        );
-        prompts.close();
-    });
-
-    it('treats LC_YES=1 as non-interactive even when stdin looks like a real TTY', async () => {
-        Object.defineProperty(process.stdin, 'isTTY', { value: true, configurable: true });
-        process.env.LC_YES = '1';
-        const prompts = createPrompts(undefined);
-        await expect(prompts.ask('Display name', 'My Organization')).resolves.toBe(
-            'My Organization'
-        );
-        prompts.close();
-    });
-
-    it('throws a descriptive error when non-interactive and no fallback exists', async () => {
-        const prompts = createPrompts(true);
-        await expect(prompts.ask('Recipient email (--to <email>)', '')).rejects.toThrow(
-            'Recipient email (--to <email>) is required when running non-interactively. Pass it as an argument or flag.'
-        );
-        prompts.close();
-    });
-});
-describe('project context', () => {
-    it('parses exported and commented seeds without changing identity', () => {
-        expect(
-            parseEnv('export SECURE_SEED="original" # keep\nPROFILE_ID=issuer # comment\n')
-        ).toEqual({ SECURE_SEED: 'original', PROFILE_ID: 'issuer' });
-        expect(upsertEnv('export PROFILE_ID=old\n', { PROFILE_ID: 'new' })).toBe(
-            'PROFILE_ID=new\n'
-        );
-        expect(() => parseEnv('SECURE_SEED=one\nSECURE_SEED=two\n')).toThrow('Conflicting');
-    });
-    it('rejects network changes when resources are already saved', () => {
-        const project = {
-            existing: '',
-            envPath: '/unused/.env',
-            env: { TEMPLATE_URI: 'lc:template' },
-        };
-        expect(() =>
-            assertProjectNetwork(project, 'https://staging.network.learncard.com/trpc')
-        ).toThrow('separate folder');
-        expect(() =>
-            assertProjectNetwork(project, 'https://network.learncard.com/trpc')
-        ).not.toThrow();
-    });
-    it('documents the stable shared keys', () => {
-        expect(Object.keys(KEYS)).toEqual([
-            'SECURE_SEED',
-            'PROFILE_ID',
-            'DISPLAY_NAME',
-            'NETWORK_URL',
-            'SIGNING_AUTHORITY_NAME',
-            'SIGNING_AUTHORITY_ENDPOINT',
-            'API_TOKEN',
-            'API_TOKEN_SCOPE',
-            'TEMPLATE_URI',
-            'CONTRACT_URI',
-            'PUBLISHABLE_KEY',
-            'INTEGRATION_ID',
-        ]);
-        expect(Object.values(KEYS)).toEqual(Object.keys(KEYS));
-    });
-    it('preserves unrelated lines and quotes scope lists', () => {
-        const result = upsertEnv('# keep\nOTHER=one\n', {
-            API_TOKEN_SCOPE: 'boosts:write inbox:read',
-        });
-        expect(result).toBe('# keep\nOTHER=one\nAPI_TOKEN_SCOPE="boosts:write inbox:read"\n');
-        expect(parseEnv(result).API_TOKEN_SCOPE).toBe('boosts:write inbox:read');
-    });
-    it('does not ask for a display name when a profile already exists', async () => {
-        const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'lc-project-'));
-        vi.spyOn(console, 'log').mockImplementation(() => {});
-        try {
-            await fs.writeFile(path.join(cwd, '.env'), 'SECURE_SEED=existing\nPROFILE_ID=issuer\n');
-            const project = await loadProject(cwd);
-            vi.spyOn(process.stdin, 'isTTY', 'get').mockReturnValue(true);
-            const identity = await Promise.race([
-                ensureIdentity(project, {}),
-                new Promise<never>((_, reject) =>
-                    setTimeout(() => reject(new Error('prompted for a display name')), 500)
-                ),
-            ]);
-            expect(identity.profileId).toBe('issuer');
-            expect((await loadProject(cwd)).env.DISPLAY_NAME).toBeUndefined();
-        } finally {
-            vi.restoreAllMocks();
-            await fs.rm(cwd, { recursive: true, force: true });
-        }
-    });
-    it('accumulates keys, does not rewrite unchanged values, and never replaces a seed', async () => {
-        const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'lc-project-'));
-        vi.spyOn(console, 'log').mockImplementation(() => {});
-        try {
-            await fs.writeFile(
-                path.join(cwd, '.env'),
-                '# keep\nSECURE_SEED=existing\nPROFILE_ID=issuer\n'
-            );
-            await fs.writeFile(path.join(cwd, '.gitignore'), '.env\n');
-            const project = await loadProject(cwd);
-            await expect(
-                ensureIdentity(project, { yes: true, profileId: 'someone-else' })
-            ).rejects.toThrow(/--as someone-else/);
-            const identity = await ensureIdentity(project, { yes: true, profileId: 'issuer' });
-            expect(identity.seed).toBe('existing');
-            expect(identity.profileId).toBe('issuer');
-            expect(console.log).not.toHaveBeenCalled();
-            await saveProject(project, { TEMPLATE_URI: 'lc:template' });
-            await saveProject(project, { API_TOKEN: 'secret' });
-            expect((await fs.stat(project.envPath)).mode & 0o777).toBe(0o600);
-            expect((await loadProject(cwd)).env).toMatchObject({
-                SECURE_SEED: 'existing',
-                TEMPLATE_URI: 'lc:template',
-                API_TOKEN: 'secret',
-            });
-            expect(console.log).toHaveBeenCalledWith('Wrote TEMPLATE_URI to .env');
-            await expect(saveProject(project, { SECURE_SEED: 'replacement' })).rejects.toThrow(
-                'Cannot replace'
-            );
-        } finally {
-            await fs.rm(cwd, { recursive: true, force: true });
-        }
-    });
-    it('refuses stale identity writes and symlinked env files', async () => {
-        const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'lc-project-safety-'));
-        const log = vi.spyOn(console, 'log').mockImplementation(() => {});
-        try {
-            const stale = await loadProject(cwd);
-            const current = await loadProject(cwd);
-            await saveProject(current, { SECURE_SEED: 'original' });
-            await expect(saveProject(stale, { SECURE_SEED: 'different' })).rejects.toThrow(
-                'Cannot replace'
-            );
-            expect((await loadProject(cwd)).env.SECURE_SEED).toBe('original');
-            await fs.rename(current.envPath, path.join(cwd, 'target'));
-            await fs.symlink(path.join(cwd, 'target'), current.envPath);
-            await expect(loadProject(cwd)).rejects.toThrow('symlink');
-        } finally {
-            log.mockRestore();
-            await fs.rm(cwd, { recursive: true, force: true });
-        }
-    });
-    it('resolves staging services together and preserves explicit local LCA URLs', () => {
-        expect(resolveServices({}, 'staging', {})).toEqual({
-            network: 'https://staging.network.learncard.com/trpc',
-            cloud: 'https://staging.cloud.learncard.com/trpc',
-            lcaAPI: 'https://staging.api.learncard.app/trpc',
-        });
-        expect(
-            resolveServices({ NETWORK_URL: 'http://localhost:4000/trpc' }, undefined, {
-                LCA_API_URL: 'http://localhost:5200/api',
-            }).lcaAPI
-        ).toBe('http://localhost:5200/api');
-        expect(() => resolveServices({}, 'file:///tmp/network', {})).toThrow('HTTP');
-    });
-});
-
-describe('upsertEnv value quoting', () => {
-    it('writes percent-encoded network URIs bare so shell scripts can read them', () => {
-        expect(upsertEnv('', { TEMPLATE_URI: 'lc:network:localhost%3A4000/trpc:boost:abc' })).toBe(
-            'TEMPLATE_URI=lc:network:localhost%3A4000/trpc:boost:abc\n'
-        );
-    });
-
-    it('quotes values with spaces or shell-significant characters', () => {
-        expect(upsertEnv('', { API_TOKEN_SCOPE: 'boosts:write inbox:read' })).toBe(
-            'API_TOKEN_SCOPE="boosts:write inbox:read"\n'
-        );
-    });
-});
-
-describe('connectAsManaged', () => {
-    it('explains how to get a profile manager when .env has none', async () => {
-        const { connectAsManaged } = await import('./project');
-        const project = { env: { SECURE_SEED: 'seed' }, envPath: '/x/.env', existing: '' };
-        await expect(connectAsManaged(project, {}, 'cs-exampleville')).rejects.toThrow(
-            /profileManager section/
-        );
-    });
-});
-
-describe('connect readOnly', () => {
-    it('does not write NETWORK_URL to .env when readOnly is set', async () => {
-        const { connect } = await import('./project');
-        const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'lc-readonly-'));
-        vi.spyOn(console, 'log').mockImplementation(() => {});
-        const project = await loadProject(cwd);
-        project.env.SECURE_SEED = 'a'.repeat(64);
-        await connect(project, { network: 'staging', readOnly: true }).catch(() => undefined);
-        expect(await fs.readdir(cwd)).toEqual([]);
-    });
-});