@papervault/cli 0.1.0

package/src/kit-runner.js

@@ -0,0 +1,72 @@
+// Shared kit-generation flow: createKit → optional disk save → optional
+// ephemeral print server. Reused by `backup` (after fetching from a source)
+// and by `init` (after manual entry or .env import).
+//
+// Keeps the in-memory-only posture consistent: secrets only touch disk if
+// the caller explicitly opts in via savePath.
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { createKit } from '@papervault/core';
+
+import { servePrintKit } from './server.js';
+import { openUrl } from './browser.js';
+
+/**
+ * @param {object} opts
+ * @param {Array<object>} opts.secrets        Structured secrets array
+ * @param {string} [opts.freeText]
+ * @param {string} opts.vaultName
+ * @param {number} opts.threshold
+ * @param {number} opts.shares
+ * @param {string[]} [opts.custodianNames]
+ * @param {string} [opts.savePath]            If set, also writes HTML to <savePath>/vault-<id>/
+ * @param {boolean} [opts.print=true]         If true, opens the ephemeral print server in the browser
+ * @returns {Promise<{vaultId: string, savedTo: string|null, printed: boolean}>}
+ */
+export async function runKitFlow(opts) {
+    const {
+        secrets, freeText, vaultName, threshold, shares,
+        custodianNames, savePath, print = true,
+    } = opts;
+
+    const kit = await createKit({
+        secrets,
+        freeText,
+        vaultName,
+        threshold,
+        shares,
+        custodianNames,
+    });
+
+    // Optional disk save (opt-in). Saved files have the auto-print script
+    // stripped — they're for archival, not for the immediate dialog.
+    let savedTo = null;
+    if (savePath) {
+        savedTo = resolve(savePath, `vault-${kit.vaultId}`);
+        await mkdir(savedTo, { recursive: true });
+        for (const page of kit.pages) {
+            const html = page.html.replace(
+                /<script>window\.addEventListener\('load',.*?<\/script>/g, ''
+            );
+            await writeFile(join(savedTo, `${page.filename}.html`), html, 'utf8');
+        }
+        process.stderr.write(`\nSaved ${kit.pages.length} files to ${savedTo}\n`);
+    }
+
+    if (!print) {
+        if (!savedTo) {
+            process.stderr.write('Note: print=false and no savePath means the kit was generated but discarded.\n');
+        }
+        return { vaultId: kit.vaultId, savedTo, printed: false };
+    }
+
+    const { url, done } = await servePrintKit(kit);
+    process.stderr.write('\nPaperVault kit ready in memory.\n');
+    process.stderr.write(`Opening browser: ${url}\n`);
+    process.stderr.write('(Click "Done" in the browser when finished to stop the server and exit.)\n');
+    openUrl(url);
+    await done;
+    process.stderr.write('Server stopped. Kit references dropped. Exiting.\n');
+    return { vaultId: kit.vaultId, savedTo, printed: true };
+}

package/src/server.js

@@ -0,0 +1,128 @@
+// Ephemeral localhost print server.
+// Serves the selector page + each kit page from memory. Binds to 127.0.0.1
+// on a random port. Shuts down on POST /__shutdown or after an idle timeout.
+
+import { createServer } from 'node:http';
+import { generateSelectorPage } from '@papervault/core';
+
+const IDLE_TIMEOUT_MS = 15 * 60 * 1000; // 15 minutes — server self-destructs if user wanders off.
+
+/**
+ * @param {import('@papervault/core').Kit} kit
+ * @returns {Promise<{url: string, done: Promise<void>}>}
+ */
+export function servePrintKit(kit) {
+    // Build the in-memory route map. Each page gets a path like /pages/0, /pages/1...
+    const routes = new Map();
+    const pageList = kit.pages.map((p, i) => ({
+        kind: p.kind,
+        path: `/pages/${i}`,
+        label: p.label,
+        seq: p.seq,
+        alias: p.alias,
+        custodian: p.custodian,
+    }));
+    kit.pages.forEach((p, i) => routes.set(`/pages/${i}`, p));
+
+    // The whole-kit printable doc lives at /print-all and is auto-printed.
+    let printAllHtml = kit.printAllHtml;
+
+    const selectorHtml = generateSelectorPage({
+        vaultName: kit.vaultName,
+        vaultId: kit.vaultId,
+        threshold: kit.threshold,
+        shares: kit.shares,
+        pages: pageList,
+        printAllPath: '/print-all',
+    });
+
+    let resolveDone;
+    const done = new Promise(resolve => { resolveDone = resolve; });
+
+    const server = createServer((req, res) => {
+        // Block any non-localhost requests defensively.
+        const remote = req.socket.remoteAddress;
+        if (remote !== '127.0.0.1' && remote !== '::1' && remote !== '::ffff:127.0.0.1') {
+            res.writeHead(403); res.end(); return;
+        }
+
+        // CSP: deny everything except inline (we control all the HTML).
+        // No external network, no scripts from elsewhere, no images outside data: URIs.
+        res.setHeader('Content-Security-Policy',
+            "default-src 'none'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; " +
+            "script-src 'self' 'unsafe-inline'; connect-src 'self'; form-action 'none'; base-uri 'none'");
+        res.setHeader('X-Content-Type-Options', 'nosniff');
+        res.setHeader('Referrer-Policy', 'no-referrer');
+        res.setHeader('Cache-Control', 'no-store');
+
+        const url = new URL(req.url, 'http://127.0.0.1');
+        const path = url.pathname;
+
+        if (req.method === 'POST' && path === '/__shutdown') {
+            res.writeHead(204); res.end();
+            shutdown();
+            return;
+        }
+        if (req.method !== 'GET') {
+            res.writeHead(405); res.end(); return;
+        }
+
+        if (path === '/' || path === '/index.html') {
+            res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+            res.end(selectorHtml);
+            return;
+        }
+
+        if (path === '/print-all') {
+            if (!printAllHtml) {
+                res.writeHead(410); res.end('Kit cleared'); return;
+            }
+            res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+            res.end(printAllHtml);
+            return;
+        }
+
+        const page = routes.get(path);
+        if (page) {
+            res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+            res.end(page.html);
+            return;
+        }
+
+        res.writeHead(404); res.end('Not found');
+    });
+
+    function shutdown() {
+        // Drop every in-memory reference we hold so the JS engine can GC the
+        // kit data. We can't truly zeroize strings in V8 (they're immutable
+        // and may live in internal tables until GC runs), but we can at least
+        // make sure nothing in our object graph still points at them.
+        routes.clear();
+        if (Array.isArray(kit.pages)) kit.pages.length = 0;
+        if (Array.isArray(kit.keyShares)) kit.keyShares.length = 0;
+        kit.cipherKeyHex = '';
+        kit.cipherTextHex = '';
+        kit.cipherIvHex = '';
+        printAllHtml = null;
+        // Allow currently-open connections to drain briefly.
+        setTimeout(() => {
+            server.close(() => resolveDone());
+        }, 100);
+    }
+
+    const idleTimer = setTimeout(() => {
+        process.stderr.write('Idle timeout — clearing kit and shutting down server.\n');
+        shutdown();
+    }, IDLE_TIMEOUT_MS);
+    // Don't keep the event loop alive solely for the timer.
+    idleTimer.unref?.();
+
+    return new Promise(resolve => {
+        // Bind to 127.0.0.1 only.
+        server.listen(0, '127.0.0.1', () => {
+            const addr = server.address();
+            const url = `http://127.0.0.1:${addr.port}/`;
+            resolve({ url, done });
+        });
+    });
+}

package/src/sources/azure.js

@@ -0,0 +1,151 @@
+// Azure Key Vault adapter.
+//
+// Auth strategy: ride the platform's existing credential cache. We never call
+// the Azure login flow ourselves — if the user hasn't run `az login` (or set
+// AZURE_TENANT_ID + AZURE_CLIENT_ID + AZURE_CLIENT_SECRET), we throw with a
+// clear hint. Same posture as the kit pipeline itself: we're a conduit, not
+// a credential store.
+//
+// URI shape: azure-kv://<vault-name>
+//   The host part is the KV name; resolved to https://<name>.vault.azure.net.
+//   We don't support custom URLs (private endpoints) in the MVP — easy to add
+//   later via azure-kv://<name>?host=<custom>.
+//
+// Mapping: every KV secret becomes one PaperVault `apikey` entry with
+//   service = secret name, key = value, notes = contentType (if set).
+//   Tags are dropped for now to keep payload small. The kind defaults to
+//   apikey because that's what most KV secrets are; users who want different
+//   kinds per secret can pre-export to file:// and edit.
+//
+// Allowed-by-default: only the secret's LATEST enabled version. Disabled and
+//   expired secrets are skipped (logged to stderr).
+
+let cachedSDK = null;
+
+async function loadAzureSDK(override) {
+    // Tests can inject a fake SDK via opts.sdkOverride to avoid a real
+    // network round-trip. Production path lazy-imports the real packages so
+    // users who never touch Azure don't pay the require-time cost.
+    if (override) return override;
+    if (!cachedSDK) {
+        const kv = await import('@azure/keyvault-secrets');
+        const id = await import('@azure/identity');
+        cachedSDK = {
+            SecretClient: kv.SecretClient,
+            DefaultAzureCredential: id.DefaultAzureCredential,
+            AzureCliCredential: id.AzureCliCredential,
+            ChainedTokenCredential: id.ChainedTokenCredential,
+        };
+    }
+    return cachedSDK;
+}
+
+const KV_NAME_RE = /^[a-zA-Z0-9-]{3,24}$/;
+
+export function createAzureKVSource(vaultName, opts = {}) {
+    if (!KV_NAME_RE.test(vaultName)) {
+        throw new Error(
+            `azure-kv: vault name "${vaultName}" is invalid. ` +
+            `Key Vault names are 3-24 chars of letters, digits, and dashes.`
+        );
+    }
+
+    const host = opts.host || `${vaultName}.vault.azure.net`;
+    const vaultUrl = `https://${host}`;
+    let client = null;
+    let propsCache = null;
+
+    return {
+        uri: `azure-kv://${vaultName}`,
+
+        async authenticate() {
+            const sdk = await loadAzureSDK(opts.sdkOverride);
+            // Prefer the Azure CLI cache first — it's what a developer on a
+            // laptop almost always has set up. Fall back to the rest of the
+            // default chain (env vars, managed identity, etc.) for CI / VM use.
+            const credential = new sdk.ChainedTokenCredential(
+                new sdk.AzureCliCredential(),
+                new sdk.DefaultAzureCredential(),
+            );
+            client = new sdk.SecretClient(vaultUrl, credential);
+
+            // Probe: try to fetch the first page of secret properties. This
+            // exercises both the credential and the data-plane permissions.
+            try {
+                const iter = client.listPropertiesOfSecrets().byPage({ maxPageSize: 1 });
+                await iter.next();
+            } catch (err) {
+                client = null;
+                throw new Error(
+                    `Azure KV authentication / permission check failed for ${vaultUrl}.\n` +
+                    `Tried: AzureCliCredential, then DefaultAzureCredential.\n` +
+                    `Hint: run 'az login' (and 'az account set --subscription <id>' if needed), or set\n` +
+                    `      AZURE_TENANT_ID + AZURE_CLIENT_ID + AZURE_CLIENT_SECRET for a service principal.\n` +
+                    `Hint: confirm your identity has 'Key Vault Secrets User' (or get/list) on this vault.\n` +
+                    `Underlying: ${err.message ?? err}`
+                );
+            }
+        },
+
+        async list() {
+            if (!client) throw new Error('azure-kv: authenticate() must be called first');
+            const refs = [];
+            const skipped = [];
+            // listPropertiesOfSecrets returns each secret's LATEST version's
+            // properties, which is what we want. Disabled or expired secrets
+            // are filtered out (with a stderr note so the user knows).
+            for await (const p of client.listPropertiesOfSecrets()) {
+                const enabled = p.enabled !== false;
+                const expired = p.expiresOn && p.expiresOn.getTime() < Date.now();
+                if (!enabled) { skipped.push(`${p.name} (disabled)`); continue; }
+                if (expired) { skipped.push(`${p.name} (expired)`);  continue; }
+                refs.push({ name: p.name, kind: 'apikey' });
+                // Stash properties for fetch() so we don't list twice.
+                propsCache ??= new Map();
+                propsCache.set(p.name, p);
+            }
+            if (skipped.length > 0) {
+                process.stderr.write(`azure-kv: skipped ${skipped.length} secret(s): ${skipped.join(', ')}\n`);
+            }
+            return refs;
+        },
+
+        async fetch(refs) {
+            if (!client) throw new Error('azure-kv: authenticate() must be called first');
+
+            // If the caller didn't pre-filter, fetch metadata for everything.
+            if (!refs) {
+                refs = await this.list();
+            }
+
+            const secrets = [];
+            for (const r of refs) {
+                let val;
+                try {
+                    val = await client.getSecret(r.name);
+                } catch (err) {
+                    throw new Error(`azure-kv: failed to fetch secret "${r.name}" — ${err.message ?? err}`);
+                }
+                const contentType = val.properties?.contentType;
+                secrets.push({
+                    kind: 'apikey',
+                    service: r.name,
+                    key: val.value,
+                    secret: '',
+                    notes: contentType ? `contentType: ${contentType}` : '',
+                });
+            }
+            return {
+                vaultName: `Azure KV: ${vaultName}`,
+                secrets,
+            };
+        },
+
+        async close() {
+            // Drop SDK refs so the credential can release any cached tokens
+            // and the secret values fall out of the closure.
+            client = null;
+            propsCache = null;
+        },
+    };
+}

package/src/sources/file.js

@@ -0,0 +1,58 @@
+// file:// adapter — reads a JSON document from disk.
+// Expected schema (also see stdin adapter):
+//   {
+//     "vaultName": "string",            // optional, can be overridden by --name
+//     "freeText": "string",              // optional
+//     "secrets": [
+//       {"kind": "password", "name": "...", "username": "...", "value": "...", "notes": "..."},
+//       {"kind": "wallet",   "name": "...", "seed": "...", "address": "..."},
+//       {"kind": "note",     "title": "...", "content": "..."},
+//       {"kind": "apikey",   "service": "...", "key": "...", "secret": "..."},
+//       {"kind": "custom",   "label": "...", "value": "..."}
+//     ]
+//   }
+
+import { readFile } from 'node:fs/promises';
+
+function refName(s) {
+    return s.name ?? s.label ?? s.service ?? s.title ?? '<unnamed>';
+}
+
+export function createFileSource(pathFromUri) {
+    return {
+        uri: `file://${pathFromUri}`,
+        async authenticate() { /* no auth */ },
+        async list() {
+            const doc = await readDoc(pathFromUri);
+            return doc.secrets.map(s => ({ name: refName(s), kind: s.kind }));
+        },
+        async fetch(refs) {
+            // file:// already loaded everything; filter to the selected refs
+            // so the caller can trust doc.secrets matches what they asked for.
+            const doc = await readDoc(pathFromUri);
+            if (!refs) return doc;
+            const wanted = new Set(refs.map(r => r.name));
+            return { ...doc, secrets: doc.secrets.filter(s => wanted.has(refName(s))) };
+        },
+        async close() { /* nothing to clear */ },
+    };
+}
+
+async function readDoc(path) {
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    } catch (err) {
+        throw new Error(`file source: cannot read "${path}" — ${err.message}`);
+    }
+    let doc;
+    try {
+        doc = JSON.parse(raw);
+    } catch (err) {
+        throw new Error(`file source: invalid JSON in "${path}" — ${err.message}`);
+    }
+    if (!doc || !Array.isArray(doc.secrets)) {
+        throw new Error('file source: JSON must have a "secrets" array.');
+    }
+    return doc;
+}

package/src/sources/index.js

@@ -0,0 +1,40 @@
+// Source URI dispatcher. New backends register here.
+
+import { createFileSource } from './file.js';
+import { createStdinSource } from './stdin.js';
+import { createAzureKVSource } from './azure.js';
+
+export function resolveSource(uri) {
+    if (uri === '-' || uri === 'stdin' || uri === 'stdin://') {
+        return createStdinSource();
+    }
+    if (uri.startsWith('file://')) {
+        return createFileSource(uri.slice('file://'.length));
+    }
+    if (uri.startsWith('azure-kv://')) {
+        const rest = uri.slice('azure-kv://'.length);
+        // Allow ?host=... in the future; for MVP everything after / is ignored.
+        const [vaultName] = rest.split(/[/?#]/, 1);
+        if (!vaultName) {
+            throw new Error('azure-kv: URI must include a vault name, e.g. azure-kv://my-vault');
+        }
+        return createAzureKVSource(vaultName);
+    }
+    // Other cloud adapters: not yet implemented.
+    if (uri.startsWith('aws-sm://')   || uri.startsWith('gcp-sm://')  ||
+        uri.startsWith('vault://')    || uri.startsWith('1password://')) {
+        throw new Error(`Source "${uri.split('://')[0]}" is on the roadmap but not yet implemented. ` +
+            `Use file://path/to/secrets.json, pipe JSON to stdin, or use azure-kv:// for now.`);
+    }
+    throw new Error(`Unknown source URI: ${uri}. Supported: file://, stdin (-), azure-kv://.`);
+}
+
+export const SUPPORTED_SOURCES = [
+    { scheme: 'file://',       status: 'ready',   description: 'JSON file on local disk' },
+    { scheme: 'stdin (-)',     status: 'ready',   description: 'JSON piped via stdin' },
+    { scheme: 'azure-kv://',   status: 'ready',   description: 'Azure Key Vault (uses `az login` cache)' },
+    { scheme: 'aws-sm://',     status: 'roadmap', description: 'AWS Secrets Manager' },
+    { scheme: 'gcp-sm://',     status: 'roadmap', description: 'GCP Secret Manager' },
+    { scheme: 'vault://',      status: 'roadmap', description: 'HashiCorp Vault' },
+    { scheme: '1password://',  status: 'roadmap', description: '1Password' },
+];

package/src/sources/stdin.js

@@ -0,0 +1,46 @@
+// stdin adapter — same JSON schema as file://, read from process.stdin.
+// Used when source URI is "-".
+
+function refName(s) {
+    return s.name ?? s.label ?? s.service ?? s.title ?? '<unnamed>';
+}
+
+export function createStdinSource() {
+    let cached = null;
+    return {
+        uri: 'stdin',
+        async authenticate() {},
+        async list() {
+            const doc = await readOnce();
+            return doc.secrets.map(s => ({ name: refName(s), kind: s.kind }));
+        },
+        async fetch(refs) {
+            const doc = await readOnce();
+            if (!refs) return doc;
+            const wanted = new Set(refs.map(r => r.name));
+            return { ...doc, secrets: doc.secrets.filter(s => wanted.has(refName(s))) };
+        },
+        async close() { cached = null; },
+    };
+
+    async function readOnce() {
+        if (cached) return cached;
+        const chunks = [];
+        for await (const chunk of process.stdin) chunks.push(chunk);
+        const raw = Buffer.concat(chunks).toString('utf8');
+        if (!raw.trim()) {
+            throw new Error('stdin source: no input received.');
+        }
+        let doc;
+        try {
+            doc = JSON.parse(raw);
+        } catch (err) {
+            throw new Error(`stdin source: invalid JSON — ${err.message}`);
+        }
+        if (!doc || !Array.isArray(doc.secrets)) {
+            throw new Error('stdin source: JSON must have a "secrets" array.');
+        }
+        cached = doc;
+        return doc;
+    }
+}