@learncard/holder-continuity 0.1.0

package/BUNDLE_SPEC.md

@@ -0,0 +1,63 @@
+# 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
+
+A holder continuity bundle exports the wallet's full raw private-key seed at `keys/private-key-seed.txt.enc`. This is a deliberate trade-off that prioritizes holder self-custody and a zero-cooperation exit path over the live wallet's threshold model.
+
+LearnCard's live wallet protects the key with 2-of-4 Shamir Secret Sharing (device, auth, recovery, and email shares), where no single share can reconstruct the key. The bundle does **not** preserve that threshold property: the exported seed alone is sufficient to reconstruct the key and DID and take full control of the identity. The bundle password (Argon2id + AES-256-GCM) is therefore the only barrier protecting the seed.
+
+Consequences:
+
+- Anyone who obtains both the bundle and its password gains complete control of the wallet, bypassing SSS entirely.
+- The `keys/recovery-phrase.txt.enc` entry is derived from the current SSS recovery share. It is provided for reference and is **not** independently sufficient to recover the key on its own; recovery from a bundle uses the exported seed.
+- Treat the bundle like a password-vault backup: store it offline, 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.

package/LICENSE

@@ -0,0 +1,21 @@
+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.

package/README.md

@@ -0,0 +1,71 @@
+# @learncard/holder-continuity
+
+Helpers for creating, reading, importing, and restoring LearnCard holder continuity bundles.
+
+A bundle is a normal ZIP file with a readable `manifest.json` and encrypted payload files for key material, credentials, presentations, LearnCloud index records, consent records, and status-list snapshots.
+
+## Install
+
+```bash
+pnpm add @learncard/holder-continuity
+```
+
+## Export a wallet
+
+```ts
+import { exportLearnCardBundle } from '@learncard/holder-continuity';
+
+await exportLearnCardBundle(learnCard, {
+    out: './learncard-export.zip',
+    password: 'use-a-strong-password',
+});
+```
+
+## Read a bundle
+
+```ts
+import { readLearnCardBundle } from '@learncard/holder-continuity';
+
+const bundle = await readLearnCardBundle('./learncard-export.zip', {
+    password: 'use-a-strong-password',
+});
+```
+
+`manifest.json` is readable without the password, but sensitive payloads are encrypted by default.
+
+## Restore the original wallet
+
+```ts
+import { restoreLearnCardFromBundle } from '@learncard/holder-continuity';
+
+const restored = await restoreLearnCardFromBundle('./learncard-export.zip', {
+    password: 'use-a-strong-password',
+    init: { network: true },
+});
+```
+
+Restore decrypts the exported `key-private-seed` and passes it to `initLearnCard(...)`, so the returned wallet has the same key material and DID as the original wallet.
+
+Restore does not upload or re-index the bundle contents. Use it when you want the original wallet identity back. Use `importLearnCardBundle(...)` when you want to copy credentials and index records into another wallet.
+
+## Import into another wallet
+
+```ts
+import { importLearnCardBundle } from '@learncard/holder-continuity';
+
+await importLearnCardBundle('./learncard-export.zip', {
+    password: 'use-a-strong-password',
+    wallet: freshWallet,
+    verifyBeforeImport: true,
+});
+```
+
+Import uploads credential and presentation payloads to the target wallet's LearnCloud store and recreates their LearnCloud index records.
+
+If `verifyBeforeImport` is not set, import only proves bundle integrity and successful decryption. It does not prove issuer signatures, so only import bundles from sources you trust.
+
+Bundle readers enforce default compressed-bundle, per-entry, and JSON parse size limits. Override `maxBundleBytes`, `maxEntryBytes`, or `maxJsonBytes` only for trusted local workflows.
+
+## Bundle format
+
+See [`BUNDLE_SPEC.md`](./BUNDLE_SPEC.md) for the ZIP layout, manifest hashing rules, and encryption model.

package/dist/__tests__/bundle.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=bundle.test.d.ts.map

package/dist/__tests__/bundle.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/bundle.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/restoreBundle.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=restoreBundle.test.d.ts.map

package/dist/__tests__/restoreBundle.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restoreBundle.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/restoreBundle.test.ts"],"names":[],"mappings":""}

package/dist/crypto.d.ts

@@ -0,0 +1,14 @@
+export declare const sha256Hex: (bytes: string | Buffer) => string;
+export declare const stableStringify: (value: unknown) => string;
+export declare const encodePayload: (plaintext: string, options: {
+    encrypt: boolean;
+    password?: string;
+}) => Promise<{
+    stored: string;
+    encrypted: boolean;
+}>;
+export declare const decodePayload: (stored: string, options: {
+    encrypted: boolean;
+    password?: string;
+}) => Promise<string>;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,SAAS,UAAW,MAAM,GAAG,MAAM,KAAG,MACC,CAAC;AAErD,eAAO,MAAM,eAAe,UAAW,OAAO,KAAG,MAWhD,CAAC;AAEF,eAAO,MAAM,aAAa,cACX,MAAM,WACR;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,KACjD,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAShD,CAAC;AAEF,eAAO,MAAM,aAAa,WACd,MAAM,WACL;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,KACnD,OAAO,CAAC,MAAM,CAchB,CAAC"}

package/dist/exportBundle.d.ts

@@ -0,0 +1,4 @@
+import type { ExportLearnCardBundleOptions, LearnCardBundleOptions, LearnCardBundleResult, LearnCardBundleWallet } from './types';
+export declare const createLearnCardBundle: (wallet: LearnCardBundleWallet, options?: LearnCardBundleOptions) => Promise<LearnCardBundleResult>;
+export declare const exportLearnCardBundle: (wallet: LearnCardBundleWallet, options: ExportLearnCardBundleOptions) => Promise<LearnCardBundleResult>;
+//# sourceMappingURL=exportBundle.d.ts.map

package/dist/exportBundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exportBundle.d.ts","sourceRoot":"","sources":["../src/exportBundle.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAER,4BAA4B,EAG5B,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,EACxB,MAAM,SAAS,CAAC;AA+bjB,eAAO,MAAM,qBAAqB,WACtB,qBAAqB,YACpB,sBAAsB,KAChC,OAAO,CAAC,qBAAqB,CA6K/B,CAAC;AAEF,eAAO,MAAM,qBAAqB,WACtB,qBAAqB,WACpB,4BAA4B,KACtC,OAAO,CAAC,qBAAqB,CAO/B,CAAC"}