@learncard/holder-continuity 0.2.5 → 0.2.6

package/src/importBundle.ts

@@ -0,0 +1,242 @@
+import { readFile } from 'node:fs/promises';
+
+import JSZip from 'jszip';
+
+import type {
+    ImportLearnCardBundleOptions,
+    ImportLearnCardBundleReport,
+    JsonValue,
+    LearnCardBundleEntryMetadata,
+    LearnCardBundleManifest,
+    ReadLearnCardBundleOptions,
+    ReadLearnCardBundleResult,
+} from './types';
+import { assertValidManifest } from './manifest';
+import { decodePayload, sha256Hex } from './crypto';
+
+const DEFAULT_MAX_BUNDLE_BYTES = 100 * 1024 * 1024;
+const DEFAULT_MAX_ENTRY_BYTES = 25 * 1024 * 1024;
+const DEFAULT_MAX_JSON_BYTES = 25 * 1024 * 1024;
+
+const byteLength = (content: string): number => Buffer.byteLength(content, 'utf8');
+
+const assertSize = (label: string, size: number, max: number): void => {
+    if (size > max) throw new Error(`${label} exceeds ${max} bytes`);
+};
+
+const parseJson = (content: string, label: string, maxBytes: number): JsonValue => {
+    assertSize(label, byteLength(content), maxBytes);
+
+    return JSON.parse(content) as JsonValue;
+};
+
+const safeMessage = (error: unknown): string =>
+    error instanceof Error ? error.message : String(error);
+
+const parseObject = (content: string, label: string, maxBytes: number): Record<string, unknown> => {
+    const value = parseJson(content, label, maxBytes);
+
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('Expected bundle metadata entry to contain a JSON object');
+    }
+
+    return value as Record<string, unknown>;
+};
+
+const isImportableCredentialEntry = (entry: LearnCardBundleEntryMetadata): boolean =>
+    entry.type === 'credential' || entry.type === 'presentation';
+
+const isFailedVerification = (result: unknown): boolean => {
+    if (Array.isArray(result)) {
+        return result.some(item => {
+            if (!item || typeof item !== 'object') return true;
+
+            const status = 'status' in item ? item.status : undefined;
+
+            return status === 'Failed' || status === 'Error';
+        });
+    }
+
+    if (!result || typeof result !== 'object') return true;
+
+    const errors = 'errors' in result ? result.errors : undefined;
+
+    return !Array.isArray(errors) || errors.length > 0;
+};
+
+const verifyImportableEntry = async (
+    entry: LearnCardBundleEntryMetadata,
+    content: JsonValue,
+    options: ImportLearnCardBundleOptions
+): Promise<void> => {
+    if (!options.verifyBeforeImport) return;
+
+    if (entry.type === 'credential') {
+        if (!options.wallet.invoke.verifyCredential) {
+            throw new Error('Target wallet does not expose invoke.verifyCredential');
+        }
+
+        const verification = await options.wallet.invoke.verifyCredential(content);
+
+        if (isFailedVerification(verification)) throw new Error('Credential verification failed');
+
+        return;
+    }
+
+    if (!options.wallet.invoke.verifyPresentation) {
+        throw new Error('Target wallet does not expose invoke.verifyPresentation');
+    }
+
+    const verification = await options.wallet.invoke.verifyPresentation(content);
+
+    if (isFailedVerification(verification)) throw new Error('Presentation verification failed');
+};
+
+export const readLearnCardBundleData = async (
+    data: Buffer,
+    options: ReadLearnCardBundleOptions = {}
+): Promise<ReadLearnCardBundleResult> => {
+    const maxBundleBytes = options.maxBundleBytes ?? DEFAULT_MAX_BUNDLE_BYTES;
+    const maxEntryBytes = options.maxEntryBytes ?? DEFAULT_MAX_ENTRY_BYTES;
+    const maxJsonBytes = options.maxJsonBytes ?? DEFAULT_MAX_JSON_BYTES;
+
+    assertSize('LearnCard bundle', data.byteLength, maxBundleBytes);
+
+    const zip = await JSZip.loadAsync(data);
+    const manifestFile = zip.file('manifest.json');
+
+    if (!manifestFile) throw new Error('LearnCard bundle is missing manifest.json');
+
+    const manifestContent = await manifestFile.async('string');
+
+    assertSize('manifest.json', byteLength(manifestContent), maxJsonBytes);
+
+    const manifest = JSON.parse(manifestContent) as LearnCardBundleManifest;
+
+    assertValidManifest(manifest);
+
+    const warnings = [...manifest.warnings];
+    const entries: ReadLearnCardBundleResult['entries'] = [];
+    const shouldDecrypt = options.decrypt ?? true;
+    let totalEntryBytes = 0;
+
+    for (const entry of manifest.contents) {
+        const file = zip.file(entry.path);
+
+        if (!file) throw new Error(`LearnCard bundle is missing ${entry.path}`);
+
+        const stored = await file.async('string');
+        const storedBytes = byteLength(stored);
+
+        assertSize(entry.path, storedBytes, maxEntryBytes);
+
+        totalEntryBytes += storedBytes;
+        assertSize('LearnCard bundle entries', totalEntryBytes, maxBundleBytes);
+
+        const actualSha = sha256Hex(stored);
+
+        if (actualSha !== entry.sha256) {
+            throw new Error(`SHA-256 mismatch for ${entry.path}`);
+        }
+
+        const content = shouldDecrypt
+            ? await decodePayload(stored, {
+                  encrypted: entry.encrypted,
+                  password: options.password,
+              })
+            : stored;
+
+        assertSize(`${entry.path} content`, byteLength(content), maxEntryBytes);
+
+        entries.push({ ...entry, content });
+    }
+
+    return { manifest, entries, warnings };
+};
+
+export const readLearnCardBundle = async (
+    path: string,
+    options: ReadLearnCardBundleOptions = {}
+): Promise<ReadLearnCardBundleResult> => readLearnCardBundleData(await readFile(path), options);
+
+export const importLearnCardBundle = async (
+    path: string,
+    options: ImportLearnCardBundleOptions
+): Promise<ImportLearnCardBundleReport> => {
+    const bundle = await readLearnCardBundle(path, options);
+    const maxJsonBytes = options.maxJsonBytes ?? DEFAULT_MAX_JSON_BYTES;
+    const report: ImportLearnCardBundleReport = {
+        importedCredentials: 0,
+        importedPresentations: 0,
+        skipped: 0,
+        skippedByType: {},
+        errors: [],
+        warnings: [...bundle.warnings],
+    };
+
+    if (!options.verifyBeforeImport) {
+        report.warnings.push(
+            'Bundle credential signatures were not verified before import; only import bundles from sources you trust.'
+        );
+    }
+
+    const entriesById = new Map(bundle.entries.map(entry => [entry.id, entry]));
+
+    for (const entry of bundle.entries) {
+        if (!isImportableCredentialEntry(entry)) {
+            report.skipped += 1;
+            report.skippedByType[entry.type] = (report.skippedByType[entry.type] ?? 0) + 1;
+            continue;
+        }
+
+        try {
+            const content = parseJson(entry.content, entry.path, maxJsonBytes);
+
+            await verifyImportableEntry(entry, content, options);
+
+            const upload =
+                options.wallet.store.LearnCloud.uploadEncrypted ??
+                options.wallet.store.LearnCloud.upload;
+
+            if (!upload)
+                throw new Error('Target wallet does not expose a LearnCloud upload method');
+
+            const uri = await upload(content);
+            const referencedIndexRecord = entry.indexRecordRef
+                ? entriesById.get(entry.indexRecordRef)
+                : undefined;
+
+            if (entry.indexRecordRef && !referencedIndexRecord) {
+                throw new Error(`Referenced index record ${entry.indexRecordRef} is missing`);
+            }
+
+            const indexRecord = referencedIndexRecord
+                ? parseObject(
+                      referencedIndexRecord.content,
+                      referencedIndexRecord.path,
+                      maxJsonBytes
+                  )
+                : { id: entry.id, uri };
+            const recordId = typeof indexRecord.id === 'string' ? indexRecord.id : entry.id;
+
+            await options.wallet.index.LearnCloud.add({
+                ...indexRecord,
+                id: recordId,
+                uri,
+                sourceExport: {
+                    manifestCreatedAt: bundle.manifest.createdAt,
+                    sourceUri: entry.sourceUri,
+                    sourcePath: entry.path,
+                    credentialId: entry.credentialId,
+                },
+            });
+
+            if (entry.type === 'presentation') report.importedPresentations += 1;
+            else report.importedCredentials += 1;
+        } catch (error) {
+            report.errors.push({ path: entry.path, message: safeMessage(error) });
+        }
+    }
+
+    return report;
+};

package/src/index.ts

@@ -0,0 +1,25 @@
+export { createLearnCardBundle, exportLearnCardBundle } from './exportBundle';
+export {
+    importLearnCardBundle,
+    readLearnCardBundle,
+    readLearnCardBundleData,
+} from './importBundle';
+export { assertValidManifest, computePayloadSha256, finalizeManifest } from './manifest';
+export {
+    readLearnCardBundleSeed,
+    readLearnCardBundleSeedData,
+    restoreLearnCardFromBundle,
+    restoreLearnCardFromBundleData,
+} from './restoreBundle';
+export type {
+    ExportLearnCardBundleOptions,
+    ImportLearnCardBundleOptions,
+    ImportLearnCardBundleReport,
+    LearnCardBundleManifest,
+    LearnCardBundleOptions,
+    LearnCardBundleResult,
+    LearnCardBundleWallet,
+    ReadLearnCardBundleOptions,
+    ReadLearnCardBundleResult,
+} from './types';
+export type { RestoreLearnCardFromBundleOptions, RestoreLearnCardInit } from './restoreBundle';

package/src/manifest.ts

@@ -0,0 +1,103 @@
+import type { LearnCardBundleEntryMetadata, LearnCardBundleManifest } from './types';
+import { stableStringify, sha256Hex } from './crypto';
+
+export const SPEC_VERSION = '1.0.0' as const;
+
+export const BUNDLE_SPEC_MD = `# LearnCard Holder Continuity Bundle v1.0.0
+
+A LearnCard holder continuity bundle is a ZIP file with readable metadata and encrypted holder payloads.
+
+## Container
+
+Required readable entries:
+
+- \`manifest.json\` — inventory, hashes, warnings, and encryption metadata.
+- \`README.md\` — human-readable recovery notes.
+- \`BUNDLE_SPEC.md\` — this format description.
+
+Sensitive entries use JSON encryption envelopes produced by \`@learncard/sss-key-manager\` \`encryptWithPassword\`: Argon2id key derivation and AES-GCM authenticated encryption. The ZIP itself is not password encrypted.
+
+## Security model
+
+This bundle exports the wallet's full raw private-key seed at \`keys/private-key-seed.txt.enc\`. LearnCard's live wallet protects the key with 2-of-4 Shamir Secret Sharing, where no single share can reconstruct it. The bundle does NOT preserve that threshold: the exported seed alone is sufficient to take full control of the identity, and the bundle password is the only barrier protecting it. \`keys/recovery-phrase.txt.enc\` is derived from the current recovery share for reference and is not independently sufficient to recover the key. Treat the bundle like a password-vault backup, use a strong unique password, and rotate the wallet if the bundle is exposed.
+
+## Paths
+
+- \`keys/recovery-phrase.txt.enc\`
+- \`keys/private-key-seed.txt.enc\`
+- \`keys/jwks.json.enc\`
+- \`keys/did-document.json\`
+- \`credentials/<sha256>.json.enc\`
+- \`presentations/<sha256>.json.enc\`
+- \`index-records/<sha256>.json.enc\`
+- \`consent-records/<sha256>.json.enc\`
+- \`status-cache/<sha256>.json.enc\`
+
+Debug exports MAY use plaintext payloads by setting \`encrypt: false\`; production exports MUST encrypt sensitive payloads.
+
+Status-list snapshot fetching is HTTPS-only and rejects private, loopback, link-local, and single-label hosts. Exporters SHOULD keep the default timeout and response-size caps unless they are running in a trusted local environment.
+
+## Manifest hashing
+
+Each \`contents[]\` entry contains the SHA-256 hash of the bytes stored at \`path\`. \`payloadSha256\` is SHA-256 over a deterministic JSON serialization of \`contents[]\` with entries sorted by path.
+
+Each credential or presentation entry MAY reference an encrypted \`index-record\` companion entry via \`indexRecordRef\`; the readable manifest does not embed the original index record JSON.
+
+## Restore vs import
+
+\`restoreLearnCardFromBundle(...)\` decrypts \`keys/private-key-seed.txt.enc\` and passes that seed to \`initLearnCard(...)\`. It recreates the original wallet identity; it does not upload payloads or recreate index records.
+
+\`importLearnCardBundle(...)\` decrypts credential and presentation payloads, uploads them to the target wallet's LearnCloud store, and recreates index records from the encrypted \`index-record\` companions.
+
+Import writes bundle contents into the target wallet. A bundle author who knows the password can include arbitrary credentials, presentations, and index metadata. Use \`verifyBeforeImport: true\` to verify VC/VP signatures before upload when the target wallet exposes \`invoke.verifyCredential\` and \`invoke.verifyPresentation\`.
+
+## Size limits
+
+Readers enforce default compressed-bundle, per-entry, and JSON parse limits to avoid accidentally processing oversized ZIP or JSON payloads. Callers can override these with \`maxBundleBytes\`, \`maxEntryBytes\`, and \`maxJsonBytes\` for trusted local workflows.
+
+## Import expectations
+
+Importers MUST verify the stored bytes against each entry hash before trusting decrypted content. Importers SHOULD verify issuer signatures before upload and preserve issuer-signed credential and presentation payloads exactly.
+`;
+
+export const BUNDLE_README_MD = `# LearnCard Holder Continuity Export
+
+This archive contains a point-in-time holder export from a LearnCard wallet.
+
+Keep the password separately. Without it, encrypted credentials, key material, consent records, and status-list snapshots cannot be recovered.
+
+This archive contains your full private-key seed (encrypted). Anyone with both this file and its password can take complete control of your wallet identity, so store it like a password-vault backup and rotate your wallet if it is exposed.
+
+The readable manifest lists every payload and its SHA-256 hash. Third-party wallets can import individual W3C Verifiable Credentials or Verifiable Presentations from the decrypted JSON files even when they do not support the LearnCard ZIP bundle directly.
+`;
+
+export const sortContents = (
+    contents: LearnCardBundleEntryMetadata[]
+): LearnCardBundleEntryMetadata[] => [...contents].sort((a, b) => a.path.localeCompare(b.path));
+
+const normalizeContents = (
+    contents: LearnCardBundleEntryMetadata[]
+): LearnCardBundleEntryMetadata[] =>
+    JSON.parse(JSON.stringify(sortContents(contents))) as LearnCardBundleEntryMetadata[];
+
+export const computePayloadSha256 = (contents: LearnCardBundleEntryMetadata[]): string =>
+    sha256Hex(stableStringify(normalizeContents(contents)));
+
+export const finalizeManifest = (
+    manifest: Omit<LearnCardBundleManifest, 'payloadSha256'>
+): LearnCardBundleManifest => ({
+    ...manifest,
+    contents: normalizeContents(manifest.contents),
+    payloadSha256: computePayloadSha256(manifest.contents),
+});
+
+export const assertValidManifest = (manifest: LearnCardBundleManifest): void => {
+    if (manifest.specVersion !== SPEC_VERSION) {
+        throw new Error(`Unsupported LearnCard bundle version: ${manifest.specVersion}`);
+    }
+
+    const expected = computePayloadSha256(manifest.contents);
+
+    if (manifest.payloadSha256 !== expected)
+        throw new Error('LearnCard bundle manifest hash mismatch');
+};

package/src/restoreBundle.ts

@@ -0,0 +1,62 @@
+import { initLearnCard } from '@learncard/init';
+import type { InitLearnCard } from '@learncard/init';
+
+import { readLearnCardBundle, readLearnCardBundleData } from './importBundle';
+import type { ReadLearnCardBundleOptions, ReadLearnCardBundleResult } from './types';
+
+type SeededInitConfig = Extract<InitLearnCard['args'], { seed: string }>;
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+
+export type RestoreLearnCardInit = DistributiveOmit<SeededInitConfig, 'seed'>;
+
+export type RestoreLearnCardFromBundleOptions = ReadLearnCardBundleOptions & {
+    init: RestoreLearnCardInit;
+};
+
+const getSeedEntry = (bundle: ReadLearnCardBundleResult): string => {
+    const seedEntry = bundle.entries.find(entry => entry.type === 'key-private-seed');
+
+    if (!seedEntry) {
+        throw new Error(
+            'LearnCard bundle does not contain key-private-seed and cannot be restored'
+        );
+    }
+
+    const seed = seedEntry.content.trim();
+
+    if (!/^[0-9a-f]{64}$/i.test(seed)) {
+        throw new Error(
+            'LearnCard bundle key-private-seed must be exactly 64 hexadecimal characters'
+        );
+    }
+
+    return seed;
+};
+
+export const readLearnCardBundleSeedData = async (
+    data: Buffer,
+    options: ReadLearnCardBundleOptions = {}
+): Promise<string> => getSeedEntry(await readLearnCardBundleData(data, options));
+
+export const readLearnCardBundleSeed = async (
+    path: string,
+    options: ReadLearnCardBundleOptions = {}
+): Promise<string> => getSeedEntry(await readLearnCardBundle(path, options));
+
+export const restoreLearnCardFromBundleData = async (
+    data: Buffer,
+    options: RestoreLearnCardFromBundleOptions
+): Promise<InitLearnCard['returnValue']> => {
+    const seed = await readLearnCardBundleSeedData(data, options);
+
+    return initLearnCard({ ...options.init, seed } as SeededInitConfig);
+};
+
+export const restoreLearnCardFromBundle = async (
+    path: string,
+    options: RestoreLearnCardFromBundleOptions
+): Promise<InitLearnCard['returnValue']> => {
+    const seed = await readLearnCardBundleSeed(path, options);
+
+    return initLearnCard({ ...options.init, seed } as SeededInitConfig);
+};

package/src/types.ts

@@ -0,0 +1,149 @@
+import type { CredentialRecord } from '@learncard/types';
+
+export type BundleContentType =
+    | 'key-recovery-phrase'
+    | 'key-private-seed'
+    | 'key-jwks'
+    | 'did-document'
+    | 'credential'
+    | 'presentation'
+    | 'consent-record'
+    | 'status-cache'
+    | 'unknown-json'
+    | 'index-record';
+
+export type BundleEncryptionMode = 'argon2id-aes-256-gcm' | 'none';
+
+export type JsonValue =
+    | null
+    | boolean
+    | number
+    | string
+    | JsonValue[]
+    | { [key: string]: JsonValue };
+
+export type LearnCardBundleEntryMetadata = {
+    id: string;
+    type: BundleContentType;
+    path: string;
+    mediaType: string;
+    sha256: string;
+    encrypted: boolean;
+    sourceUri?: string;
+    credentialId?: string;
+    indexRecordRef?: string;
+    warnings?: string[];
+};
+
+export type LearnCardBundleManifest = {
+    specVersion: '1.0.0';
+    createdAt: string;
+    primaryDid: string;
+    walletName: 'LearnCard';
+    encryption: {
+        mode: BundleEncryptionMode;
+        encryptedPayloads: boolean;
+        envelope?: 'sss-key-manager-encryptWithPassword-v1';
+        kdf?: 'argon2id';
+        cipher?: 'AES-256-GCM';
+    };
+    contents: LearnCardBundleEntryMetadata[];
+    warnings: string[];
+    payloadSha256: string;
+};
+
+export type LearnCardBundleOptions = {
+    password?: string;
+    encrypt?: boolean;
+    createdAt?: string;
+    fetchStatusLists?: boolean;
+    statusListFetchTimeoutMs?: number;
+    maxStatusListBytes?: number;
+};
+
+export type ExportLearnCardBundleOptions = LearnCardBundleOptions & {
+    out: string;
+};
+
+export type ReadLearnCardBundleOptions = {
+    password?: string;
+    decrypt?: boolean;
+    maxBundleBytes?: number;
+    maxEntryBytes?: number;
+    maxJsonBytes?: number;
+};
+
+export type ImportLearnCardBundleOptions = ReadLearnCardBundleOptions & {
+    wallet: LearnCardBundleWallet;
+    verifyBeforeImport?: boolean;
+};
+
+export type LearnCardBundleResult = {
+    data: Buffer;
+    manifest: LearnCardBundleManifest;
+    warnings: string[];
+};
+
+export type ReadLearnCardBundleResult = {
+    manifest: LearnCardBundleManifest;
+    entries: Array<LearnCardBundleEntryMetadata & { content: string }>;
+    warnings: string[];
+};
+
+export type ImportLearnCardBundleReport = {
+    importedCredentials: number;
+    importedPresentations: number;
+    skipped: number;
+    /** Count of skipped (non-importable) entries broken down by their bundle content type. */
+    skippedByType: Partial<Record<BundleContentType, number>>;
+    errors: Array<{ path: string; message: string }>;
+    warnings: string[];
+};
+
+export type LearnCardBundleWallet = {
+    id: {
+        did: (method?: string) => string;
+        keypair?: (algorithm?: 'ed25519' | 'secp256k1') => JsonValue;
+    };
+    invoke: {
+        getKey?: () => string;
+        resolveDid?: (did: string) => Promise<JsonValue>;
+        verifyCredential?: (
+            credential: JsonValue,
+            options?: Record<string, unknown>
+        ) => Promise<unknown>;
+        verifyPresentation?: (
+            presentation: JsonValue,
+            options?: Record<string, unknown>
+        ) => Promise<unknown>;
+        getHolderExportMetadata?: () => Promise<JsonValue>;
+        getConsentedContracts?: () => Promise<JsonValue>;
+    };
+    index: {
+        LearnCloud: {
+            get: (query?: Record<string, unknown>) => Promise<CredentialRecord[]>;
+            add: (record: CredentialRecord) => Promise<unknown>;
+        };
+    };
+    read: {
+        get: (uri: string) => Promise<JsonValue | undefined>;
+    };
+    store: {
+        LearnCloud: {
+            upload?: (content: JsonValue) => Promise<string>;
+            uploadEncrypted?: (content: JsonValue) => Promise<string>;
+        };
+    };
+};
+
+export type EncryptedPayloadEnvelope = {
+    ciphertext: string;
+    iv: string;
+    salt: string;
+    kdfParams: {
+        algorithm: 'argon2id';
+        timeCost: number;
+        memoryCost: number;
+        parallelism: number;
+    };
+};

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Learning Economy Foundation <sdk@learningeconomy.io>
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.