Holder Continuity & Portability

How holders can export, verify, and move LearnCard wallet data

"Your credentials are yours" is only true if you can leave. This page is the specific guarantee: what a LearnCard user can take with them, how, and what happens to it afterwards — with no cooperation from LearnCard required.

Where the key lives today

A LearnCard app user's private key is split with Shamir Secret Sharing, 2-of-4:

Where it lives

Purpose

Device share

Local IndexedDB

Fast same-device login

Auth share

LearnCard API server, encrypted at rest

Authenticated recovery and login

Recovery share

Passkey, phrase, or password backup

User-controlled recovery

Email share

Verified recovery email backup, encrypted before delivery

Optional additional recovery path

Any two shares can reconstruct the key. One share alone is not useful.

What the holder controls

The holder continuity export includes:

DID key material as encrypted JWKs and the private key seed.
A recovery phrase derived from the current SSS recovery share.
The primary DID document and locally derivable DID variants.
W3C Verifiable Credential and Verifiable Presentation payloads exactly as resolved from the holder's wallet index.
Encrypted LearnCloud index metadata, including URI, record ID, category, and title where available.
ConsentFlow contracts, including their current public recipients and audience version, plus terms, statuses, and transaction history returned by the authenticated holder export metadata route.
Status-list credential snapshots when the status URL is publicly fetchable during export.

Contract audiences describe the configuration at export time. They do not reconstruct which recipients were present at each historical consent or transaction.

The export preserves issuer-signed JSON. It does not normalize proofs or rewrite credential contents.

Zero-cooperation exit path

A holder who can still access their wallet can export a bundle using exportLearnCardBundle, copy credentials into another wallet with importLearnCardBundle, and restore the original identity with restoreLearnCardFromBundle. These helpers are exported by @learncard/holder-continuity.

Install @learncard/init and @learncard/holder-continuity, and set SECURE_SEED to your 64-hex seed. This Node.js example exports to a temporary directory, imports into a fresh wallet, restores the original identity, and removes the temporary bundle. For a real backup, keep the ZIP in a secure location and choose your own strong password.

import { randomBytes } from 'node:crypto';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { initLearnCard } from '@learncard/init';
import {
    exportLearnCardBundle,
    importLearnCardBundle,
    restoreLearnCardFromBundle,
} from '@learncard/holder-continuity';

if (!process.env.SECURE_SEED) throw new Error('Set SECURE_SEED');
const learnCard = await initLearnCard({ seed: process.env.SECURE_SEED, network: true });
await learnCard.invoke.getProfile(); // Load the network identity before comparing DIDs.
const original = learnCard.id.did();
// Example only: choose a unique, strong password for a real export.
const password = 'correct horse battery staple';
const directory = await mkdtemp(join(tmpdir(), 'learncard-bundle-'));
try {
    const path = join(directory, 'learncard-export.zip');
    await exportLearnCardBundle(learnCard, { out: path, password });
    const freshWallet = await initLearnCard({
        seed: randomBytes(32).toString('hex'),
        network: true,
    });
    const report = await importLearnCardBundle(path, {
        password,
        wallet: freshWallet,
        verifyBeforeImport: true,
    });
    if (report.errors.length) throw new Error('Some bundle entries could not be imported');
    console.log(`imported: ${report.importedCredentials}`);
    const restored = await restoreLearnCardFromBundle(path, { password, init: { network: true } });
    await restored.invoke.getProfile();
    console.log(`restored: ${restored.id.did() === original}`);
} finally {
    await rm(directory, { recursive: true, force: true });
}

The LearnCard CLI also supports await exportLearnCardBundle({ ...options }), which exports its default learnCard wallet. getLearnCardBundlePassword() is a CLI REPL helper, not an export of the bundle package.

After the ZIP is created, the holder can decrypt and inspect it with only the bundle password and public tooling. The readable manifest.json lists every payload and SHA-256 hash, while sensitive payloads and LearnCloud index records remain encrypted. Encrypted files use Argon2id and AES-GCM through the same @learncard/sss-key-manager password envelope used for account backup files.

Import writes to the target wallet. Use verifyBeforeImport: true when the target wallet can verify VCs/VPs before upload; otherwise, only import bundles from sources you trust.

Status-list snapshots are fetched only from public HTTPS URLs, with timeout and response-size limits, to avoid turning holder-supplied credentials into server-side fetches to private networks.

Restore passes the exported key-private-seed to initLearnCard(...). It recreates the original key and DID; it does not upload payloads or recreate index records. Use restore when you want the original wallet identity back, and use import when you want to copy credentials into another wallet.

Continuity of service

The exported artifacts are based on public standards and readable formats:

DIDs and DID Documents are JSON.
Verifiable Credentials and Verifiable Presentations are W3C VC/VP JSON payloads.
JSON-LD proofs, JWT VCs, and BitstringStatusList or StatusList2021 credentials can be verified by non-LearnCard libraries that support those suites and contexts.
Consent records are JSON snapshots with contract terms and transaction history.
The outer container is a normal ZIP file; encryption is per-payload JSON, not proprietary ZIP encryption.

If LearnCard services are unavailable, the bundle remains useful for independent verification, audit, and migration work.

What is not exported

Some LearnCard network behavior is service-specific and cannot be fully reconstructed from holder artifacts alone:

Boost authoring semantics and issuer-side template management.
Claim hooks, notification queues, inbox delivery state, and server-only activity feeds.
Network graph edges that are not represented in a credential, consent record, or transaction.
LearnCard convenience relationships such as profile recommendations or app-specific UI grouping.

Some of this can be recreated from credentials and consent records. For example, a credential's issuer, subject, proof, and status fields remain available. Server-only state that was never written into a holder-controlled artifact is not portable.

Sensitivity warning

A holder continuity export is personal data. It can include identifiers, credentials, consent history, transaction timestamps, and key material. Store it like a password vault backup, rotate the export if it is exposed, and treat status-cache files as point-in-time snapshots rather than live revocation guarantees.

Critically, the export contains the wallet's full raw private-key seed (encrypted with the bundle password). The live wallet normally protects this key with the 2-of-4 SSS threshold described above, where no single share is enough to reconstruct it. The bundle does not preserve that threshold: the exported seed alone is sufficient to take full control of the identity, so the bundle password is the only thing protecting it. The exported recovery phrase is derived from the current recovery share for reference and is not independently sufficient to recover the key — restore uses the exported seed.

Compatibility with other wallets

No third-party wallet imports the LearnCard ZIP bundle directly today. External wallets receive credentials through protocols (OID4VCI, DIDComm) or through SDK-level JSON import, not by reading manifest.json and decrypting entries.

In practice, the portable path is: decrypt the bundle, take the individual Verifiable Credential and Presentation JSON payloads, and hand them to the target wallet through whatever import path that wallet documents. Keep the original ZIP as an audit backup.

The table below reflects what each vendor's public docs describe at the time of writing. Treat it as a starting point — verify against current vendor docs, and do not assume a wallet supports the LearnCard bundle unless it has been tested against the ZIP format.

Wallet / toolkit

Raw ZIP import

Credential JSON import (after decrypt)

OID4VCI receive

DIDComm receive

Spruce / SpruceKit

Yes — CredentialPack.addJsonVc(...)

Yes

Not documented

Sphereon Wallet / SSI SDK

Not documented

Yes