@certysign/sdk 2.1.0 → 2.3.0

package/README.md

@@ -26,6 +26,7 @@ Official Node.js SDK for **CertySign Trust Services** — hash-based digital sig
 - [Complete Examples](#complete-examples)
 - [Error Handling](#error-handling)
 - [Rate Limiting](#rate-limiting)
+- [Timestamp Authority (TSA)](#timestamp-authority-tsa)
 - [Migration from v1](#migration-from-v1)
 - [PKI Trust Chain](#pki-trust-chain)
 - [Security Best Practices](#security-best-practices)
@@ -35,65 +36,26 @@ Official Node.js SDK for **CertySign Trust Services** — hash-based digital sig
 
 ## Installation
 
-### Local / internal use (current)
-
-The SDK is not yet published to the public npm registry. Use one of the methods below.
-
-**Option A — file path dependency** (recommended for services in this monorepo):
-
-```bash
-# From any service directory, e.g. a DHA integration project:
-npm install ../../sdk
-```
-
-This adds the following to the consuming project's `package.json`:
-
-```json
-"dependencies": {
-  "@certysign/sdk": "file:../../sdk"
-}
-```
-
-**Option B — `npm link`** (for local development outside the monorepo):
-
-```bash
-# In the sdk/ directory — register it globally once:
-cd sdk
-npm link
-
-# In any other project:
-npm link @certysign/sdk
-```
-
-**Option C — install directly from the folder path**:
-
-```bash
-npm install /absolute/path/to/Certy_Sign/sdk
-```
-
-### Publishing to npm (when ready)
-
-```bash
-# Log in to npm:
-npm login
-
-# From the sdk/ directory:
-npm publish --access public
-```
-
-After publishing, standard installation will work:
-
 ```bash
 npm install @certysign/sdk
 ```
 
 Node.js >= 18 required.
 
+**Peer dependencies** (installed automatically):
+- `pdf-lib` — PDF manipulation for visual stamps and /Sig dictionaries
+- `node-forge` — PKCS#7/CMS ASN.1 construction for cryptographic embedding
+
 ---
 
 ## Quick Start
 
-### Sign a single document (hash-based)
+### PAdES Signing — Cryptographically Valid PDF Signatures (Recommended)
+
+This is the **recommended** approach for v2.2.0+. It produces **PAdES Baseline B-T**
+PDF signatures with embedded RFC 3161 timestamps, recognised as valid by
+Adobe Reader, Foxit Reader, and other PDF validators. The TSA URL is resolved
+automatically from your environment — no configuration needed.
 
 ```js
 const { CertySignClient } = require('@certysign/sdk');
@@ -105,28 +67,68 @@ const client = new CertySignClient({
   environment: 'production'   // 'staging' | 'development'
 });
 
-// 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)
+// Get the active certificate for the visual stamp
+const cert = await client.certificates.getActive();
+
+// One call does everything:
+//   1. Prepares PDF with visual stamp + /Sig placeholder
+//   2. Computes SHA-256 hash of the ByteRange regions
+//   3. Calls your signCallback to sign the hash via HSM
+//   4. Builds PKCS#7 SignedData and patches into /Contents
+const signedPdf = await client.embedder.embedInPdf(pdfBuffer, {
+  certSerialNumber: cert.data?.serialNumber,
+  signerEmail:      'dr.okonkwo@dha.go.ke',
+  signerName:       'Dr. Amina Okonkwo',
+  reason:           'Health claim approval — DHA Kenya',
+  location:         'Nairobi, Kenya',
+  signCallback: async (byteRangeHash) => {
+    // The embedder computed the ByteRange hash — now sign it via HSM
+    return client.sign.signHash({
+      documentHash:  byteRangeHash,
+      hashAlgorithm: 'sha256',
+      fileName:      'claim.pdf',
+      reason:        'Health claim approval'
+    });
+  }
+});
+
+fs.writeFileSync('./claim-signed.pdf', signedPdf);
+// Open in Adobe Reader → Signature Panel shows:
+//   ✓ Valid digital signature
+//   ✓ Timestamp: RFC 3161 (proves when it was signed)
+//   ✓ Standard: PAdES Baseline B-T
+```
+
+### Simple Signing — Hash → Sign → Embed (Legacy approach)
+
+This approach signs the document hash first, then embeds the pre-computed signature.
+The PDF will have visual stamps and PKCS#7 structure, but the signature covers the
+original document hash rather than the ByteRange, so PDF readers may show a warning.
+
+```js
+const pdfBuffer = fs.readFileSync('./claim.pdf');
+
+// 1. Hash locally & sign remotely
 const result = await client.sign.hashAndSign({
   document:   pdfBuffer,
   fileName:   'claim.pdf',
   signerName: 'Dr. Amina Okonkwo',
-  reason:     'Health claim approval — DHA Kenya',
-  location:   'Nairobi, Kenya'
+  reason:     'Health claim approval'
 });
 
-// 3. Embed the signature into the PDF locally
+// 2. Embed signature into PDF
 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
+  signature:       result.data.signature,
+  certificate:     result.data.certificate,     // PEM string
+  certSerialNumber: result.data.certSerialNumber,
+  chain:           result.data.chain,            // PEM chain string
+  signerName:      'Dr. Amina Okonkwo',
+  reason:          'Health claim approval',
+  documentHash:    result.data.documentHash,
+  hashAlgorithm:   result.data.hashAlgorithm,
+  algorithm:       result.data.algorithm
 });
 
 fs.writeFileSync('./claim-signed.pdf', signedPdf);
@@ -172,46 +174,53 @@ const signed = await client.sessions.recipientSign(
 
 ## Architecture
 
+### PAdES Flow (Recommended — `signCallback`)
+
 ```
-┌─────────────────────────────────────────────────────────────────┐
-│                    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)             │                    │
-│                      └──────────────────────┘                    │
-│                                                                   │
-└─────────────────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────────────┐
+│                    SUBSCRIBER'S INFRASTRUCTURE                    │
+│                                                                    │
+│  ┌───────────┐                                                     │
+│  │ PDF       │                                                     │
+│  │ Document  │─────────────┐                                       │
+│  └───────────┘             ▼                                       │
+│              ┌──────────────────────────────┐                      │
+│              │  embedInPdf(pdf, {           │                      │
+│              │    signCallback: async (h) => │   1. Prepare PDF     │
+│              │      client.sign.signHash()   │      + visual stamp  │
+│              │  })                           │      + /Sig dict     │
+│              └──────────┬───────────────────┘                      │
+│                         │ 2. SHA-256(ByteRange)                    │
+│                         ▼                                          │
+│              ┌───────────────────────────────────┐                 │
+│              │        CertySign API               │                 │
+│              │  POST /sdk/v1/sign/hash            │                 │
+│              │  ┌─────────────────────────────┐   │                 │
+│              │  │  HSM (Google Cloud KMS)      │   │                 │
+│              │  │  Signs ByteRange hash        │   │                 │
+│              │  └─────────────────────────────┘   │                 │
+│              └───────────────┬───────────────────┘                 │
+│                              │ RSA signature + cert PEM + chain    │
+│                              ▼                                     │
+│              ┌──────────────────────────────┐                      │
+│              │  3. Build PKCS#7 SignedData   │                      │
+│              │  4. Patch into /Contents      │                      │
+│              │  5. Patch /ByteRange          │                      │
+│              └──────────────┬───────────────┘                      │
+│                             ▼                                      │
+│              ┌──────────────────────────────┐                      │
+│              │  PAdES-Signed PDF             │                      │
+│              │  ✓ Adobe Reader validates     │                      │
+│              │  ✓ /Sig + /ByteRange + PKCS#7 │                      │
+│              │  ✓ RFC 3161 timestamp (TSA)    │                      │
+│              │  ✓ 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.
+**What crosses the network:** Only the SHA-256 hash of the PDF ByteRange (64 hex characters).
+**What stays local:** The original document, the signing preparation, the PKCS#7 construction, and the final signed PDF.
 
 ---
 
@@ -232,11 +241,30 @@ The secret key is shown **once** at creation. Store it in a secrets manager (Vau
 
 ## Environments
 
-| Environment | Base URL |
-|-------------|----------|
-| `production` | `https://api.certysign.io` |
-| `staging` | `https://api-staging.certysign.io` |
-| `development` | `http://localhost:8000` |
+| Environment | Base URL | TSA URL |
+|-------------|----------|----------|
+| `production` | `https://core.certysign.io` | `https://tsa.certysign.io` |
+| `staging` | `https://service.certysign.io` | `https://tsa-staging.certysign.io` |
+| `development` | `http://localhost:8000` | `http://localhost:5015` |
+
+The **TSA URL** is resolved automatically from your environment — no manual configuration needed. Every PDF signature includes an RFC 3161 timestamp proving when the signature was created. Override with the `tsaUrl` constructor option if needed.
+
+```js
+// TSA is automatic — just set your environment
+const client = new CertySignClient({
+  publicKey:   process.env.CERTYSIGN_PUBLIC_KEY,
+  secretKey:   process.env.CERTYSIGN_SECRET_KEY,
+  environment: 'production'  // TSA → https://tsa.certysign.io (automatic)
+});
+
+// Or override TSA URL explicitly
+const client = new CertySignClient({
+  publicKey:   process.env.CERTYSIGN_PUBLIC_KEY,
+  secretKey:   process.env.CERTYSIGN_SECRET_KEY,
+  environment: 'production',
+  tsaUrl:      'https://custom-tsa.example.com'  // Custom TSA endpoint
+});
+```
 
 ---
 
@@ -259,14 +287,15 @@ const result = await client.sign.hashAndSign({
   location:   'Nairobi, Kenya',     // Optional
   metadata:   { claimId: '...' }    // Optional
 });
-// result.data.signature           — base64-encoded CMS/PKCS#7 signature
+// result.data.signature           — base64-encoded raw RSA 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.certificate.chain   — full trust chain PEM
-// result.data.signedAt            — ISO 8601 timestamp
+// result.data.certificate         — signer certificate PEM string
+// result.data.chain               — full trust chain PEM string
+// result.data.certSerialNumber    — certificate serial (hex)
+// result.data.certFingerprint     — SHA-256 fingerprint (hex)
+// result.data.timestamp           — ISO 8601 timestamp
 ```
 
 #### `signHash(options)` — Sign a pre-computed hash
@@ -300,7 +329,9 @@ const result = await client.sign.batchHashAndSign({
 // result.data.results[]            — array of signed results
 // result.data.results[].documentHash
 // result.data.results[].signature
-// result.data.certificate.pem      — shared certificate for the batch
+// result.data.certificate           — shared certificate PEM for the batch
+// result.data.certSerialNumber      — certificate serial (hex)
+// result.data.chain                 — chain PEM
 ```
 
 #### `batchSignHashes(options)` — Sign multiple pre-computed hashes
@@ -535,75 +566,99 @@ const results = await client.hasher.hashFiles([
 
 ### `client.embedder` — Local Signature Embedding
 
-Embeds CMS/PKCS#7 signatures into documents **locally** on your machine. No data is sent to CertySign during embedding.
+Embeds CMS/PKCS#7 signatures into documents **locally** on your machine. PDF embedding creates cryptographically valid PAdES signatures recognised by Adobe Reader and Foxit.
+
+#### `embedInPdf(pdfBuffer, options)` — Embed PAdES signature into PDF
+
+Creates a visual signature stamp and a proper PDF `/Sig` dictionary with PKCS#7/CMS
+cryptographic embedding. The resulting PDF passes validation in Adobe Reader, Foxit
+Reader, and other PDF signature validators.
 
-#### `embedInPdf(pdfBuffer, options)` — Embed signature into PDF
+**Recommended: `signCallback` approach (PAdES Baseline B-T)**
 
-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.
+The `signCallback` approach produces cryptographically valid PAdES B-T signatures
+with embedded RFC 3161 timestamps:
 
-**Single signer:**
+1. The embedder prepares the PDF with visual stamp and an empty `/Sig` placeholder
+2. It computes the SHA-256 hash of the PDF's ByteRange regions
+3. Your `signCallback` sends that hash to CertySign's HSM for signing
+4. The embedder fetches an RFC 3161 timestamp from the TSA (automatic)
+5. The embedder builds a PKCS#7 SignedData structure with the timestamp as an unsigned attribute and patches it into `/Contents`
 
 ```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
+  signerEmail:      'ndolimathews@gmail.com',          // Shown on visual stamp
+  signerName:       'Mathews Ndoli',                   // Fallback if no email
+  certSerialNumber: '9EF9C8E88478FC08C6759942274EB8A2', // Shown on visual stamp
+  reason:           'Document approval',                // Shown on stamp + /Sig dict
+  location:         'Nairobi, Kenya',                   // Optional
+  signCallback: async (byteRangeHash) => {
+    // byteRangeHash is a hex-encoded SHA-256 of the ByteRange regions
+    return client.sign.signHash({
+      documentHash:  byteRangeHash,
+      hashAlgorithm: 'sha256',
+      fileName:      'document.pdf'
+    });
+    // Must return: { data: { signature, certificate, chain, certSerialNumber } }
+  }
 });
-// Returns: Buffer — signed PDF
+// Returns: Buffer — PAdES-signed PDF
 fs.writeFileSync('./signed.pdf', signedPdf);
 ```
 
-**Multi-recipient (2+ signers):**
+**Alternative: Pre-computed signature (legacy)**
+
+You can pass a pre-computed `signature` instead of `signCallback`. The signature
+will be embedded in a PKCS#7 structure, but since it was computed over the original
+document hash (not the ByteRange), PDF readers may not fully validate it.
 
 ```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'
+  signature:       result.data.signature,        // Base64 raw RSA signature
+  certificate:     result.data.certificate,      // PEM string
+  chain:           result.data.chain,            // PEM chain string
+  certSerialNumber: result.data.certSerialNumber,
+  signerEmail:     'ndolimathews@gmail.com',
+  reason:          'Approval'
+});
+```
+
+**Signature Position:**
+
+```js
+const signedPdf = await client.embedder.embedInPdf(pdfBuffer, {
+  // ... signCallback or signature ...
+  signaturePosition: {
+    page:  1,      // Page number (1-indexed, default: last page)
+    x:     20,     // X offset from left (default: 20)
+    y:     20,     // Y offset from bottom (default: 20)
+    width: 260     // Stamp width in points (default: 260)
+  }
 });
 ```
 
-Each signer gets a visual stamp matching the CertySign platform format:
+Each signature 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         │
-└──────────────────────────────────────┘
+┌──────────────────────────────────────────┐
+│ Digitally signed by: ndolimathews@gmail.com│
+│ Date: 2026-03-16T14:30:00.000Z            │
+│ Certificate: 9EF9C8E88478FC08C6759942     │
+│ Standard: PAdES Baseline B-T              │
+│ Timestamp: RFC 3161 (TSA)                 │
+└──────────────────────────────────────────┘
 ```
 
-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.).
+**PDF Signature Structure (what gets created):**
+
+| PDF Object | Description |
+|------------|-------------|
+| `/Sig` dictionary | `Filter: Adobe.PPKLite`, `SubFilter: adbe.pkcs7.detached` |
+| `/ByteRange` | Byte offsets of signed regions (everything except `/Contents` hex) |
+| `/Contents` | DER-encoded PKCS#7 SignedData (hex, zero-padded to 8192 bytes) |
+| Widget annotation | Links visual stamp rectangle to the `/Sig` dictionary |
+| AcroForm | `SigFlags: 3` (SignaturesExist \| AppendOnly) |
+| Certificates | Signing cert + intermediate CA + root CA embedded in PKCS#7 |
 
 #### `embedInXml(xmlString, options)` — Embed XMLDSig signature
 
@@ -815,14 +870,12 @@ 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
+// data.serialNumber
+// data.fingerprint
+// data.algorithm         — e.g. 'RSA-2048'
+// data.validFrom
+// data.validUntil
+// data.subject           — { commonName, organization, ... }
 ```
 
 #### `issue(options)` — Issue a per-document certificate
@@ -990,7 +1043,7 @@ Legacy methods: `quickSign()`, `batchSign()`, `verifyById()`, `verifyDocument()`
 
 ## Complete Examples
 
-### PDF: Hash → Sign → Embed
+### PDF: PAdES Sign with signCallback (Recommended)
 
 ```js
 const fs = require('fs');
@@ -1003,30 +1056,27 @@ const client = new CertySignClient({
 
 async function signPdf(filePath) {
   const pdf = fs.readFileSync(filePath);
+  const cert = await client.certificates.getActive();
 
-  // 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
+    certSerialNumber: cert.data?.serialNumber,
+    signerName:       'Legal Department',
+    signerEmail:      'legal@company.co.ke',
+    reason:           'Contract execution',
+    location:         'Nairobi, Kenya',
+    signCallback: async (byteRangeHash) => {
+      return client.sign.signHash({
+        documentHash:  byteRangeHash,
+        hashAlgorithm: 'sha256',
+        fileName:      filePath.split('/').pop(),
+        reason:        'Contract execution'
+      });
+    }
   });
 
-  fs.writeFileSync(filePath.replace('.pdf', '-signed.pdf'), signed);
-  console.log('Signed:', data.certificate.serialNumber);
+  const outPath = filePath.replace('.pdf', '-signed.pdf');
+  fs.writeFileSync(outPath, signed);
+  console.log('PAdES signed:', outPath);
 }
 ```
 
@@ -1044,12 +1094,12 @@ async function signXml(filePath) {
   });
 
   const signedXml = client.embedder.embedInXml(xml, {
-    signature:      data.signature,
-    certificate:    data.certificate.pem,
-    certSerialNumber: data.certificate.serialNumber,
-    documentHash:   hash,
-    hashAlgorithm:  algorithm,
-    algorithm:      data.algorithm
+    signature:       data.signature,
+    certificate:     data.certificate,       // PEM string
+    certSerialNumber: data.certSerialNumber,
+    documentHash:    hash,
+    hashAlgorithm:   algorithm,
+    algorithm:       data.algorithm
   });
 
   fs.writeFileSync(filePath.replace('.xml', '-signed.xml'), signedXml);
@@ -1059,23 +1109,23 @@ async function signXml(filePath) {
 ### JSON: Hash → Sign → Envelope
 
 ```js
-async function signJson(data) {
-  const json = JSON.stringify(data);
+async function signJson(inputData) {
+  const json = JSON.stringify(inputData);
   const { hash, algorithm } = client.hasher.hash(Buffer.from(json), 'sha256');
 
-  const { data: sig } = await client.sign.signHash({
+  const { data } = 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
+  return client.embedder.embedInJson(inputData, {
+    signature:       data.signature,
+    certificate:     data.certificate,       // PEM string
+    certSerialNumber: data.certSerialNumber,
+    documentHash:    hash,
+    hashAlgorithm:   algorithm,
+    algorithm:       data.algorithm
   });
 }
 ```
@@ -1099,15 +1149,20 @@ const { data } = await client.sign.batchHashAndSign({
   reason:     'Monthly provider reimbursement'
 });
 
-// Embed signatures locally
+// Embed PAdES signatures locally using signCallback for each
 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
+    certSerialNumber: data.certSerialNumber,
+    signerName:       'NHIF Finance System',
+    signerEmail:      'finance@nhif.or.ke',
+    reason:           'Monthly provider reimbursement',
+    signCallback: async (byteRangeHash) => {
+      return client.sign.signHash({
+        documentHash:  byteRangeHash,
+        hashAlgorithm: 'sha256',
+        fileName:      files[i]
+      });
+    }
   });
   fs.writeFileSync(`./invoices/signed/${files[i]}`, signed);
 }
@@ -1256,6 +1311,61 @@ For batch workloads, use `batchHashAndSign()` or `batchSignHashes()` to sign up
 
 ## Migration from v1
 
+### What's New in v2.2.0
+
+| Feature | Description |
+|---------|-------------|
+| **PAdES Baseline B-T** | Every PDF signature now includes an RFC 3161 timestamp from CertySign's HSM-backed TSA |
+| **Automatic TSA URL** | TSA URL is resolved from your environment — no manual `tsaUrl` parameter needed |
+| **HSM-backed TSA key** | Timestamps are signed with a dedicated HSM key (RSA-3072, FIPS 140-2 Level 3) |
+| **OTP email delivery** | OTP emails for signing sessions are now fully operational |
+| **Audit blockchain anchoring** | Signing session events (`SIGNING_SESSION_RECIPIENT_SIGNED`, `SIGNING_OTP_VERIFIED`) are now archived to WORM storage and included in daily Merkle tree anchoring |
+
+### What's New in v2.1.0
+
+| Feature | Description |
+|---------|-------------|
+| **PAdES cryptographic embedding** | `embedInPdf()` now creates proper PDF `/Sig` dictionaries with PKCS#7/CMS that Adobe Reader and Foxit validate |
+| **`signCallback` option** | Pass an async callback to `embedInPdf()` — the embedder computes ByteRange hash, your callback signs it via HSM |
+| **PKCS#7 SignedData** | Full CMS ASN.1 structure: signing cert + chain embedded, SHA-256 digest algorithm, detached content |
+| **ByteRange signing** | Signature covers the actual PDF ByteRange regions, not just the original document hash |
+| **`node-forge` dependency** | Added for ASN.1/PKCS#7 construction |
+
+#### Constructor Change (v2.2.0)
+
+The `tsaUrl` parameter is now optional. TSA is resolved automatically:
+
+```js
+// v2.1.0 — manual TSA URL required for timestamps
+const client = new CertySignClient({
+  publicKey, secretKey,
+  tsaUrl: 'http://localhost:5015'
+});
+
+// v2.2.0 — TSA is automatic
+const client = new CertySignClient({
+  publicKey, secretKey,
+  environment: 'production'   // TSA URL auto-resolved
+});
+```
+
+#### Response Shape Change (v2.1.0)
+
+The signing API response has a flat structure (not nested):
+
+```js
+// v2.0.0 (incorrect docs):
+result.data.certificate.pem          // ❌ was never an object
+result.data.certificate.serialNumber  // ❌
+result.data.certificate.chain         // ❌
+
+// v2.1.0 (correct — always was this shape):
+result.data.certificate         // ✅ PEM string directly
+result.data.certSerialNumber    // ✅ hex serial string
+result.data.chain               // ✅ PEM chain string
+result.data.certFingerprint     // ✅ SHA-256 hex fingerprint
+```
+
 ### Breaking Changes in v2.0.0
 
 | v1 | v2 | Notes |
@@ -1325,8 +1435,83 @@ OCSP: `https://pki.certysign.io/ocsp`
 - **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
+- **Secure OTP delivery** — OTPs are single-use, expire in 10 minutes, and lock after 5 failed attempts. OTP codes are stored as SHA-256 hashes and verified with constant-time comparison
+- **Signing tokens** — 30-minute expiry, cryptographically random (32 bytes), single-use, stored as SHA-256 hashes
+- **Timestamps** — every signature includes an RFC 3161 timestamp from an HSM-backed TSA, proving when the document was signed
+- **Audit immutability** — signing events are archived to WORM object storage and anchored via daily Merkle trees
+
+---
+
+## Timestamp Authority (TSA)
+
+All PDF signatures include an **RFC 3161 timestamp** that cryptographically proves
+when the document was signed. The timestamp is issued by CertySign's HSM-backed
+Timestamp Authority and embedded as an unsigned attribute in the PKCS#7 SignedData.
+
+### How It Works
+
+| Step | What happens |
+|------|--------------|
+| 1 | The PDF ByteRange hash is signed by the tenant's HSM key |
+| 2 | The signature bytes are hashed (SHA-256) |
+| 3 | The hash is sent to the TSA (`POST /v1/tsa/json`) |
+| 4 | The TSA signs the hash with its dedicated HSM key and returns an RFC 3161 TimeStampToken |
+| 5 | The TimeStampToken is added as an unsigned attribute (OID `1.2.840.113549.1.9.16.2.14`) in the PKCS#7 |
+
+### TSA URL Resolution
+
+The TSA URL is resolved **automatically** from your environment:
+
+```js
+// No tsaUrl needed — resolved from environment
+const client = new CertySignClient({
+  publicKey: '...',
+  secretKey: '...',
+  environment: 'production'   // → https://tsa.certysign.io
+});
+
+console.log(client.tsaUrl);   // https://tsa.certysign.io
+```
+
+| Environment | TSA URL |
+|-------------|----------|
+| `production` | `https://tsa.certysign.io` |
+| `staging` | `https://tsa-staging.certysign.io` |
+| `development` | `http://localhost:5015` |
+| `test` | `http://localhost:5015` |
+
+Override with `tsaUrl` if you run a custom TSA:
+
+```js
+const client = new CertySignClient({
+  publicKey: '...', secretKey: '...',
+  tsaUrl: 'https://custom-tsa.example.com'
+});
+```
+
+### PAdES Compliance Levels
+
+| Standard | Timestamp | When |
+|----------|-----------|------|
+| **PAdES Baseline B-T** | RFC 3161 embedded | TSA URL available (default) |
+| **PAdES Baseline B-B** | None | TSA URL is `null` (manually disabled) |
+
+Since v2.2.0, all environments have TSA configured by default, so every signature
+is **PAdES Baseline B-T** unless you explicitly pass `tsaUrl: null`.
+
+### Verifying Timestamps
+
+The timestamp token is embedded in the PKCS#7 SignedData as an unsigned attribute.
+PDF validators (Adobe Reader, Foxit) display:
+
+```
+Signature is timestamped
+The signature includes an embedded timestamp.
+Timestamp time: 2026-03-17T09:05:29.000Z
+```
+
+To verify programmatically, parse the PKCS#7 ASN.1 and check for the unsigned
+attribute with OID `1.2.840.113549.1.9.16.2.14` (id-smime-aa-timeStampToken).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@certysign/sdk",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "Official Node.js SDK for CertySign — hash-based digital signing, X.509 certificates, and PKI services. Documents never leave your system.",
   "main": "src/index.js",
   "types": "src/index.d.ts",

package/src/index.js

@@ -84,7 +84,8 @@ class CertySignClient {
       environment = 'production',
       timeout,
       retries,
-      debug = false
+      debug = false,
+      tsaUrl,
     } = options;
 
     if (!publicKey) throw new Error('CertySignClient: publicKey is required');
@@ -118,11 +119,15 @@ class CertySignClient {
     this.sessions     = new SigningSessionResource(this._http); // Multi-recipient signing sessions
     this.dashboard    = new DashboardResource(this._http);      // SDK usage analytics
     this.hasher       = new DocumentHasher();                   // Local document hashing
-    this.embedder     = new SignatureEmbedder();                // Local signature embedding
+
+    // TSA URL: explicit > environment-derived
+    const resolvedTsaUrl = tsaUrl ?? CertySignClient.TSA_URLS[environment] ?? null;
+    this.embedder     = new SignatureEmbedder({ tsaUrl: resolvedTsaUrl }); // PAdES-T when TSA URL available
 
     this.publicKey   = publicKey;
     this.environment = environment;
     this.baseUrl     = resolvedBaseUrl;
+    this.tsaUrl      = resolvedTsaUrl;
   }
 
   /**
@@ -138,6 +143,19 @@ class CertySignClient {
     };
   }
 
+  /**
+   * Environment → TSA URL mapping.
+   * Override via the `tsaUrl` constructor option.
+   */
+  static get TSA_URLS() {
+    return {
+      production:  'https://tsa.certysign.io',
+      staging:     'https://tsa-staging.certysign.io',
+      development: 'http://localhost:5015',
+      test:        'http://localhost:5015'
+    };
+  }
+
   /**
    * Verify that the API key is valid and return the key metadata.
    * Useful as a "ping" / health check at startup.

package/src/lib/SignatureEmbedder.js

@@ -29,10 +29,19 @@ const STAMP_PADDING_X = 8;
 const STAMP_PADDING_Y = 8;
 const STAMP_WIDTH  = 260;
 const STAMP_MARGIN = 6;      // gap between multiple stamps
-// Placeholder size for PKCS#7 signature content (8192 bytes = 16384 hex chars)
-const SIG_PLACEHOLDER_LENGTH = 16384;
+// Placeholder size for PKCS#7 signature content (16384 bytes = 32768 hex chars)
+// Sized for PAdES-T: main PKCS#7 (~4KB) + TSA timestamp token (~6-8KB hybrid)
+const SIG_PLACEHOLDER_LENGTH = 32768;
 
 class SignatureEmbedder {
+  /**
+   * @param {Object} [opts]
+   * @param {string} [opts.tsaUrl] - TSA Service URL for PAdES-T timestamps
+   */
+  constructor(opts = {}) {
+    this.tsaUrl = opts.tsaUrl || null;
+  }
+
   /**
    * Embed one or more digital signatures into a PDF document with
    * proper PKCS#7/CMS cryptographic embedding (PAdES compliant).
@@ -94,21 +103,48 @@ class SignatureEmbedder {
     if (!entry) throw new Error('embedInPdf: at least one signature entry is required');
 
     const signerEmail    = entry.signerEmail || entry.recipientEmail || entry.signerName || 'CertySign';
-    const certSerial     = entry.certSerialNumber || '';
+    let   certSerial     = entry.certSerialNumber || '';
     const signDate       = entry.timestamp  ? new Date(entry.timestamp) :
                            entry.signedAt   ? new Date(entry.signedAt)  : new Date();
     const reason         = entry.reason     || 'Digital signature';
     const location       = entry.location   || '';
-    const standard       = entry.standard   || 'PAdES Baseline B-B';
     const certPem        = entry.certificate || null;
     const chainPem       = entry.chain       || null;
     const signCallback   = entry.signCallback || options.signCallback || null;
     const precomputedSig = entry.signature   || null;
+    const tsaUrl         = entry.tsaUrl || options.tsaUrl || this.tsaUrl || null;
+    const standard       = entry.standard   || (tsaUrl ? 'PAdES Baseline B-T' : 'PAdES Baseline B-B');
 
     if (!signCallback && !precomputedSig) {
       throw new Error('embedInPdf: either signCallback or signature is required');
     }
 
+    // ── Auto-resolve cert serial from PEM if not explicitly provided ──
+    if (!certSerial && certPem) {
+      try {
+        const parsedCert = forge.certificateFromPem(certPem);
+        certSerial = (parsedCert.serialNumber || '').toUpperCase();
+      } catch { /* ignore parse errors — stamp will show empty cert serial */ }
+    }
+
+    // ── signCallback pre-flight: discover cert serial before drawing stamp ──
+    // When using signCallback without a known cert serial, we call the callback
+    // with a dummy hash to learn the certificate. Then we re-call with the real
+    // ByteRange hash below. This ensures the visual stamp shows the cert serial.
+    let preflightResult = null;
+    if (signCallback && !certSerial) {
+      const dummyHash = '0'.repeat(64); // SHA-256 dummy
+      preflightResult = await signCallback(dummyHash);
+      const preflightCertPem = preflightResult.data?.certificate || preflightResult.certificate;
+      certSerial = preflightResult.data?.certSerialNumber || preflightResult.certSerialNumber || '';
+      if (!certSerial && preflightCertPem) {
+        try {
+          const parsedCert = forge.certificateFromPem(preflightCertPem);
+          certSerial = (parsedCert.serialNumber || '').toUpperCase();
+        } catch { /* ignore */ }
+      }
+    }
+
     // ── Determine target page ──
     const pos     = entry.signaturePosition || {};
     const pageIdx = pos.page
@@ -273,10 +309,19 @@ class SignatureEmbedder {
       rawSigBase64 = precomputedSig;
     }
 
+    // ── Phase 4.5: Fetch TSA timestamp token (PAdES B-B → PAdES B-T) ──
+    let timestampTokenAsn1 = null;
+    if (tsaUrl) {
+      // Hash the raw signature value — the timestamp proves the signature existed at this time
+      const rawSigBytes = Buffer.from(rawSigBase64, 'base64');
+      const sigHash = crypto.createHash('sha256').update(rawSigBytes).digest('hex');
+      timestampTokenAsn1 = await _fetchTimestamp(forge, tsaUrl, sigHash);
+    }
+
     // ── Phase 5: Build PKCS#7 and patch into /Contents ──
     const p7 = _buildPkcs7(forge, rawSigBase64, sigCertPem, sigChainPem, signDate, {
       signerEmail, reason, location, certSerial
-    });
+    }, timestampTokenAsn1);
     const p7Der = forge.asn1.toDer(p7).getBytes();
     const p7Hex = Buffer.from(p7Der, 'binary').toString('hex');
 
@@ -457,8 +502,12 @@ function _xmlEscape(str) {
  *
  * The HSM already produced the raw RSA signature over the document hash.
  * We wrap it into a CMS SignedData container so PDF readers recognise it.
+ *
+ * When timestampTokenAsn1 is provided, it is added as an unsigned attribute
+ * (id-smime-aa-timeStampToken, OID 1.2.840.113549.1.9.16.2.14) in SignerInfo,
+ * upgrading the signature from PAdES B-B to PAdES B-T.
  */
-function _buildPkcs7(forge, rawSigBase64, certPem, chainPem, signDate, meta) {
+function _buildPkcs7(forge, rawSigBase64, certPem, chainPem, signDate, meta, timestampTokenAsn1) {
   const rawSigBytes = forge.util.decode64(rawSigBase64);
 
   // Parse the signing certificate
@@ -538,7 +587,20 @@ function _buildPkcs7(forge, rawSigBase64, certPem, chainPem, signDate, meta) {
         ]),
         // signature
         forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.OCTETSTRING, false,
-          rawSigBytes)
+          rawSigBytes),
+        // unauthenticatedAttributes [1] IMPLICIT (PAdES-T timestamp token)
+        ...(timestampTokenAsn1 ? [
+          forge.asn1.create(forge.asn1.Class.CONTEXT_SPECIFIC, 1, true, [
+            forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.SEQUENCE, true, [
+              // id-smime-aa-timeStampToken (1.2.840.113549.1.9.16.2.14)
+              forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.OID, false,
+                forge.asn1.oidToDer('1.2.840.113549.1.9.16.2.14').getBytes()),
+              forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.SET, true, [
+                timestampTokenAsn1
+              ])
+            ])
+          ])
+        ] : [])
       ]
     );
     signerInfoSets.push(signerInfo);
@@ -600,6 +662,74 @@ function _pdfDate(date) {
          `${pad(date.getUTCHours())}${pad(date.getUTCMinutes())}${pad(date.getUTCSeconds())}+00'00'`;
 }
 
+/**
+ * Fetch an RFC 3161 timestamp token from the TSA Service.
+ *
+ * Calls the TSA JSON endpoint with the SHA-256 hash of the signature value.
+ * Parses the TimeStampResp and extracts the TimeStampToken (ContentInfo).
+ *
+ * @param {Object} forge - node-forge instance
+ * @param {string} tsaUrl - Base URL of the TSA Service (e.g. http://localhost:5015)
+ * @param {string} sigHashHex - SHA-256 hash of the signature value (hex)
+ * @returns {Object} ASN.1 ContentInfo (TimeStampToken) for embedding as unsigned attribute
+ */
+async function _fetchTimestamp(forge, tsaUrl, sigHashHex) {
+  const http = require('http');
+  const https = require('https');
+  const url = new URL('/v1/tsa/json', tsaUrl);
+
+  const body = JSON.stringify({
+    hash: sigHashHex,
+    hashAlgorithm: 'sha-256',
+    mode: 'classical',
+    certReq: true,
+  });
+
+  const transport = url.protocol === 'https:' ? https : http;
+
+  const tsaResp = await new Promise((resolve, reject) => {
+    const req = transport.request(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body),
+      },
+      timeout: 15000,
+    }, (res) => {
+      const chunks = [];
+      res.on('data', c => chunks.push(c));
+      res.on('end', () => {
+        try {
+          resolve(JSON.parse(Buffer.concat(chunks).toString()));
+        } catch (e) {
+          reject(new Error(`TSA response parse error: ${e.message}`));
+        }
+      });
+    });
+
+    req.on('error', e => reject(new Error(`TSA request failed: ${e.message}`)));
+    req.on('timeout', () => { req.destroy(); reject(new Error('TSA request timed out')); });
+    req.write(body);
+    req.end();
+  });
+
+  if (!tsaResp.success || !tsaResp.token) {
+    throw new Error(`TSA timestamp request failed: ${tsaResp.error || 'no token returned'}`);
+  }
+
+  // Parse TimeStampResp → extract TimeStampToken (ContentInfo)
+  const respDer = Buffer.from(tsaResp.token, 'base64');
+  const respAsn1 = forge.asn1.fromDer(forge.util.createBuffer(respDer));
+
+  // TimeStampResp ::= SEQUENCE { PKIStatusInfo, TimeStampToken OPTIONAL }
+  if (!respAsn1.value || respAsn1.value.length < 2) {
+    throw new Error('Invalid TimeStampResp: missing TimeStampToken');
+  }
+
+  // respAsn1.value[1] is the ContentInfo (TimeStampToken)
+  return respAsn1.value[1];
+}
+
 /**
  * Patch the placeholder /Contents hex string in the saved PDF with actual PKCS#7 DER bytes.
  * Searches for the placeholder pattern and replaces it with the real signature.