@profullstack/coinpay 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to `@profullstack/coinpay` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.22.0] - 2026-10-19
+
+### Added
+- `coinpay document publish <dir> --business-id <id>`: encrypt and publish a whole directory, keeping
+  its structure (under a folder named like the directory, or `--folder dest`, `--folder /` for the top
+  level). Publishing again syncs: new files upload, changed files become a new version, unchanged files
+  are skipped, signed documents are left alone, nothing remote is deleted. `--dry-run` shows the plan;
+  hidden files and `node_modules` are skipped unless `--include-hidden`.
+- `coinpay document move <id> <folder>`; `upload --folder a/b`; `list` shows folders.
+- Any file type can be uploaded (unknown types are opaque downloads; the server only holds ciphertext).
+- SDK: `publishDirectory`, `planPublish`, `moveDocument`; `uploadDocument({ folder })`.
+
+## [0.21.0] - 2026-10-19
+
+### Added
+- Documents, end-to-end encrypted: `coinpay document vault-setup|list|upload|share|get|link|revoke|download|void|delete`.
+  Files are encrypted on your machine (AES-256-GCM, one key per document, wrapped under the
+  business vault key, which is wrapped under a PBKDF2 passphrase); CoinPay stores only ciphertext.
+  `share` adds signers and viewers and prints each full link with its `#k=` key; the invite
+  emails omit the key unless `--email-key`. `download` decrypts and verifies the sha256.
+  Invites can be signers, editors (upload new versions) or viewers (`--signers/--editors/--viewers`).
+  Every version is kept: `versions <id>`, `new-version <id> <file>`, `download --revision N`.
+- SDK: `listDocuments`, `getDocument`, `setupDocumentsVault`, `unlockDocumentsVault`,
+  `uploadDocument`, `shareDocument`, `newDocumentLink`, `revokeDocumentRecipient`,
+  `voidDocument`, `deleteDocument`, `downloadDocument`, `listDocumentVersions`, `uploadDocumentVersion`.
+- MCP: `document_list`, `document_get`, `document_void` (metadata only; no keys).
+
 ## [0.19.0] - 2026-10-17
 
 ### Added

package/bin/coinpay.js

@@ -66,6 +66,23 @@ import {
   recordPayRunPayments,
   get1099Summary,
 } from '../src/contractors.js';
+import {
+  listDocuments,
+  getDocument,
+  setupDocumentsVault,
+  unlockDocumentsVault,
+  uploadDocument,
+  shareDocument,
+  newDocumentLink,
+  revokeDocumentRecipient,
+  voidDocument,
+  deleteDocument,
+  downloadDocument,
+  listDocumentVersions,
+  uploadDocumentVersion,
+  moveDocument,
+} from '../src/documents.js';
+import { publishDirectory } from '../src/documents-publish.js';
 import { readFileSync, writeFileSync, existsSync, unlinkSync, chmodSync } from 'fs';
 import { execSync, spawn } from 'child_process';
 import { createInterface } from 'readline';
@@ -534,6 +551,26 @@ ${colors.cyan}Commands:${colors.reset}
     1099                  Totals and who needs a 1099-NEC (--year 2026)
     offboard <id>         End contracts and revoke the portal link
 
+  ${colors.bright}document${colors.reset}  (end-to-end encrypted: CoinPay never sees the contents)
+    vault-setup           Create the documents passphrase (--business-id, admins)
+    list                  Documents (--business-id) with signing progress
+    upload <file>         Encrypt and upload: --business-id [--folder a/b] [--title] [--message]
+    publish <dir>         Sync a whole directory, keeping its structure: --business-id
+                          [--folder dest | --folder / for top level] [--dry-run] [--include-hidden]
+                          new files upload, changed ones become versions, signed ones are left alone
+    move <id> <folder>    File a document elsewhere (/ = top level)
+    share <id>            --signers "Ada <ada@x.com>, bob@y.com" [--editors "..."] [--viewers "..."]
+                          [--message] [--no-email] [--email-key puts the key in the email]
+                          Prints each full link (with #k= key): send it privately
+    get <id>              Status, people and audit trail
+    link <id> <recipient> New link for one person (old one stops working)
+    revoke <id> <recipient>  Remove someone who has not signed
+    versions <id>         The history: every uploaded version
+    new-version <id> <file>  Encrypt and upload the next version [--note]
+    download <id>         Decrypt to a file [--signed | --revision N] [--out path]
+    void <id>             [--reason]    delete <id>
+                          Passphrase: COINPAY_DOCUMENTS_PASSPHRASE or a hidden prompt
+
   ${colors.bright}payrun${colors.reset}
     list                  Pay runs
     create                Draft from fixed fees due + approved work [--date YYYY-MM-DD]
@@ -1277,6 +1314,192 @@ function usageExit(usage) {
   process.exit(1);
 }
 
+/** "Ada <ada@x.com>, bob@y.com" -> [{ name, email }] */
+function parsePeople(text, role) {
+  return String(text || '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map((s) => {
+      const m = /^(.*?)\s*<([^>]+)>$/.exec(s);
+      const email = (m ? m[2] : s).trim();
+      return { name: (m && m[1].trim()) || email, email, role };
+    });
+}
+
+async function documentsVault(client, businessId) {
+  const passphrase = process.env.COINPAY_DOCUMENTS_PASSPHRASE || (await promptPassword('Documents passphrase: '));
+  return unlockDocumentsVault(client, { businessId, passphrase });
+}
+
+async function handleDocument(subcommand, args, flags) {
+  const client = createClient();
+  requireFlagValues(flags, ['business-id', 'title', 'message', 'signers', 'viewers', 'editors', 'reason', 'out', 'note', 'revision', 'folder']);
+  switch (subcommand) {
+    case 'vault-setup': {
+      if (!flags['business-id']) usageExit('coinpay document vault-setup --business-id <id>');
+      print.warn('If this passphrase is lost, nobody (including CoinPay) can recover the documents.');
+      const passphrase = process.env.COINPAY_DOCUMENTS_PASSPHRASE || (await promptPassword('New documents passphrase: '));
+      if (!process.env.COINPAY_DOCUMENTS_PASSPHRASE && (await promptPassword('Repeat it: ')) !== passphrase) usageExit('The passphrases do not match');
+      const vault = await setupDocumentsVault(client, { businessId: flags['business-id'], passphrase });
+      return flags.json ? print.json({ version: vault.version }) : print.success('Documents vault created (version ' + vault.version + ')');
+    }
+    case 'list': {
+      const rows = await listDocuments(client, { businessId: flags['business-id'] });
+      if (flags.json) return print.json(rows);
+      if (!rows.length) return print.info('No documents');
+      for (const d of rows) {
+        const progress = d.signers ? '  ' + d.signed + '/' + d.signers + ' signed' : '';
+        print.info(d.id + '  ' + (d.folder ? d.folder + '/' : '') + d.title + '  ' + d.status + progress);
+      }
+      return;
+    }
+    case 'publish': {
+      if (args.length !== 1 || !flags['business-id']) usageExit('coinpay document publish <dir> --business-id <id> [--folder path | --folder /] [--dry-run] [--include-hidden]');
+      if (!existsSync(args[0])) usageExit('No such directory: ' + args[0]);
+      const businessId = flags['business-id'];
+      const dryRun = !!flags['dry-run'];
+      const vault = dryRun ? undefined : await documentsVault(client, businessId);
+      const labels = { upload: 'new', version: 'new version', unchanged: 'unchanged', locked: 'signed, left alone', too_large: 'too large (9 MB max)', empty: 'empty, skipped' };
+      const result = await publishDirectory(client, {
+        businessId,
+        vault,
+        dir: args[0],
+        folder: flags.folder,
+        includeHidden: !!flags['include-hidden'],
+        dryRun,
+        onFile: (p) => {
+          if (flags.json) return;
+          const where = (p.folder ? p.folder + '/' : '') + p.filename;
+          if (p.result === 'ok') print.success((p.action === 'upload' ? 'uploaded ' : 'v' + p.version + ' ') + where);
+          else print.error('failed ' + where + ': ' + p.error);
+        },
+      });
+      if (flags.json) return print.json(result);
+      const count = (a) => result.plan.filter((p) => p.action === a).length;
+      if (dryRun) {
+        for (const p of result.plan) print.info(labels[p.action].padEnd(20) + ' ' + (p.folder ? p.folder + '/' : '') + p.filename);
+        print.info('Dry run: nothing was uploaded.');
+      }
+      const failed = result.plan.filter((p) => p.result === 'failed').length;
+      print.info(
+        'Into ' + (result.folder ? result.folder + '/' : 'the top level') + ': ' +
+          count('upload') + ' new, ' + count('version') + ' new versions, ' + count('unchanged') + ' unchanged' +
+          (count('locked') ? ', ' + count('locked') + ' signed (left alone)' : '') +
+          (count('too_large') ? ', ' + count('too_large') + ' too large' : '') +
+          (result.skippedHidden ? ', ' + result.skippedHidden + ' hidden skipped' : '') +
+          (failed ? ', ' + failed + ' FAILED' : '')
+      );
+      if (failed) process.exitCode = 1;
+      return;
+    }
+    case 'move': {
+      if (args.length !== 2) usageExit('coinpay document move <id> <folder>   (use / for the top level)');
+      const result = await moveDocument(client, args[0], args[1]);
+      return flags.json ? print.json(result) : print.success('Moved to ' + (result.folder || 'the top level'));
+    }
+    case 'upload': {
+      if (args.length !== 1 || !flags['business-id']) usageExit('coinpay document upload <file> --business-id <id> [--folder path] [--title "..."] [--message "..."]');
+      const vault = await documentsVault(client, flags['business-id']);
+      const doc = await uploadDocument(client, {
+        businessId: flags['business-id'],
+        vault,
+        bytes: readFileSync(args[0]),
+        filename: args[0],
+        title: flags.title,
+        message: flags.message,
+        folder: flags.folder,
+      });
+      if (flags.json) return print.json(doc);
+      print.success('Uploaded (encrypted): ' + doc.id);
+      return print.info('Send it with: coinpay document share ' + doc.id + ' --signers "Name <email>"');
+    }
+    case 'share': {
+      const recipients = [...parsePeople(flags.signers, 'signer'), ...parsePeople(flags.editors, 'editor'), ...parsePeople(flags.viewers, 'viewer')];
+      if (args.length !== 1 || !recipients.length) usageExit('coinpay document share <id> --signers "Ada <ada@x.com>" [--editors "..."] [--viewers "..."] [--message] [--no-email] [--email-key]');
+      const { document } = await getDocument(client, args[0]);
+      const vault = await documentsVault(client, document.business_id);
+      const result = await shareDocument(client, args[0], {
+        recipients,
+        message: flags.message,
+        sendEmail: !flags['no-email'],
+        emailKey: !!flags['email-key'],
+        vault,
+      });
+      if (flags.json) return print.json(result);
+      print.success('Shared; document is now ' + result.status);
+      if (!flags['email-key']) print.warn('The emails do NOT contain the key. Send each person their full link below on another channel:');
+      for (const r of result.recipients) print.info(r.role.padEnd(6) + ' ' + r.email + '  ' + r.link);
+      return;
+    }
+    case 'get': {
+      if (args.length !== 1) usageExit('coinpay document get <id>');
+      const data = await getDocument(client, args[0]);
+      if (flags.json) return print.json(data);
+      const d = data.document;
+      print.info(d.title + '  ' + d.status + '  ' + d.filename + ' (' + d.bytes + ' bytes)');
+      print.info('sha256 ' + d.sha256 + (d.signed_sha256 ? '\nsigned sha256 ' + d.signed_sha256 : ''));
+      for (const r of data.recipients) {
+        if (r.revoked_at) continue;
+        print.info('  ' + r.id + '  ' + r.role + '  ' + r.name + ' <' + r.email + '>  ' + r.status + (r.signed_at ? ' ' + r.signed_at : ''));
+      }
+      for (const e of data.events) print.info('  ' + e.created_at + '  ' + e.event + (e.actor_label ? '  ' + e.actor_label : '') + (e.ip ? '  ' + e.ip : ''));
+      return;
+    }
+    case 'link': {
+      if (args.length !== 2) usageExit('coinpay document link <id> <recipient-id> [--no-email] [--email-key]');
+      const { document } = await getDocument(client, args[0]);
+      const vault = await documentsVault(client, document.business_id);
+      const result = await newDocumentLink(client, args[0], args[1], { sendEmail: !flags['no-email'], emailKey: !!flags['email-key'], vault });
+      return flags.json ? print.json(result) : print.info(result.link);
+    }
+    case 'revoke': {
+      if (args.length !== 2) usageExit('coinpay document revoke <id> <recipient-id>');
+      const result = await revokeDocumentRecipient(client, args[0], args[1]);
+      return flags.json ? print.json(result) : print.success('Revoked; document is now ' + result.status);
+    }
+    case 'versions': {
+      if (args.length !== 1) usageExit('coinpay document versions <id>');
+      const rows = await listDocumentVersions(client, args[0]);
+      if (flags.json) return print.json(rows);
+      for (const v of rows) print.info('v' + v.version + '  ' + v.created_at + '  ' + v.filename + '  ' + v.bytes + ' bytes' + (v.uploaded_by ? '  ' + v.uploaded_by : '') + (v.note ? '  ' + v.note : ''));
+      return;
+    }
+    case 'new-version': {
+      if (args.length !== 2) usageExit('coinpay document new-version <id> <file> [--note "what changed"]');
+      const { document } = await getDocument(client, args[0]);
+      const vault = await documentsVault(client, document.business_id);
+      const result = await uploadDocumentVersion(client, args[0], { vault, bytes: readFileSync(args[1]), filename: args[1], note: flags.note });
+      return flags.json ? print.json(result) : print.success('Uploaded version ' + result.version + ' (encrypted)');
+    }
+    case 'download': {
+      if (args.length !== 1) usageExit('coinpay document download <id> [--signed | --revision N] [--out path]');
+      const { document } = await getDocument(client, args[0]);
+      const vault = await documentsVault(client, document.business_id);
+      const file = await downloadDocument(client, args[0], {
+        version: flags.signed ? 'signed' : 'original',
+        revision: flags.revision ? Number(flags.revision) : undefined,
+        vault,
+      });
+      const out = flags.out || file.filename;
+      writeFileSync(out, file.bytes, { mode: 0o600 });
+      return print.success('Decrypted ' + file.bytes.length + ' bytes to ' + out + ' (sha256 verified)');
+    }
+    case 'void': {
+      if (args.length !== 1) usageExit('coinpay document void <id> [--reason "..."]');
+      await voidDocument(client, args[0], { reason: flags.reason });
+      return print.success('Voided');
+    }
+    case 'delete': {
+      if (args.length !== 1) usageExit('coinpay document delete <id>');
+      await deleteDocument(client, args[0]);
+      return print.success('Deleted');
+    }
+    default:
+      usageExit('coinpay document <vault-setup|list|upload|publish|move|share|get|versions|new-version|link|revoke|download|void|delete>');
+  }
+}
+
 async function handleContractor(subcommand, args, flags) {
   const client = createClient();
   requireFlagValues(flags, ['business-id', 'name', 'email', 'country', 'title', 'kind', 'rate', 'frequency', 'start', 'end', 'note', 'signature', 'reason', 'amount', 'contract', 'description', 'status', 'year']);
@@ -5257,6 +5480,11 @@ async function handleLightning(subcommand, args, flags) {
         await handleProject(subcommand, args, flags);
         break;
 
+      case 'document':
+      case 'documents':
+        await handleDocument(subcommand, args, flags);
+        break;
+
       case 'contractor':
       case 'contractors':
         await handleContractor(subcommand, args, flags);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/coinpay",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "CoinPay SDK & CLI \u2014 Accept cryptocurrency and card payments (BTC, ETH, SOL, POL, BCH, USDC) with wallet, swap and a live finances dashboard",
   "type": "module",
   "main": "./src/index.js",

package/src/documents-publish.d.ts

@@ -0,0 +1,29 @@
+import type { CoinPayClient } from './client.js';
+import type { CoinPayDocument, UnlockedVault } from './documents.js';
+
+export interface PublishEntry {
+  abs: string;
+  rel: string;
+  size: number;
+  filename: string;
+  folder: string | null;
+  sha256?: string;
+  action: 'upload' | 'version' | 'unchanged' | 'locked' | 'too_large' | 'empty';
+  documentId?: string;
+  version?: number;
+  result?: 'ok' | 'failed';
+  error?: string;
+}
+
+export interface PublishResult {
+  plan: PublishEntry[];
+  skippedHidden: number;
+  folder: string | null;
+}
+
+export function walkDirectory(dir: string, opts?: { includeHidden?: boolean }): Promise<{ files: { abs: string; rel: string; size: number }[]; skipped: number }>;
+export function planPublish(local: Omit<PublishEntry, 'action'>[], remote: Pick<CoinPayDocument, 'id' | 'folder' | 'filename' | 'sha256' | 'status' | 'signed'>[]): PublishEntry[];
+export function publishDirectory(
+  client: CoinPayClient,
+  opts: { businessId: string; vault?: UnlockedVault; dir: string; folder?: string; includeHidden?: boolean; dryRun?: boolean; concurrency?: number; onFile?: (entry: PublishEntry) => void }
+): Promise<PublishResult>;

package/src/documents-publish.js

@@ -0,0 +1,110 @@
+/**
+ * Publish a local directory to a business's documents: every file is
+ * encrypted on this machine (see documents.js) and filed under the same
+ * folder structure. Publishing again syncs: new files are uploaded, changed
+ * files become a new version, unchanged ones are skipped, and documents that
+ * are already signed are never touched. Nothing remote is ever deleted.
+ */
+
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { basename, join, relative, resolve, sep } from 'node:path';
+import {
+  isSkippedPath,
+  listDocuments,
+  MAX_DOCUMENT_BYTES,
+  normalizeFolder,
+  sha256Hex,
+  uploadDocument,
+  uploadDocumentVersion,
+} from './documents.js';
+
+/** Every file under `dir`, with its path relative to `dir` ('/'-separated). Symlinks are not followed. */
+export async function walkDirectory(dir, { includeHidden = false } = {}) {
+  const root = resolve(dir);
+  const out = [];
+  let skipped = 0;
+  const visit = async (abs) => {
+    for (const entry of await readdir(abs, { withFileTypes: true })) {
+      const child = join(abs, entry.name);
+      const rel = relative(root, child).split(sep).join('/');
+      if (!includeHidden && isSkippedPath(rel)) {
+        skipped++;
+        continue;
+      }
+      if (entry.isDirectory()) await visit(child);
+      else if (entry.isFile()) out.push({ abs: child, rel, size: (await stat(child)).size });
+    }
+  };
+  await visit(root);
+  out.sort((a, b) => a.rel.localeCompare(b.rel));
+  return { files: out, skipped };
+}
+
+const key = (folder, filename) => `${folder ?? ''}\u0000${filename}`;
+
+/**
+ * Decide what to do with each local file. `remote` is listDocuments() output
+ * (newest first, so the first match for a path wins). Pure: no I/O.
+ *
+ * Actions: upload | version | unchanged | locked (signed, completed, declined
+ * or voided remotely) | too_large | empty.
+ */
+export function planPublish(local, remote) {
+  const byPath = new Map();
+  for (const d of remote) if (!byPath.has(key(d.folder, d.filename))) byPath.set(key(d.folder, d.filename), d);
+  return local.map((f) => {
+    if (f.size === 0) return { ...f, action: 'empty' };
+    if (f.size > MAX_DOCUMENT_BYTES) return { ...f, action: 'too_large' };
+    const existing = byPath.get(key(f.folder, f.filename));
+    if (!existing) return { ...f, action: 'upload' };
+    if (existing.sha256 === f.sha256) return { ...f, action: 'unchanged', documentId: existing.id };
+    const locked = ['completed', 'declined', 'voided'].includes(existing.status) || (existing.signed ?? 0) > 0;
+    return { ...f, action: locked ? 'locked' : 'version', documentId: existing.id, status: existing.status };
+  });
+}
+
+/**
+ * Publish `dir`. `folder` is where its contents go: by default a folder named
+ * like the directory (as a desktop copy would); pass '' or '/' for the top level.
+ */
+export async function publishDirectory(client, { businessId, vault, dir, folder, includeHidden = false, dryRun = false, concurrency = 3, onFile } = {}) {
+  if (!businessId) throw new Error('businessId is required');
+  const prefix = normalizeFolder(folder === undefined ? basename(resolve(dir)) : folder);
+  const { files, skipped } = await walkDirectory(dir, { includeHidden });
+
+  const local = [];
+  for (const f of files) {
+    const parts = f.rel.split('/');
+    const filename = parts.pop();
+    const entry = { ...f, filename, folder: normalizeFolder([prefix ?? '', ...parts].join('/')) };
+    if (f.size > 0 && f.size <= MAX_DOCUMENT_BYTES) entry.sha256 = await sha256Hex(await readFile(f.abs));
+    local.push(entry);
+  }
+  const plan = planPublish(local, await listDocuments(client, { businessId }));
+  if (dryRun) return { plan, skippedHidden: skipped, folder: prefix };
+
+  let next = 0;
+  const work = plan.filter((p) => p.action === 'upload' || p.action === 'version');
+  const worker = async () => {
+    while (next < work.length) {
+      const p = work[next++];
+      try {
+        const bytes = await readFile(p.abs);
+        if (p.action === 'upload') {
+          const doc = await uploadDocument(client, { businessId, vault, bytes, filename: p.filename, folder: p.folder });
+          p.documentId = doc.id;
+        } else {
+          const result = await uploadDocumentVersion(client, p.documentId, { vault, bytes, filename: p.filename, note: 'published from ' + p.rel });
+          p.version = result.version;
+        }
+        p.result = 'ok';
+      } catch (err) {
+        p.result = 'failed';
+        p.error = err.message;
+      }
+      onFile?.(p);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(concurrency, work.length) }, worker));
+  return { plan, skippedHidden: skipped, folder: prefix };
+}

package/src/documents.d.ts

@@ -0,0 +1,90 @@
+import type { CoinPayClient } from './client.js';
+
+export interface CoinPayDocument {
+  id: string;
+  business_id: string;
+  title: string;
+  message: string | null;
+  folder: string | null;
+  filename: string;
+  content_type: string;
+  bytes: number;
+  sha256: string;
+  wrapped_key: string;
+  vault_version: number;
+  current_version: number;
+  status: 'draft' | 'shared' | 'out_for_signature' | 'completed' | 'declined' | 'voided';
+  signed_sha256: string | null;
+  signed_bytes: number | null;
+  completed_at: string | null;
+  voided_at: string | null;
+  created_at: string;
+  signers?: number;
+  signed?: number;
+  viewers?: number;
+}
+
+export interface DocumentRecipient {
+  id: string;
+  name: string;
+  email: string;
+  role: 'signer' | 'viewer' | 'editor';
+  status: 'pending' | 'viewed' | 'signed' | 'declined';
+  signed_at: string | null;
+  signature_name: string | null;
+  revoked_at: string | null;
+  /** The link without the key (server copy). */
+  url?: string;
+  /** The link with `#k=<key>`, when the vault was unlocked. Hand it over yourself. */
+  link?: string | null;
+}
+
+export interface DocumentVersion {
+  version: number;
+  filename: string;
+  content_type: string;
+  bytes: number;
+  sha256: string;
+  note: string | null;
+  uploaded_by: string | null;
+  created_at: string;
+}
+
+export interface DocumentVault {
+  version: number;
+  kdf_salt: string;
+  kdf_iterations: number;
+  wrapped_key: string;
+  created_at: string;
+}
+
+export interface UnlockedVault {
+  vaultKey: Uint8Array;
+  version: number;
+}
+
+export function listDocuments(client: CoinPayClient, opts?: { businessId?: string; status?: string; folder?: string }): Promise<CoinPayDocument[]>;
+export function moveDocument(client: CoinPayClient, documentId: string, folder: string | null): Promise<{ folder: string | null }>;
+export function normalizeFolder(input: string | null | undefined): string | null;
+export function contentTypeFor(filename: string): string;
+export function getDocument(client: CoinPayClient, documentId: string): Promise<{ document: CoinPayDocument & { signed_available: boolean }; recipients: DocumentRecipient[]; events: unknown[]; versions: DocumentVersion[]; certificate: unknown }>;
+export function listDocumentVaults(client: CoinPayClient, opts?: { businessId?: string }): Promise<DocumentVault[]>;
+export function setupDocumentsVault(client: CoinPayClient, opts: { businessId: string; passphrase: string }): Promise<UnlockedVault>;
+export function unlockDocumentsVault(client: CoinPayClient, opts: { businessId: string; passphrase: string }): Promise<UnlockedVault>;
+export function uploadDocument(client: CoinPayClient, opts: { businessId: string; vault: UnlockedVault; bytes: Uint8Array; filename: string; title?: string; message?: string; folder?: string | null }): Promise<CoinPayDocument>;
+export function shareDocument(
+  client: CoinPayClient,
+  documentId: string,
+  opts: { recipients: { name: string; email: string; role?: 'signer' | 'viewer' | 'editor'; expires_in_days?: number }[]; message?: string | null; sendEmail?: boolean; emailKey?: boolean; vault?: UnlockedVault }
+): Promise<{ status: string; recipients: DocumentRecipient[] }>;
+export function newDocumentLink(client: CoinPayClient, documentId: string, recipientId: string, opts?: { sendEmail?: boolean; emailKey?: boolean; vault?: UnlockedVault }): Promise<{ url: string; link: string | null }>;
+export function revokeDocumentRecipient(client: CoinPayClient, documentId: string, recipientId: string): Promise<{ status: string }>;
+export function voidDocument(client: CoinPayClient, documentId: string, opts?: { reason?: string }): Promise<unknown>;
+export function deleteDocument(client: CoinPayClient, documentId: string): Promise<unknown>;
+export function listDocumentVersions(client: CoinPayClient, documentId: string): Promise<DocumentVersion[]>;
+export function uploadDocumentVersion(client: CoinPayClient, documentId: string, opts: { vault: UnlockedVault; bytes: Uint8Array; filename: string; note?: string }): Promise<{ version: number }>;
+export function downloadDocument(
+  client: CoinPayClient,
+  documentId: string,
+  opts: { version?: 'original' | 'signed'; revision?: number; vault: UnlockedVault }
+): Promise<{ bytes: Uint8Array; filename: string; document: CoinPayDocument; revision?: number }>;

package/src/documents.js

@@ -0,0 +1,318 @@
+/**
+ * Documents: upload, share by private link and collect e-signatures, end-to-end
+ * encrypted. CoinPay stores only ciphertext; every key is handled here, on
+ * your machine, exactly as the web app does it in the browser
+ * (src/lib/documents/e2e.ts in coinpayportal):
+ *
+ * - each document has its own random AES-256-GCM key (DK);
+ * - the business keeps DK wrapped under its vault key (VK);
+ * - VK is wrapped under a key derived from the documents passphrase (PBKDF2-SHA256);
+ * - a recipient link carries DK after `#k=`, which is never sent to the server.
+ *
+ * Sealed blob format: 0x01 || 12-byte IV || AES-GCM ciphertext+tag.
+ */
+
+const VERSION = 0x01;
+const IV_BYTES = 12;
+export const PBKDF2_ITERATIONS = 600_000;
+
+const subtle = () => globalThis.crypto.subtle;
+const enc = (s) => new TextEncoder().encode(s);
+const q = (params) => {
+  const entries = Object.entries(params).filter(([, v]) => v !== undefined && v !== null && v !== '');
+  return entries.length ? '?' + new URLSearchParams(entries.map(([k, v]) => [k, String(v)])).toString() : '';
+};
+const json = (method, body) => ({ method, body: JSON.stringify(body) });
+const id = (v) => encodeURIComponent(v);
+
+export const DOCUMENT_TYPES = {
+  pdf: 'application/pdf',
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  txt: 'text/plain',
+  md: 'text/plain',
+  csv: 'text/csv',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+};
+
+export const GENERIC_CONTENT_TYPE = 'application/octet-stream';
+export const MAX_DOCUMENT_BYTES = 9 * 1024 * 1024;
+
+/** Known types preview in the browser; anything else is an opaque download (it is ciphertext to the server). */
+export function contentTypeFor(filename) {
+  const name = String(filename);
+  const ext = name.includes('.') ? name.toLowerCase().split('.').pop() : '';
+  return DOCUMENT_TYPES[ext] ?? GENERIC_CONTENT_TYPE;
+}
+
+/** Same rules as the web app (src/lib/documents/types.ts): '/'-joined, no '.', '..' refused, null = top level. */
+export function normalizeFolder(input) {
+  if (input == null) return null;
+  const segments = String(input)
+    .split(/[\\/]+/)
+    // eslint-disable-next-line no-control-regex
+    .map((s) => s.replace(/[\u0000-\u001f\u007f]/g, '').trim())
+    .filter((s) => s && s !== '.');
+  if (segments.some((s) => s === '..')) throw new Error('Folder paths cannot contain ".."');
+  if (segments.length > 20) throw new Error('Folders can be at most 20 levels deep');
+  const joined = segments.map((s) => s.slice(0, 100)).join('/');
+  if (joined.length > 1000) throw new Error('Folder path is too long');
+  return joined || null;
+}
+
+export function isSkippedPath(relativePath) {
+  return String(relativePath)
+    .split(/[\\/]+/)
+    .some((s) => (s.startsWith('.') && s !== '.' && s !== '..') || s === 'node_modules' || s === 'Thumbs.db' || s === 'desktop.ini');
+}
+
+export const AAD = {
+  original: (documentId) => `coinpay-doc:original:${documentId}`,
+  version: (documentId, n) => (n === 1 ? `coinpay-doc:original:${documentId}` : `coinpay-doc:original:${documentId}:v${n}`),
+  signed: (documentId) => `coinpay-doc:signed:${documentId}`,
+  documentKey: (businessId) => `coinpay-doc:dk:${businessId}`,
+  vaultKey: (businessId) => `coinpay-doc:vk:${businessId}`,
+};
+
+// ---------------------------------------------------------------------------
+// Crypto (byte-for-byte the same as the web app)
+// ---------------------------------------------------------------------------
+
+export function toB64url(bytes) {
+  return Buffer.from(bytes).toString('base64url');
+}
+
+export function fromB64url(text) {
+  if (!/^[A-Za-z0-9_-]*$/.test(text)) throw new Error('Not base64url');
+  return new Uint8Array(Buffer.from(text, 'base64url'));
+}
+
+export async function sha256Hex(data) {
+  return Buffer.from(await subtle().digest('SHA-256', data)).toString('hex');
+}
+
+async function aesKey(raw) {
+  if (raw.length !== 32) throw new Error('Expected a 256-bit key');
+  return subtle().importKey('raw', raw, 'AES-GCM', false, ['encrypt', 'decrypt']);
+}
+
+export function newKey() {
+  return globalThis.crypto.getRandomValues(new Uint8Array(32));
+}
+
+export async function seal(rawKey, plain, aad) {
+  const iv = globalThis.crypto.getRandomValues(new Uint8Array(IV_BYTES));
+  const ct = new Uint8Array(await subtle().encrypt({ name: 'AES-GCM', iv, additionalData: enc(aad) }, await aesKey(rawKey), plain));
+  const out = new Uint8Array(1 + IV_BYTES + ct.length);
+  out[0] = VERSION;
+  out.set(iv, 1);
+  out.set(ct, 1 + IV_BYTES);
+  return out;
+}
+
+export async function open(rawKey, sealed, aad) {
+  if (sealed.length < 1 + IV_BYTES + 16 || sealed[0] !== VERSION) throw new Error('Not an encrypted document');
+  try {
+    return new Uint8Array(
+      await subtle().decrypt({ name: 'AES-GCM', iv: sealed.subarray(1, 1 + IV_BYTES), additionalData: enc(aad) }, await aesKey(rawKey), sealed.subarray(1 + IV_BYTES))
+    );
+  } catch {
+    throw new Error('Wrong key, or the file was altered');
+  }
+}
+
+export async function passphraseKey(passphrase, salt, iterations = PBKDF2_ITERATIONS) {
+  const base = await subtle().importKey('raw', enc(passphrase.normalize('NFKC')), 'PBKDF2', false, ['deriveBits']);
+  return new Uint8Array(await subtle().deriveBits({ name: 'PBKDF2', hash: 'SHA-256', salt, iterations }, base, 256));
+}
+
+export async function wrapVault(businessId, vaultKey, passphrase) {
+  const salt = globalThis.crypto.getRandomValues(new Uint8Array(16));
+  const kek = await passphraseKey(passphrase, salt);
+  return { kdf_salt: toB64url(salt), kdf_iterations: PBKDF2_ITERATIONS, wrapped_key: toB64url(await seal(kek, vaultKey, AAD.vaultKey(businessId))) };
+}
+
+export async function unlockVaultRecord(businessId, record, passphrase) {
+  const kek = await passphraseKey(passphrase, fromB64url(record.kdf_salt), record.kdf_iterations);
+  try {
+    return await open(kek, fromB64url(record.wrapped_key), AAD.vaultKey(businessId));
+  } catch {
+    throw new Error('Wrong passphrase');
+  }
+}
+
+/** `<url>#k=<document key>`: the link a recipient needs to open the file. */
+export function linkWithKey(url, documentKey) {
+  return `${url}#k=${toB64url(documentKey)}`;
+}
+
+// ---------------------------------------------------------------------------
+// API
+// ---------------------------------------------------------------------------
+
+export async function listDocuments(client, { businessId, status, folder } = {}) {
+  const data = await client.request('/documents' + q({ business_id: businessId, status, folder }));
+  return data.documents ?? [];
+}
+
+/** The document (metadata only), who has it and the audit trail. */
+export async function getDocument(client, documentId) {
+  return client.request('/documents/' + id(documentId));
+}
+
+export async function listDocumentVaults(client, { businessId } = {}) {
+  const data = await client.request('/documents/vault' + q({ business_id: businessId }));
+  return data.vaults ?? [];
+}
+
+/** Create the business's documents vault (admin). Lose the passphrase and the documents are gone. */
+export async function setupDocumentsVault(client, { businessId, passphrase }) {
+  if (!businessId) throw new Error('businessId is required');
+  if (!passphrase || passphrase.length < 10) throw new Error('Use a passphrase of at least 10 characters');
+  const existing = await listDocumentVaults(client, { businessId });
+  if (existing.length) throw new Error('This business already has a documents vault');
+  const vaultKey = newKey();
+  const data = await client.request('/documents/vault', json('POST', { business_id: businessId, ...(await wrapVault(businessId, vaultKey, passphrase)) }));
+  return { vaultKey, version: data.vault.version };
+}
+
+/** The vault key, from the passphrase. Tries every version, newest first. */
+export async function unlockDocumentsVault(client, { businessId, passphrase }) {
+  if (!businessId) throw new Error('businessId is required');
+  const vaults = await listDocumentVaults(client, { businessId });
+  if (!vaults.length) throw new Error('This business has no documents vault yet; run `coinpay document vault-setup`');
+  for (const v of vaults) {
+    try {
+      return { vaultKey: await unlockVaultRecord(businessId, v, passphrase), version: v.version };
+    } catch {
+      // next version
+    }
+  }
+  throw new Error('Wrong passphrase');
+}
+
+async function documentKey(client, doc, vault) {
+  return open(vault.vaultKey, fromB64url(doc.wrapped_key), AAD.documentKey(doc.business_id));
+}
+
+/** Encrypt and upload. `bytes` is the file content; `filename` decides its type. */
+export async function uploadDocument(client, { businessId, vault, bytes, filename, title, message, folder }) {
+  const contentType = contentTypeFor(filename);
+  const plain = new Uint8Array(bytes);
+  const docId = globalThis.crypto.randomUUID();
+  const dk = newKey();
+  const meta = {
+    id: docId,
+    business_id: businessId,
+    title: title || String(filename).replace(/\.[A-Za-z0-9]{1,5}$/, ''),
+    message: message || null,
+    folder: normalizeFolder(folder),
+    filename: String(filename).split(/[\\/]/).pop(),
+    content_type: contentType,
+    bytes: plain.length,
+    sha256: await sha256Hex(plain),
+    wrapped_key: toB64url(await seal(vault.vaultKey, dk, AAD.documentKey(businessId))),
+    vault_version: vault.version,
+  };
+  const form = new FormData();
+  form.set('meta', JSON.stringify(meta));
+  form.set('file', new Blob([await seal(dk, plain, AAD.original(docId))], { type: 'application/octet-stream' }), 'sealed.bin');
+  const data = await client.requestForm('/documents', form);
+  return data.document;
+}
+
+/**
+ * Share with signers and viewers. With `vault`, each returned link carries the
+ * key; hand it to the person yourself. `emailKey: true` also puts the key in
+ * the invite email (convenient, but the mail path can then read the document).
+ */
+export async function shareDocument(client, documentId, { recipients, message, sendEmail, emailKey, vault }) {
+  const doc = (await getDocument(client, documentId)).document;
+  const dk = vault ? await documentKey(client, doc, vault) : null;
+  if (emailKey && !dk) throw new Error('emailKey needs the vault unlocked');
+  const body = { recipients };
+  if (message !== undefined) body.message = message;
+  if (sendEmail === false) body.send_email = false;
+  if (emailKey) body.email_document_key = toB64url(dk);
+  const data = await client.request(`/documents/${id(documentId)}/recipients`, json('POST', body));
+  return { ...data, recipients: data.recipients.map((r) => ({ ...r, link: dk ? linkWithKey(r.url, dk) : null })) };
+}
+
+/** A new link for one recipient; the old one stops working. */
+export async function newDocumentLink(client, documentId, recipientId, { sendEmail, emailKey, vault } = {}) {
+  const doc = (await getDocument(client, documentId)).document;
+  const dk = vault ? await documentKey(client, doc, vault) : null;
+  const body = {};
+  if (sendEmail === false) body.send_email = false;
+  if (emailKey && dk) body.email_document_key = toB64url(dk);
+  const data = await client.request(`/documents/${id(documentId)}/recipients/${id(recipientId)}`, json('POST', body));
+  return { url: data.url, link: dk ? linkWithKey(data.url, dk) : null };
+}
+
+export async function revokeDocumentRecipient(client, documentId, recipientId) {
+  return client.request(`/documents/${id(documentId)}/recipients/${id(recipientId)}`, { method: 'DELETE' });
+}
+
+export async function voidDocument(client, documentId, { reason } = {}) {
+  return client.request('/documents/' + id(documentId), json('PATCH', { action: 'void', ...(reason ? { reason } : {}) }));
+}
+
+/** File a document under another folder (null = top level). */
+export async function moveDocument(client, documentId, folder) {
+  return client.request('/documents/' + id(documentId), json('PATCH', { action: 'move', folder: normalizeFolder(folder) }));
+}
+
+export async function deleteDocument(client, documentId) {
+  return client.request('/documents/' + id(documentId), { method: 'DELETE' });
+}
+
+/** Every version of the document, newest first (metadata; the files stay sealed). */
+export async function listDocumentVersions(client, documentId) {
+  const data = await client.request(`/documents/${id(documentId)}/versions`);
+  return data.versions ?? [];
+}
+
+/**
+ * Encrypt and upload the next version. Refused once anyone has signed;
+ * earlier versions stay in the history.
+ */
+export async function uploadDocumentVersion(client, documentId, { vault, bytes, filename, note }) {
+  const doc = (await getDocument(client, documentId)).document;
+  const contentType = contentTypeFor(filename);
+  const dk = await documentKey(client, doc, vault);
+  const plain = new Uint8Array(bytes);
+  const next = doc.current_version + 1;
+  const form = new FormData();
+  form.set(
+    'meta',
+    JSON.stringify({ version: next, filename: String(filename).split(/[\\/]/).pop(), content_type: contentType, bytes: plain.length, sha256: await sha256Hex(plain), note: note || null })
+  );
+  form.set('file', new Blob([await seal(dk, plain, AAD.version(documentId, next))], { type: 'application/octet-stream' }), 'sealed.bin');
+  return client.requestForm(`/documents/${id(documentId)}/versions`, form);
+}
+
+/**
+ * Download and decrypt the current file, an earlier `revision`, or the signed
+ * copy (`version: 'signed'`), checking its sha256.
+ */
+export async function downloadDocument(client, documentId, { version = 'original', revision, vault }) {
+  const data = await getDocument(client, documentId);
+  const doc = data.document;
+  const dk = await documentKey(client, doc, vault);
+  if (version === 'signed') {
+    const { bytes } = await client.requestBinary(`/documents/${id(documentId)}/file?version=signed`);
+    const plain = await open(dk, bytes, AAD.signed(documentId));
+    if (doc.signed_sha256 && (await sha256Hex(plain)) !== doc.signed_sha256) throw new Error('The file does not match its recorded sha256');
+    return { bytes: plain, filename: doc.filename.replace(/\.[A-Za-z0-9]{1,5}$/, '') + '-signed.pdf', document: doc };
+  }
+  const n = revision || doc.current_version;
+  const entry = (data.versions ?? []).find((v) => v.version === n) ?? (n === doc.current_version ? doc : null);
+  if (!entry) throw new Error('No such version');
+  const { bytes } = await client.requestBinary(`/documents/${id(documentId)}/file?n=${n}`);
+  const plain = await open(dk, bytes, AAD.version(documentId, n));
+  if ((await sha256Hex(plain)) !== entry.sha256) throw new Error('The file does not match its recorded sha256');
+  return { bytes: plain, filename: entry.filename, document: doc, revision: n };
+}

package/src/index.d.ts

@@ -114,6 +114,26 @@ export {
   get1099Summary,
 } from './contractors.js';
 export type { Contractor, ContractorContract, ContractorMilestone, ContractorWorkItem, PayRun, PayRunItem, PayOutcome } from './contractors.js';
+export {
+  listDocuments,
+  getDocument,
+  listDocumentVaults,
+  setupDocumentsVault,
+  unlockDocumentsVault,
+  uploadDocument,
+  shareDocument,
+  newDocumentLink,
+  revokeDocumentRecipient,
+  voidDocument,
+  deleteDocument,
+  downloadDocument,
+  listDocumentVersions,
+  uploadDocumentVersion,
+  moveDocument,
+} from './documents.js';
+export { publishDirectory, planPublish } from './documents-publish.js';
+export type { PublishEntry, PublishResult } from './documents-publish.js';
+export type { CoinPayDocument, DocumentRecipient, DocumentVault, DocumentVersion, UnlockedVault } from './documents.js';
 
 // Webhook exports
 export {

package/src/index.js

@@ -128,6 +128,25 @@ import {
   get1099Summary,
 } from './contractors.js';
 
+import {
+  listDocuments,
+  getDocument,
+  listDocumentVaults,
+  setupDocumentsVault,
+  unlockDocumentsVault,
+  uploadDocument,
+  shareDocument,
+  newDocumentLink,
+  revokeDocumentRecipient,
+  voidDocument,
+  deleteDocument,
+  downloadDocument,
+  listDocumentVersions,
+  uploadDocumentVersion,
+  moveDocument,
+} from './documents.js';
+import { publishDirectory, planPublish } from './documents-publish.js';
+
 // Wallet exports
 import {
   WalletClient,
@@ -312,6 +331,23 @@ export {
   payPayRun,
   recordPayRunPayments,
   get1099Summary,
+  listDocuments,
+  getDocument,
+  listDocumentVaults,
+  setupDocumentsVault,
+  unlockDocumentsVault,
+  uploadDocument,
+  shareDocument,
+  newDocumentLink,
+  revokeDocumentRecipient,
+  voidDocument,
+  deleteDocument,
+  downloadDocument,
+  listDocumentVersions,
+  uploadDocumentVersion,
+  moveDocument,
+  publishDirectory,
+  planPublish,
   
   // Wallet
   WalletClient,

package/src/mcp.js

@@ -18,6 +18,7 @@ import * as sf from './statements-fetch.js';
 import { listInvoices, getInvoice, createInvoice } from './invoices.js';
 import * as projects from './projects.js';
 import * as contractors from './contractors.js';
+import * as documents from './documents.js';
 
 export const PROTOCOL_VERSION = '2025-06-18';
 
@@ -386,6 +387,31 @@ export const TOOLS = [
     inputSchema: { type: 'object', properties: { businessId: { type: 'string' }, year: { type: 'integer' } }, additionalProperties: false },
     handler: async (args, { client }) => text(await contractors.get1099Summary(client, args)),
   },
+  // Documents are end-to-end encrypted. These tools see only metadata and the
+  // audit trail; opening, uploading or sharing a file needs the passphrase,
+  // which stays with a person (dashboard or `coinpay document`), never an agent.
+  {
+    name: 'document_list',
+    description: 'List documents with status (draft, shared, out_for_signature, completed, declined, voided) and signing progress. Contents are end-to-end encrypted and not available here.',
+    inputSchema: { type: 'object', properties: { businessId: { type: 'string' }, status: { type: 'string' } }, additionalProperties: false },
+    handler: async (args, { client }) => text({ documents: await documents.listDocuments(client, args) }),
+  },
+  {
+    name: 'document_get',
+    description: 'One document: who it was sent to, who signed (name, time, IP), and the full audit trail. No file contents or keys.',
+    inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'], additionalProperties: false },
+    handler: async (args, { client }) => {
+      const { document, recipients, events } = await documents.getDocument(client, args.id);
+      const { wrapped_key: _k, ...meta } = document;
+      return text({ document: meta, recipients, events });
+    },
+  },
+  {
+    name: 'document_void',
+    description: 'Void a document that has not been completed: links stop working and nobody can sign it. Cannot be undone.',
+    inputSchema: { type: 'object', properties: { id: { type: 'string' }, reason: { type: 'string' } }, required: ['id'], additionalProperties: false },
+    handler: async (args, { client }) => text(await documents.voidDocument(client, args.id, { reason: args.reason })),
+  },
 ];
 
 /** Answer one JSON-RPC message; null for a notification. */