@learncard/cli 3.5.1 → 3.6.0

package/examples/branded.network.yaml

@@ -0,0 +1,20 @@
+# Profile branding as seen in the LearnCard wallet. Images must be https URLs you host.
+# Only fields listed here are compared; `display` colours are merged, never wiped.
+issuer:
+    profileId: example-issuer
+    displayName: Example Issuer
+    branding:
+        image: https://cdn.example.org/example-issuer/logo.png
+        heroImage: https://cdn.example.org/example-issuer/hero.jpg
+        shortBio: Issuing verified learning records since 2026.
+        bio: Longer description shown on the full profile page.
+        websiteLink: https://example.org
+        type: organization
+        display:
+            backgroundColor: '#18224E'
+            fontColor: '#FFFFFF'
+            accentColor: '#2E7D32'
+            accentFontColor: '#FFFFFF'
+    signingAuthority:
+        type: learncard-hosted
+        name: example-signer

package/examples/delegated-service-account.network.yaml

@@ -0,0 +1,23 @@
+# A service account limited to specific managed profiles instead of '*' (see state-districts).
+issuer:
+    profileId: example-issuer
+    displayName: Example Issuer
+    signingAuthority:
+        type: learncard-hosted
+        name: example-signer
+
+profileManager:
+    displayName: Example Districts
+    managed:
+        - profileId: sc-greenville
+          displayName: Greenville County Schools
+        - profileId: sc-north
+          displayName: North County Schools
+
+serviceAccounts:
+    - name: districts-issuer
+      # boosts:write lets the token send through a district's signer via `send({ template })`.
+      scopes: [boosts:write, inbox:write, inbox:read, credentials:write, credentials:read]
+      expiresAt: 2027-06-30
+      # Only these two profiles can be delegated to, not every profile under profileManager.
+      actAs: [sc-greenville, sc-north]

package/examples/minimal.network.yaml

@@ -0,0 +1,7 @@
+# The smallest useful org: one issuer profile that LearnCard signs for.
+issuer:
+    profileId: example-issuer
+    displayName: Example Issuer
+    signingAuthority:
+        type: learncard-hosted
+        name: example-signer

package/examples/self-hosted-signing.network.yaml

@@ -0,0 +1,10 @@
+# The issuer keeps its own keys: LearnCard calls your VC-API endpoint to sign.
+# `did` is the DID your service signs with; it becomes the credential's issuer.
+issuer:
+    profileId: example-issuer
+    displayName: Example Issuer
+    signingAuthority:
+        type: self-hosted
+        name: example-signer
+        endpoint: https://signing.example.org/api
+        did: did:web:example.org

package/examples/service-account.network.yaml

@@ -0,0 +1,13 @@
+# An issuer plus one scoped, expiring API token for a backend that must not hold the seed.
+# The token is written once to --secrets-out; the seed stays with whoever runs `org apply`.
+issuer:
+    profileId: example-issuer
+    displayName: Example Issuer
+    signingAuthority:
+        type: learncard-hosted
+        name: example-signer
+
+serviceAccounts:
+    - name: nightly-issuer
+      scopes: [inbox:write, inbox:read, credentials:write, credentials:read]
+      expiresAt: 2027-06-30

package/examples/state-districts.network.yaml

@@ -0,0 +1,36 @@
+# A state agency with districts underneath it. The agency issues; each district is a
+# managed profile (no seed of its own) that the agency can act as with `send --as`.
+issuer:
+    profileId: exde
+    displayName: Example Department of Education
+    branding:
+        image: https://cdn.example.org/exde-logo.png
+        shortBio: State education agency for Example.
+        websiteLink: https://ed.example.gov
+        type: organization
+        display:
+            backgroundColor: '#18224E'
+            accentColor: '#2E7D32'
+    signingAuthority:
+        type: learncard-hosted
+        name: exde-clr
+
+profileManager:
+    displayName: Example Districts
+    managed:
+        - profileId: cs-exampleville
+          displayName: Exampleville County Schools
+          branding:
+              websiteLink: https://exampleville.k12.example
+              display: { accentColor: '#B45309' }
+
+serviceAccounts:
+    - name: ex-clr-issuer
+      # boosts:write lets the token send through a district's signer via `send({ template })`.
+      scopes: [boosts:write, inbox:write, inbox:read, credentials:write, credentials:read]
+      expiresAt: 2027-06-30
+      # '*' lets this token act as any profile under profileManager.managed (e.g. cs-exampleville).
+      actAs: '*'
+
+webhooks:
+    - url: https://clr.example.org/learncard/webhook

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@learncard/cli",
-    "version": "3.5.1",
+    "version": "3.6.0",
     "description": "Command Line Interface for LearnCard",
     "main": "dist/index.js",
     "bin": "dist/index.js",
@@ -16,33 +16,37 @@
     "author": "Learning Economy Foundation (www.learningeconomy.io)",
     "license": "MIT",
     "dependencies": {
-        "@learncard/core": "9.4.35",
-        "@learncard/didkit-plugin": "^1.10.0",
-        "@learncard/init": "^2.4.16",
-        "@learncard/lca-api-plugin": "2.0.5",
-        "@learncard/learn-cloud-plugin": "2.3.41",
-        "@learncard/ler-rs-plugin": "0.1.26",
-        "@learncard/linked-claims-plugin": "0.2.35",
-        "@learncard/open-badge-v2-plugin": "1.1.36",
-        "@learncard/render-method-plugin": "7.0.0",
-        "@learncard/holder-continuity": "0.2.18",
-        "@learncard/types": "5.20.0",
+        "@learncard/core": "9.4.36",
+        "@learncard/didkit-plugin": "^1.10.1",
+        "@learncard/holder-continuity": "0.2.19",
+        "@learncard/init": "^2.5.0",
+        "@learncard/lca-api-plugin": "2.0.6",
+        "@learncard/learn-cloud-plugin": "2.3.42",
+        "@learncard/ler-rs-plugin": "0.1.27",
+        "@learncard/linked-claims-plugin": "0.2.36",
+        "@learncard/network-brain-client": "2.5.57",
+        "@learncard/open-badge-v2-plugin": "1.1.37",
+        "@learncard/render-method-plugin": "8.0.0",
+        "@learncard/types": "5.21.0",
         "clipboardy": "^4.0.0",
         "commander": "^9.3.0",
         "figlet": "^1.5.2",
         "gradient-string": "^2.0.1",
-        "pretty-repl": "^3.1.1"
+        "pretty-repl": "^3.1.1",
+        "yaml": "^2.9.1",
+        "zod": "^4.1.13"
     },
     "devDependencies": {
+        "@learncard/credential-library": "2.0.4",
+        "@rollup/plugin-json": "^4.1.0",
         "@types/cors": "^2.8.12",
         "@types/figlet": "^1.5.4",
         "@types/node": "^18.0.0",
         "nodemon": "^2.0.16",
-        "ts-node": "^10.8.1",
-        "vitest": "4.1.11",
-        "@rollup/plugin-json": "^4.1.0",
         "rollup": "^2.80.0",
-        "rollup-plugin-esbuild": "^4.9.1"
+        "rollup-plugin-esbuild": "^4.9.1",
+        "ts-node": "^10.8.1",
+        "vitest": "4.1.11"
     },
     "repository": {
         "type": "git",

package/src/auth-grant.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+import {
+    describeActAs,
+    getGrantActAs,
+    normalizeActAs,
+    type AuthGrantWithActAs,
+} from './auth-grant';
+
+describe('getGrantActAs', () => {
+    it('reads actAs off a grant', () => {
+        const grant: AuthGrantWithActAs = { id: 'g1', actAs: 'sc-greenville,sc-north' };
+        expect(getGrantActAs(grant)).toBe('sc-greenville,sc-north');
+    });
+
+    it('is undefined when the grant has no actAs', () => {
+        expect(getGrantActAs({ id: 'g1' })).toBeUndefined();
+    });
+
+    it.each([null, ''])(
+        'coerces %j from the wire to undefined so it matches an absent spec value',
+        value => {
+            expect(getGrantActAs({ id: 'g1', actAs: value as unknown as string })).toBeUndefined();
+        }
+    );
+});
+
+describe('describeActAs', () => {
+    it('renders a comma-separated list with spaces', () => {
+        expect(describeActAs('sc-greenville,sc-north')).toBe('sc-greenville, sc-north');
+    });
+
+    it('renders "*" as any managed profile', () => {
+        expect(describeActAs('*')).toBe('any managed profile');
+    });
+
+    it('renders undefined as no delegation', () => {
+        expect(describeActAs(undefined)).toBe('no delegation');
+    });
+});
+
+describe('normalizeActAs', () => {
+    it('sorts, trims, and de-duplicates profile IDs', () => {
+        expect(normalizeActAs(' sc-north , sc-greenville,sc-north ')).toBe(
+            'sc-greenville,sc-north'
+        );
+    });
+
+    it('keeps "*" and treats empty values as no delegation', () => {
+        expect(normalizeActAs(' * ')).toBe('*');
+        expect(normalizeActAs('')).toBeUndefined();
+        expect(normalizeActAs(' , ')).toBeUndefined();
+        expect(normalizeActAs(undefined)).toBeUndefined();
+    });
+});

package/src/auth-grant.ts

@@ -0,0 +1,34 @@
+import type { AuthGrantType } from '@learncard/types';
+
+/**
+ * `actAs` on an auth grant: `'*'` = the token may act as any managed profile,
+ * a comma-separated list of profileIds = only those profiles, absent = the
+ * token may not act as anyone (deny-by-default).
+ */
+export type AuthGrantWithActAs = Partial<AuthGrantType>;
+
+/** Coerces `null` / `''` from the wire to `undefined` so drift checks compare like with like. */
+export const getGrantActAs = (grant: Partial<AuthGrantType>): string | undefined =>
+    grant.actAs || undefined;
+
+/** `'*'` -> "any managed profile"; `'a,b'` -> "a, b"; absent -> "no delegation". */
+export const describeActAs = (actAs: string | undefined): string => {
+    if (!actAs) return 'no delegation';
+    if (actAs === '*') return 'any managed profile';
+    return actAs.split(',').filter(Boolean).join(', ');
+};
+
+/** Order- and whitespace-insensitive form for drift checks: `'b, a'` and `'a,b'` are the same policy. */
+export const normalizeActAs = (actAs: string | undefined): string | undefined => {
+    if (!actAs) return undefined;
+    if (actAs.trim() === '*') return '*';
+    const ids = [
+        ...new Set(
+            actAs
+                .split(',')
+                .map(id => id.trim())
+                .filter(Boolean)
+        ),
+    ].sort();
+    return ids.length ? ids.join(',') : undefined;
+};

package/src/clr/validate.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest';
+import { clrProvisionalTranscript, clrWestbridgeFull } from '@learncard/credential-library';
+
+import { validateClr } from './validate';
+
+const clone = <T>(value: T): T => structuredClone(value);
+
+const provisional = (): Record<string, unknown> =>
+    clone(clrProvisionalTranscript.credential) as Record<string, unknown>;
+
+describe('validateClr', () => {
+    it('passes the library provisional transcript with zero errors', () => {
+        const result = validateClr(provisional(), { profile: 'provisional' });
+        expect(result.errors).toEqual([]);
+        expect(result.warnings).toEqual([]);
+    });
+
+    it('errors on partial when the same transcript is checked as official', () => {
+        const result = validateClr(provisional(), { profile: 'official' });
+        expect(result.errors.some(e => /partial/i.test(e))).toBe(true);
+    });
+
+    it('errors when @context uses the 2.0.1 URL that requires remote loading', () => {
+        const credential = clone(clrWestbridgeFull.credential) as Record<string, unknown>;
+        credential['@context'] = (credential['@context'] as unknown[]).map(entry =>
+            entry === 'https://purl.imsglobal.org/spec/clr/v2p0/context.json'
+                ? 'https://purl.imsglobal.org/spec/clr/v2p0/context-2.0.1.json'
+                : entry
+        );
+        const result = validateClr(credential);
+        expect(
+            result.errors.some(e => e.includes('2.0.1 URL requires remote context loading'))
+        ).toBe(true);
+    });
+
+    it('errors when id is missing', () => {
+        const credential = clone(clrWestbridgeFull.credential) as Record<string, unknown>;
+        delete credential.id;
+        const result = validateClr(credential);
+        expect(result.errors.some(e => /^id:/.test(e))).toBe(true);
+    });
+
+    it('warns on a dateOfBirth field added anywhere in the document', () => {
+        const credential = clone(clrWestbridgeFull.credential) as Record<string, unknown>;
+        (credential.credentialSubject as Record<string, unknown>).dateOfBirth = '1999-03-14';
+        const result = validateClr(credential, { profile: 'official' });
+        expect(result.warnings.some(e => /dateOfBirth/.test(e))).toBe(true);
+    });
+
+    it('warns when a provisional transcript omits validUntil', () => {
+        const credential = provisional();
+        delete credential.validUntil;
+        const result = validateClr(credential, { profile: 'provisional' });
+        expect(result.warnings.some(e => /validUntil/.test(e))).toBe(true);
+    });
+
+    it('errors when an InProgress result has no Status-typed ResultDescription', () => {
+        const credential = provisional();
+        const subject = credential.credentialSubject as Record<string, unknown>;
+        const achievement = (subject.achievement as Record<string, unknown>[])[0]!;
+        (achievement.resultDescription as Record<string, unknown>[])[0]!.resultType = 'RawScore';
+        const result = validateClr(credential, { profile: 'provisional' });
+        expect(result.errors.some(e => /resultType "Status"/.test(e))).toBe(true);
+    });
+});

package/src/clr/validate.ts

@@ -0,0 +1,242 @@
+import { ClrCredentialValidator, UnsignedClrCredentialValidator } from '@learncard/types';
+
+/**
+ * Issuer-facing lint profile. `provisional` transcripts are expected to change again
+ * before finalization; `official` transcripts are the final, certified record.
+ */
+export type ClrValidationProfile = 'provisional' | 'official';
+
+export interface ClrValidationOptions {
+    profile?: ClrValidationProfile;
+}
+
+export interface ClrValidationSummary {
+    name?: string;
+    id?: string;
+    partial?: boolean;
+    achievementCount: number;
+    resultStatuses: Record<string, number>;
+}
+
+export interface ClrValidationResult {
+    errors: string[];
+    warnings: string[];
+    summary: ClrValidationSummary;
+}
+
+const CLR_V2_CONTEXT_URL = 'https://purl.imsglobal.org/spec/clr/v2p0/context.json';
+const CLR_V2_CONTEXT_PATTERN = /purl\.imsglobal\.org\/spec\/clr\/v2p0\/context/;
+const CLR_V2_LEGACY_CONTEXT_PATTERN = /context-2\.0\.1\.json/;
+const PII_KEY_PATTERN = /ssn|socialsecurity|dateofbirth|dob|birthdate/i;
+const IN_PROGRESS_STATUSES = new Set(['InProgress', 'Provisional']);
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+    typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const toArray = (value: unknown): unknown[] => {
+    if (value === undefined || value === null) return [];
+    return Array.isArray(value) ? value : [value];
+};
+
+/** `@context` must include the CLR v2 context; the 2.0.1 URL fails to sign (remote-load only). */
+const lintContext = (doc: Record<string, unknown>, errors: string[]): void => {
+    const contexts = toArray(doc['@context']).filter(
+        (entry): entry is string => typeof entry === 'string'
+    );
+    const clrEntry = contexts.find(entry => CLR_V2_CONTEXT_PATTERN.test(entry));
+    if (!clrEntry) {
+        errors.push(`@context: must include the CLR v2 context (${CLR_V2_CONTEXT_URL}).`);
+        return;
+    }
+    if (CLR_V2_LEGACY_CONTEXT_PATTERN.test(clrEntry)) {
+        errors.push(
+            `Use ${CLR_V2_CONTEXT_URL} (the 2.0.1 URL requires remote context loading and will fail to sign)`
+        );
+    }
+};
+
+/** A missing id is an error; a non-`urn:uuid:` id is a warning (ids must be stable across versions). */
+const lintId = (doc: Record<string, unknown>, errors: string[], warnings: string[]): void => {
+    const id = doc.id;
+    if (typeof id !== 'string' || !id) {
+        errors.push('id: missing — every CLR transcript needs a stable id.');
+        return;
+    }
+    if (!id.startsWith('urn:uuid:')) {
+        warnings.push('id: use a stable urn:uuid per transcript, never per version');
+    }
+};
+
+/** Recursively flag keys that look like they hold PII, wherever they appear in the document. */
+const collectPii = (value: unknown, path: string, warnings: string[]): void => {
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => collectPii(item, `${path}[${index}]`, warnings));
+        return;
+    }
+    if (!isRecord(value)) return;
+    for (const [key, nested] of Object.entries(value)) {
+        const nextPath = path ? `${path}.${key}` : key;
+        if (PII_KEY_PATTERN.test(key)) {
+            warnings.push(
+                `${nextPath}: possible PII field ("${key}") — avoid embedding sensitive personal data in a transcript.`
+            );
+        }
+        collectPii(nested, nextPath, warnings);
+    }
+};
+
+interface ClrResultNode {
+    path: string;
+    status?: string;
+    resultDescription?: string;
+}
+
+interface ClrWalkData {
+    achievementCount: number;
+    resultDescriptionTypes: Map<string, string>;
+    results: ClrResultNode[];
+}
+
+const addAchievement = (achievement: unknown, data: ClrWalkData): void => {
+    if (!isRecord(achievement)) return;
+    data.achievementCount += 1;
+    for (const resultDescription of toArray(achievement.resultDescription)) {
+        if (
+            isRecord(resultDescription) &&
+            typeof resultDescription.id === 'string' &&
+            typeof resultDescription.resultType === 'string'
+        ) {
+            data.resultDescriptionTypes.set(resultDescription.id, resultDescription.resultType);
+        }
+    }
+};
+
+/**
+ * Walks the CLR document collecting every achievement (top-level and nested, so
+ * `resultDescription`s from both can satisfy a result's reference), and every result
+ * carried by a nested `AchievementCredential` (CLR subjects have no `result` field of
+ * their own — only nested verifiableCredentials do).
+ */
+const walkClr = (doc: Record<string, unknown>): ClrWalkData => {
+    const data: ClrWalkData = {
+        achievementCount: 0,
+        resultDescriptionTypes: new Map(),
+        results: [],
+    };
+
+    toArray(doc.credentialSubject).forEach((subject, subjectIndex) => {
+        if (!isRecord(subject)) return;
+
+        for (const achievement of toArray(subject.achievement)) addAchievement(achievement, data);
+
+        toArray(subject.verifiableCredential).forEach((nested, nestedIndex) => {
+            if (!isRecord(nested)) return;
+
+            toArray(nested.credentialSubject).forEach((nestedSubject, nestedSubjectIndex) => {
+                if (!isRecord(nestedSubject)) return;
+
+                for (const achievement of toArray(nestedSubject.achievement)) {
+                    addAchievement(achievement, data);
+                }
+
+                for (const result of toArray(nestedSubject.result)) {
+                    if (!isRecord(result)) continue;
+                    data.results.push({
+                        path: `credentialSubject[${subjectIndex}].verifiableCredential[${nestedIndex}].credentialSubject[${nestedSubjectIndex}].result`,
+                        status: typeof result.status === 'string' ? result.status : undefined,
+                        resultDescription:
+                            typeof result.resultDescription === 'string'
+                                ? result.resultDescription
+                                : undefined,
+                    });
+                }
+            });
+        });
+    });
+
+    return data;
+};
+
+/**
+ * Lints a CLR 2.0 transcript (signed or unsigned) against schema and issuer-profile rules.
+ * Pure: performs no I/O and never throws on malformed input — problems are reported in
+ * `errors`/`warnings` instead.
+ */
+export const validateClr = (
+    json: unknown,
+    opts: ClrValidationOptions = {}
+): ClrValidationResult => {
+    const errors: string[] = [];
+    const warnings: string[] = [];
+
+    const hasProof = isRecord(json) && json.proof !== undefined;
+    const parsed = hasProof
+        ? ClrCredentialValidator.safeParse(json)
+        : UnsignedClrCredentialValidator.safeParse(json);
+
+    if (!parsed.success) {
+        for (const issue of parsed.error.issues) {
+            const path = issue.path.length ? issue.path.join('.') : '(root)';
+            errors.push(`${path}: ${issue.message}`);
+        }
+    }
+
+    const doc = isRecord(json) ? json : {};
+
+    lintContext(doc, errors);
+    lintId(doc, errors, warnings);
+    collectPii(doc, '', warnings);
+
+    const walked = walkClr(doc);
+
+    const resultStatuses: Record<string, number> = {};
+    for (const result of walked.results) {
+        if (!result.status) continue;
+        resultStatuses[result.status] = (resultStatuses[result.status] ?? 0) + 1;
+    }
+
+    const partial = typeof doc.partial === 'boolean' ? doc.partial : undefined;
+
+    if (opts.profile === 'provisional') {
+        if (partial !== true) {
+            errors.push('partial: must be true for a provisional transcript (set partial: true).');
+        }
+        for (const result of walked.results) {
+            if (!result.status || !IN_PROGRESS_STATUSES.has(result.status)) continue;
+            const resultType = result.resultDescription
+                ? walked.resultDescriptionTypes.get(result.resultDescription)
+                : undefined;
+            if (resultType !== 'Status') {
+                errors.push(
+                    `${result.path}: status "${result.status}" must reference a ResultDescription with resultType "Status" (found ${resultType ? `"${resultType}"` : 'none'}).`
+                );
+            }
+        }
+        if (typeof doc.validUntil !== 'string' || !doc.validUntil) {
+            warnings.push(
+                'validUntil: missing — provisional transcripts should set an expected finalization date.'
+            );
+        }
+    } else if (opts.profile === 'official') {
+        if (partial === true) {
+            errors.push('partial: must not be true for an official transcript.');
+        }
+        for (const result of walked.results) {
+            if (result.status && IN_PROGRESS_STATUSES.has(result.status)) {
+                errors.push(
+                    `${result.path}: status "${result.status}" is not allowed in an official transcript.`
+                );
+            }
+        }
+    }
+
+    const summary: ClrValidationSummary = {
+        name: typeof doc.name === 'string' ? doc.name : undefined,
+        id: typeof doc.id === 'string' ? doc.id : undefined,
+        partial,
+        achievementCount: walked.achievementCount,
+        resultStatuses,
+    };
+
+    return { errors, warnings, summary };
+};