@certysign/sdk 1.0.0 → 2.0.0

package/README.md

@@ -1,6 +1,37 @@
 # @certysign/sdk
 
-Official Node.js SDK for **CertySign Trust Services** — digital document signing, X.509 certificate issuance, and PKI operations built for East Africa.
+Official Node.js SDK for **CertySign Trust Services** — hash-based digital signing, multi-recipient signing sessions, X.509 certificate management, and PKI operations built for East Africa.
+
+**Documents never leave your infrastructure.** The SDK hashes documents locally, sends only the cryptographic hash to CertySign for HSM-backed signing, receives the CMS/PKCS#7 signature, and embeds it into PDF/XML/JSON — all on your system.
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Architecture](#architecture)
+- [Authentication](#authentication)
+- [Environments](#environments)
+- [API Resources](#api-resources)
+  - [client.sign — Hash-Based Signing](#clientsign--hash-based-signing)
+  - [client.sessions — Multi-Recipient Signing Sessions](#clientsessions--multi-recipient-signing-sessions)
+  - [client.hasher — Local Document Hashing](#clienthasher--local-document-hashing)
+  - [client.embedder — Local Signature Embedding](#clientembedder--local-signature-embedding)
+  - [client.dashboard — SDK Analytics](#clientdashboard--sdk-analytics)
+  - [client.certificates — X.509 Certificate Management](#clientcertificates--x509-certificate-management)
+  - [client.pki — PKI Infrastructure](#clientpki--pki-infrastructure)
+  - [client.envelopes — Envelope Management](#clientenvelopes--envelope-management)
+  - [client.legacySign — Legacy Document Signing](#clientlegacysign--legacy-document-signing)
+- [Complete Examples](#complete-examples)
+- [Error Handling](#error-handling)
+- [Rate Limiting](#rate-limiting)
+- [Migration from v1](#migration-from-v1)
+- [PKI Trust Chain](#pki-trust-chain)
+- [Security Best Practices](#security-best-practices)
+- [Support](#support)
+
+---
 
 ## Installation
 
@@ -58,10 +89,15 @@ npm install @certysign/sdk
 
 Node.js >= 18 required.
 
-## Quick start
+---
+
+## Quick Start
+
+### Sign a single document (hash-based)
 
 ```js
 const { CertySignClient } = require('@certysign/sdk');
+const fs = require('fs');
 
 const client = new CertySignClient({
   publicKey:   process.env.CERTYSIGN_PUBLIC_KEY,   // cs_pk_...
@@ -69,19 +105,114 @@ const client = new CertySignClient({
   environment: 'production'   // 'staging' | 'development'
 });
 
-// Sign a document
-const result = await client.sign.quickSign({
-  document:    require('fs').readFileSync('./claim.pdf'),
-  filename:    'claim.pdf',
-  signerName:  'Dr. Amina Okonkwo',
-  signerEmail: 'amina.okonkwo@dha.go.ke',
-  reason:      'Health claim approval — DHA Kenya'
+// 1. Hash locally — document never leaves your system
+const pdfBuffer = fs.readFileSync('./claim.pdf');
+
+// 2. Hash & sign in one call (SDK hashes locally, sends only hash)
+const result = await client.sign.hashAndSign({
+  document:   pdfBuffer,
+  fileName:   'claim.pdf',
+  signerName: 'Dr. Amina Okonkwo',
+  reason:     'Health claim approval — DHA Kenya',
+  location:   'Nairobi, Kenya'
+});
+
+// 3. Embed the signature into the PDF locally
+const signedPdf = await client.embedder.embedInPdf(pdfBuffer, {
+  signature:      result.data.signature,
+  certificate:    result.data.certificate.pem,
+  certSerialNumber: result.data.certificate.serialNumber,
+  signerName:     'Dr. Amina Okonkwo',
+  reason:         'Health claim approval — DHA Kenya',
+  documentHash:   result.data.documentHash,
+  hashAlgorithm:  result.data.hashAlgorithm,
+  algorithm:      result.data.algorithm
 });
 
-console.log(result.data.envelopeId);
-console.log(result.data.certificate.serialNumber);
+fs.writeFileSync('./claim-signed.pdf', signedPdf);
 ```
 
+### Multi-recipient signing with OTP verification
+
+```js
+// 1. Hash documents locally
+const { hash } = client.hasher.hash(pdfBuffer, 'sha256');
+
+// 2. Create a signing session with recipients
+const session = await client.sessions.create({
+  name: 'Q1 Financial Report Approval',
+  documents: [{
+    documentId: 'doc-q1-report',
+    fileName:   'Q1-report.pdf',
+    hash,
+    hashAlgorithm: 'sha256'
+  }],
+  recipients: [
+    { email: 'cfo@company.co.ke', name: 'CFO', role: 'signer', order: 1 },
+    { email: 'ceo@company.co.ke', name: 'CEO', role: 'signer', order: 2 }
+  ],
+  signingOrder: 'sequential'   // CFO signs first, then CEO
+});
+
+// 3. Send OTP to recipient
+await client.sessions.sendOtp(session.data.session._id, recipientId);
+
+// 4. Verify OTP (recipient enters code from email)
+const { data } = await client.sessions.verifyOtp(session.data.session._id, recipientId, '485721');
+
+// 5. Recipient signs with their token
+const signed = await client.sessions.recipientSign(
+  session.data.session._id,
+  recipientId,
+  data.signingToken
+);
+```
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    SUBSCRIBER'S INFRASTRUCTURE                   │
+│                                                                   │
+│  ┌──────────┐    hash()     ┌──────────────────┐                 │
+│  │ Document  │─────────────▶│   DocumentHasher  │                 │
+│  │ (PDF/XML/ │              │   (SHA-256/384/   │                 │
+│  │  JSON)    │              │    512)           │                 │
+│  └──────────┘              └────────┬──────────┘                 │
+│       │                             │ hex hash only               │
+│       │                             ▼                             │
+│       │         ┌───────────────────────────────────┐            │
+│       │         │          CertySign API             │            │
+│       │         │  POST /sdk/v1/sign/hash            │            │
+│       │         │  ┌─────────────────────────────┐   │            │
+│       │         │  │  HSM (Google Cloud KMS)      │   │            │
+│       │         │  │  Signs hash with tenant key  │   │            │
+│       │         │  └─────────────────────────────┘   │            │
+│       │         └───────────────┬───────────────────┘            │
+│       │                         │ CMS signature + cert + chain    │
+│       │                         ▼                                 │
+│       │              ┌──────────────────────┐                    │
+│       └─────────────▶│  SignatureEmbedder    │                    │
+│                      │  embedInPdf()         │                    │
+│                      │  embedInXml()         │                    │
+│                      │  embedInJson()        │                    │
+│                      └──────────┬───────────┘                    │
+│                                 │                                 │
+│                                 ▼                                 │
+│                      ┌──────────────────────┐                    │
+│                      │  Signed Document      │                    │
+│                      │  (stays on YOUR       │                    │
+│                      │   system)             │                    │
+│                      └──────────────────────┘                    │
+│                                                                   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**What crosses the network:** Only the cryptographic hash (64-128 hex characters).  
+**What stays local:** The original document, the signed document, and the embedding process.
+
 ---
 
 ## Authentication
@@ -103,47 +234,87 @@ The secret key is shown **once** at creation. Store it in a secrets manager (Vau
 
 | Environment | Base URL |
 |-------------|----------|
-| `production` | `https://api.certysign.com` |
-| `staging` | `https://api-staging.certysign.com` |
+| `production` | `https://api.certysign.io` |
+| `staging` | `https://api-staging.certysign.io` |
 | `development` | `http://localhost:8000` |
 
 ---
 
 ## API Resources
 
-### `client.sign` — Document Signing
+### `client.sign` — Hash-Based Signing
 
-#### `quickSign(options)` — Sign a PDF in one call
+> **v2 (default):** Documents are hashed locally. Only the hash is sent to CertySign.  
+> For the legacy file-upload flow, see [`client.legacySign`](#clientlegacysign--legacy-document-signing).
+
+#### `hashAndSign(options)` — Hash locally & sign in one call
 
 ```js
-const result = await client.sign.quickSign({
-  document:    Buffer,              // Required — PDF buffer or ReadStream
-  filename:    'document.pdf',      // Optional — default: 'document.pdf'
-  signerName:  'Full Name',         // Required
-  signerEmail: 'email@example.com', // Optional
-  reason:      'Approval',          // Optional
-  location:    'Nairobi, Kenya',    // Optional
-  metadata:    { claimId: '...' }   // Optional — stored with envelope
+const result = await client.sign.hashAndSign({
+  document:   Buffer | string,      // Required — document content
+  fileName:   'claim.pdf',          // Optional — default: 'document.pdf'
+  mimeType:   'application/pdf',    // Optional — auto-detected from fileName
+  signerName: 'Dr. Amina Okonkwo', // Optional
+  reason:     'Approval',           // Optional
+  location:   'Nairobi, Kenya',     // Optional
+  metadata:   { claimId: '...' }    // Optional
 });
-// result.data.envelopeId
+// result.data.signature           — base64-encoded CMS/PKCS#7 signature
+// result.data.documentHash        — hex hash of the document
+// result.data.hashAlgorithm       — 'sha256' | 'sha384' | 'sha512'
+// result.data.algorithm           — 'SHA256withRSA' etc.
+// result.data.certificate.pem     — signer certificate PEM
 // result.data.certificate.serialNumber
-// result.data.signedDocumentUrl
+// result.data.certificate.chain   — full trust chain PEM
+// result.data.signedAt            — ISO 8601 timestamp
+```
+
+#### `signHash(options)` — Sign a pre-computed hash
+
+Use this when you already computed the hash yourself.
+
+```js
+const result = await client.sign.signHash({
+  documentHash:   'a3f2b8c1d4e5...',  // Required — hex-encoded hash
+  hashAlgorithm:  'sha256',            // Required — 'sha256' | 'sha384' | 'sha512'
+  fileName:       'report.pdf',        // Optional
+  signerName:     'NHIF System',       // Optional
+  reason:         'Automated signing', // Optional
+  location:       'Nairobi',           // Optional
+  metadata:       { batchId: '...' }   // Optional
+});
+// Same response shape as hashAndSign
+```
+
+#### `batchHashAndSign(options)` — Hash & sign multiple documents
+
+```js
+const result = await client.sign.batchHashAndSign({
+  documents: [
+    { document: fs.readFileSync('./invoice-1.pdf'), fileName: 'invoice-1.pdf' },
+    { document: fs.readFileSync('./invoice-2.pdf'), fileName: 'invoice-2.pdf' }
+  ],
+  signerName: 'NHIF Finance System',
+  reason:     'Batch provider reimbursement'
+});
+// result.data.results[]            — array of signed results
+// result.data.results[].documentHash
+// result.data.results[].signature
+// result.data.certificate.pem      — shared certificate for the batch
 ```
 
-#### `batchSign(options)` — Sign multiple PDFs at once
+#### `batchSignHashes(options)` — Sign multiple pre-computed hashes
 
 ```js
-const result = await client.sign.batchSign({
+const result = await client.sign.batchSignHashes({
   documents: [
-    { data: fs.readFileSync('./invoice-1.pdf'), filename: 'invoice-1.pdf' },
-    { data: fs.readFileSync('./invoice-2.pdf'), filename: 'invoice-2.pdf' }
+    { documentHash: 'a3f2...', hashAlgorithm: 'sha256', fileName: 'doc1.pdf' },
+    { documentHash: 'b7e1...', hashAlgorithm: 'sha256', fileName: 'doc2.pdf' }
   ],
-  signerName:  'NHIF Finance System',
-  signerEmail: 'invoicing@nhif.or.ke',
-  reason:      'Batch provider reimbursement'
+  signerName: 'Batch System',
+  reason:     'Monthly invoices'
 });
-// result.data.results[].envelopeId
-// result.data.results[].success
+// Up to 50 documents per batch
 ```
 
 #### `verifyById(envelopeId)` — Verify a signed envelope
@@ -155,16 +326,505 @@ const result = await client.sign.verifyById('env_abc123');
 // result.data.signedAt
 ```
 
-#### `verifyDocument(document, filename)` — Verify by uploading
+---
+
+### `client.sessions` — Multi-Recipient Signing Sessions
+
+Signing sessions support multi-recipient workflows with OTP email verification. Documents are represented by their hashes — the actual files never leave your system.
+
+#### Signing Order
+
+- **`sequential`** — recipients sign in the order specified by their `order` field. Recipient 2 cannot sign until recipient 1 has completed.
+- **`parallel`** — all recipients can sign independently in any order.
+
+#### `create(options)` — Create a signing session
+
+```js
+const session = await client.sessions.create({
+  name: 'Q1 Board Resolution',                    // Required
+  documents: [                                      // Required — at least one
+    {
+      documentId:    'doc-resolution',              // Required — your unique ID
+      fileName:      'board-resolution.pdf',        // Required
+      hash:          'a3f2b8c1d4e5f6...',          // Required — hex hash
+      hashAlgorithm: 'sha256',                      // Required
+      mimeType:      'application/pdf'              // Optional
+    }
+  ],
+  recipients: [                                     // Required — at least one
+    {
+      email: 'chair@board.co.ke',
+      name:  'Board Chair',
+      role:  'signer',          // 'signer' | 'viewer' | 'approver'
+      order: 1
+    },
+    {
+      email: 'secretary@board.co.ke',
+      name:  'Company Secretary',
+      role:  'signer',
+      order: 2
+    }
+  ],
+  signingOrder: 'sequential',   // 'sequential' | 'parallel'
+  expiresAt: '2026-02-01T00:00:00Z'  // Optional — default: 7 days
+});
+// session.data.session._id
+// session.data.session.status       — 'active'
+// session.data.session.recipients[] — each has .recipientId
+```
+
+#### `get(sessionId)` — Get session details
+
+```js
+const { data } = await client.sessions.get(sessionId);
+// data.session.status              — 'active' | 'completed' | 'expired'
+// data.session.documents[]         — includes .signature after signing
+// data.session.recipients[].status — 'pending' | 'otp_sent' | 'verified' | 'signed'
+```
+
+#### `list(options)` — List signing sessions
 
 ```js
-const result = await client.sign.verifyDocument(fs.readFileSync('./signed.pdf'));
+const { data } = await client.sessions.list({
+  page:   1,
+  limit:  20,
+  status: 'active'   // Optional filter
+});
+// data.sessions[]
+// data.pagination.total
+```
+
+#### `sendOtp(sessionId, recipientId)` — Send OTP email
+
+Sends a 6-digit OTP code to the recipient's email address. The OTP is valid for 10 minutes. Respects signing order — in sequential mode, you cannot send OTP to recipient 2 until recipient 1 has signed.
+
+```js
+await client.sessions.sendOtp(sessionId, recipientId);
+// OTP email sent to recipient
+```
+
+#### `verifyOtp(sessionId, recipientId, code)` — Verify OTP
+
+Validates the OTP code. After 5 failed attempts, the OTP is locked and must be re-sent. Returns a signing token valid for 30 minutes.
+
+```js
+const { data } = await client.sessions.verifyOtp(sessionId, recipientId, '485721');
+// data.signingToken   — use this for the signing step
+// data.expiresAt      — token expiry (30 minutes)
+```
+
+#### `recipientSign(sessionId, recipientId, signingToken)` — Recipient signs
+
+Signs all document hashes in the session using the tenant's HSM-backed certificate. The signing token must be valid and unexpired.
+
+```js
+const { data } = await client.sessions.recipientSign(sessionId, recipientId, signingToken);
+// data.session.status               — 'completed' if all recipients have signed
+// data.session.documents[].signature — base64 CMS signature for each document
+// data.session.documents[].signedAt
+// data.session.documents[].signedBy
+```
+
+#### Full Signing Session Flow
+
+```js
+const fs = require('fs');
+const { CertySignClient, DocumentHasher } = require('@certysign/sdk');
+
+const client = new CertySignClient({ publicKey, secretKey });
+const hasher = new DocumentHasher();
+
+// 1. Hash documents locally
+const doc1 = fs.readFileSync('./contract.pdf');
+const doc2 = fs.readFileSync('./addendum.pdf');
+const hash1 = hasher.hash(doc1, 'sha256');
+const hash2 = hasher.hash(doc2, 'sha256');
+
+// 2. Create session
+const { data: { session } } = await client.sessions.create({
+  name: 'Service Contract Signing',
+  documents: [
+    { documentId: 'contract', fileName: 'contract.pdf', hash: hash1.hash, hashAlgorithm: 'sha256' },
+    { documentId: 'addendum', fileName: 'addendum.pdf', hash: hash2.hash, hashAlgorithm: 'sha256' }
+  ],
+  recipients: [
+    { email: 'vendor@example.com', name: 'Vendor Rep', role: 'signer', order: 1 },
+    { email: 'client@example.com', name: 'Client Rep', role: 'signer', order: 2 }
+  ],
+  signingOrder: 'sequential'
+});
+
+// 3. First recipient: send OTP → verify → sign
+const recipientId = session.recipients[0].recipientId;
+await client.sessions.sendOtp(session._id, recipientId);
+
+// (Recipient enters code from their email)
+const { data: { signingToken } } = await client.sessions.verifyOtp(
+  session._id, recipientId, '123456'
+);
+await client.sessions.recipientSign(session._id, recipientId, signingToken);
+
+// 4. Second recipient follows the same flow...
+
+// 5. Retrieve completed session and embed signatures
+const completed = await client.sessions.get(session._id);
+for (const doc of completed.data.session.documents) {
+  const originalBuffer = doc.documentId === 'contract' ? doc1 : doc2;
+  const signed = await client.embedder.embedInPdf(originalBuffer, {
+    signature:      doc.signature,
+    certificate:    completed.data.session.certSerialNumber,
+    documentHash:   doc.hash,
+    hashAlgorithm:  doc.hashAlgorithm
+  });
+  fs.writeFileSync(`./signed-${doc.fileName}`, signed);
+}
+```
+
+---
+
+### `client.hasher` — Local Document Hashing
+
+All hashing is done **locally** on your machine. No data is sent to CertySign.
+
+#### `hash(data, algorithm)` — Hash a buffer or string
+
+```js
+const { hash, algorithm, size } = client.hasher.hash(
+  fs.readFileSync('./document.pdf'),
+  'sha256'   // Optional — default: 'sha256'. Also: 'sha384', 'sha512'
+);
+// hash       — hex-encoded hash string
+// algorithm  — 'sha256'
+// size       — input size in bytes
+```
+
+#### `hashFile(filePath, algorithm)` — Hash a file by path (streaming)
+
+Memory-efficient for large files — reads with streaming instead of loading the entire file.
+
+```js
+const { hash, algorithm, size } = await client.hasher.hashFile(
+  '/path/to/large-report.pdf',
+  'sha256'
+);
+```
+
+#### `hashMany(documents, algorithm)` — Batch hash buffers
+
+```js
+const results = client.hasher.hashMany([
+  { data: fs.readFileSync('./doc1.pdf'), fileName: 'doc1.pdf' },
+  { data: fs.readFileSync('./doc2.pdf'), fileName: 'doc2.pdf' }
+], 'sha256');
+// results[] — each: { fileName, hash, algorithm, size }
+```
+
+#### `hashFiles(filePaths, algorithm)` — Batch hash file paths
+
+```js
+const results = await client.hasher.hashFiles([
+  '/path/to/doc1.pdf',
+  '/path/to/doc2.pdf'
+], 'sha256');
+// results[] — each: { filePath, fileName, hash, algorithm, size }
+```
+
+**Supported algorithms:** `sha256`, `sha384`, `sha512`
+
+---
+
+### `client.embedder` — Local Signature Embedding
+
+Embeds CMS/PKCS#7 signatures into documents **locally** on your machine. No data is sent to CertySign during embedding.
+
+#### `embedInPdf(pdfBuffer, options)` — Embed signature into PDF
+
+Creates a visual signature stamp matching the CertySign platform and embeds CMS metadata into the PDF. Supports **multi-recipient** signing — each recipient gets their own visual stamp, stacked from the bottom of the page upward.
+
+**Single signer:**
+
+```js
+const signedPdf = await client.embedder.embedInPdf(pdfBuffer, {
+  signature:       'base64-cms-signature',       // Required
+  signerEmail:     'ndolimathews@gmail.com',     // Recommended — shown on stamp
+  signerName:      'Mathews Ndoli',              // Fallback if no email
+  certSerialNumber: '9EF9C8E88478FC08C6759942274EB8A2', // Optional
+  certificate:     '-----BEGIN CERTIFICATE-----...', // Optional — PEM
+  chain:           '-----BEGIN CERTIFICATE-----...', // Optional — chain PEM
+  documentHash:    'a3f2b8c1...',                 // Optional — hex hash
+  hashAlgorithm:   'sha256',                      // Optional
+  algorithm:       'SHA256withRSA',               // Optional
+});
+// Returns: Buffer — signed PDF
+fs.writeFileSync('./signed.pdf', signedPdf);
+```
+
+**Multi-recipient (2+ signers):**
+
+```js
+const signedPdf = await client.embedder.embedInPdf(pdfBuffer, {
+  signatures: [
+    {
+      signature: 'base64-cms-sig-cfo',
+      recipientEmail: 'cfo@company.co.ke',
+      recipientName: 'Jane Mwangi',
+      certSerialNumber: 'A1B2C3D4E5F6...',
+      signatureAlgorithm: 'SHA256withRSA',
+      signedAt: '2026-03-13T11:07:28.927Z'
+    },
+    {
+      signature: 'base64-cms-sig-ceo',
+      recipientEmail: 'ceo@company.co.ke',
+      recipientName: 'James Otieno',
+      certSerialNumber: 'F6E5D4C3B2A1...',
+      signatureAlgorithm: 'SHA256withRSA',
+      signedAt: '2026-03-13T11:12:45.000Z'
+    }
+  ],
+  documentHash: 'a3f2b8c1...',
+  hashAlgorithm: 'sha256'
+});
+```
+
+Each signer gets a visual stamp matching the CertySign platform format:
+
+```
+┌──────────────────────────────────────┐
+│ Digitally signed by: cfo@company.co.ke│
+│ Date: 2026-03-13T11:07:28.927Z       │
+│ Certificate: A1B2C3D4E5F6...         │
+│ Standard: PAdES Baseline B-B         │
+└──────────────────────────────────────┘
+┌──────────────────────────────────────┐
+│ Digitally signed by: ceo@company.co.ke│
+│ Date: 2026-03-13T11:12:45.000Z       │
+│ Certificate: F6E5D4C3B2A1...         │
+│ Standard: PAdES Baseline B-B         │
+└──────────────────────────────────────┘
+```
+
+Multiple stamps auto-stack from the bottom-left of each page upward. PDF metadata includes per-signer entries (`CertySign-Signature-0`, `CertySign-Signer-0`, `CertySign-CertSerial-0`, etc.).
+
+#### `embedInXml(xmlString, options)` — Embed XMLDSig signature
+
+Creates W3C XML Digital Signature (XMLDSig) enveloped signatures. Supports multi-signer — each signer gets a separate `<ds:Signature>` element.
+
+```js
+// Single signer
+const signedXml = client.embedder.embedInXml(xmlString, {
+  signature:       'base64-cms-signature',
+  certificate:     '-----BEGIN CERTIFICATE-----...',
+  certSerialNumber: 'A1B2C3...',
+  signerEmail:     'signer@company.co.ke',
+  signerName:      'System',
+  documentHash:    'a3f2b8c1...',
+  hashAlgorithm:   'sha256',
+  algorithm:       'SHA256withRSA'
+});
+
+// Multi-signer
+const signedXml = client.embedder.embedInXml(xmlString, {
+  signatures: [
+    { signature: 'sig1', recipientEmail: 'cfo@co.ke', certSerialNumber: 'A1...' },
+    { signature: 'sig2', recipientEmail: 'ceo@co.ke', certSerialNumber: 'B2...' }
+  ],
+  certificate: '-----BEGIN CERTIFICATE-----...',
+  documentHash: 'a3f2b8c1...',
+  hashAlgorithm: 'sha256',
+  algorithm: 'SHA256withRSA'
+});
+// Returns: string — XML with <ds:Signature> elements
+```
+
+Each `<ds:Signature>` element includes signer-specific properties:
+
+```xml
+<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#" Id="CertySign-Signature-0">
+  <ds:SignedInfo>
+    <ds:CanonicalizationMethod Algorithm="...xml-c14n11#"/>
+    <ds:SignatureMethod Algorithm="...rsa-sha256"/>
+    <ds:Reference URI="">
+      <ds:DigestMethod Algorithm="...sha256"/>
+      <ds:DigestValue>...</ds:DigestValue>
+    </ds:Reference>
+  </ds:SignedInfo>
+  <ds:SignatureValue>...</ds:SignatureValue>
+  <ds:KeyInfo>
+    <ds:X509Data>
+      <ds:X509Certificate>...</ds:X509Certificate>
+    </ds:X509Data>
+  </ds:KeyInfo>
+  <ds:Object>
+    <ds:SignatureProperties>
+      <ds:SignatureProperty>
+        <SignerEmail>cfo@co.ke</SignerEmail>
+        <CertSerial>A1...</CertSerial>
+        <Standard>PAdES Baseline B-B</Standard>
+      </ds:SignatureProperty>
+    </ds:SignatureProperties>
+  </ds:Object>
+</ds:Signature>
+```
+
+#### `embedInJson(jsonData, options)` — Create a signed JSON envelope
+
+Creates a signed JSON envelope with a `signatures[]` array. Supports multi-signer.
+
+```js
+// Single signer
+const signedJson = client.embedder.embedInJson(jsonData, {
+  signature:       'base64-cms-signature',
+  certificate:     '-----BEGIN CERTIFICATE-----...',
+  certSerialNumber: 'A1B2C3...',
+  signerEmail:     'signer@company.co.ke',
+  signerName:      'API System',
+  documentHash:    'a3f2b8c1...',
+  hashAlgorithm:   'sha256',
+  algorithm:       'SHA256withRSA'
+});
+
+// Multi-signer
+const signedJson = client.embedder.embedInJson(jsonData, {
+  signatures: [
+    { signature: 'sig1', recipientEmail: 'cfo@co.ke', recipientName: 'Jane', certSerialNumber: 'A1...' },
+    { signature: 'sig2', recipientEmail: 'ceo@co.ke', recipientName: 'James', certSerialNumber: 'B2...' }
+  ],
+  documentHash: 'a3f2b8c1...',
+  hashAlgorithm: 'sha256',
+  algorithm: 'SHA256withRSA'
+});
+// Returns: object
+```
+
+Output structure (v2 — **breaking change** from v1's single `signature` object):
+
+```json
+{
+  "data": { /* original JSON data */ },
+  "signatures": [
+    {
+      "value": "base64-cms-sig-1",
+      "algorithm": "SHA256withRSA",
+      "certificate": "-----BEGIN CERTIFICATE-----...",
+      "signer": {
+        "email": "cfo@co.ke",
+        "name": "Jane",
+        "certSerialNumber": "A1...",
+        "signedAt": "2026-03-13T11:07:28.927Z"
+      },
+      "standard": "PAdES Baseline B-B",
+      "digest": { "hash": "a3f2b8c1...", "algorithm": "sha256" }
+    },
+    {
+      "value": "base64-cms-sig-2",
+      "algorithm": "SHA256withRSA",
+      "certificate": "-----BEGIN CERTIFICATE-----...",
+      "signer": {
+        "email": "ceo@co.ke",
+        "name": "James",
+        "certSerialNumber": "B2...",
+        "signedAt": "2026-03-13T11:12:45.000Z"
+      },
+      "standard": "PAdES Baseline B-B",
+      "digest": { "hash": "a3f2b8c1...", "algorithm": "sha256" }
+    }
+  ],
+  "metadata": {
+    "provider": "CertySign Trust Services",
+    "version": "2.0.0",
+    "signatureCount": 2,
+    "signedAt": "2026-03-13T11:12:45.000Z"
+  }
+}
+```
+
+---
+
+### `client.dashboard` — SDK Analytics
+
+Track documents signed via the SDK, unique recipients, success/failure rates, and daily trends.
+
+#### `getStats(options?)` — Aggregate signing statistics
+
+```js
+const { data } = await client.dashboard.getStats({
+  from: '2026-01-01',  // Optional — ISO date
+  to:   '2026-03-31'   // Optional — ISO date
+});
+
+// data.documentsSignedTotal      — total documents signed across all sessions
+// data.documentsSignedToday      — documents signed today
+// data.documentsSignedThisMonth  — documents signed this month
+// data.signingSessionsTotal      — total signing sessions created
+// data.signingSessionsByStatus   — { draft, active, completed, expired, cancelled }
+// data.successRate               — percentage of completed sessions
+// data.uniqueRecipientsCount     — unique recipients (deduplicated by email)
+// data.recipientsList            — top recipients sorted by signCount desc
+// data.dailyTrend                — last 30 days: [{ date, documentsSigned }]
+// data.dateRange                 — { from, to } applied filter
+```
+
+#### `getRecipients(options?)` — Unique recipient list with activity
+
+```js
+const { data } = await client.dashboard.getRecipients({
+  page:   1,            // Default: 1
+  limit:  20,           // Default: 20
+  search: 'company.co'  // Optional — filter by name or email
+});
+
+// data.recipients[] — each entry:
+//   .email            — unique email address
+//   .name             — recipient name
+//   .totalSessions    — sessions this recipient was part of
+//   .signedSessions   — sessions where they signed
+//   .pendingSessions  — sessions still pending their signature
+//   .declinedSessions — sessions they declined
+//   .lastActivity     — last interaction timestamp
+//   .firstSeen        — first time they appeared
+// data.pagination     — { page, limit, total, pages }
+```
+
+#### `getDocuments(options?)` — Document-level signing details
+
+```js
+const { data } = await client.dashboard.getDocuments({
+  page:   1,
+  limit:  20,
+  status: 'completed'  // Optional — filter by session status
+});
+
+// data.documents[] — each entry:
+//   .sessionId       — parent signing session ID
+//   .sessionName     — session name
+//   .fileName        — document file name
+//   .hash            — document hash
+//   .signatures[]    — per-recipient signatures with email, certSerial, signedAt
+//   .signatureCount  — number of signatures on this document
+//   .recipientCount  — total recipients in the session
+// data.pagination    — { page, limit, total, pages }
 ```
 
 ---
 
 ### `client.certificates` — X.509 Certificate Management
 
+#### `getActive()` — Get your tenant's active signing certificate
+
+Returns the HSM-backed certificate used for hash signing operations.
+
+```js
+const { data } = await client.certificates.getActive();
+// data.certificate.serialNumber
+// data.certificate.fingerprint
+// data.certificate.pem           — PEM certificate
+// data.certificate.chain         — full trust chain PEM
+// data.certificate.validFrom
+// data.certificate.validUntil
+// data.certificate.subject       — { commonName, organization, ... }
+// data.certificate.trustSettings  — signing capabilities
+```
+
 #### `issue(options)` — Issue a per-document certificate
 
 ```js
@@ -188,9 +848,9 @@ const result = await client.certificates.issue({
 ```
 
 Issued certificates include:
-- **CRL Distribution Point** → `https://pki.certysign.com/crl/intermediate.crl`
-- **OCSP (AIA)** → `https://pki.certysign.com/ocsp`
-- **CA Issuers (AIA)** → `https://pki.certysign.com/certs/intermediate.crt`
+- **CRL Distribution Point** → `https://pki.certysign.io/crl/intermediate.crl`
+- **OCSP (AIA)** → `https://pki.certysign.io/ocsp`
+- **CA Issuers (AIA)** → `https://pki.certysign.io/certs/intermediate.crt`
 
 #### `verify(serialNumber, atTime?)` — Verify certificate validity
 
@@ -275,7 +935,7 @@ const { data } = await client.pki.info();
 
 ### `client.envelopes` — Envelope Management
 
-For integrations that need full control over the envelope lifecycle (instead of `quickSign`).
+For integrations that need full control over the envelope lifecycle.
 
 ```js
 // 1. Create envelope
@@ -309,6 +969,235 @@ const { data } = await client.envelopes.getAuditTrail(envelope._id);
 
 ---
 
+### `client.legacySign` — Legacy Document Signing
+
+> **Deprecated in v2.** Uploads entire documents to CertySign for server-side signing. Use [`client.sign`](#clientsign--hash-based-signing) instead for hash-based signing where documents never leave your system.
+
+```js
+// Legacy quickSign (documents are uploaded to CertySign)
+const result = await client.legacySign.quickSign({
+  document:    fs.readFileSync('./claim.pdf'),
+  filename:    'claim.pdf',
+  signerName:  'Dr. Amina Okonkwo',
+  signerEmail: 'amina.okonkwo@dha.go.ke',
+  reason:      'Health claim approval'
+});
+```
+
+Legacy methods: `quickSign()`, `batchSign()`, `verifyById()`, `verifyDocument()`.
+
+---
+
+## Complete Examples
+
+### PDF: Hash → Sign → Embed
+
+```js
+const fs = require('fs');
+const { CertySignClient } = require('@certysign/sdk');
+
+const client = new CertySignClient({
+  publicKey:   process.env.CERTYSIGN_PUBLIC_KEY,
+  secretKey:   process.env.CERTYSIGN_SECRET_KEY
+});
+
+async function signPdf(filePath) {
+  const pdf = fs.readFileSync(filePath);
+
+  // Hash & sign — document stays local
+  const { data } = await client.sign.hashAndSign({
+    document:   pdf,
+    fileName:   'contract.pdf',
+    signerName: 'Legal Department',
+    reason:     'Contract execution'
+  });
+
+  // Embed signature into PDF locally
+  const signed = await client.embedder.embedInPdf(pdf, {
+    signature:      data.signature,
+    certificate:    data.certificate.pem,
+    certSerialNumber: data.certificate.serialNumber,
+    chain:          data.certificate.chain,
+    signerName:     'Legal Department',
+    reason:         'Contract execution',
+    documentHash:   data.documentHash,
+    hashAlgorithm:  data.hashAlgorithm,
+    algorithm:      data.algorithm
+  });
+
+  fs.writeFileSync(filePath.replace('.pdf', '-signed.pdf'), signed);
+  console.log('Signed:', data.certificate.serialNumber);
+}
+```
+
+### XML: Hash → Sign → Embed XMLDSig
+
+```js
+async function signXml(filePath) {
+  const xml = fs.readFileSync(filePath, 'utf-8');
+  const { hash, algorithm } = client.hasher.hash(Buffer.from(xml), 'sha256');
+
+  const { data } = await client.sign.signHash({
+    documentHash:  hash,
+    hashAlgorithm: algorithm,
+    fileName:      'invoice.xml'
+  });
+
+  const signedXml = client.embedder.embedInXml(xml, {
+    signature:      data.signature,
+    certificate:    data.certificate.pem,
+    certSerialNumber: data.certificate.serialNumber,
+    documentHash:   hash,
+    hashAlgorithm:  algorithm,
+    algorithm:      data.algorithm
+  });
+
+  fs.writeFileSync(filePath.replace('.xml', '-signed.xml'), signedXml);
+}
+```
+
+### JSON: Hash → Sign → Envelope
+
+```js
+async function signJson(data) {
+  const json = JSON.stringify(data);
+  const { hash, algorithm } = client.hasher.hash(Buffer.from(json), 'sha256');
+
+  const { data: sig } = await client.sign.signHash({
+    documentHash:  hash,
+    hashAlgorithm: algorithm,
+    fileName:      'payload.json'
+  });
+
+  return client.embedder.embedInJson(data, {
+    signature:      sig.signature,
+    certificate:    sig.certificate.pem,
+    certSerialNumber: sig.certificate.serialNumber,
+    documentHash:   hash,
+    hashAlgorithm:  algorithm,
+    algorithm:      sig.algorithm
+  });
+}
+```
+
+### Batch Signing (50 invoices)
+
+```js
+const invoiceDir = './invoices/pending/';
+const files = fs.readdirSync(invoiceDir).filter(f => f.endsWith('.pdf'));
+
+// Hash all locally
+const documents = files.map(f => ({
+  document: fs.readFileSync(`${invoiceDir}${f}`),
+  fileName: f
+}));
+
+// One API call for all 50
+const { data } = await client.sign.batchHashAndSign({
+  documents,
+  signerName: 'NHIF Finance System',
+  reason:     'Monthly provider reimbursement'
+});
+
+// Embed signatures locally
+for (let i = 0; i < data.results.length; i++) {
+  const signed = await client.embedder.embedInPdf(documents[i].document, {
+    signature:      data.results[i].signature,
+    certificate:    data.certificate.pem,
+    certSerialNumber: data.certificate.serialNumber,
+    documentHash:   data.results[i].documentHash,
+    hashAlgorithm:  data.results[i].hashAlgorithm,
+    algorithm:      data.results[i].algorithm
+  });
+  fs.writeFileSync(`./invoices/signed/${files[i]}`, signed);
+}
+```
+
+### Multi-Recipient Signing Session → Embed
+
+```js
+const fs = require('fs');
+const { CertySignClient } = require('@certysign/sdk');
+
+const client = new CertySignClient({
+  publicKey:   process.env.CERTYSIGN_PUBLIC_KEY,
+  secretKey:   process.env.CERTYSIGN_SECRET_KEY
+});
+
+async function multiRecipientSign() {
+  const pdf = fs.readFileSync('./board-resolution.pdf');
+  const { hash, algorithm } = client.hasher.hash(pdf, 'sha256');
+
+  // 1. Create signing session with multiple recipients
+  const { data: session } = await client.sessions.create({
+    name: 'Board Resolution Q1 2026',
+    documents: [{ fileName: 'board-resolution.pdf', hash, hashAlgorithm: algorithm }],
+    recipients: [
+      { name: 'Jane Mwangi', email: 'cfo@company.co.ke', role: 'signer' },
+      { name: 'James Otieno', email: 'ceo@company.co.ke', role: 'signer' }
+    ],
+    signingOrder: 'sequential', // or 'parallel'
+    expiresIn: '7d'
+  });
+
+  // 2. Each recipient signs after OTP verification
+  //    (Normally triggered from the recipient's signing link)
+  //    After all recipients sign, session status becomes 'completed'
+
+  // 3. Retrieve completed session with all signatures
+  const { data: completed } = await client.sessions.get(session.sessionId);
+
+  // 4. Embed all signatures into the PDF
+  const doc = completed.documents[0];
+  const signedPdf = await client.embedder.embedInPdf(pdf, {
+    signatures:    doc.signatures,  // Array of per-recipient signatures
+    documentHash:  doc.hash,
+    hashAlgorithm: doc.hashAlgorithm
+  });
+
+  fs.writeFileSync('./board-resolution-signed.pdf', signedPdf);
+  // PDF now has stacked visual stamps for each signer
+}
+```
+
+### Dashboard: Track SDK Signing Activity
+
+```js
+async function showDashboard() {
+  // Overall stats
+  const { data: stats } = await client.dashboard.getStats({
+    from: '2026-01-01',
+    to:   '2026-03-31'
+  });
+  console.log(`Total documents signed: ${stats.documentsSignedTotal}`);
+  console.log(`Success rate: ${stats.successRate}%`);
+  console.log(`Unique recipients: ${stats.uniqueRecipientsCount}`);
+
+  // Daily trend chart data
+  stats.dailyTrend.forEach(d => {
+    console.log(`  ${d.date}: ${d.documentsSigned} documents`);
+  });
+
+  // Paginated recipient list
+  const { data: recipients } = await client.dashboard.getRecipients({
+    page: 1, limit: 10, search: 'company.co'
+  });
+  recipients.recipients.forEach(r => {
+    console.log(`${r.email}: ${r.signedSessions} signed, ${r.pendingSessions} pending`);
+  });
+
+  // Document-level details
+  const { data: docs } = await client.dashboard.getDocuments({
+    status: 'completed', page: 1, limit: 10
+  });
+  docs.documents.forEach(d => {
+    console.log(`${d.fileName}: ${d.signatureCount} signatures`);
+  });
+}
+```
+
+---
+
 ## Error Handling
 
 All SDK methods throw `CertySignError` on failure:
@@ -317,7 +1206,7 @@ All SDK methods throw `CertySignError` on failure:
 const { CertySignClient, CertySignError } = require('@certysign/sdk');
 
 try {
-  await client.sign.quickSign({ ... });
+  await client.sign.hashAndSign({ document: pdfBuffer });
 } catch (err) {
   if (err instanceof CertySignError) {
     console.error(err.message);       // Human-readable message
@@ -337,6 +1226,15 @@ Common error codes:
 | `INSUFFICIENT_SDK_PERMISSIONS` | 403 | Key lacks required permission |
 | `IP_NOT_ALLOWED` | 403 | Request IP not in IP allowlist |
 | `RATE_LIMIT_EXCEEDED` | 429 | Requests per minute exceeded |
+| `NO_ACTIVE_CERTIFICATE` | 404 | Tenant has no active signing certificate |
+| `CERTIFICATE_REVOKED` | 400 | Active certificate has been revoked |
+| `INVALID_HASH` | 400 | Hash format is invalid (must be hex) |
+| `INVALID_OTP` | 400 | OTP code is incorrect |
+| `OTP_EXPIRED` | 400 | OTP has expired (10 minute window) |
+| `OTP_MAX_ATTEMPTS` | 400 | Too many failed OTP attempts (max 5) |
+| `SIGNING_TOKEN_EXPIRED` | 400 | Signing token has expired (30 minute window) |
+| `SESSION_EXPIRED` | 400 | Signing session has expired |
+| `SIGNING_ORDER_VIOLATION` | 400 | Previous recipient hasn't signed yet (sequential mode) |
 | `NETWORK_ERROR` | 0 | Could not reach the API |
 
 The SDK automatically retries `429`, `502`, `503`, `504` responses up to 3 times with exponential back-off.
@@ -352,17 +1250,54 @@ Each API key has a configurable rate limit (requests per minute, set in the Cert
 - SDK retries automatically (up to 3 times) if the issue is transient
 - After retries are exhausted, `CertySignError` with code `RATE_LIMIT_EXCEEDED` is thrown
 
-For batch workloads, use `batchSign()` to sign multiple documents in a single API call rather than calling `quickSign()` in a loop.
+For batch workloads, use `batchHashAndSign()` or `batchSignHashes()` to sign up to 50 documents in a single API call.
 
 ---
 
-## Examples
-
-| File | Description |
-|------|-------------|
-| [examples/dha-integration.js](examples/dha-integration.js) | DHA Kenya claims quick-sign + certificate issuance |
-| [examples/nhif-batch-sign.js](examples/nhif-batch-sign.js) | NHIF nightly invoice batch signing |
-| [examples/certificate-flow.js](examples/certificate-flow.js) | Full X.509 lifecycle: issue, verify, CRL, OCSP, chain |
+## Migration from v1
+
+### Breaking Changes in v2.0.0
+
+| v1 | v2 | Notes |
+|----|-----|-------|
+| `client.sign.quickSign()` | `client.sign.hashAndSign()` | Documents no longer uploaded. Hash locally, sign remotely. |
+| `client.sign.batchSign()` | `client.sign.batchHashAndSign()` | Same principle — only hashes cross the network. |
+| `client.sign` (SigningResource) | `client.legacySign` | Old file-upload signing moved to `legacySign` |
+| — | `client.sign` (HashSigningResource) | New hash-based signing is now `client.sign` |
+| — | `client.sessions` | New multi-recipient signing sessions with OTP |
+| — | `client.hasher` | New local document hashing utility |
+| — | `client.embedder` | New local signature embedding (PDF/XML/JSON) |
+| — | `client.dashboard` | New SDK analytics (stats, recipients, documents) |
+| — | `client.certificates.getActive()` | New active cert retrieval |
+| `embedInJson` → `signature: {}` | `embedInJson` → `signatures: []` | JSON output changed from single object to array |
+
+### Migration Steps
+
+1. **Replace `quickSign`** with `hashAndSign` + `embedInPdf`:
+   ```js
+   // v1 — document uploaded to CertySign
+   await client.sign.quickSign({ document: pdf, filename: 'doc.pdf', signerName: '...' });
+
+   // v2 — document stays local
+   const result = await client.sign.hashAndSign({ document: pdf, fileName: 'doc.pdf' });
+   const signed = await client.embedder.embedInPdf(pdf, { signature: result.data.signature, ... });
+   ```
+
+2. **Replace `batchSign`** with `batchHashAndSign`:
+   ```js
+   // v1
+   await client.sign.batchSign({ documents: [...] });
+
+   // v2
+   const result = await client.sign.batchHashAndSign({ documents: [...] });
+   // Then embed each signature locally
+   ```
+
+3. **Use `client.legacySign`** if you need the old behavior temporarily:
+   ```js
+   // Still works — but deprecated
+   await client.legacySign.quickSign({ ... });
+   ```
 
 ---
 
@@ -372,27 +1307,31 @@ For batch workloads, use `batchSign()` to sign multiple documents in a single AP
 CertySign Root CA (C=KE, RSA-4096, 20yr)
   └── CertySign Intermediate CA (C=KE, RSA-4096, 10yr, pathLen=0)
         ├── Per-document X.509 certs  (issued via /sdk/v1/certificates/issue)
-        └── Tenant signing certs      (managed in CertySign portal)
+        └── Tenant signing certs      (HSM-backed, used for hash signing)
 ```
 
-CA bundle: `https://pki.certysign.com/certs/chain.pem`  
-CRL: `https://pki.certysign.com/crl/intermediate.crl`  
-OCSP: `https://pki.certysign.com/ocsp`
+CA bundle: `https://pki.certysign.io/certs/chain.pem`  
+CRL: `https://pki.certysign.io/crl/intermediate.crl`  
+OCSP: `https://pki.certysign.io/ocsp`
 
 ---
 
 ## Security Best Practices
 
+- **Documents never leave your system** — only cryptographic hashes are sent to CertySign
 - **Rotate keys** every 90 days: use the CertySign portal → API Keys → Rotate
 - **IP allowlist** every production key to your deployment's egress IPs
 - **Use `staging` environment** for development and CI pipelines (separate key pair)
 - **Store the private key** from `certificates.issue()` response in a HSM or secrets manager — CertySign does not retain it
 - **Cache CRL / OCSP responses** up to `nextUpdate` to reduce latency in HIE systems
+- **Verify hashes** after embedding — re-hash the original document to confirm integrity
+- **Secure OTP delivery** — OTPs are single-use, expire in 10 minutes, and lock after 5 failed attempts
+- **Signing tokens** — 30-minute expiry, cryptographically random, single-use
 
 ---
 
 ## Support
 
-- Docs: https://docs.certysign.com/sdk
+- Docs: https://docs.certysign.io/sdk
 - Issues: https://github.com/certysign/sdk-node/issues
-- Email: sdk@certysign.com
+- Email: sdk@certysign.io