@papervault/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 PaperVault.xyz
+
+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,127 @@
+# PaperVault Core — Crypto + Shamir + page generation library
+
+**PaperVault 📄🔐** is a free open source tool for creating offline paper-based data vaults for your foundational secrets, such as passwords, 2FA recovery codes, digital asset keys, hard drive encryption keys, and other critical data.
+
+This is the **core library** — the AES-256-GCM crypto, Shamir Secret Sharing, and printable HTML page generation that powers [`@papervault/cli`](https://www.npmjs.com/package/@papervault/cli) and [`@papervault/mcp`](https://www.npmjs.com/package/@papervault/mcp). The browser app lives at [papervault.xyz](https://papervault.xyz).
+
+If you just want to back up secrets to paper, install [`@papervault/cli`](https://www.npmjs.com/package/@papervault/cli) instead. This package is the building block — useful if you want to embed kit generation in your own tool.
+
+## 🔐 Overview
+
+`@papervault/core` is a pure-JavaScript library (no native deps) that:
+
+- Encrypts plaintext with a fresh AES-256-GCM key (via Web Crypto API)
+- Splits the key into N shares using [Shamir's Secret Sharing](https://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing) over GF(2^8), recoverable with any M of N
+- Generates standalone printable HTML pages: one vault page with the ciphertext QR and N key pages with one share QR each
+- Produces the **v2 vault format** — byte-identical to vaults produced at [papervault.xyz](https://papervault.xyz), so kits unlock at [papervault.xyz/unlock](https://papervault.xyz/unlock)
+
+## 🚀 Quick Start
+
+```bash
+npm install @papervault/core
+```
+
+```js
+import { createKit } from '@papervault/core';
+
+const kit = await createKit({
+  secrets: [
+    { kind: 'password', service: 'GitHub', username: 'alice', password: 's3cret' },
+    { kind: 'wallet',   name: 'BTC cold', seed: 'abandon abandon ... about' },
+  ],
+  vaultName: 'My DR Kit',
+  threshold: 2,
+  shares: 3,
+});
+
+// kit.pages = [
+//   { kind: 'vault', html: '...', filename: 'vault', ... },
+//   { kind: 'key',   html: '...', filename: 'key-1-atom-river', seq: 'Key 1', alias: 'atom-river', ... },
+//   ...
+// ]
+// kit.keyShares, kit.cipherKeyHex, kit.cipherTextHex, kit.cipherIvHex available for round-trip / verify.
+```
+
+Requires Node.js ≥ 24 (needs global `crypto` and `crypto.subtle`).
+
+## 🔑 Public API
+
+| Export | Purpose |
+|---|---|
+| `createKit(opts)` | High-level: compress → encrypt → split → generate HTML. Returns the full `Kit`. |
+| `compress(secrets, freeText?)` | Convert structured entries into the web-app's ultra-compact JSON. Byte-identical to what papervault.xyz produces. |
+| `countUserContent(secrets, freeText?)` | Character-count for the 300-char limit (matches the web app's `getUserContentLength`). |
+| `encrypt(plaintext)` | Fresh-key AES-256-GCM. Returns `{cipherText, cipherKey, cipherIV}` (all hex). |
+| `decrypt(cipherTextHex, keyHex, ivHex)` | Inverse. |
+| `splitKey(secretKeyHex, n, t)` | Shamir split. 32-byte hex key in, array of hex shares out. |
+| `combineShares(shares)` | Inverse — give it ≥ threshold shares, get the original key back. |
+| `generateKeyAliases(n)` | Two-word BIP-39 aliases (e.g. `atom-river`). |
+| `generateVaultId()` | 6-char public hex ID. |
+| `generateVaultPage(opts)` / `buildVaultBody(opts)` | Standalone vault HTML, or just its inner body fragment. |
+| `generateKeyPage(opts)` / `buildKeyBody(opts)` | Same for key pages. |
+| `generatePrintAllPage(opts)` | Single doc concatenating every kit page with CSS page breaks — one print dialog for the whole packet. |
+| `generateSelectorPage(opts)` | Orchestration page used by the CLI's ephemeral print server. |
+| `LIMITS` | `{MAX_KEYS: 20, MAX_STORAGE: 300, MAX_QR_PAYLOAD_BYTES: 102400}` |
+| `VAULT_VERSION` | `'2'` |
+| `VAULT_IDENT` | `'papervault.xyz'` — sentinel in vault QR payloads. |
+
+## 📄 Vault format
+
+v2 vaults use:
+
+- **AES-256-GCM** for encryption (Web Crypto API)
+- **Shamir Secret Sharing over GF(2^8)** for key splitting ([shamir-secret-sharing](https://github.com/privy-io/shamir-secret-sharing))
+- **Random 12-byte nonce** per encryption, generated by `crypto.getRandomValues()`
+- **Level-M QR codes** for ~15% damage tolerance
+
+The QR payload shapes match the web app exactly:
+
+```js
+// Vault QR (single-QR form; splits to metadata + data QRs if > 420 bytes)
+{ id: 1, vault: 'papervault.xyz', version: '2', name, shares, threshold,
+  cipherIV, keys: [...], data: cipherText }
+
+// Key QR
+{ ident: keyAlias, key: keyShare }
+```
+
+V1 vault decryption (legacy CryptoJS / AES-CTR / `secrets.js`) lives in the web app, not here — this package is v2-only by design.
+
+## 🛡️ Security Notes
+
+- All randomness via `crypto.getRandomValues()`. Never `Math.random()`.
+- `crypto.subtle` for AES-GCM — no JS reimplementation of the cipher.
+- No persistent state. The library never writes anywhere.
+- The returned `Kit` object holds the raw AES key + Shamir shares so the caller can audit / round-trip. Treat it like a secret and drop the reference when done.
+
+For the full PaperVault threat model, see the main app's [README](https://github.com/boazeb/papervault) and [SECURITY.md](https://github.com/boazeb/papervault/blob/main/SECURITY.md).
+
+## 📦 Limits
+
+- **Maximum Keys**: 20 (Shamir library constraint)
+- **Storage Limit**: 300 characters of user content per vault (QR optimization — matches the web app)
+
+`createKit` enforces both and throws clear errors.
+
+## 🔗 Related Packages
+
+- [`@papervault/cli`](https://www.npmjs.com/package/@papervault/cli) — Command-line front-end (most users want this)
+- [`@papervault/mcp`](https://www.npmjs.com/package/@papervault/mcp) — MCP server for AI agents
+- [`@papervault/init`](https://www.npmjs.com/package/@papervault/init) — `npx` setup wizard
+- [PaperVault web app](https://papervault.xyz) — same crypto, browser version
+- [Main repo](https://github.com/boazeb/papervault) — issues, docs, SECURITY.md, full Vault-vs-key-shares explanation, AI-audit links
+
+## 🤝 Contributing
+
+Contributions are welcome! See the main repo at [github.com/boazeb/papervault](https://github.com/boazeb/papervault).
+
+## 📄 License
+
+MIT — see [LICENSE](LICENSE).
+
+## 🙏 Acknowledgments
+
+- [Shamir's Secret Sharing](https://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing) algorithm by Adi Shamir
+- [shamir-secret-sharing](https://github.com/privy-io/shamir-secret-sharing) — v2 Shamir over GF(2^8)
+- [bip39](https://github.com/bitcoinjs/bip39) — mnemonic word lists for key aliases
+- [qrcode](https://github.com/soldair/node-qrcode) — QR generation

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@papervault/core",
+  "version": "0.1.0",
+  "description": "Crypto + Shamir Secret Sharing + printable HTML page generation for PaperVault disaster-recovery kits. Produces vaults that unlock at papervault.xyz.",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./crypto": "./src/crypto.js",
+    "./templates": "./src/templates/index.js"
+  },
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24.x"
+  },
+  "homepage": "https://papervault.xyz",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/boazeb/papervault.git",
+    "directory": "papervault-core"
+  },
+  "bugs": {
+    "url": "https://github.com/boazeb/papervault/issues"
+  },
+  "keywords": [
+    "papervault",
+    "cryptography",
+    "shamir-secret-sharing",
+    "aes-256-gcm",
+    "secret-sharing",
+    "paper-wallet",
+    "cold-storage",
+    "threshold-encryption",
+    "qr-code",
+    "open-source"
+  ],
+  "author": "PaperVault.xyz",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "bip39": "^3.1.0",
+    "qrcode": "^1.5.3",
+    "shamir-secret-sharing": "^0.0.4"
+  }
+}

package/src/compress.js

@@ -0,0 +1,170 @@
+// Convert structured CLI-input secrets into the web-app's ultra-compact format,
+// matching papervault/src/components/SecretDataEntry.jsx convertToCompressedText().
+// This is the plaintext that gets AES-GCM encrypted, so byte-identical output
+// is what makes kits unlockable on papervault.xyz.
+//
+// Also exposes countUserContent() — character-counting that mirrors the web
+// app's getUserContentLength(): sum of non-empty field values across all
+// structured entries + freeText, EXCLUDING JSON overhead. This is what gets
+// compared against LIMITS.MAX_STORAGE (300 chars) so the QR stays scannable.
+
+import { LIMITS } from './constants.js';
+
+// Field orders MUST match SecretDataEntry.jsx exactly.
+const FIELD_ORDER = {
+    passwords: ['service', 'username', 'password', 'url', 'notes'],
+    wallets: ['name', 'seed', 'privateKey', 'address', 'notes'],
+    notes: ['title', 'content'],
+    apiKeys: ['service', 'key', 'secret', 'notes'],
+    custom: ['label', 'value', 'notes'],
+};
+
+const ALLOWED_KINDS = new Set([
+    'password', 'wallet', 'note', 'apikey', 'custom',
+]);
+
+// Map singular kind -> plural section name used in the compressed format.
+const KIND_TO_SECTION = {
+    password: 'passwords',
+    wallet: 'wallets',
+    note: 'notes',
+    apikey: 'apiKeys',
+    custom: 'custom',
+};
+
+// Map well-known CLI field names -> structured entry. Lets users write
+// {"name": "github", "value": "ghp_..."} as a generic shape and we put it
+// in the right field slot per kind.
+function normalizeEntry(kind, raw) {
+    if (kind === 'password') {
+        return {
+            service: raw.service ?? raw.name ?? '',
+            username: raw.username ?? raw.user ?? '',
+            password: raw.password ?? raw.value ?? '',
+            url: raw.url ?? '',
+            notes: raw.notes ?? '',
+        };
+    }
+    if (kind === 'wallet') {
+        return {
+            name: raw.name ?? raw.service ?? '',
+            seed: raw.seed ?? raw.mnemonic ?? raw.value ?? '',
+            privateKey: raw.privateKey ?? raw.private_key ?? '',
+            address: raw.address ?? '',
+            notes: raw.notes ?? '',
+        };
+    }
+    if (kind === 'note') {
+        return {
+            title: raw.title ?? raw.name ?? '',
+            content: raw.content ?? raw.value ?? raw.body ?? '',
+        };
+    }
+    if (kind === 'apikey') {
+        return {
+            service: raw.service ?? raw.name ?? '',
+            key: raw.key ?? raw.value ?? '',
+            secret: raw.secret ?? '',
+            notes: raw.notes ?? '',
+        };
+    }
+    // custom
+    return {
+        label: raw.label ?? raw.name ?? '',
+        value: raw.value ?? '',
+        notes: raw.notes ?? '',
+    };
+}
+
+function createUltraCompactArray(values) {
+    const result = [];
+    for (const v of values) {
+        if (v && String(v).trim() !== '') {
+            result.push(String(v));
+        }
+    }
+    return result.length > 0 ? result : null;
+}
+
+/**
+ * @param {Array<{kind: string, [k: string]: any}>} secrets - User-facing structured input
+ * @param {string} [freeText] - Optional freeform text block
+ * @returns {string} - Compressed JSON exactly matching the web-app format
+ */
+export function compress(secrets, freeText) {
+    if (!Array.isArray(secrets)) {
+        throw new Error('compress: secrets must be an array.');
+    }
+    if (secrets.length > LIMITS.MAX_KEYS * 5) {
+        // Loose upper bound; the real cap comes from QR payload size.
+        throw new Error('compress: too many secrets.');
+    }
+
+    // Group entries by section in the order the web app expects.
+    const sections = { passwords: [], wallets: [], notes: [], apiKeys: [], custom: [] };
+
+    for (const raw of secrets) {
+        if (!raw || typeof raw !== 'object') {
+            throw new Error('compress: each secret must be an object.');
+        }
+        const kind = String(raw.kind || '').toLowerCase();
+        if (!ALLOWED_KINDS.has(kind)) {
+            throw new Error(`compress: unknown kind "${kind}". Allowed: ${[...ALLOWED_KINDS].join(', ')}.`);
+        }
+        const section = KIND_TO_SECTION[kind];
+        const normalized = normalizeEntry(kind, raw);
+        const ordered = FIELD_ORDER[section].map(f => normalized[f] ?? '');
+        const compact = createUltraCompactArray(ordered);
+        if (compact) sections[section].push(compact);
+    }
+
+    const cleanData = {};
+    const sectionsWithData = [];
+    for (const section of Object.keys(sections)) {
+        if (sections[section].length > 0) {
+            cleanData[section] = sections[section];
+            sectionsWithData.push(section);
+        }
+    }
+    if (freeText && String(freeText).trim() !== '') {
+        cleanData.freeText = String(freeText);
+        sectionsWithData.push('freeText');
+    }
+
+    // Same optimizations as SecretDataEntry.jsx — important for byte-identical output.
+    const nonFreeTextSections = sectionsWithData.filter(s => s !== 'freeText');
+    if (nonFreeTextSections.length === 1 && !cleanData.freeText) {
+        const onlySection = nonFreeTextSections[0];
+        const data = cleanData[onlySection];
+        if (data.length === 1) return JSON.stringify(data[0]);
+        return JSON.stringify(data);
+    }
+    return Object.keys(cleanData).length > 0 ? JSON.stringify(cleanData) : '';
+}
+
+/**
+ * Sum the character lengths of all non-empty string field values across the
+ * input secrets, plus freeText. Matches the web app's getUserContentLength()
+ * exactly so the same content hits the same limit in both places.
+ *
+ * @param {Array<object>} secrets
+ * @param {string} [freeText]
+ * @returns {number}
+ */
+export function countUserContent(secrets, freeText) {
+    if (!Array.isArray(secrets)) return 0;
+    let total = 0;
+    for (const entry of secrets) {
+        if (!entry || typeof entry !== 'object') continue;
+        for (const [key, value] of Object.entries(entry)) {
+            if (key === 'kind') continue; // metadata, not user content
+            if (typeof value === 'string' && value) {
+                total += value.length;
+            }
+        }
+    }
+    if (freeText && typeof freeText === 'string') {
+        total += freeText.length;
+    }
+    return total;
+}

package/src/constants.js

@@ -0,0 +1,19 @@
+// Mirrors papervault/src/config/limits.js and vaultConfig.js
+// Kept in sync manually for now; future: extract a single source of truth.
+
+export const VAULT_VERSION = '2';
+
+export const LIMITS = {
+    MAX_KEYS: 20,
+    MAX_STORAGE: 300,
+    MAX_QR_PAYLOAD_BYTES: 100 * 1024,
+};
+
+export const GCM_NONCE_BYTES = 12;
+export const KEY_BYTES = 32;
+export const MAX_CIPHERTEXT_HEX_LENGTH = 2 * 1024 * 1024;
+
+export const HEX_REGEX = /^[0-9a-fA-F]+$/;
+
+// Sentinel used in the vault QR `vault` field — matches what papervault.xyz expects.
+export const VAULT_IDENT = 'papervault.xyz';

package/src/crypto.js

@@ -0,0 +1,184 @@
+// V2 crypto only: AES-256-GCM via WebCrypto + Shamir Secret Sharing.
+// Extracted from papervault/src/services/EncryptionService.js.
+// Node 24.x exposes globalThis.crypto with WebCrypto subtle support.
+
+import { split as shamirSplit, combine as shamirCombine } from 'shamir-secret-sharing';
+import bip39 from 'bip39';
+import {
+    GCM_NONCE_BYTES,
+    KEY_BYTES,
+    MAX_CIPHERTEXT_HEX_LENGTH,
+    HEX_REGEX,
+    LIMITS,
+} from './constants.js';
+
+const subtle = globalThis.crypto?.subtle;
+if (!subtle) {
+    throw new Error('@papervault/core requires Node 24+ with WebCrypto (globalThis.crypto.subtle).');
+}
+
+export function secureRandomBytes(length) {
+    if (!globalThis.crypto?.getRandomValues) {
+        throw new Error('secureRandomBytes: crypto.getRandomValues is not available.');
+    }
+    return globalThis.crypto.getRandomValues(new Uint8Array(length));
+}
+
+export function hexToUint8Array(hex) {
+    if (typeof hex !== 'string' || hex.length % 2 !== 0) {
+        throw new Error('hexToUint8Array: hex string must have even length.');
+    }
+    const len = hex.length / 2;
+    const out = new Uint8Array(len);
+    for (let i = 0; i < len; i++) {
+        out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}
+
+export function uint8ArrayToHex(arr) {
+    return Array.from(arr).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+
+function validateHexInput(value, label, exactBytes, maxHexLength) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`Invalid ${label}: must be a non-empty hex string.`);
+    }
+    if (!HEX_REGEX.test(value)) {
+        throw new Error(`Invalid ${label}: not a valid hex string.`);
+    }
+    if (value.length % 2 !== 0) {
+        throw new Error(`Invalid ${label}: hex string must have even length.`);
+    }
+    if (exactBytes != null) {
+        const expectedLen = exactBytes * 2;
+        if (value.length !== expectedLen) {
+            throw new Error(`Invalid ${label}: expected ${exactBytes} bytes, got ${value.length / 2}.`);
+        }
+    }
+    if (maxHexLength != null && value.length > maxHexLength) {
+        throw new Error(`Invalid ${label}: exceeds maximum allowed size.`);
+    }
+}
+
+/**
+ * Encrypt a UTF-8 string with a freshly-generated AES-256-GCM key + nonce.
+ * Returns { cipherText, cipherKey, cipherIV, version } — all hex strings.
+ */
+export async function encrypt(plaintext) {
+    if (typeof plaintext !== 'string') {
+        throw new Error('encrypt: plaintext must be a string.');
+    }
+    const keyBytes = secureRandomBytes(KEY_BYTES);
+    const nonce = secureRandomBytes(GCM_NONCE_BYTES);
+    const key = await subtle.importKey('raw', keyBytes, { name: 'AES-GCM', length: 256 }, false, ['encrypt']);
+    const encoded = new TextEncoder().encode(plaintext);
+    const ciphertextWithTag = await subtle.encrypt(
+        { name: 'AES-GCM', iv: nonce, tagLength: 128 },
+        key,
+        encoded,
+    );
+    return {
+        cipherText: uint8ArrayToHex(new Uint8Array(ciphertextWithTag)),
+        cipherKey: uint8ArrayToHex(keyBytes),
+        cipherIV: uint8ArrayToHex(nonce),
+        version: '2',
+    };
+}
+
+/**
+ * Decrypt v2 ciphertext given the AES key + nonce in hex. Returns the UTF-8 string.
+ * Throws if validation fails or tag doesn't match.
+ */
+export async function decrypt(cipherTextHex, keyHex, ivHex) {
+    validateHexInput(ivHex, 'IV', GCM_NONCE_BYTES, null);
+    validateHexInput(keyHex, 'key', KEY_BYTES, null);
+    validateHexInput(cipherTextHex, 'ciphertext', null, MAX_CIPHERTEXT_HEX_LENGTH);
+    const key = await subtle.importKey('raw', hexToUint8Array(keyHex), { name: 'AES-GCM', length: 256 }, false, ['decrypt']);
+    const plaintext = await subtle.decrypt(
+        { name: 'AES-GCM', iv: hexToUint8Array(ivHex), tagLength: 128 },
+        key,
+        hexToUint8Array(cipherTextHex),
+    );
+    return new TextDecoder().decode(plaintext);
+}
+
+/**
+ * Split a hex-encoded 32-byte key into N shares with threshold T using Shamir over GF(2^8).
+ * Matches the v2 web-app split exactly so kits are unlockable by papervault.xyz.
+ */
+export async function splitKey(secretKeyHex, numberOfShares, threshold) {
+    if (typeof secretKeyHex !== 'string' || secretKeyHex.length === 0) {
+        throw new Error('splitKey: secretKey must be a non-empty string.');
+    }
+    if (secretKeyHex.length !== KEY_BYTES * 2 || !HEX_REGEX.test(secretKeyHex)) {
+        throw new Error('splitKey: secretKey must be 32-byte hex (64 chars).');
+    }
+    const n = Number(numberOfShares);
+    const t = Number(threshold);
+    if (!Number.isInteger(n) || n < 1 || n > LIMITS.MAX_KEYS) {
+        throw new Error(`splitKey: numberOfShares must be 1..${LIMITS.MAX_KEYS}.`);
+    }
+    if (!Number.isInteger(t) || t < 1 || t > n) {
+        throw new Error('splitKey: threshold must be 1..numberOfShares.');
+    }
+    if (n > 1 && t < 2) {
+        throw new Error('Shamir requires threshold >= 2 when shares > 1.');
+    }
+    const secret = hexToUint8Array(secretKeyHex);
+    const shareArrays = await shamirSplit(secret, n, t);
+    return shareArrays.map(arr => uint8ArrayToHex(arr));
+}
+
+/**
+ * Recombine threshold-or-more hex shares back into the 32-byte key (hex).
+ */
+export async function combineShares(shares) {
+    if (!Array.isArray(shares) || shares.length === 0) {
+        throw new Error('combineShares: shares must be a non-empty array.');
+    }
+    if (shares.length > LIMITS.MAX_KEYS) {
+        throw new Error(`combineShares: too many shares (max ${LIMITS.MAX_KEYS}).`);
+    }
+    for (let i = 0; i < shares.length; i++) {
+        const s = shares[i];
+        if (typeof s !== 'string' || s.length === 0 || s.length % 2 !== 0 || !HEX_REGEX.test(s)) {
+            throw new Error(`combineShares: share ${i} must be a valid hex string with even length.`);
+        }
+    }
+    const shareArrays = shares.map(hex => hexToUint8Array(hex));
+    const secret = await shamirCombine(shareArrays);
+    return uint8ArrayToHex(secret);
+}
+
+/**
+ * Generate human-friendly two-word key aliases using BIP39 wordlist.
+ * Returns N aliases like "atom-river", "moon-glass".
+ */
+export function generateKeyAliases(amount) {
+    if (!Number.isInteger(amount) || amount < 1 || amount > LIMITS.MAX_KEYS) {
+        throw new Error(`generateKeyAliases: amount must be 1..${LIMITS.MAX_KEYS}.`);
+    }
+    const cleanWords = [];
+    for (let i = 0; i < 4; i++) {
+        const entropyBytes = secureRandomBytes(16);
+        const entropyHex = uint8ArrayToHex(entropyBytes);
+        const words = bip39.entropyToMnemonic(entropyHex).split(' ');
+        cleanWords.push(...words);
+    }
+    const result = [];
+    let c = 0;
+    for (let i = 0; i < cleanWords.length && c < amount; i += 2) {
+        result.push(`${cleanWords[i]}-${cleanWords[i + 1]}`);
+        c++;
+    }
+    return result;
+}
+
+/**
+ * Short public ID for a vault (6 hex chars). Used for folder naming and display.
+ * NOT a secret — derived from fresh random bytes, no relation to the key.
+ */
+export function generateVaultId() {
+    return uint8ArrayToHex(secureRandomBytes(3));
+}

package/src/index.js

@@ -0,0 +1,22 @@
+// Public API for @papervault/core.
+// Consumed by @papervault/cli and (in the future) @papervault/mcp.
+
+export { createKit } from './kit.js';
+export { compress, countUserContent } from './compress.js';
+export {
+    encrypt,
+    decrypt,
+    splitKey,
+    combineShares,
+    generateKeyAliases,
+    generateVaultId,
+    secureRandomBytes,
+    uint8ArrayToHex,
+    hexToUint8Array,
+} from './crypto.js';
+export {
+    generateVaultPage,
+    generateKeyPage,
+    generateSelectorPage,
+} from './templates/index.js';
+export { LIMITS, VAULT_VERSION, VAULT_IDENT } from './constants.js';