@learncard/cli 3.5.1 → 3.6.0

package/src/org/branding.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest';
+import { brandingDiff } from './apply';
+import { brandingSchema } from './schema';
+
+describe('brandingSchema', () => {
+    it('accepts https images and hex colours', () => {
+        expect(
+            brandingSchema.safeParse({
+                image: 'https://cdn.example.org/logo.png',
+                display: { accentColor: '#2E7D32' },
+                type: 'organization',
+            }).success
+        ).toBe(true);
+    });
+
+    it('rejects a local path with a hint about hosting the image', () => {
+        const result = brandingSchema.safeParse({ image: './assets/logo.png' });
+        expect(result.success).toBe(false);
+        expect(JSON.stringify(result.error?.issues)).toContain('not uploaded yet');
+    });
+
+    it('rejects non-hex colours and unknown display keys', () => {
+        expect(brandingSchema.safeParse({ display: { accentColor: 'green' } }).success).toBe(false);
+        expect(brandingSchema.safeParse({ display: { borderColor: '#000000' } }).success).toBe(
+            false
+        );
+    });
+});
+
+describe('brandingDiff', () => {
+    const existing = {
+        image: 'https://cdn.example.org/old.png',
+        websiteLink: 'https://ed.example.gov',
+        display: { backgroundColor: '#111111', fontColor: '#FFFFFF' },
+    };
+
+    it('reports nothing when every spec field already matches', () => {
+        const { changed } = brandingDiff(
+            { websiteLink: 'https://ed.example.gov', display: { fontColor: '#FFFFFF' } },
+            existing
+        );
+        expect(changed).toEqual([]);
+    });
+
+    it('only sends changed scalars and merges display instead of replacing it', () => {
+        const { update, changed } = brandingDiff(
+            {
+                image: 'https://cdn.example.org/new.png',
+                websiteLink: 'https://ed.example.gov',
+                display: { accentColor: '#2E7D32' },
+            },
+            existing
+        );
+        expect(changed).toEqual(['image', 'display.accentColor']);
+        expect(update).toEqual({
+            image: 'https://cdn.example.org/new.png',
+            display: { backgroundColor: '#111111', fontColor: '#FFFFFF', accentColor: '#2E7D32' },
+        });
+    });
+});

package/src/org/diff.ts

@@ -0,0 +1,14 @@
+import type { OrgChange } from './apply';
+
+export const hasChanges = (changes: OrgChange[]): boolean =>
+    changes.some(change => change.action !== 'unchanged');
+
+export const formatChanges = (changes: OrgChange[]): string[] => {
+    if (!changes.length) return [];
+    const resourceWidth = Math.max(...changes.map(change => change.resource.length));
+    const nameWidth = Math.max(...changes.map(change => change.name.length));
+    return changes.map(change => {
+        const detail = change.detail ? `  (${change.detail})` : '';
+        return `${change.resource.padEnd(resourceWidth)}  ${change.name.padEnd(nameWidth)}  ${change.action}${detail}`;
+    });
+};

package/src/org/load.ts

@@ -0,0 +1,50 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { z } from 'zod';
+import { OrgSpecValidator, type OrgSpec } from './schema';
+import { out } from '../out';
+
+const SUPPORTED_EXTENSIONS = ['.yaml', '.yml', '.json'];
+
+export const formatIssues = (error: z.ZodError): string[] =>
+    error.issues.map(
+        issue =>
+            `${issue.path.length ? issue.path.map(String).join('.') : '(root)'}: ${issue.message}`
+    );
+
+export const loadOrgSpec = async (file: string): Promise<OrgSpec> => {
+    const absolute = path.resolve(file);
+    const ext = path.extname(absolute).toLowerCase();
+    if (!SUPPORTED_EXTENSIONS.includes(ext))
+        throw new Error(`Unsupported file type "${ext || file}". Use .yaml, .yml, or .json.`);
+
+    let text: string;
+    try {
+        text = await fs.readFile(absolute, 'utf8');
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT')
+            throw new Error(`Could not find ${file}.`, { cause: error });
+        throw error;
+    }
+
+    let parsed: unknown;
+    try {
+        parsed = ext === '.json' ? JSON.parse(text) : parseYaml(text);
+    } catch (error) {
+        throw new Error(
+            `Could not parse ${file}: ${error instanceof Error ? error.message : String(error)}`,
+            { cause: error }
+        );
+    }
+
+    const result = OrgSpecValidator.safeParse(parsed);
+    if (!result.success) {
+        const issues = formatIssues(result.error);
+        for (const issue of issues) out.log(`  ${issue}`);
+        throw new Error(
+            `Invalid org spec in ${file}: ${issues.length} issue${issues.length === 1 ? '' : 's'} (${issues.join('; ')})`
+        );
+    }
+    return result.data;
+};

package/src/org/schema.test.ts

@@ -0,0 +1,256 @@
+import { describe, expect, it } from 'vitest';
+import { OrgSpecValidator } from './schema';
+
+const validSpec = {
+    issuer: {
+        profileId: 'scde',
+        displayName: 'South Carolina Department of Education',
+        signingAuthority: { type: 'learncard-hosted', name: 'scde-clr' },
+    },
+    profileManager: {
+        displayName: 'SC Districts',
+        managed: [{ profileId: 'sc-greenville', displayName: 'Greenville County Schools' }],
+    },
+    serviceAccounts: [
+        {
+            name: 'ea-clr-issuer',
+            scopes: ['inbox:write', 'inbox:read', 'credentials:write', 'credentials:read'],
+            expiresAt: '2027-06-30',
+        },
+    ],
+    webhooks: [{ url: 'https://clr.example.org/learncard/webhook' }],
+};
+
+describe('OrgSpecValidator', () => {
+    it.each([
+        ['read-only', 'READ_ONLY'],
+        ['issuer', 'issuer'],
+        ['Issuer', 'issuer'],
+    ])('rejects duplicate normalized secrets keys: %s / %s', (first, second) => {
+        const result = OrgSpecValidator.safeParse({
+            ...validSpec,
+            serviceAccounts: [first, second].map(name => ({ name, scopes: ['inbox:read'] })),
+        });
+        expect(result.success).toBe(false);
+        if (!result.success)
+            expect(result.error.issues).toContainEqual(
+                expect.objectContaining({
+                    path: ['serviceAccounts', 1, 'name'],
+                    message: expect.stringContaining('Duplicate service-account secrets key'),
+                })
+            );
+    });
+
+    it('accepts distinct normalized secrets keys', () => {
+        expect(
+            OrgSpecValidator.safeParse({
+                ...validSpec,
+                serviceAccounts: ['read-only', 'write-only'].map(name => ({
+                    name,
+                    scopes: ['inbox:read'],
+                })),
+            }).success
+        ).toBe(true);
+    });
+
+    it('accepts a fully-populated spec', () => {
+        const result = OrgSpecValidator.safeParse(validSpec);
+        expect(result.success).toBe(true);
+    });
+
+    it('accepts the minimal issuer-only spec', () => {
+        const result = OrgSpecValidator.safeParse({ issuer: validSpec.issuer });
+        expect(result.success).toBe(true);
+    });
+
+    it('rejects a self-hosted signing authority missing endpoint/did', () => {
+        const result = OrgSpecValidator.safeParse({
+            issuer: {
+                ...validSpec.issuer,
+                signingAuthority: { type: 'self-hosted', name: 'my-issuer' },
+            },
+        });
+        expect(result.success).toBe(false);
+    });
+
+    it('accepts a valid self-hosted signing authority', () => {
+        const result = OrgSpecValidator.safeParse({
+            issuer: {
+                ...validSpec.issuer,
+                signingAuthority: {
+                    type: 'self-hosted',
+                    name: 'my-issuer',
+                    endpoint: 'https://issuer.example/api',
+                    did: 'did:web:issuer.example',
+                },
+            },
+        });
+        expect(result.success).toBe(true);
+    });
+
+    it('rejects an unknown scope resource', () => {
+        const result = OrgSpecValidator.safeParse({
+            ...validSpec,
+            serviceAccounts: [{ name: 'ea-clr-issuer', scopes: ['unicorns:write'] }],
+        });
+        expect(result.success).toBe(false);
+        if (!result.success)
+            expect(
+                result.error.issues.some(issue => issue.message.includes('Unknown scope resource'))
+            ).toBe(true);
+    });
+
+    it('rejects a malformed scope action', () => {
+        const result = OrgSpecValidator.safeParse({
+            ...validSpec,
+            serviceAccounts: [{ name: 'ea-clr-issuer', scopes: ['boosts:admin'] }],
+        });
+        expect(result.success).toBe(false);
+    });
+
+    it('rejects a signing authority name that is too long', () => {
+        const result = OrgSpecValidator.safeParse({
+            issuer: {
+                ...validSpec.issuer,
+                signingAuthority: { type: 'learncard-hosted', name: 'this-name-is-way-too-long' },
+            },
+        });
+        expect(result.success).toBe(false);
+    });
+
+    it('rejects a signing authority name with uppercase or invalid characters', () => {
+        const result = OrgSpecValidator.safeParse({
+            issuer: {
+                ...validSpec.issuer,
+                signingAuthority: { type: 'learncard-hosted', name: 'SCDE_CLR' },
+            },
+        });
+        expect(result.success).toBe(false);
+    });
+
+    it('rejects a profileId that is too short', () => {
+        const result = OrgSpecValidator.safeParse({
+            issuer: { ...validSpec.issuer, profileId: 'ab' },
+        });
+        expect(result.success).toBe(false);
+    });
+
+    it('rejects a profileId with uppercase or invalid characters', () => {
+        const result = OrgSpecValidator.safeParse({
+            issuer: { ...validSpec.issuer, profileId: 'SCDE_Org!' },
+        });
+        expect(result.success).toBe(false);
+    });
+
+    it('rejects a webhook URL that is not https', () => {
+        const result = OrgSpecValidator.safeParse({
+            ...validSpec,
+            webhooks: [{ url: 'http://clr.example.org/webhook' }],
+        });
+        expect(result.success).toBe(false);
+    });
+
+    it('defaults profileManager.managed to an empty array when omitted', () => {
+        const result = OrgSpecValidator.safeParse({
+            issuer: validSpec.issuer,
+            profileManager: { displayName: 'SC Districts' },
+        });
+        expect(result.success).toBe(true);
+        if (result.success) expect(result.data.profileManager?.managed).toEqual([]);
+    });
+
+    it.each([
+        [
+            'profileManager.managedProfiles',
+            { profileManager: { displayName: 'SC Districts', managedProfiles: [] } },
+            ['profileManager'],
+        ],
+        [
+            'issuer.signingAuthority.endpoint on a hosted signer',
+            {
+                issuer: {
+                    ...validSpec.issuer,
+                    signingAuthority: {
+                        type: 'learncard-hosted',
+                        name: 'scde-clr',
+                        endpoint: 'https://x',
+                    },
+                },
+            },
+            ['issuer', 'signingAuthority'],
+        ],
+        [
+            'serviceAccounts[].scope',
+            { serviceAccounts: [{ name: 'a', scope: ['inbox:read'] }] },
+            ['serviceAccounts', 0],
+        ],
+        ['top-level typo', { webhook: [{ url: 'https://x' }] }, []],
+    ])('rejects unknown keys instead of silently dropping them: %s', (_label, override, path) => {
+        const result = OrgSpecValidator.safeParse({ ...validSpec, ...override });
+        expect(result.success).toBe(false);
+        if (!result.success)
+            expect(result.error.issues).toContainEqual(
+                expect.objectContaining({ code: 'unrecognized_keys', path })
+            );
+    });
+});
+
+describe('serviceAccounts[].actAs', () => {
+    it('accepts "*" when a profileManager is present', () => {
+        const result = OrgSpecValidator.safeParse({
+            ...validSpec,
+            serviceAccounts: [{ ...validSpec.serviceAccounts[0], actAs: '*' }],
+        });
+        expect(result.success).toBe(true);
+    });
+
+    it('accepts a list of profileIds that are all managed', () => {
+        const result = OrgSpecValidator.safeParse({
+            ...validSpec,
+            serviceAccounts: [{ ...validSpec.serviceAccounts[0], actAs: ['sc-greenville'] }],
+        });
+        expect(result.success).toBe(true);
+    });
+
+    it('rejects a list naming a profileId that is not managed', () => {
+        const result = OrgSpecValidator.safeParse({
+            ...validSpec,
+            serviceAccounts: [
+                { ...validSpec.serviceAccounts[0], actAs: ['sc-greenville', 'sc-north'] },
+            ],
+        });
+        expect(result.success).toBe(false);
+        if (!result.success) {
+            const issue = result.error.issues.find(i => i.message.includes('sc-north'));
+            expect(issue?.message).toBe('"sc-north" is not a managed profile in this spec');
+            expect(issue?.path).toEqual(['serviceAccounts', 0, 'actAs']);
+        }
+    });
+
+    it('rejects "*" when there is no profileManager', () => {
+        const result = OrgSpecValidator.safeParse({
+            issuer: validSpec.issuer,
+            serviceAccounts: [{ ...validSpec.serviceAccounts[0], actAs: '*' }],
+        });
+        expect(result.success).toBe(false);
+        if (!result.success)
+            expect(
+                result.error.issues.some(issue => issue.message.includes('profileManager'))
+            ).toBe(true);
+    });
+});
+
+describe('examples/*.network.yaml', () => {
+    it('every shipped example parses', async () => {
+        const fs = await import('node:fs/promises');
+        const path = await import('node:path');
+        const { loadOrgSpec } = await import('./load');
+        const dir = path.resolve(__dirname, '../../examples');
+        const files = (await fs.readdir(dir)).filter(f => f.endsWith('.network.yaml'));
+        expect(files.length).toBeGreaterThanOrEqual(5);
+        for (const file of files) {
+            const spec = await loadOrgSpec(path.join(dir, file));
+            expect(spec.issuer.profileId, file).toBeTruthy();
+        }
+    });
+});

package/src/org/schema.ts

@@ -0,0 +1,216 @@
+import { z } from 'zod';
+import { validateScope } from '../token';
+
+// Server constraint: `LCNProfileValidator.profileId` (packages/learn-card-types/src/lcn.ts).
+const PROFILE_ID_PATTERN = /^[a-z0-9-]{3,40}$/;
+// Server constraint: `LCNSigningAuthorityForUserValidator.relationship.name`.
+const SIGNING_AUTHORITY_NAME_PATTERN = /^[a-z0-9-]+$/;
+
+const profileIdSchema = z
+    .string()
+    .regex(PROFILE_ID_PATTERN, 'must be 3-40 characters: lowercase letters, numbers, and hyphens');
+
+const displayNameSchema = z.string().min(1, 'is required');
+
+const signingAuthorityNameSchema = z
+    .string()
+    .max(15, 'must be at most 15 characters')
+    .regex(SIGNING_AUTHORITY_NAME_PATTERN, 'must be lowercase letters, numbers, and hyphens');
+
+const hostedSigningAuthoritySchema = z
+    .object({
+        type: z.literal('learncard-hosted'),
+        name: signingAuthorityNameSchema,
+    })
+    .strict();
+
+const selfHostedSigningAuthoritySchema = z
+    .object({
+        type: z.literal('self-hosted'),
+        name: signingAuthorityNameSchema,
+        endpoint: z
+            .string()
+            .url('must be a valid URL')
+            .startsWith('https://', 'must be an https:// URL'),
+        did: z.string().regex(/^did:/, 'must be a DID (did:web:..., did:key:...)'),
+    })
+    .strict();
+
+const signingAuthoritySchema = z.discriminatedUnion('type', [
+    hostedSigningAuthoritySchema,
+    selfHostedSigningAuthoritySchema,
+]);
+
+const hexColorSchema = z.string().regex(/^#[0-9a-fA-F]{6}$/, 'must be a hex color like #18224E');
+
+const imageUrlSchema = z.string().superRefine((value, ctx) => {
+    if (/^https:\/\//.test(value)) return;
+    ctx.addIssue({
+        code: 'custom',
+        message: /^(\.{1,2}\/|\/|[a-zA-Z]:\\)/.test(value)
+            ? 'local files are not uploaded yet — host the image and use its https:// URL'
+            : 'must be an https:// URL',
+    });
+});
+
+const displaySchema = z
+    .object({
+        backgroundColor: hexColorSchema.optional(),
+        backgroundImage: imageUrlSchema.optional(),
+        fadeBackgroundImage: z.boolean().optional(),
+        repeatBackgroundImage: z.boolean().optional(),
+        fontColor: hexColorSchema.optional(),
+        accentColor: hexColorSchema.optional(),
+        accentFontColor: hexColorSchema.optional(),
+        idBackgroundImage: imageUrlSchema.optional(),
+        fadeIdBackgroundImage: z.boolean().optional(),
+        idBackgroundColor: hexColorSchema.optional(),
+        repeatIdBackgroundImage: z.boolean().optional(),
+    })
+    .strict();
+
+export const brandingSchema = z
+    .object({
+        image: imageUrlSchema.optional(),
+        heroImage: imageUrlSchema.optional(),
+        shortBio: z.string().max(280, 'must be at most 280 characters').optional(),
+        bio: z.string().optional(),
+        websiteLink: z.string().url('must be a valid URL').optional(),
+        type: z.enum(['organization', 'service', 'person']).optional(),
+        display: displaySchema.optional(),
+    })
+    .strict();
+
+export type OrgBranding = z.infer<typeof brandingSchema>;
+
+const issuerSchema = z
+    .object({
+        profileId: profileIdSchema,
+        displayName: displayNameSchema,
+        branding: brandingSchema.optional(),
+        signingAuthority: signingAuthoritySchema,
+    })
+    .strict();
+
+const managedProfileSchema = z
+    .object({
+        profileId: profileIdSchema,
+        displayName: displayNameSchema,
+        branding: brandingSchema.optional(),
+    })
+    .strict();
+
+const profileManagerSchema = z
+    .object({
+        displayName: displayNameSchema,
+        managed: z.array(managedProfileSchema).default([]),
+    })
+    .strict();
+
+const scopesSchema = z
+    .array(z.string().min(1, 'must not be empty'))
+    .min(1, 'must list at least one scope')
+    .superRefine((scopes, ctx) => {
+        try {
+            validateScope(scopes.join(' '));
+        } catch (error) {
+            ctx.addIssue({
+                code: 'custom',
+                message: error instanceof Error ? error.message : 'Invalid scope',
+            });
+        }
+    });
+
+const isoDateSchema = z.string().refine(value => !Number.isNaN(Date.parse(value)), {
+    message: 'must be a valid ISO date',
+});
+
+/** Normalize a service-account name to its shell-safe secrets-file key. */
+export const toEnvKey = (name: string): string => name.replace(/-/g, '_').toUpperCase();
+
+// Becomes the key in `--secrets-out`, so keep it shell-safe.
+const SERVICE_ACCOUNT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+
+const serviceAccountNameSchema = z
+    .string()
+    .regex(
+        SERVICE_ACCOUNT_NAME_PATTERN,
+        'must start with a letter or underscore and contain only letters, numbers, hyphens, and underscores'
+    );
+
+// '*' = any profile under profileManager.managed; a list is refined below against it.
+const actAsSchema = z.union([
+    z.literal('*'),
+    z.array(profileIdSchema).min(1, 'must list at least one profileId'),
+]);
+
+const serviceAccountSchema = z
+    .object({
+        name: serviceAccountNameSchema,
+        scopes: scopesSchema,
+        expiresAt: isoDateSchema.optional(),
+        actAs: actAsSchema.optional(),
+    })
+    .strict();
+
+const webhookSchema = z
+    .object({
+        url: z
+            .string()
+            .url('must be a valid URL')
+            .startsWith('https://', 'must be an https:// URL'),
+    })
+    .strict();
+
+export const OrgSpecValidator = z
+    .object({
+        issuer: issuerSchema,
+        profileManager: profileManagerSchema.optional(),
+        serviceAccounts: z
+            .array(serviceAccountSchema)
+            .superRefine((accounts, ctx) => {
+                const keys = new Set<string>();
+                accounts.forEach((account, index) => {
+                    const key = toEnvKey(account.name);
+                    if (keys.has(key))
+                        ctx.addIssue({
+                            code: 'custom',
+                            path: [index, 'name'],
+                            message: `Duplicate service-account secrets key "${key}" after normalizing names`,
+                        });
+                    keys.add(key);
+                });
+            })
+            .optional(),
+        webhooks: z.array(webhookSchema).optional(),
+    })
+    .strict()
+    .superRefine((spec, ctx) => {
+        const managedIds = new Set(spec.profileManager?.managed.map(entry => entry.profileId));
+        spec.serviceAccounts?.forEach((account, index) => {
+            if (!account.actAs) return;
+            const path = ['serviceAccounts', index, 'actAs'];
+            if (account.actAs === '*') {
+                if (!spec.profileManager)
+                    ctx.addIssue({
+                        code: 'custom',
+                        path,
+                        message: '"*" requires a profileManager in this spec',
+                    });
+                return;
+            }
+            for (const profileId of account.actAs) {
+                if (!managedIds.has(profileId))
+                    ctx.addIssue({
+                        code: 'custom',
+                        path,
+                        message: `"${profileId}" is not a managed profile in this spec`,
+                    });
+            }
+        });
+    });
+
+export type OrgSpec = z.infer<typeof OrgSpecValidator>;
+export type OrgSigningAuthoritySpec = z.infer<typeof signingAuthoritySchema>;
+export type OrgManagedProfileSpec = z.infer<typeof managedProfileSchema>;
+export type OrgServiceAccountSpec = z.infer<typeof serviceAccountSchema>;