@learncard/cli 3.5.0 → 3.6.0

package/src/send.ts

@@ -3,6 +3,7 @@ import path from 'path';
 import { randomUUID } from 'node:crypto';
 import {
     connect,
+    connectAsManaged,
     createPrompts,
     ensureIdentity,
     ensureProfile,
@@ -54,6 +55,7 @@ export const templateCredential = (issuerDid: string, badge: Badge = DEFAULT_BAD
 };
 
 type SendOptions = ProjectOptions & {
+    as?: string;
     badge?: string;
     description?: string;
     template?: boolean;
@@ -120,20 +122,113 @@ export const personalizeSendFromTemplateMjs = (deliveryOptions?: SendDeliveryOpt
         deliveryOptions
     );
 
+/** Bind a generated script to its managed issuer, never the parent seed identity. */
+export const withManagedIssuer = (content: string, managedDid: string): string =>
+    content
+        .replace(
+            'const learnCard = await initLearnCard(',
+            `if (process.env.MANAGED_DID !== ${JSON.stringify(managedDid)}) {
+    throw new Error('MANAGED_DID is missing or changed. Re-run the CLI with --as to send as the intended profile.');
+}
+const learnCard = await initLearnCard(`
+        )
+        .replace(
+            'seed: process.env.SECURE_SEED,',
+            'seed: process.env.SECURE_SEED, didWeb: process.env.MANAGED_DID,'
+        )
+        .replace(
+            /if \(!\(await learnCard\.invoke\.getProfile\(\)\)\) \{[\s\S]*?\n\}/,
+            `if (!(await learnCard.invoke.getProfile())) {
+    throw new Error('The managed issuer profile could not be found.');
+}`
+        );
+
 const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 const PHONE = /^\+?\d{10,15}$/;
+const DID = /^did:[a-z0-9]+:.+$/;
+const PROFILE_ID = /^[a-z0-9-]{3,40}$/;
+
+export type RecipientKind = 'email' | 'phone' | 'did' | 'profileId';
+
+export const classifyRecipient = (value: string): RecipientKind => {
+    if (EMAIL.test(value)) return 'email';
+    if (PHONE.test(value)) return 'phone';
+    if (DID.test(value)) return 'did';
+    if (PROFILE_ID.test(value)) return 'profileId';
+    throw new Error(
+        `"${value}" is not an email, phone number, profile ID, or DID. Example: npx @learncard/cli send you@yourdomain.com`
+    );
+};
 
-export const runSend = async (recipientEmail: string, options: SendOptions): Promise<void> => {
-    if (!EMAIL.test(recipientEmail) && !PHONE.test(recipientEmail))
+/** Domains reserved for documentation (RFC 2606 / RFC 6761). Mail to them goes nowhere. */
+const PLACEHOLDER_DOMAIN = /(^|\.)example\.(com|net|org)$|(^|\.)(example|test|invalid|localhost)$/i;
+
+export const RECIPIENT_PROMPT =
+    'Where should we send your first badge? (email, phone number, profile ID, or DID)';
+
+export const isPlaceholderRecipient = (recipient: string): boolean => {
+    const at = recipient.lastIndexOf('@');
+    return at !== -1 && PLACEHOLDER_DOMAIN.test(recipient.slice(at + 1));
+};
+
+/**
+ * Returns a human-readable reason `recipient` cannot receive a badge, or `undefined` if it can.
+ * Placeholder addresses like you@example.com pass a naive email check but are undeliverable,
+ * so they are called out specifically — docs readers paste them verbatim.
+ */
+export const invalidRecipientReason = (recipient: string): string | undefined => {
+    if (!recipient) return 'Enter an email, phone number, profile ID, or DID.';
+    if (EMAIL.test(recipient) && isPlaceholderRecipient(recipient))
+        return `"${recipient}" is a placeholder address — nobody will receive the badge. Use a real email you can open.`;
+    if (
+        !EMAIL.test(recipient) &&
+        !PHONE.test(recipient) &&
+        !DID.test(recipient) &&
+        !PROFILE_ID.test(recipient)
+    )
+        return `"${recipient}" is not an email, phone number, profile ID, or DID.`;
+    return undefined;
+};
+
+type Prompts = ReturnType<typeof createPrompts>;
+
+/**
+ * Settle on a deliverable recipient. When a human is at the terminal, bad or missing input
+ * re-prompts instead of failing; non-interactive runs throw a clear error.
+ */
+export const resolveRecipient = async (
+    recipient: string | undefined,
+    prompts: Prompts
+): Promise<string> => {
+    let candidate = recipient?.trim() ?? '';
+    if (!candidate && !prompts.interactive)
         throw new Error(
-            `"${recipientEmail}" is not an email address or phone number. Example: npx @learncard/cli send you@example.com`
+            'A recipient is required when running non-interactively. Example: npx @learncard/cli send you@yourdomain.com --yes'
         );
+    if (!candidate) candidate = (await prompts.ask(RECIPIENT_PROMPT, '')).trim();
+    let reason = invalidRecipientReason(candidate);
+    while (reason) {
+        if (!prompts.interactive)
+            throw new Error(`${reason} Example: npx @learncard/cli send you@yourdomain.com`);
+        out.log(reason);
+        candidate = (await prompts.ask(RECIPIENT_PROMPT, '')).trim();
+        reason = invalidRecipientReason(candidate);
+    }
+    return candidate;
+};
+
+export const runSend = async (
+    recipient: string | undefined,
+    options: SendOptions
+): Promise<void> => {
     const cwd = process.cwd();
     const project = await loadProject(cwd);
     const prompts = createPrompts(options.yes);
+    let resolvedRecipient: string;
     let displayName: string | undefined;
     let badge: Badge;
     try {
+        resolvedRecipient = await resolveRecipient(recipient, prompts);
         const needsName = !project.env.PROFILE_ID && !options.profileId && !options.name;
         displayName = needsName
             ? await prompts.ask('Display name for your issuer profile', 'My Organization')
@@ -145,12 +240,34 @@ export const runSend = async (recipientEmail: string, options: SendOptions): Pro
     } finally {
         prompts.close();
     }
+    const recipientKind = classifyRecipient(resolvedRecipient);
     const identity = await ensureIdentity(project, { ...options, name: displayName, yes: true });
-    const useTemplate = options.template || !!options.templateUri;
-    const learnCard = useTemplate
-        ? await connect(project, { ...options, lca: true })
-        : await connect(project, options);
-    await ensureProfile(learnCard, identity, project);
+    const asManaged = options.as ? await connectAsManaged(project, options, options.as) : undefined;
+    const hostedSigning = !!project.env.SIGNING_AUTHORITY_NAME;
+    const explicitTemplate = options.templateUri ? true : options.template;
+    const useTemplate = !asManaged && (explicitTemplate ?? hostedSigning);
+    if (useTemplate && explicitTemplate === undefined) {
+        out.log(
+            `Signing through the registered signing authority "${project.env.SIGNING_AUTHORITY_NAME}" (pass --no-template to sign with the local key instead).`
+        );
+    }
+    if (asManaged && explicitTemplate) {
+        out.log("--as signs with the managed profile's key; --template is ignored.");
+    }
+    const learnCard = asManaged
+        ? asManaged
+        : useTemplate
+          ? await connect(project, { ...options, lca: true })
+          : await connect(project, options);
+    if (asManaged) {
+        const managed = await learnCard.invoke.getProfile();
+        if (!managed) throw new Error(`Could not sign in as managed profile "${options.as}".`);
+        out.log(
+            `Acting as "${managed.displayName}" (${managed.profileId}) — a profile you manage.`
+        );
+    } else {
+        await ensureProfile(learnCard, identity, project);
+    }
 
     const effectiveSendOptions = sendOptions(options);
     let result;
@@ -184,7 +301,7 @@ export const runSend = async (recipientEmail: string, options: SendOptions): Pro
         }
         result = await learnCard.invoke.send({
             type: 'boost',
-            recipient: recipientEmail,
+            recipient: resolvedRecipient,
             templateUri: options.templateUri ?? project.env.TEMPLATE_URI!,
             ...effectiveSendOptions,
         });
@@ -194,7 +311,7 @@ export const runSend = async (recipientEmail: string, options: SendOptions): Pro
         );
         result = await learnCard.invoke.send({
             type: 'boost',
-            recipient: recipientEmail,
+            recipient: resolvedRecipient,
             signedCredential: credential,
             ...effectiveSendOptions,
         });
@@ -202,11 +319,15 @@ export const runSend = async (recipientEmail: string, options: SendOptions): Pro
     out.log('');
     if (result.inbox?.status === 'PENDING') {
         out.log(
-            `Sent. ${recipientEmail} will get a claim email. You can also share this link directly:\n${result.inbox.claimUrl}`
+            `Sent. ${resolvedRecipient} will get a claim ${recipientKind === 'phone' ? 'text' : 'email'}. You can also share this link directly:\n${result.inbox.claimUrl}`
+        );
+    } else if (recipientKind === 'email' || recipientKind === 'phone') {
+        out.log(
+            `Delivered. ${resolvedRecipient} already uses LearnCard — the credential is in their wallet.`
         );
     } else {
         out.log(
-            `Delivered. ${recipientEmail} already uses LearnCard — the credential is in their wallet.`
+            `Delivered directly to ${resolvedRecipient} — it is waiting in their LearnCard wallet.`
         );
     }
     out.log(`Reusable template for this badge: ${result.uri}`);
@@ -214,26 +335,33 @@ export const runSend = async (recipientEmail: string, options: SendOptions): Pro
     const sendPath = path.join(cwd, filename);
     let wroteSendFile = false;
     if (!(await fs.stat(sendPath).catch(() => null))) {
-        await fs.writeFile(
-            sendPath,
-            localizeSnippet(
-                useTemplate
-                    ? personalizeSendFromTemplateMjs(effectiveSendOptions.options)
-                    : personalizeSendMjs(identity.displayName, badge, effectiveSendOptions.options),
-                resolveServices(project.env, options.network)
-            )
-        );
+        let content = useTemplate
+            ? personalizeSendFromTemplateMjs(effectiveSendOptions.options)
+            : personalizeSendMjs(identity.displayName, badge, effectiveSendOptions.options);
+        content = localizeSnippet(content, resolveServices(project.env, options.network));
+        if (asManaged) {
+            const managedDid = learnCard.id.did();
+            await saveProject(project, { MANAGED_DID: managedDid });
+            content = withManagedIssuer(content, managedDid);
+        }
+        await fs.writeFile(sendPath, content);
         wroteSendFile = true;
         out.log(
-            `\nThe code that just ran is in ./${filename} — run it yourself:\n  npm install @learncard/init\n  node --env-file=.env ${filename} ${recipientEmail}`
+            `\nThe code that just ran is in ./${filename} — run it yourself:\n  npm install @learncard/init\n  node --env-file=.env ${filename} ${resolvedRecipient}`
+        );
+    } else if (asManaged) {
+        out.log(
+            `Existing ./${filename} was not changed and may use a different issuer. Repeat this send with the CLI --as ${options.as} instead.`
         );
     }
     out.log(`Check whether it was claimed: npx @learncard/cli status ${result.activityId}`);
     out.log(`See it in the app: npx @learncard/cli open${options.template ? ' template' : ''}`);
     out.set({
-        profileId: identity.profileId,
+        profileId: options.as ?? identity.profileId,
+        ...(options.as && { onBehalfOf: identity.profileId }),
         did: learnCard.id.did(),
-        recipient: recipientEmail,
+        recipient: resolvedRecipient,
+        recipientKind,
         status: result.inbox?.status === 'PENDING' ? 'PENDING' : 'ISSUED',
         ...(result.inbox?.claimUrl && { claimUrl: result.inbox.claimUrl }),
         templateUri: result.uri,

package/src/setup-signing.ts

@@ -180,6 +180,6 @@ export const runSetupSigning = async (options: SetupSigningOptions): Promise<voi
         alreadyConfigured: authority.alreadyConfigured,
     });
     out.log(
-        'Send from a template: npx @learncard/cli send you@example.com --template\nSee it in the app: npx @learncard/cli open'
+        'Send from a template: npx @learncard/cli send --template\nSee it in the app: npx @learncard/cli open'
     );
 };

package/src/status.ts

@@ -46,9 +46,7 @@ type StatusOptions = ProjectOptions & { limit?: string; event?: string };
 export const runStatus = async (activityId: string | undefined, options: StatusOptions) => {
     const project = await loadProject(process.cwd());
     if (!project.env.SECURE_SEED)
-        throw new Error(
-            'No SECURE_SEED in .env. Send something first: npx @learncard/cli send you@example.com'
-        );
+        throw new Error('No SECURE_SEED in .env. Send something first: npx @learncard/cli send');
     await ensureIdentity(project, options);
     const learnCard = await connect(project, options);
 
@@ -73,7 +71,7 @@ export const runStatus = async (activityId: string | undefined, options: StatusO
     });
     const records = page.records as ActivityEvent[];
     if (!records.length) {
-        out.log('No sends yet. Try: npx @learncard/cli send you@example.com');
+        out.log('No sends yet. Try: npx @learncard/cli send');
         out.set({ activities: [] });
         return;
     }

package/src/whoami.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+import { Command } from 'commander';
+
+import { registerWhoamiCommand, summarizeServiceAccounts } from './whoami';
+import type { AuthGrantWithActAs } from './auth-grant';
+
+describe('whoami command', () => {
+    it('registers with --network and --json only', () => {
+        const program = new Command();
+        registerWhoamiCommand(program, async () => {});
+        const cmd = program.commands.find(c => c.name() === 'whoami');
+        expect(cmd).toBeDefined();
+        expect(
+            program
+                .createHelp()
+                .visibleOptions(cmd!)
+                .map(o => o.long)
+                .filter(l => l !== '--help')
+                .sort()
+        ).toEqual(['--json', '--network']);
+    });
+});
+
+describe('summarizeServiceAccounts', () => {
+    it('shapes active grants as { name, scope, actAs } for --json, dropping revoked ones', () => {
+        const grants: AuthGrantWithActAs[] = [
+            {
+                id: 'g1',
+                name: 'ea-clr-issuer',
+                status: 'active',
+                scope: 'inbox:write',
+                actAs: 'sc-greenville,sc-north',
+            },
+            { id: 'g2', name: 'star-issuer', status: 'active', scope: 'inbox:write', actAs: '*' },
+            { id: 'g3', name: 'no-delegation', status: 'active', scope: 'inbox:write' },
+            { id: 'g4', name: 'old-issuer', status: 'revoked', scope: 'inbox:write', actAs: '*' },
+        ];
+
+        expect(summarizeServiceAccounts(grants)).toEqual([
+            { name: 'ea-clr-issuer', scope: 'inbox:write', actAs: 'sc-greenville,sc-north' },
+            { name: 'star-issuer', scope: 'inbox:write', actAs: '*' },
+            { name: 'no-delegation', scope: 'inbox:write', actAs: undefined },
+        ]);
+    });
+
+    it('returns an empty array when there are no grants', () => {
+        expect(summarizeServiceAccounts([])).toEqual([]);
+    });
+});
+
+describe('LEARNCARD_AS', () => {
+    it('is the env fallback for --as on inbox list', async () => {
+        const { registerInboxCommand } = await import('./inbox');
+        const program = new Command().exitOverride();
+        let seen: Record<string, unknown> | undefined;
+        registerInboxCommand(program, async (_cmd, options) => {
+            seen = options as Record<string, unknown>;
+        });
+        process.env.LEARNCARD_AS = 'cs-exampleville';
+        try {
+            await program.parseAsync(['node', 'learncard', 'inbox', 'list']);
+        } finally {
+            delete process.env.LEARNCARD_AS;
+        }
+        expect(seen?.as).toBe('cs-exampleville');
+    });
+});

package/src/whoami.ts

@@ -0,0 +1,129 @@
+import type { Command } from 'commander';
+import type { AuthGrantType } from '@learncard/types';
+
+import {
+    connect,
+    connectAsDidWeb,
+    loadProject,
+    resolveServices,
+    type ProjectOptions,
+} from './project';
+import { out } from './out';
+import type { RunCommand } from './doctor';
+import { describeActAs, getGrantActAs } from './auth-grant';
+
+export interface ManagedSummary {
+    profileId: string;
+    displayName: string;
+    did: string;
+}
+
+export interface ServiceAccountSummary {
+    name: string;
+    scope: string;
+    actAs?: string;
+}
+
+/** Only active grants are relevant here; revoked ones are noise for this summary. */
+export const summarizeServiceAccounts = (
+    grants: Array<Partial<AuthGrantType>>
+): ServiceAccountSummary[] =>
+    grants
+        .filter(grant => grant.status === 'active')
+        .map(grant => ({
+            name: grant.name ?? '',
+            scope: grant.scope ?? '',
+            actAs: getGrantActAs(grant),
+        }));
+
+export const runWhoami = async (options: ProjectOptions): Promise<void> => {
+    const project = await loadProject(process.cwd());
+    if (!project.env.SECURE_SEED) {
+        throw new Error(
+            'No identity in this folder. Run `npx @learncard/cli send you@example.com` or `org apply` first.'
+        );
+    }
+    const services = resolveServices(project.env, options.network);
+    const learnCard = await connect(project, options);
+    const profile = await learnCard.invoke.getProfile();
+
+    out.log(
+        profile
+            ? `You are "${profile.displayName}" (${profile.profileId}) on ${services.network}`
+            : `Seed present but no profile on ${services.network} yet (PROFILE_ID=${project.env.PROFILE_ID ?? '?'}).`
+    );
+    out.log(`  did: ${learnCard.id.did()}`);
+    if (project.env.SIGNING_AUTHORITY_NAME)
+        out.log(`  signing authority: ${project.env.SIGNING_AUTHORITY_NAME}`);
+
+    const managerDid = project.env.ORG_PROFILE_MANAGER_DID;
+    const managed: ManagedSummary[] = [];
+    if (managerDid) {
+        const manager = await connectAsDidWeb(project, options, managerDid);
+        let cursor: string | undefined;
+        do {
+            const page = await manager.invoke.getManagedProfiles({ limit: 100, cursor });
+            for (const record of page.records) {
+                managed.push({
+                    profileId: record.profileId,
+                    displayName: record.displayName,
+                    did: record.did,
+                });
+            }
+            cursor = page.hasMore ? (page.cursor ?? undefined) : undefined;
+        } while (cursor);
+
+        out.log(`  manager: ${managerDid}`);
+        if (managed.length) {
+            out.log('You can act as (--as <profileId> or LEARNCARD_AS=<profileId>):');
+            for (const entry of managed)
+                out.log(`  ${entry.profileId.padEnd(24)} ${entry.displayName}`);
+        } else {
+            out.log(
+                '  no managed profiles yet — add them under profileManager.managed and run `org apply`.'
+            );
+        }
+    }
+
+    const grants = profile ? ((await learnCard.invoke.getAuthGrants()) ?? []) : [];
+    const serviceAccounts = summarizeServiceAccounts(grants);
+    if (serviceAccounts.length) {
+        out.log('Service accounts:');
+        const nameWidth = Math.max(...serviceAccounts.map(entry => entry.name.length));
+        const scopeWidth = Math.max(...serviceAccounts.map(entry => entry.scope.length));
+        for (const entry of serviceAccounts)
+            out.log(
+                `  ${entry.name.padEnd(nameWidth)}  ${entry.scope.padEnd(scopeWidth)}  ${describeActAs(entry.actAs)}`
+            );
+    }
+
+    if (process.env.LEARNCARD_AS)
+        out.log(
+            `LEARNCARD_AS is set: commands that support --as will act as "${process.env.LEARNCARD_AS}".`
+        );
+
+    out.set({
+        network: services.network,
+        profileId: profile?.profileId ?? project.env.PROFILE_ID,
+        displayName: profile?.displayName,
+        did: learnCard.id.did(),
+        signingAuthority: project.env.SIGNING_AUTHORITY_NAME,
+        managerDid,
+        managed,
+        serviceAccounts,
+        actingAs: process.env.LEARNCARD_AS,
+    });
+};
+
+export const registerWhoamiCommand = (program: Command, run: RunCommand): void => {
+    program
+        .command('whoami')
+        .description('Show the identity in this folder and the managed profiles --as can target.')
+        .option('--network <url>', 'network tRPC URL or staging (default: production)')
+        .option('--json', 'print a single JSON result on stdout')
+        .action(options =>
+            run('whoami', options, async didkit => {
+                await runWhoami({ ...options, didkit });
+            })
+        );
+};

package/tsconfig.json

@@ -1,7 +1,7 @@
 {
     "extends": "../../tsconfig.library.json",
     "compilerOptions": {
-        "lib": ["es2017"],
+        "lib": ["es2022"],
         "module": "esnext",
         "moduleResolution": "bundler",
         "resolveJsonModule": true,