@learncard/holder-continuity 0.2.4 → 0.2.6

package/README.md

@@ -7,7 +7,7 @@ A bundle is a normal ZIP file with a readable `manifest.json` and encrypted payl
 ## Install
 
 ```bash
-pnpm add @learncard/holder-continuity
+bun add @learncard/holder-continuity
 ```
 
 ## Export a wallet

package/package.json

@@ -1,42 +1,51 @@
 {
-  "name": "@learncard/holder-continuity",
-  "version": "0.2.4",
-  "description": "Holder continuity bundle helpers for LearnCard wallets",
-  "main": "./dist/index.js",
-  "module": "./dist/holder-continuity.esm.js",
-  "types": "./dist/index.d.ts",
-  "files": [
-    "dist",
-    "BUNDLE_SPEC.md",
-    "README.md"
-  ],
-  "author": "Learning Economy Foundation (www.learningeconomy.io)",
-  "license": "MIT",
-  "homepage": "https://github.com/learningeconomy/LearnCard/tree/main/packages/holder-continuity-bundle/BUNDLE_SPEC.md",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/learningeconomy/LearnCard"
-  },
-  "bugs": {
-    "url": "https://github.com/learningeconomy/LearnCard/issues"
-  },
-  "dependencies": {
-    "jszip": "^3.10.1",
-    "@learncard/init": "2.4.2",
-    "@learncard/sss-key-manager": "0.1.13",
-    "@learncard/types": "5.17.3"
-  },
-  "devDependencies": {
-    "@types/node": "^18.19.68",
-    "esbuild": "^0.27.1",
-    "shx": "^0.3.4",
-    "typescript": "5.6.2",
-    "vitest": "^1.6.0"
-  },
-  "sideEffects": false,
-  "scripts": {
-    "build": "node ./scripts/build.mjs && shx cp ./scripts/mixedEntrypoint.js ./dist/index.js && tsc --p tsconfig.json",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  }
-}
+    "name": "@learncard/holder-continuity",
+    "version": "0.2.6",
+    "description": "Holder continuity bundle helpers for LearnCard wallets",
+    "main": "./dist/index.js",
+    "module": "./dist/holder-continuity.esm.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "development": "./src/index.ts",
+            "import": "./dist/holder-continuity.esm.js",
+            "require": "./dist/index.js",
+            "default": "./dist/holder-continuity.esm.js"
+        }
+    },
+    "files": [
+        "dist",
+        "src",
+        "BUNDLE_SPEC.md",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "node ./scripts/build.mjs && shx cp ./scripts/mixedEntrypoint.js ./dist/index.js && tsc --p tsconfig.json",
+        "test": "vitest run",
+        "test:watch": "vitest"
+    },
+    "author": "Learning Economy Foundation (www.learningeconomy.io)",
+    "license": "MIT",
+    "homepage": "https://github.com/learningeconomy/LearnCard/tree/main/packages/holder-continuity-bundle/BUNDLE_SPEC.md",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/learningeconomy/LearnCard"
+    },
+    "bugs": {
+        "url": "https://github.com/learningeconomy/LearnCard/issues"
+    },
+    "dependencies": {
+        "@learncard/init": "workspace:*",
+        "@learncard/sss-key-manager": "workspace:*",
+        "@learncard/types": "workspace:*",
+        "jszip": "^3.10.1"
+    },
+    "devDependencies": {
+        "@types/node": "^18.19.68",
+        "esbuild": "^0.27.1",
+        "shx": "^0.3.4",
+        "typescript": "5.6.2",
+        "vitest": "^1.6.0"
+    },
+    "sideEffects": false
+}

package/src/__tests__/bundle.test.ts

@@ -0,0 +1,296 @@
+import { mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { webcrypto } from 'node:crypto';
+import JSZip from 'jszip';
+
+import { beforeAll, describe, expect, it } from 'vitest';
+
+import { createLearnCardBundle } from '../exportBundle';
+import { importLearnCardBundle, readLearnCardBundleData } from '../importBundle';
+import { computePayloadSha256 } from '../manifest';
+import type { JsonValue, LearnCardBundleWallet } from '../types';
+
+const vc = {
+    '@context': ['https://www.w3.org/2018/credentials/v1'],
+    id: 'urn:uuid:credential-1',
+    type: ['VerifiableCredential'],
+    issuer: 'did:example:issuer',
+    issuanceDate: '2024-01-01T00:00:00Z',
+    credentialSubject: { id: 'did:example:holder' },
+    proof: { type: 'Ed25519Signature2018', jws: 'test' },
+};
+
+const vp = {
+    '@context': ['https://www.w3.org/2018/credentials/v1'],
+    id: 'urn:uuid:presentation-1',
+    type: ['VerifiablePresentation'],
+    holder: 'did:example:holder',
+    verifiableCredential: [vc],
+};
+
+const createWallet = (): LearnCardBundleWallet & {
+    stored: JsonValue[];
+    added: Array<Record<string, unknown>>;
+} => {
+    const stored: JsonValue[] = [];
+    const added: Array<Record<string, unknown>> = [];
+    const payloads: Record<string, JsonValue | undefined> = {
+        'lc:cloud:https%3A%2F%2Fcloud.example:credentials:1': vc,
+        'lc:cloud:https%3A%2F%2Fcloud.example:presentations:1': vp,
+        'lc:cloud:https%3A%2F%2Fcloud.example:missing:1': undefined,
+    };
+
+    return {
+        stored,
+        added,
+        id: {
+            did: method => (method ? `did:${method}:holder` : 'did:key:holder'),
+            keypair: (algorithm = 'ed25519') => ({
+                kty: 'OKP',
+                crv: algorithm,
+                d: `${algorithm}-private`,
+            }),
+        },
+        invoke: {
+            getKey: () => '1'.repeat(64),
+            resolveDid: async did => ({ id: did, verificationMethod: [] }),
+            getHolderExportMetadata: async () => ({
+                consentRecords: [
+                    {
+                        termsUri: 'lc:consent:terms:1',
+                        status: 'live',
+                        contract: { id: 'contract-1' },
+                        terms: { read: {} },
+                        transactions: [{ id: 'transaction-1' }],
+                    },
+                ],
+            }),
+            verifyCredential: async credential =>
+                typeof credential === 'object' &&
+                credential !== null &&
+                'id' in credential &&
+                credential.id === vc.id
+                    ? { checks: ['proof'], warnings: [], errors: [] }
+                    : { checks: [], warnings: [], errors: ['invalid'] },
+            verifyPresentation: async presentation =>
+                typeof presentation === 'object' &&
+                presentation !== null &&
+                'id' in presentation &&
+                presentation.id === vp.id
+                    ? { checks: ['proof'], warnings: [], errors: [] }
+                    : { checks: [], warnings: [], errors: ['invalid'] },
+        },
+        index: {
+            LearnCloud: {
+                get: async () => [
+                    {
+                        id: 'credential-record',
+                        uri: 'lc:cloud:https%3A%2F%2Fcloud.example:credentials:1',
+                        category: 'Achievement',
+                        title: 'Credential',
+                    },
+                    {
+                        id: 'duplicate-record',
+                        uri: 'lc:cloud:https%3A%2F%2Fcloud.example:credentials:1',
+                    },
+                    {
+                        id: 'presentation-record',
+                        uri: 'lc:cloud:https%3A%2F%2Fcloud.example:presentations:1',
+                    },
+                    {
+                        id: 'missing-record',
+                        uri: 'lc:cloud:https%3A%2F%2Fcloud.example:missing:1',
+                    },
+                ],
+                add: async record => {
+                    added.push(record);
+
+                    return true;
+                },
+            },
+        },
+        read: {
+            get: async uri => payloads[uri],
+        },
+        store: {
+            LearnCloud: {
+                uploadEncrypted: async content => {
+                    stored.push(content);
+
+                    return `imported:${stored.length}`;
+                },
+            },
+        },
+    };
+};
+
+beforeAll(() => {
+    Object.defineProperty(globalThis, 'crypto', { value: webcrypto, configurable: true });
+});
+
+describe('LearnCard holder continuity bundles', () => {
+    it('computes deterministic manifest payload hashes', () => {
+        const contents = [
+            {
+                id: 'b',
+                type: 'credential' as const,
+                path: 'credentials/b.json',
+                mediaType: 'application/json',
+                sha256: 'b',
+                encrypted: false,
+            },
+            {
+                id: 'a',
+                type: 'credential' as const,
+                path: 'credentials/a.json',
+                mediaType: 'application/json',
+                sha256: 'a',
+                encrypted: false,
+            },
+        ];
+
+        expect(computePayloadSha256(contents)).toBe(computePayloadSha256([...contents].reverse()));
+    });
+
+    it('round-trips encrypted entries through the existing password envelope', async () => {
+        const bundle = await createLearnCardBundle(createWallet(), {
+            password: 'correct horse battery staple',
+            createdAt: '2024-01-01T00:00:00.000Z',
+            fetchStatusLists: false,
+        });
+
+        expect(bundle.manifest.encryption.mode).toBe('argon2id-aes-256-gcm');
+        expect(bundle.manifest.contents.some(entry => entry.encrypted)).toBe(true);
+
+        const read = await readLearnCardBundleData(bundle.data, {
+            password: 'correct horse battery staple',
+        });
+
+        expect(read.entries.some(entry => entry.content.includes('urn:uuid:credential-1'))).toBe(
+            true
+        );
+    });
+
+    it('exports fake wallet credentials, presentations, consent records, and missing URI warnings', async () => {
+        const bundle = await createLearnCardBundle(createWallet(), {
+            encrypt: false,
+            createdAt: '2024-01-01T00:00:00.000Z',
+            fetchStatusLists: false,
+        });
+        const zip = await JSZip.loadAsync(bundle.data);
+        const manifest = JSON.parse(await zip.file('manifest.json')!.async('string')) as {
+            contents: Array<Record<string, unknown>>;
+        };
+        const credentialManifestEntry = manifest.contents.find(
+            entry => entry.type === 'credential'
+        );
+
+        expect(bundle.manifest.contents.filter(entry => entry.type === 'credential')).toHaveLength(
+            2
+        );
+        expect(
+            bundle.manifest.contents.filter(entry => entry.type === 'presentation')
+        ).toHaveLength(1);
+        expect(
+            bundle.manifest.contents.filter(entry => entry.type === 'consent-record')
+        ).toHaveLength(1);
+        expect(
+            bundle.warnings.some(warning =>
+                warning.startsWith('Could not resolve wallet index URI ')
+            )
+        ).toBe(true);
+        expect(credentialManifestEntry?.indexRecordRef).toBeDefined();
+        expect(credentialManifestEntry).not.toHaveProperty('indexRecord');
+        expect(credentialManifestEntry).not.toHaveProperty('title');
+        expect(credentialManifestEntry).not.toHaveProperty('category');
+        expect(JSON.stringify(manifest)).not.toContain('"credential-record"');
+    });
+    it('imports credentials and presentations into a fresh wallet store and index', async () => {
+        const source = createWallet();
+        const target = createWallet();
+        const bundle = await createLearnCardBundle(source, {
+            encrypt: false,
+            createdAt: '2024-01-01T00:00:00.000Z',
+            fetchStatusLists: false,
+        });
+        const dir = await mkdtemp(join(tmpdir(), 'learncard-bundle-'));
+        const path = join(dir, 'bundle.zip');
+
+        await writeFile(path, bundle.data);
+
+        const report = await importLearnCardBundle(path, { wallet: target });
+
+        expect(report.warnings).toContain(
+            'Bundle credential signatures were not verified before import; only import bundles from sources you trust.'
+        );
+        expect(report.errors).toEqual([]);
+        expect(report.importedCredentials).toBe(2);
+        expect(report.importedPresentations).toBe(1);
+        expect(report.skipped).toBe(
+            Object.values(report.skippedByType).reduce((sum, count) => sum + count, 0)
+        );
+        expect(report.skippedByType['index-record']).toBeGreaterThan(0);
+        expect(report.skippedByType['consent-record']).toBe(1);
+        expect(target.stored).toHaveLength(3);
+        expect(target.added).toHaveLength(3);
+        expect(target.added[0]?.sourceExport).toMatchObject({
+            manifestCreatedAt: '2024-01-01T00:00:00.000Z',
+            credentialId: 'urn:uuid:credential-1',
+        });
+    });
+
+    it('verifies signatures before import when requested', async () => {
+        const source = createWallet();
+        const target = createWallet();
+        const bundle = await createLearnCardBundle(source, {
+            encrypt: false,
+            createdAt: '2024-01-01T00:00:00.000Z',
+            fetchStatusLists: false,
+        });
+        const dir = await mkdtemp(join(tmpdir(), 'learncard-bundle-'));
+        const path = join(dir, 'bundle.zip');
+
+        await writeFile(path, bundle.data);
+
+        const report = await importLearnCardBundle(path, {
+            wallet: target,
+            verifyBeforeImport: true,
+        });
+
+        expect(report.warnings).not.toContain(
+            'Bundle credential signatures were not verified before import; only import bundles from sources you trust.'
+        );
+        expect(report.errors).toEqual([]);
+        expect(report.importedCredentials).toBe(2);
+        expect(report.importedPresentations).toBe(1);
+    });
+
+    it('rejects status-list URLs that are not public HTTPS URLs', async () => {
+        const wallet = createWallet();
+
+        wallet.read.get = async uri =>
+            uri.includes('credentials')
+                ? {
+                      ...vc,
+                      credentialStatus: {
+                          type: 'BitstringStatusListEntry',
+                          statusListCredential: 'http://127.0.0.1/latest-status?token=secret',
+                      },
+                  }
+                : uri.includes('presentations')
+                ? vp
+                : undefined;
+
+        const bundle = await createLearnCardBundle(wallet, {
+            encrypt: false,
+            createdAt: '2024-01-01T00:00:00.000Z',
+        });
+
+        expect(bundle.warnings).toContain(
+            'Could not cache status-list credential http://[redacted-host]/latest-status?[redacted]: status-list URL must use https'
+        );
+        expect(JSON.stringify(bundle.manifest)).not.toContain('127.0.0.1');
+        expect(JSON.stringify(bundle.manifest)).not.toContain('token=secret');
+    });
+});

package/src/__tests__/restoreBundle.test.ts

@@ -0,0 +1,121 @@
+import { webcrypto } from 'node:crypto';
+
+import JSZip from 'jszip';
+import { beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { createLearnCardBundle } from '../exportBundle';
+import { sha256Hex } from '../crypto';
+import { computePayloadSha256 } from '../manifest';
+import { readLearnCardBundleSeedData, restoreLearnCardFromBundleData } from '../restoreBundle';
+import type { JsonValue, LearnCardBundleWallet } from '../types';
+
+const { initLearnCardMock } = vi.hoisted(() => ({ initLearnCardMock: vi.fn() }));
+
+vi.mock('@learncard/init', () => ({
+    initLearnCard: initLearnCardMock,
+}));
+
+const createWallet = (): LearnCardBundleWallet & {
+    stored: JsonValue[];
+    added: Array<Record<string, unknown>>;
+} => ({
+    stored: [],
+    added: [],
+    id: {
+        did: method => (method ? `did:${method}:holder` : 'did:key:holder'),
+        keypair: (algorithm = 'ed25519') => ({
+            kty: 'OKP',
+            crv: algorithm,
+            d: `${algorithm}-private`,
+        }),
+    },
+    invoke: {
+        getKey: () => '1'.repeat(64),
+        resolveDid: async did => ({ id: did, verificationMethod: [] }),
+    },
+    index: {
+        LearnCloud: {
+            get: async () => [],
+            add: async record => record,
+        },
+    },
+    read: {
+        get: async () => undefined,
+    },
+    store: {
+        LearnCloud: {},
+    },
+});
+
+beforeAll(() => {
+    Object.defineProperty(globalThis, 'crypto', { value: webcrypto, configurable: true });
+});
+
+beforeEach(() => {
+    initLearnCardMock.mockReset();
+    initLearnCardMock.mockResolvedValue({ restored: true });
+});
+
+describe('restore helpers', () => {
+    it('reads the exported seed from an encrypted bundle', async () => {
+        const bundle = await createLearnCardBundle(createWallet(), {
+            password: 'correct horse battery staple',
+            fetchStatusLists: false,
+        });
+
+        await expect(
+            readLearnCardBundleSeedData(bundle.data, { password: 'correct horse battery staple' })
+        ).resolves.toBe('1'.repeat(64));
+    });
+
+    it('restores a LearnCard by passing the exported seed to initLearnCard', async () => {
+        const bundle = await createLearnCardBundle(createWallet(), {
+            password: 'correct horse battery staple',
+            fetchStatusLists: false,
+        });
+
+        const restored = await restoreLearnCardFromBundleData(bundle.data, {
+            password: 'correct horse battery staple',
+            init: { network: true, allowRemoteContexts: true, didkit: 'node' },
+        });
+
+        expect(initLearnCardMock).toHaveBeenCalledWith({
+            seed: '1'.repeat(64),
+            network: true,
+            allowRemoteContexts: true,
+            didkit: 'node',
+        });
+        expect(restored).toEqual({ restored: true });
+    });
+
+    it('rejects malformed exported seeds', async () => {
+        const bundle = await createLearnCardBundle(createWallet(), {
+            password: 'correct horse battery staple',
+            fetchStatusLists: false,
+        });
+        const zip = await JSZip.loadAsync(bundle.data);
+        const seedPath = 'keys/private-key-seed.txt.enc';
+        const tamperedSeed = `${'f'.repeat(63)}\n`;
+        const contents = bundle.manifest.contents.map(entry =>
+            entry.path === seedPath
+                ? { ...entry, encrypted: false, sha256: sha256Hex(tamperedSeed) }
+                : entry
+        );
+        const manifest = {
+            ...bundle.manifest,
+            contents,
+            payloadSha256: computePayloadSha256(contents),
+        };
+
+        zip.file(seedPath, tamperedSeed, { date: new Date('2024-01-01T00:00:00.000Z') });
+        zip.file('manifest.json', `${JSON.stringify(manifest, null, 2)}\n`);
+
+        const data = await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+
+        await expect(
+            readLearnCardBundleSeedData(data, { password: 'correct horse battery staple' })
+        ).rejects.toThrow(
+            'LearnCard bundle key-private-seed must be exactly 64 hexadecimal characters'
+        );
+    });
+});

package/src/crypto.ts

@@ -0,0 +1,56 @@
+import { createHash } from 'node:crypto';
+
+import { decryptWithPassword, encryptWithPassword } from '@learncard/sss-key-manager';
+
+import type { EncryptedPayloadEnvelope } from './types';
+
+export const sha256Hex = (bytes: string | Buffer): string =>
+    createHash('sha256').update(bytes).digest('hex');
+
+export const stableStringify = (value: unknown): string => {
+    if (value === null || typeof value !== 'object') return JSON.stringify(value);
+
+    if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+
+    const object = value as Record<string, unknown>;
+
+    return `{${Object.keys(object)
+        .sort()
+        .map(key => `${JSON.stringify(key)}:${stableStringify(object[key])}`)
+        .join(',')}}`;
+};
+
+export const encodePayload = async (
+    plaintext: string,
+    options: { encrypt: boolean; password?: string }
+): Promise<{ stored: string; encrypted: boolean }> => {
+    if (!options.encrypt) return { stored: plaintext, encrypted: false };
+
+    if (!options.password)
+        throw new Error('A password is required for encrypted LearnCard exports');
+
+    return {
+        stored: JSON.stringify(await encryptWithPassword(plaintext, options.password), null, 2),
+        encrypted: true,
+    };
+};
+
+export const decodePayload = async (
+    stored: string,
+    options: { encrypted: boolean; password?: string }
+): Promise<string> => {
+    if (!options.encrypted) return stored;
+
+    if (!options.password)
+        throw new Error('A password is required to decrypt this LearnCard export');
+
+    const envelope = JSON.parse(stored) as EncryptedPayloadEnvelope;
+
+    return decryptWithPassword(
+        envelope.ciphertext,
+        envelope.iv,
+        envelope.salt,
+        options.password,
+        envelope.kdfParams
+    );
+};