e-sig documentation

Introduction

e-sig is an MIT-licensed toolkit for adding real cryptographic PDF signing to your own product. There is no SaaS in the loop: your certificates, your database, your object storage, your audit trail. No metering, no per-document fees.

The suite is nine published packages plus a Next.js starter example:

Install

Published to the public npm registry — no auth or registry config needed.

npm i @e-sig/core            # engine only
npm i @e-sig/core @e-sig/supabase @e-sig/react   # full stack

Runtime requirements: Node ≥ 20, ESM. The only crypto dependencies are node-forge and the @signpdf/* packages. HTML→PDF rendering uses puppeteer-core (bring your own Chrome, or @sparticuz/chromium on Lambda).

Quickstart

Issue a cert, render an agreement to PDF, sign it, and verify the result. Rendering needs a local Chrome; for a zero-dependency runnable version that signs an existing PDF (no browser), copy examples/quickstart.

import {
  generateSelfSignedCert,
  renderHtmlToPdf,
  signPdf,
  verifyPdfSignature,
} from "@e-sig/core";

// 1. Issue a one-off signing cert (in production, persist + reuse — see below).
const cert = generateSelfSignedCert({ subjectName: "Acme Corp" });

// 2. Render HTML → unsigned PDF.
const unsigned = await renderHtmlToPdf({
  html: `<h1>Service Agreement</h1><p>Signed by Jane Doe.</p>`,
});

// 3. Sign it (PKCS#7 detached, ETSI.CAdES.detached subfilter).
const { signedPdf } = await signPdf({
  pdf: unsigned,
  keyPem: cert.keyPem,
  certPem: cert.certPem,
  reason: "Service Agreement acceptance",
  location: "https://acme.example",
  contactInfo: "jane@example.com",
  name: "Jane Doe",
});

// 4. Verify cryptographically.
const v = verifyPdfSignature(signedPdf);
console.log(v.ok, v.digestValid, v.signatureValid, v.signerCommonName);
// → true, true, true, "E-sig (Acme Corp)"

Certificates & keys

generateSelfSignedCert() produces an RSA-2048 X.509 cert suitable for PKCS#7 detached PDF signing (128-bit CSPRNG serial, digitalSignature + nonRepudiation key usage, emailProtection EKU, subject key identifier).

const { keyPem, certPem, fingerprint, notBefore, notAfter } =
  generateSelfSignedCert({ subjectName: "Acme Corp" });

subjectName is ASCII-only — node-forge miscounts DER byte length for non-ASCII subject values on round-trip, so the guard rejects them up front.

Encrypting keys at rest

Wrap the private key with AES-256-GCM (scrypt-derived from a passphrase) before persisting it, so a database leak doesn't hand over signing authority:

import { encryptKeyPem, decryptKeyPem } from "@e-sig/core";

const blob = encryptKeyPem(keyPem, passphrase);   // Uint8Array, opaque
// ... store blob ...
const keyPemBack = decryptKeyPem(blob, passphrase);

The passphrase must be ≥ 24 characters (high-entropy env secret). Layout is version | salt | iv | authTag | ciphertext; a wrong passphrase or any tampering surfaces as a GCM auth-tag error.

Cert lifecycle per tenant

ensureActiveCert() caches one active cert per tenant over a CertStore you supply, generating on first use and reusing thereafter (no churn):

import { ensureActiveCert } from "@e-sig/core";

const { cert, certPem, keyPem } = await ensureActiveCert({
  store, tenantId: "acme", subjectName: "Acme Corp", passphrase,
});

Rendering HTML → PDF

renderHtmlToPdf() turns a document template into a PDF with headless Chromium. It auto-detects Lambda (@sparticuz/chromium) vs local/system Chrome.

const pdf = await renderHtmlToPdf({
  html,
  format: "Letter",              // any puppeteer PaperFormat
  printBackground: true,
  javascriptEnabled: false,      // default — see note
  timeoutMs: 30_000,
});

Signing

signPdf() injects a signature placeholder and embeds a PKCS#7 detached signature under the ETSI.CAdES.detached subfilter, with the ESS signing-certificate-v2 attribute (RFC 5035) binding the signer cert into the signed data.

const { signedPdf } = await signPdf({
  pdf, keyPem, certPem,
  name: "Jane Doe",
  reason: "DUA acceptance",
  location: "acme.example",
  contactInfo: "legal@acme.example",
  padesStrict: true,       // strict PAdES B-B
});

The result opens cleanly in Preview / Adobe Reader with a valid signature panel; any post-signing edit invalidates the signature.

Trusted timestamps (CAdES-T)

Pass a tsa transport to embed an RFC-3161 TimeStampToken, upgrading the signature from CAdES-B to CAdES-T. The token is added as the id-aa-timeStampToken unsigned attribute over the SignerInfo signature value.

e-sig performs no network egress — you inject the POST, so the package stays dependency-free. The TSA only ever receives a SHA-256 hash, never the document:

import type { TsaTransport } from "@e-sig/core";

const tsa: TsaTransport = {
  required: false,  // false = degrade to CAdES-B on TSA failure; true = throw
  fetch: async (reqDerBytes) => {
    const res = await fetch("http://timestamp.digicert.com", {
      method: "POST",
      headers: { "Content-Type": "application/timestamp-query" },
      body: reqDerBytes,
    });
    return new Uint8Array(await res.arrayBuffer());
  },
};

const { signedPdf, timestamped, tsaError } = await signPdf({
  pdf, keyPem, certPem, name: "Acme", reason: "acceptance",
  location: "", contactInfo: "", tsa,
});

• Budget: when tsa is supplied and signatureLength is omitted, the /Contents budget defaults to 30720 (vs 8192) to fit the token + TSA chain. Overflow is rejected, never truncated.
• Degradation: required: false yields a valid CAdES-B signature and sets tsaError; required: true rethrows.
• Verification enforces the RFC-3161 §2.4.2 binding: the token's messageImprint must equal sha256(SignerInfo.signature), else ok:false.

Verification

verifyPdfStructure() (aliased verifyPdfSignature()) is fully cryptographic: it recomputes SHA-256 over the ByteRange-covered bytes and compares to the signed messageDigest, and RSA-verifies the signature over the DER-encoded signed attributes.

const v = verifyPdfStructure(signedPdf);
if (!v.ok) throw new Error("signature invalid");
// v.digestValid, v.signatureValid, v.signerCommonName,
// v.timestamped, v.timestampTime, v.tsaCommonName

signDocument() — end-to-end

The optional orchestrator ties the pieces together over your stores: ensure the tenant cert, render, sign (optional TSA), persist the signed PDF, and write an audit-log entry — one call.

import { signDocument } from "@e-sig/core";

const result = await signDocument({
  html,                      // fully-rendered, signature-embedded HTML
  tenantId: "acme",
  subjectName: "Acme Corp",
  passphrase,                // key-at-rest passphrase (≥ 24 chars)
  signer: { name: "Jane Doe", email: "jane@acme.example" },
  certStore, auditStore, storage,
  pathPrefix: "acme/doc-42",
  reason: "Service Agreement acceptance",
  tsa,                       // optional → CAdES-T
});
// result.signedPdfUrl, result.auditLogId, result.certId,
// result.certFingerprint, result.timestamped

You bring the three store implementations; @e-sig/supabase is a ready reference set.

Envelopes — multi-signer + signing links

An envelope tracks N signers over one document. Each signer gets an opaque single-use signing token (32-byte CSPRNG) minted at creation and returned exactly once — only its SHA-256 hash is persisted, so a leaked store cannot forge signing links. Signing order is a 1-based integer: equal order signs in parallel, lower orders gate higher ones. A decline voids the envelope.

import {
  createEnvelope, resolveSigningToken, recordSignature,
  composeEnvelopeHtml, signDocument,
} from "@e-sig/core";

// 1. Create — returns each signer's raw token ONCE. Email them as links.
const { envelope, signingTokens } = await createEnvelope({
  store,                                  // your EnvelopeStore (or FsEnvelopeStore)
  tenantId: "acme",
  title: "Master Service Agreement",
  html: agreementHtml,
  signers: [
    { name: "Ada Lovelace",  email: "ada@acme.example",  roleLabel: "CEO",     order: 1 },
    { name: "Grace Hopper",  email: "grace@acme.example", roleLabel: "Witness", order: 2 },
  ],
  expiresAt: new Date(Date.now() + 14 * 864e5),
});

// 2. Signing surface: resolve the token from the link…
const res = await resolveSigningToken({ store, token });
// res.status: "ok" | "not_your_turn" | "already_signed" | "expired" | "voided" | "completed" | "invalid"

// 3. …record the drawn signature (single-use; order-gated).
const updated = await recordSignature({ store, token, signatureImageDataUrl });

// 4. When updated.status === "completed": compose + apply the cryptographic seal.
const finalHtml = composeEnvelopeHtml(updated, { platformLabel: "Acme sign" });
await signDocument({ html: finalHtml, /* stores, tenant, passphrase, … */ });

Persistence is one small EnvelopeStore interface (insert, update, findById, findByTokenHash). A filesystem implementation ships in @e-sig/core/fs.

Storage adapters

e-sig keeps persistence, auth, and UI out of the core. You implement three small interfaces (or use @e-sig/supabase):

// Postgres + Storage (multi-tenant production)
import {
  SupabaseCertStore,
  SupabaseAuditLogStore,
  SupabasePdfStorageStore,
} from "@e-sig/supabase";

// …or a bare directory (dev, demos, CLIs, single-node) — no services at all:
import {
  FsCertStore,
  FsAuditLogStore,     // append-only NDJSON
  FsPdfStorageStore,
  FsEnvelopeStore,
} from "@e-sig/core/fs";

For Supabase: apply migrations/0001_esig_self_contained.sql (tenant-keyed org_signing_certs + esig_audit_log tables) and replace the esig_tenant_member() stub with your membership check. The fs adapters are single-process (atomic-replace JSON state) — reach for Supabase (or your own implementation) when multiple processes sign concurrently.

React UI

@e-sig/react ships the signature-capture surface so you don't build it from scratch:

import { SelfSignFlow } from "@e-sig/react";

<SelfSignFlow
  documentHtml={html}
  onSigned={(receipt) => { /* persist / redirect */ }}
/>

Signature images are validated as image data URLs before they reach the PDF template.

MCP server (@e-sig/mcp)

An MCP (Model Context Protocol) server for agent-driven e-signature workflows: agents draft, send, and track envelopes over @e-sig/core; a human holds the pen by default. Cryptographic control of signing stays with the human — no tool can produce a signature, and no tool can return a raw signing link, unless an operator explicitly opts in (ESIG_MCP_RETURN_LINKS=1, local demos only).

# zero setup — no passphrase, no data dir, no Chrome
npx @e-sig/mcp demo --auto

# wire it in for real: writes ./esig-data/, a .esig-mcp.env, and a ready .mcp.json snippet
npx @e-sig/mcp init

Three env vars start it: ESIG_MCP_PASSPHRASE (≥ 24 chars — encrypts the tenant's signing cert + PQ key bundle at rest), ESIG_MCP_DELIVERY (no default — see Email delivery and reminders), and ESIG_MCP_DATA_DIR.

Tool surface

Email delivery and reminders

ESIG_MCP_DELIVERY has no default — an operator must pick where signing links go:

ESIG_MCP_DELIVERY=email
ESIG_MCP_EMAIL_TRANSPORT=smtp        # or "ses"
ESIG_MCP_EMAIL_FROM="Acme <noreply@acme.com>"
ESIG_MCP_EMAIL_REPLY_TO=support@acme.com      # optional
ESIG_MCP_EMAIL_SUBJECT_PREFIX="[Acme] "       # optional

# smtp:
ESIG_MCP_SMTP_HOST=smtp.example.com
ESIG_MCP_SMTP_PORT=587               # 465 implies implicit TLS even without SMTP_SECURE=1
ESIG_MCP_SMTP_USER=...
ESIG_MCP_SMTP_PASS=...

# ses (needs the optional peer dependency @aws-sdk/client-sesv2):
ESIG_MCP_SES_REGION=us-east-1

smtp is dependency-free (node:net/node:tls only — EHLO, STARTTLS, AUTH PLAIN/LOGIN). ses calls SESv2 SendEmail through @aws-sdk/client-sesv2, an optional peer dependency this package never installs — without it, ESIG_MCP_EMAIL_TRANSPORT=ses fails at first send with a clear install error, not a silent no-op.

Reminders

ESIG_MCP_REMINDERS=24h,72h   # durations after creation; default off
ESIG_MCP_REMINDER_MAX=3      # hard cap per signer

Requires ESIG_MCP_DELIVERY=email — refused at startup otherwise, since there's no other channel to resend the original link through. An in-process 60-second tick sends a reminder to each still-pending signer whose next scheduled reminder is due; esig_send_reminder(envelopeId, signerId?) sends one on demand, counted against the server's shared hourly rate window (the same one envelope creation and other write tools draw from). The scheduler's automatic sends take no rate limit at all — so a burst of manual tool calls can never starve the reminders a human is actually waiting on, though a manual call can itself be refused while the hourly window is exhausted.

Lifecycle events and webhooks

Every state change on an envelope appends an event to its log (metadata.mcp.events[], capped at 200). esig_envelope_status returns the last 10; esig_list_events(envelopeId, since?) returns them all, oldest first.

12 types total (the two seal/decline pairs above each share a row). data — and every other field — never contains a signing link, token, proof, or document byte.

Webhook delivery

ESIG_MCP_EVENTS_WEBHOOK_URL=https://your-app.example.com/esig-events
ESIG_MCP_EVENTS_WEBHOOK_SECRET="a random secret, at least 32 characters"

Operator config only — no tool can ever set or change it. Every event is persisted to <ESIG_MCP_DATA_DIR>/events/queue/<eventId>.json before any delivery attempt, then delivered in order, per envelope, at-least-once: a non-2xx response, a timeout (10s), or any 3xx redirect (never followed) counts as a failure and retries with exponential backoff — 1m → 2m → 4m → 8m → 16m → 32m, up to 6 attempts — after which the event is parked dead (audited webhook.dead_lettered).

Every request carries Content-Type: application/json, User-Agent: esig-mcp/<version>, X-Esig-Event-Id, X-Esig-Timestamp (ISO-8601), and X-Esig-Signature: sha256=<hex> — an HMAC-SHA256 over timestamp + "." + body, keyed by the webhook secret:

import crypto from "node:crypto";

const expected = "sha256=" + crypto
  .createHmac("sha256", secret)
  .update(`${timestamp}.${rawBody}`)
  .digest("hex");
// constant-time compare against the X-Esig-Signature header, reject
// anything older than 5 minutes, and dedupe by X-Esig-Event-Id — at-least-
// once delivery means a retried event can legitimately arrive twice.

Signer identity (L0–L2)

Bind who signed to a verifiable identity — UUAID identifiers and IAASO TAE assurance levels (ADR-006). Off by default; set it per envelope, per server floor, or both.

{
  "identity": {
    "minLevel": "L1",
    "signers": [{ "index": 0, "uuaid": "uuaid:foundation:agent:<uuid>" }]
  }
}

minLevel may only raise the server's ESIG_MCP_IDENTITY_MIN_LEVEL floor (default none) for that one envelope, never lower it. Obtain a challenge with the esig_identity_challenge tool or GET /sign/<token>/challenge — both idempotently re-issue the same live challenge until it's consumed or expires.

Refusal codes

Pre-verified identity via proof sources. A recipient agent can reply with a sealed identity proof instead of a human ever pasting JSON — esig-mcp polls its own inbox (see Agent-to-agent (Pillar) below), runs the same verification path POST /sign's identityProof uses, and stores the result bound to that signer's challenge. The approval page then shows "Identity verified" and POST /sign accepts the signature with no identityProof at all.

Agent-to-agent over Pillar

Reach a signer that is itself an agent — no inbound HTTP, no email — over Pillar (IAASO-3050), UUAID's agent-to-agent communication substrate: signed, end-to-end encrypted envelopes over a store-and-forward carrier. Delivered by the optional peer package @e-sig/pillar-bridge (published, 0.1.0) — @e-sig/mcp never depends on it, and loads it only with a dynamic import() the moment it's actually needed.

ESIG_PILLAR_HOME          # keychain dir, default <ESIG_MCP_DATA_DIR>/pillar
ESIG_PILLAR_PASSPHRASE    # required with pillar — same ≥24-char floor as ESIG_MCP_PASSPHRASE
ESIG_PILLAR_CARRIERS      # required with pillar — comma-separated https:// carrier URLs
ESIG_PILLAR_SUBSCRIBERS   # optional JSON [{uuaid, publicKey}] — lifecycle-event subscribers
ESIG_PILLAR_PROOF_POLL    # seconds between inbox long-polls for identity proofs, default 1
ESIG_MCP_PILLAR_ALLOW_UNREGISTERED   # "1" to allow a signer with no UUAID registry badge

Sender verification, in order. Before an esig:identity-proof payload is ever decrypted or handed to a caller: (1) a pre-decrypt size cap (default 512 KiB, the community carrier-tier floor) is checked against the envelope's own serialized size; (2) the envelope's transport signature is verified against the sender's key before decryption; (3) the now-authenticated sender must pass an injectable allowlist — default deny, omitting it refuses every sender; (4) a per-sender rate cap (default 30/minute) applies. Anything that fails any of these is dropped and counted, never logged in detail.

Verifying a counter-signed document (A2A recipe)

import { verifyDocument } from "@e-sig/core";

// 1. Transport: envelope.open() already proved the sealed message came
//    from the claimed sender's Pillar key (see "Sender verification" above).

// 2. Document seal: check the PDF itself before counter-signing.
const v = verifyDocument(pdfBytes, {
  expectedUuaid: senderUuaid,
  requirePq: true,
});
if (!v.ok || !v.postQuantum.uuaidMatches) {
  throw new Error("seal identity does not match the claimed sender");
}
// only now countersign / accept

Security & compliance

What e-sig gives you

• Integrity: the signed ByteRange is hashed and RSA-signed; any later edit fails verification.
• Attribution: the signer cert + signature dictionary (name/reason/time) bind who signed and why.
• PAdES: ETSI.CAdES.detached subfilter with ESS signing-certificate-v2; padesStrict for B-B.
• CAdES-T: optional RFC-3161 timestamp proves the signature existed at a point in time.
• Evidence: an append-only audit log per signing event for ESIGN / UETA / 21 CFR §11 support.

The self-signed trust model

By default the signing cert is self-issued. That makes signatures cryptographically valid but not automatically trusted by third-party readers — Adobe shows "validity unknown" until the cert (or its issuer) is in a trust store. Two ways to establish trust:

1. Closed ecosystem: import your org cert into the relevant trust stores. Sufficient for internal / B2B flows where both sides know the issuer.
2. Public trust: plug an AATL/CA-issued signer (or a qualified TSP) into the same signPdf path — the code is signer-agnostic.

API reference

Everything exported from @e-sig/core:

Full consumer guide: packages/esig-core/CONSUMING.md in the repo.