@profullstack/coinpay 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ 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.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,21 @@ import {
   recordPayRunPayments,
   get1099Summary,
 } from '../src/contractors.js';
+import {
+  listDocuments,
+  getDocument,
+  setupDocumentsVault,
+  unlockDocumentsVault,
+  uploadDocument,
+  shareDocument,
+  newDocumentLink,
+  revokeDocumentRecipient,
+  voidDocument,
+  deleteDocument,
+  downloadDocument,
+  listDocumentVersions,
+  uploadDocumentVersion,
+} from '../src/documents.js';
 import { readFileSync, writeFileSync, existsSync, unlinkSync, chmodSync } from 'fs';
 import { execSync, spawn } from 'child_process';
 import { createInterface } from 'readline';
@@ -534,6 +549,22 @@ ${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 [--title] [--message]
+    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 +1308,147 @@ 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']);
+  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.title + '  ' + d.status + progress);
+      }
+      return;
+    }
+    case 'upload': {
+      if (args.length !== 1 || !flags['business-id']) usageExit('coinpay document upload <file> --business-id <id> [--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,
+      });
+      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|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 +5429,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.21.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.d.ts

@@ -0,0 +1,86 @@
+import type { CoinPayClient } from './client.js';
+
+export interface CoinPayDocument {
+  id: string;
+  business_id: string;
+  title: string;
+  message: 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 }): Promise<CoinPayDocument[]>;
+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 }): 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,285 @@
+/**
+ * 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 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 } = {}) {
+  const data = await client.request('/documents' + q({ business_id: businessId, status }));
+  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 }) {
+  const ext = String(filename).toLowerCase().split('.').pop();
+  const contentType = DOCUMENT_TYPES[ext];
+  if (!contentType) throw new Error('Unsupported file type: use ' + Object.keys(DOCUMENT_TYPES).join(', '));
+  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,
+    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 } : {}) }));
+}
+
+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 ext = String(filename).toLowerCase().split('.').pop();
+  const contentType = DOCUMENT_TYPES[ext];
+  if (!contentType) throw new Error('Unsupported file type: use ' + Object.keys(DOCUMENT_TYPES).join(', '));
+  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,23 @@ 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,
+} from './documents.js';
+export type { CoinPayDocument, DocumentRecipient, DocumentVault, DocumentVersion, UnlockedVault } from './documents.js';
 
 // Webhook exports
 export {

package/src/index.js

@@ -128,6 +128,23 @@ import {
   get1099Summary,
 } from './contractors.js';
 
+import {
+  listDocuments,
+  getDocument,
+  listDocumentVaults,
+  setupDocumentsVault,
+  unlockDocumentsVault,
+  uploadDocument,
+  shareDocument,
+  newDocumentLink,
+  revokeDocumentRecipient,
+  voidDocument,
+  deleteDocument,
+  downloadDocument,
+  listDocumentVersions,
+  uploadDocumentVersion,
+} from './documents.js';
+
 // Wallet exports
 import {
   WalletClient,
@@ -312,6 +329,20 @@ export {
   payPayRun,
   recordPayRunPayments,
   get1099Summary,
+  listDocuments,
+  getDocument,
+  listDocumentVaults,
+  setupDocumentsVault,
+  unlockDocumentsVault,
+  uploadDocument,
+  shareDocument,
+  newDocumentLink,
+  revokeDocumentRecipient,
+  voidDocument,
+  deleteDocument,
+  downloadDocument,
+  listDocumentVersions,
+  uploadDocumentVersion,
   
   // 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. */