@papervault/core 0.1.0

package/src/kit.js

@@ -0,0 +1,206 @@
+// High-level orchestrator: turns a list of user-facing secrets into a printable
+// PaperVault kit. Output is in-memory only — the caller decides whether to
+// serve it from a localhost server, write to disk, or both.
+
+import {
+    encrypt, splitKey, generateKeyAliases, generateVaultId,
+    secureRandomBytes,
+} from './crypto.js';
+import { compress, countUserContent } from './compress.js';
+import {
+    generateVaultPage, buildVaultBody,
+    generateKeyPage, buildKeyBody,
+    generatePrintAllPage,
+} from './templates/index.js';
+import { LIMITS } from './constants.js';
+
+const DEFAULT_COLOR_PALETTE = [
+    '#FF0000', '#0000FF', '#008000', '#FFA500', '#800080',
+    '#A52A2A', '#000000', '#FF00FF', '#00FFFF', '#FFD700',
+];
+
+function pickThreeColors() {
+    const pool = [...DEFAULT_COLOR_PALETTE];
+    const picked = [];
+    for (let i = 0; i < 3 && pool.length > 0; i++) {
+        const idx = secureRandomBytes(1)[0] % pool.length;
+        picked.push(pool[idx]);
+        pool.splice(idx, 1);
+    }
+    return picked;
+}
+
+/**
+ * @typedef {object} KitPage
+ * @property {'vault'|'key'} kind
+ * @property {string} filename       Filesystem-safe basename (no extension)
+ * @property {string} label          Display label, e.g. "Vault PDF". For keys
+ *                                   this is just the alias (the seq # is
+ *                                   carried separately so the UI can style
+ *                                   the two parts differently).
+ * @property {string|null} seq       e.g. "Key 1" for key pages, null for vault
+ * @property {string|null} alias     Two-word alias for key pages
+ * @property {string|null} custodian Optional custodian name
+ * @property {string} html           Full standalone HTML document (for preview/save)
+ *
+ * @typedef {object} Kit
+ * @property {string} vaultId
+ * @property {string} vaultName
+ * @property {number} threshold
+ * @property {number} shares
+ * @property {string[]} keyAliases
+ * @property {string[]} keyShares
+ * @property {string} cipherKeyHex
+ * @property {string} cipherTextHex
+ * @property {string} cipherIvHex
+ * @property {string[]} colors
+ * @property {number} createdAt
+ * @property {KitPage[]} pages
+ * @property {string} printAllHtml   Single doc containing every page, for
+ *                                   one-shot printing of the whole packet.
+ */
+
+/**
+ * Build a complete in-memory PaperVault kit.
+ *
+ * @param {object} opts
+ * @param {Array<object>} opts.secrets
+ * @param {string} [opts.freeText]
+ * @param {string} opts.vaultName
+ * @param {number} opts.threshold
+ * @param {number} opts.shares
+ * @param {string[]} [opts.custodianNames]
+ * @param {string[]} [opts.colors]
+ * @returns {Promise<Kit>}
+ */
+export async function createKit(opts) {
+    const {
+        secrets,
+        freeText,
+        vaultName,
+        threshold,
+        shares,
+        custodianNames,
+        colors,
+    } = opts;
+
+    if (!vaultName || typeof vaultName !== 'string') {
+        throw new Error('createKit: vaultName is required.');
+    }
+    if (!Number.isInteger(shares) || shares < 1 || shares > LIMITS.MAX_KEYS) {
+        throw new Error(`createKit: shares must be 1..${LIMITS.MAX_KEYS}.`);
+    }
+    if (!Number.isInteger(threshold) || threshold < 1 || threshold > shares) {
+        throw new Error('createKit: threshold must be 1..shares.');
+    }
+    if (shares > 1 && threshold < 2) {
+        throw new Error('createKit: Shamir requires threshold >= 2 when shares > 1.');
+    }
+
+    // Count USER CONTENT only (matches web app's getUserContentLength).
+    // The compressed JSON plaintext is larger due to bracket/quote overhead,
+    // but that's not the user-facing limit — MAX_STORAGE bounds the content
+    // the user actually typed so the QR stays scannable on real paper.
+    const userChars = countUserContent(secrets, freeText);
+    if (userChars === 0) {
+        throw new Error('createKit: no secrets to back up.');
+    }
+    if (userChars > LIMITS.MAX_STORAGE) {
+        throw new Error(
+            `createKit: ${userChars} chars of secret content exceeds the ${LIMITS.MAX_STORAGE}-char limit. ` +
+            `This matches papervault.xyz's storage cap so the QR codes stay scannable. ` +
+            `Trim the secrets, split into multiple vaults, or remove low-priority entries.`
+        );
+    }
+
+    const plaintext = compress(secrets, freeText);
+    if (!plaintext) {
+        throw new Error('createKit: no secrets to back up.');
+    }
+
+    const { cipherText, cipherKey, cipherIV } = await encrypt(plaintext);
+
+    let keyShares;
+    if (shares === 1) {
+        keyShares = [cipherKey];
+    } else {
+        keyShares = await splitKey(cipherKey, shares, threshold);
+    }
+
+    const aliases = generateKeyAliases(shares);
+    const effectiveColors = colors && colors.length > 0 ? colors : pickThreeColors();
+    const createdAt = Math.floor(Date.now() / 1000);
+    const vaultId = generateVaultId();
+
+    // Build both the standalone page (for preview/save) and the body fragment
+    // (for the print-all wrapper) from one shared template.
+    const vaultBaseOpts = {
+        vaultName, cipherText, cipherIV, threshold,
+        keyAliases: aliases, createdAt, colors: effectiveColors,
+    };
+    const vaultBody = await buildVaultBody(vaultBaseOpts);
+    const vaultHtml = await generateVaultPage(vaultBaseOpts);
+
+    /** @type {KitPage[]} */
+    const pages = [
+        {
+            kind: 'vault',
+            filename: 'vault',
+            label: 'Vault PDF',
+            seq: null,
+            alias: null,
+            custodian: null,
+            html: vaultHtml,
+        },
+    ];
+
+    /** Body fragments, parallel to pages[] — used to assemble print-all. */
+    const bodies = [vaultBody];
+
+    for (let i = 0; i < shares; i++) {
+        const alias = aliases[i];
+        const custodian = custodianNames?.[i] ?? null;
+        const keyBaseOpts = {
+            vaultName,
+            keyAlias: alias,
+            keyShare: keyShares[i],
+            createdAt,
+            colors: effectiveColors,
+        };
+        const keyBody = await buildKeyBody(keyBaseOpts);
+        const keyHtml = await generateKeyPage(keyBaseOpts);
+
+        pages.push({
+            kind: 'key',
+            filename: `key-${i + 1}-${alias}`,
+            label: alias,
+            seq: `Key ${i + 1}`,
+            alias,
+            custodian,
+            html: keyHtml,
+        });
+        bodies.push(keyBody);
+    }
+
+    const printAllHtml = generatePrintAllPage({
+        vaultName,
+        bodies,
+        autoPrint: true,
+    });
+
+    return {
+        vaultId,
+        vaultName,
+        threshold,
+        shares,
+        keyAliases: aliases,
+        keyShares,
+        cipherKeyHex: cipherKey,
+        cipherTextHex: cipherText,
+        cipherIvHex: cipherIV,
+        colors: effectiveColors,
+        createdAt,
+        pages,
+        printAllHtml,
+    };
+}

package/src/templates/index.js

@@ -0,0 +1,4 @@
+export { generateVaultPage, buildVaultBody } from './vault.js';
+export { generateKeyPage, buildKeyBody } from './key.js';
+export { generateSelectorPage } from './selector.js';
+export { generatePrintAllPage } from './printall.js';

package/src/templates/key.js

@@ -0,0 +1,95 @@
+import QRCode from 'qrcode';
+import { SHARED_CSS, KEY_ASCII, DEFAULT_COLORS, esc, formatTime } from './styles.js';
+
+async function qrDataUrl(payload) {
+    return QRCode.toDataURL(payload, {
+        errorCorrectionLevel: 'M',
+        width: 280,
+        margin: 2,
+    });
+}
+
+/**
+ * Inner key page content (no HTML/HEAD/BODY wrapper). Shared between the
+ * standalone preview and the multi-page print-all wrapper.
+ */
+export async function buildKeyBody(opts) {
+    const {
+        vaultName,
+        keyAlias,
+        keyShare,
+        createdAt,
+        colors = DEFAULT_COLORS,
+    } = opts;
+
+    // QR payload matches PDFKeyBackup.jsx exactly: { ident, key }
+    const qrPayload = JSON.stringify({ ident: keyAlias, key: keyShare });
+    const qrUrl = await qrDataUrl(qrPayload);
+    const colorStrip = colors.map(c => `<span class="color-swatch" style="background:${esc(c)}"></span>`).join('');
+
+    return `<div class="layout">
+    <div class="qr-column">
+        <div class="qr-box"><img src="${qrUrl}" alt="Key QR"></div>
+        <div class="do-not-fold">DO NOT FOLD</div>
+    </div>
+    <div class="info-column">
+        <div class="header-row">
+            <h1 class="page-title">PAPERVAULT.XYZ KEY</h1>
+            <div class="color-strip">${colorStrip}</div>
+        </div>
+        <pre class="ascii-art">${KEY_ASCII}</pre>
+        <div class="key-alias-display">${esc(keyAlias)}</div>
+        <div class="panel">
+            <h3>How to Use This Key</h3>
+            <ol>
+                <li>Go to <strong>papervault.xyz/unlock</strong></li>
+                <li>Go offline</li>
+                <li>Scan your vault QR code</li>
+                <li>Scan the key(s) required to unlock the vault</li>
+            </ol>
+            <p>The unlock utility is open source: https://github.com/boazeb/papervault</p>
+        </div>
+        <div class="panel-white">
+            <h3>Key Details</h3>
+            <div class="detail-row"><strong>Vault:</strong> ${esc(vaultName)}</div>
+            <div class="detail-row"><strong>Key Name:</strong> ${esc(keyAlias)}</div>
+            <div class="detail-row"><strong>Created:</strong> ${esc(formatTime(createdAt))}</div>
+        </div>
+        <div class="panel-warning">
+            <div class="warning-title">🔒 KEEP SECURE</div>
+            <div class="warning-body">Store this key in a safe private location. Give it to its custodian in person, not over a network.</div>
+        </div>
+    </div>
+</div>`;
+}
+
+/**
+ * Standalone key page (full HTML document).
+ *
+ * @param {object} opts                   See buildKeyBody, plus:
+ * @param {boolean} [opts.autoPrint]
+ * @returns {Promise<string>}
+ */
+export async function generateKeyPage(opts) {
+    const body = await buildKeyBody(opts);
+    const autoPrintScript = opts.autoPrint
+        ? `<script>window.addEventListener('load', () => { setTimeout(() => window.print(), 200); });</script>`
+        : '';
+    const notice = opts.autoPrint
+        ? '<div class="auto-print-notice">Opening print dialog…</div>'
+        : '';
+
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>PaperVault Key — ${esc(opts.keyAlias)}</title>
+<style>${SHARED_CSS}</style>
+</head>
+<body>
+${notice}
+${body}
+${autoPrintScript}
+</body>
+</html>`;
+}

package/src/templates/printall.js

@@ -0,0 +1,67 @@
+import { SHARED_CSS, esc } from './styles.js';
+
+/**
+ * Single HTML document containing every kit page concatenated with page breaks,
+ * so a browser opens ONE native print dialog for the entire packet. From that
+ * dialog the user picks Print or "Save as PDF" from the OS dropdown.
+ *
+ * @param {object} opts
+ * @param {string} opts.vaultName
+ * @param {string[]} opts.bodies         Inner-body HTML strings, vault first then keys
+ * @param {boolean} [opts.autoPrint=true]  Trigger window.print() + window.close() on load
+ * @returns {string}                     Complete HTML document
+ */
+export function generatePrintAllPage(opts) {
+    const { vaultName, bodies, autoPrint = true } = opts;
+
+    const pages = bodies.map((body, i) => `<section class="kit-page" data-page="${i}">${body}</section>`).join('\n');
+
+    // After the print dialog returns (resolves or is cancelled), close the
+    // popup window so it doesn't sit there empty. Only works because the
+    // popup was opened via window.open() from the selector.
+    const autoPrintScript = autoPrint ? `
+<script>
+window.addEventListener('load', () => {
+    setTimeout(() => {
+        try {
+            const before = Date.now();
+            window.print();
+            // Defer close: some browsers return synchronously from print(),
+            // others (Chrome) return after the dialog closes. Either way,
+            // closing after a short delay is fine because the popup is
+            // owned by us.
+            setTimeout(() => { try { window.close(); } catch (e) {} }, 250);
+        } catch (e) { /* noop */ }
+    }, 200);
+});
+</script>` : '';
+
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>PaperVault Kit — ${esc(vaultName)}</title>
+<style>${SHARED_CSS}</style>
+<style>
+.kit-page { padding: 0; margin: 0; }
+.kit-page + .kit-page {
+    page-break-before: always;
+    break-before: page;
+    margin-top: 30px;
+}
+@media print {
+    .kit-page + .kit-page {
+        page-break-before: always;
+        break-before: page;
+        margin-top: 0;
+    }
+}
+</style>
+</head>
+<body>
+${autoPrint ? '<div class="auto-print-notice">Opening print dialog…</div>' : ''}
+${pages}
+${autoPrintScript}
+</body>
+</html>`;
+}

package/src/templates/selector.js

@@ -0,0 +1,193 @@
+import { esc } from './styles.js';
+
+/**
+ * Orchestration page: shows the kit manifest with a single "Print kit" button
+ * that opens the full packet in one native print dialog. From there the user
+ * picks Print or "Save as PDF" via the OS dropdown. Bytes never touch disk.
+ *
+ * @param {object} opts
+ * @param {string} opts.vaultName
+ * @param {number} opts.threshold
+ * @param {number} opts.shares
+ * @param {Array<{kind: 'vault'|'key', label: string, seq: string|null, alias: string|null, custodian: string|null}>} opts.pages
+ * @param {string} opts.printAllPath     Server path that returns the full packet HTML
+ */
+export function generateSelectorPage(opts) {
+    const { vaultName, threshold, shares, pages, printAllPath } = opts;
+
+    const rows = pages.map((p) => {
+        const icon = p.kind === 'vault' ? '📄' : '🔑';
+        let labelHtml;
+        if (p.kind === 'vault') {
+            labelHtml = `<span class="row-label">${esc(p.label)}</span>`;
+        } else {
+            const custodian = p.custodian
+                ? ` <span class="row-custodian">→ ${esc(p.custodian)}</span>`
+                : '';
+            labelHtml = `<span class="row-seq">${esc(p.seq)}</span><span class="row-alias">${esc(p.alias ?? p.label)}</span>${custodian}`;
+        }
+        return `<tr>
+            <td class="cell-icon">${icon}</td>
+            <td class="cell-label">${labelHtml}</td>
+        </tr>`;
+    }).join('');
+
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>PaperVault.xyz Kit — ${esc(vaultName)}</title>
+<style>
+* { box-sizing: border-box; }
+html, body { margin: 0; padding: 0; background: #f5f7fa; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif; color: #2c3e50; }
+.container { max-width: 720px; margin: 40px auto; padding: 0 20px; }
+.card { background: #fff; border: 1px solid #e9ecef; border-radius: 12px; padding: 28px; box-shadow: 0 1px 3px rgba(0,0,0,0.04); }
+h1 { font-size: 22px; margin: 0 0 4px 0; }
+.subtitle { color: #6c757d; font-size: 14px; margin: 0 0 24px 0; }
+
+.print-bar {
+    display: flex; align-items: center; justify-content: space-between;
+    gap: 16px; padding: 18px 20px;
+    background: linear-gradient(135deg, #0d6efd 0%, #0b5ed7 100%);
+    border-radius: 10px;
+}
+.print-bar-text { color: #fff; flex: 1; }
+.print-bar-text .title { font-size: 15px; font-weight: 600; margin-bottom: 2px; }
+.print-bar-text .hint { font-size: 12px; opacity: 0.85; }
+.print-button {
+    font-size: 15px; font-weight: 600; padding: 10px 22px;
+    border-radius: 7px; border: none; background: #fff; color: #0d6efd;
+    cursor: pointer; font-family: inherit;
+    box-shadow: 0 1px 2px rgba(0,0,0,0.1);
+}
+.print-button:hover { background: #f1f5fb; }
+
+/* Lives below the print bar — only rendered after the first click,
+   so it doesn't reserve empty space and unbalance the bar. */
+.print-status {
+    font-size: 12px;
+    color: #198754;
+    margin: 10px 4px 0 4px;
+    padding-left: 2px;
+}
+.print-bar-wrap { margin-bottom: 24px; }
+
+table { width: 100%; border-collapse: collapse; }
+th { text-align: left; font-size: 11px; text-transform: uppercase; letter-spacing: 0.6px; color: #8a94a3; padding: 8px 6px; border-bottom: 1px solid #e9ecef; font-weight: 600; }
+td { padding: 12px 6px; border-bottom: 1px solid #f0f2f5; vertical-align: middle; }
+tr:last-child td { border-bottom: none; }
+
+.cell-icon { width: 32px; font-size: 20px; }
+.cell-label { /* contains seq + alias for keys, or just a label for vault */ }
+
+.row-label { font-size: 14px; font-weight: 600; color: #2c3e50; }
+.row-seq {
+    display: inline-block;
+    font-size: 11px;
+    font-weight: 600;
+    color: #8a94a3;
+    text-transform: uppercase;
+    letter-spacing: 0.5px;
+    margin-right: 10px;
+    min-width: 38px;
+}
+.row-alias {
+    font-family: 'SF Mono', Menlo, Consolas, monospace;
+    font-size: 14px;
+    font-weight: 600;
+    color: #0d6efd;
+    letter-spacing: 0.2px;
+}
+.row-custodian {
+    margin-left: 8px;
+    color: #6c757d;
+    font-size: 12px;
+    font-style: italic;
+}
+
+.footer { display: flex; justify-content: space-between; align-items: center; margin-top: 24px; padding-top: 20px; border-top: 1px solid #e9ecef; }
+.footer-branding { font-size: 12px; color: #8a94a3; }
+.footer-branding a { color: #6c757d; text-decoration: none; font-weight: 600; }
+.footer-branding a:hover { color: #0d6efd; text-decoration: underline; }
+.done-button { font-size: 14px; padding: 10px 18px; border-radius: 6px; border: 1px solid #dee2e6; background: #fff; color: #6c757d; cursor: pointer; font-family: inherit; }
+.done-button:hover { background: #f8f9fa; color: #2c3e50; }
+.done-button.ready { background: #198754; border-color: #198754; color: #fff; }
+.done-button.ready:hover { background: #157347; }
+
+.modal { display: none; position: fixed; inset: 0; background: rgba(0,0,0,0.5); align-items: center; justify-content: center; z-index: 1000; }
+.modal.open { display: flex; }
+.modal-card { background: #fff; border-radius: 12px; padding: 28px; max-width: 420px; text-align: center; }
+.modal-card h2 { margin: 0 0 12px 0; font-size: 20px; }
+.modal-card p { color: #6c757d; margin: 0 0 8px 0; line-height: 1.5; }
+.modal-card .fine { font-size: 12px; color: #8a94a3; margin-top: 14px; }
+</style>
+</head>
+<body>
+<div class="container">
+    <div class="card">
+        <h1>PaperVault.xyz Kit Ready</h1>
+        <p class="subtitle">${esc(vaultName)} — ${threshold} of ${shares} keys</p>
+
+        <div class="print-bar-wrap">
+            <div class="print-bar">
+                <div class="print-bar-text">
+                    <div class="title">Print the whole packet</div>
+                    <div class="hint">${pages.length} pages</div>
+                </div>
+                <button class="print-button" onclick="printKit()">Print kit</button>
+            </div>
+            <div class="print-status" id="status"></div>
+        </div>
+
+        <table>
+            <thead><tr><th></th><th>Contents</th></tr></thead>
+            <tbody>${rows}</tbody>
+        </table>
+
+        <div class="footer">
+            <div class="footer-branding">powered by <a href="https://papervault.xyz" target="_blank" rel="noopener">papervault.xyz</a></div>
+            <button id="doneBtn" class="done-button" onclick="doneAndExit()">Done</button>
+        </div>
+    </div>
+</div>
+
+<div class="modal" id="doneModal">
+    <div class="modal-card">
+        <h2>Done</h2>
+        <p>The server has stopped and the kit is no longer reachable from this tab.</p>
+    </div>
+</div>
+
+<script>
+let actionCount = 0;
+const PRINT_ALL = ${JSON.stringify(printAllPath)};
+
+function printKit() {
+    const w = window.open(PRINT_ALL, 'papervault-print', 'width=900,height=1100');
+    if (!w) {
+        alert('Popup blocked. Please allow popups for this page so the print dialog can open.');
+        return;
+    }
+    actionCount++;
+    const status = document.getElementById('status');
+    status.textContent = actionCount === 1
+        ? '✓ Print dialog opened.'
+        : '✓ Print dialog opened (' + actionCount + ' times).';
+    document.getElementById('doneBtn').classList.add('ready');
+}
+
+async function doneAndExit() {
+    try { await fetch('/__shutdown', { method: 'POST' }); } catch (e) { /* already gone */ }
+    document.getElementById('doneModal').classList.add('open');
+}
+
+window.addEventListener('beforeunload', (e) => {
+    if (actionCount === 0) {
+        e.preventDefault();
+        e.returnValue = 'You have not printed the kit yet. It will be lost.';
+    }
+});
+</script>
+</body>
+</html>`;
+}