@certysign/sdk 2.0.0 → 2.2.0

package/src/lib/SignatureEmbedder.js

@@ -5,7 +5,7 @@
  * Documents NEVER leave the subscriber's infrastructure.
  *
  * Supports:
- *  - PDF (PAdES-style with pdf-lib) — single or multi-recipient visual stamps
+ *  - PDF (PAdES-style with cryptographic PKCS#7 embedding) — single or multi-recipient visual stamps
  *  - XML (XMLDSig enveloped signature)
  *  - JSON (JWS-like detached signature)
  *
@@ -29,23 +29,35 @@ 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 (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 {
   /**
-   * Embed one or more digital signatures into a PDF document.
+   * @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).
    *
-   * Supports two call patterns:
-   *   1. Single signature  — pass options with a single `signature` field
-   *   2. Multiple signer   — pass options with a `signatures[]` array
+   * Creates a PDF /Sig dictionary with /ByteRange and /Contents
+   * that Adobe Reader, Foxit, and other PDF readers recognise as
+   * a valid digital signature.
    *
-   * Each signature gets its own visual stamp matching the CertySign platform:
-   *   Digitally signed by: <email>
-   *   Date: <ISO 8601>
-   *   Certificate: <serial>
-   *   Standard: PAdES Baseline B-B
+   * **Recommended:** Pass a `signCallback` function — the embedder will:
+   *  1. Prepare the PDF with visual stamps and an empty /Sig placeholder
+   *  2. Compute the SHA-256 hash of the ByteRange regions
+   *  3. Call your `signCallback(hash)` to get the HSM signature
+   *  4. Build a valid PKCS#7 and patch it into /Contents
    *
-   * Multiple stamps are stacked from the bottom of the page upward,
-   * or positioned explicitly via `signaturePosition`.
+   * This produces a cryptographically valid PAdES signature that
+   * Adobe Reader, Foxit, and other PDF readers can verify.
    *
    * @param {Buffer} pdfBuffer - Original unsigned PDF
    * @param {EmbedPdfOptions} options
@@ -54,13 +66,16 @@ class SignatureEmbedder {
   async embedInPdf(pdfBuffer, options) {
     if (!pdfBuffer) throw new Error('embedInPdf: pdfBuffer is required');
 
-    let PDFDocument, PDFName, PDFHexString, PDFDict, rgb, StandardFonts;
+    let PDFDocument, PDFName, PDFHexString, PDFString, PDFDict, PDFArray, PDFNumber, rgb, StandardFonts;
     try {
       const pdfLib = require('pdf-lib');
       PDFDocument  = pdfLib.PDFDocument;
       PDFName      = pdfLib.PDFName;
       PDFHexString = pdfLib.PDFHexString;
+      PDFString    = pdfLib.PDFString;
       PDFDict      = pdfLib.PDFDict;
+      PDFArray     = pdfLib.PDFArray;
+      PDFNumber    = pdfLib.PDFNumber;
       rgb          = pdfLib.rgb;
       StandardFonts = pdfLib.StandardFonts;
     } catch {
@@ -69,134 +84,233 @@ class SignatureEmbedder {
       );
     }
 
+    let forge;
+    try {
+      forge = require('node-forge');
+    } catch {
+      throw new Error(
+        'node-forge is required for cryptographic PDF signing. Install it: npm install node-forge'
+      );
+    }
+
     const pdfDoc = await PDFDocument.load(pdfBuffer, { ignoreEncryption: true });
     const font   = await pdfDoc.embedFont(StandardFonts.Helvetica);
     const pages  = pdfDoc.getPages();
 
-    // ── Normalise to an array of signature entries ──
-    const sigEntries = options.signatures
-      ? options.signatures
-      : [options];
+    // ── Normalise to a single signature entry ──
+    // For PAdES we process one signature at a time (each needs its own ByteRange)
+    const entry = options.signatures ? options.signatures[0] : options;
+    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 || '';
+    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 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');
+    }
+
+    // ── Determine target page ──
+    const pos     = entry.signaturePosition || {};
+    const pageIdx = pos.page
+      ? Math.min(pos.page - 1, pages.length - 1)
+      : pages.length - 1;
+    const sigPage = pages[pageIdx];
+
+    // 4 text lines = height
+    const stampHeight = (4 * STAMP_LINE_HEIGHT) + (2 * STAMP_PADDING_Y);
+    const stampWidth  = pos.width  || STAMP_WIDTH;
+    const x = pos.x != null ? pos.x : 20;
+    const y = pos.y != null ? pos.y : 20;
+
+    // ── Draw stamp box ──
+    sigPage.drawRectangle({
+      x, y,
+      width:  stampWidth,
+      height: stampHeight,
+      borderColor: rgb(0.4, 0.4, 0.4),
+      borderWidth: 0.75,
+      color: rgb(0.97, 0.97, 0.97),
+      opacity: 0.95
+    });
 
-    if (sigEntries.length === 0) {
-      throw new Error('embedInPdf: at least one signature is required');
+    // ── Draw text lines matching CertySign platform format ──
+    const textLines = [
+      `Digitally signed by: ${signerEmail}`,
+      `Date: ${signDate.toISOString()}`,
+      `Certificate: ${certSerial}`,
+      `Standard: ${standard}`
+    ];
+
+    let textY = y + stampHeight - STAMP_PADDING_Y - STAMP_FONT_SIZE;
+    for (const line of textLines) {
+      sigPage.drawText(line, {
+        x: x + STAMP_PADDING_X,
+        y: textY,
+        size: STAMP_FONT_SIZE,
+        font,
+        color: rgb(0.4, 0.4, 0.4),
+        maxWidth: stampWidth - (2 * STAMP_PADDING_X)
+      });
+      textY -= STAMP_LINE_HEIGHT;
     }
 
-    // Track how many stamps we've drawn per page for auto-stacking
-    const pageStampCounts = {};
+    // ── Create the /Sig dictionary with empty placeholder ──
+    const sigDict = pdfDoc.context.obj({
+      Type: 'Sig',
+      Filter: 'Adobe.PPKLite',
+      SubFilter: 'adbe.pkcs7.detached',
+      // Large placeholder numbers ensure enough bytes for patching
+      ByteRange: [0, 9999999999, 9999999999, 9999999999],
+      Contents: PDFHexString.of('0'.repeat(SIG_PLACEHOLDER_LENGTH)),
+      Reason: PDFString.of(reason),
+      M: PDFString.of(_pdfDate(signDate)),
+      Name: PDFString.of(signerEmail),
+      Location: location ? PDFString.of(location) : undefined,
+      ContactInfo: PDFString.of(signerEmail)
+    });
 
-    for (let idx = 0; idx < sigEntries.length; idx++) {
-      const entry = sigEntries[idx];
-      const sig   = entry.signature;
-      if (!sig) throw new Error(`embedInPdf: signature is required (entry ${idx})`);
-
-      const signerEmail    = entry.signerEmail || entry.recipientEmail || entry.signerName || 'CertySign';
-      const 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';
-
-      // ── Determine target page ──
-      const pos     = entry.signaturePosition || {};
-      const pageIdx = pos.page
-        ? Math.min(pos.page - 1, pages.length - 1)
-        : pages.length - 1;
-      const sigPage = pages[pageIdx];
-
-      // ── Auto-stacking: each stamp stacks above the previous one ──
-      const stampKey = pageIdx;
-      if (!(stampKey in pageStampCounts)) pageStampCounts[stampKey] = 0;
-      const stampIndex = pageStampCounts[stampKey];
-      pageStampCounts[stampKey]++;
-
-      // 4 text lines = height
-      const stampHeight = (4 * STAMP_LINE_HEIGHT) + (2 * STAMP_PADDING_Y);
-      const stampWidth  = pos.width  || STAMP_WIDTH;
-
-      // Position: explicit position or auto-stack from bottom-left
-      const x = pos.x != null ? pos.x : 20;
-      const baseY = pos.y != null ? pos.y : 20;
-      const y = baseY + stampIndex * (stampHeight + STAMP_MARGIN);
-
-      // ── Draw stamp box ──
-      sigPage.drawRectangle({
-        x, y,
-        width:  stampWidth,
-        height: stampHeight,
-        borderColor: rgb(0.4, 0.4, 0.4),
-        borderWidth: 0.75,
-        color: rgb(0.97, 0.97, 0.97),
-        opacity: 0.95
+    const sigDictRef = pdfDoc.context.register(sigDict);
+
+    // ── Create widget annotation for the visual stamp ──
+    const widgetDict = pdfDoc.context.obj({
+      Type: 'Annot',
+      Subtype: 'Widget',
+      FT: 'Sig',
+      Rect: [x, y, x + stampWidth, y + stampHeight],
+      V: sigDictRef,
+      T: PDFString.of('CertySign-Sig-0'),
+      F: 4, // Print flag
+      P: pages[pageIdx].ref,
+    });
+
+    const widgetRef = pdfDoc.context.register(widgetDict);
+
+    // Add widget to page Annots array
+    const pageDict = pages[pageIdx].node;
+    let annots = pageDict.lookup(PDFName.of('Annots'));
+    if (!annots || !(annots instanceof PDFArray)) {
+      annots = pdfDoc.context.obj([]);
+      pageDict.set(PDFName.of('Annots'), annots);
+    }
+    annots.push(widgetRef);
+
+    // Add to AcroForm
+    let acroForm = pdfDoc.catalog.lookup(PDFName.of('AcroForm'));
+    if (!acroForm || !(acroForm instanceof PDFDict)) {
+      acroForm = pdfDoc.context.obj({
+        Fields: [],
+        SigFlags: 3 // SignaturesExist | AppendOnly
       });
+      pdfDoc.catalog.set(PDFName.of('AcroForm'), acroForm);
+    } else {
+      acroForm.set(PDFName.of('SigFlags'), PDFNumber.of(3));
+    }
 
-      // ── Draw text lines matching CertySign platform format ──
-      const textLines = [
-        `Digitally signed by: ${signerEmail}`,
-        `Date: ${signDate.toISOString()}`,
-        `Certificate: ${certSerial}`,
-        `Standard: ${standard}`
-      ];
-
-      let textY = y + stampHeight - STAMP_PADDING_Y - STAMP_FONT_SIZE;
-      for (const line of textLines) {
-        sigPage.drawText(line, {
-          x: x + STAMP_PADDING_X,
-          y: textY,
-          size: STAMP_FONT_SIZE,
-          font,
-          color: rgb(0.4, 0.4, 0.4),
-          maxWidth: stampWidth - (2 * STAMP_PADDING_X)
-        });
-        textY -= STAMP_LINE_HEIGHT;
-      }
+    let fields = acroForm.lookup(PDFName.of('Fields'));
+    if (!fields || !(fields instanceof PDFArray)) {
+      fields = pdfDoc.context.obj([]);
+      acroForm.set(PDFName.of('Fields'), fields);
     }
+    fields.push(widgetRef);
 
-    // ── Embed signature metadata as document properties ──
-    // Store the last (or primary) signature's CMS data for programmatic verification
-    const primary = sigEntries[0];
-    const sigMetadata = {
-      'CertySign-SignatureCount': String(sigEntries.length),
-      'CertySign-Algorithm': primary.algorithm || 'SHA256withRSA',
-      'CertySign-CertSerial': primary.certSerialNumber || '',
-      'CertySign-Timestamp': (primary.timestamp ? new Date(primary.timestamp) : new Date()).toISOString(),
-      'CertySign-Signer': primary.signerEmail || primary.recipientEmail || primary.signerName || 'CertySign',
-      'CertySign-DocumentHash': primary.documentHash || '',
-      'CertySign-HashAlgorithm': primary.hashAlgorithm || 'sha256',
-      'CertySign-Standard': primary.standard || 'PAdES Baseline B-B'
-    };
+    pdfDoc.setProducer('CertySign Trust Services');
+    pdfDoc.setModificationDate(new Date());
+
+    // ── Phase 1: Save PDF with empty signature placeholder ──
+    let pdfBytes = Buffer.from(await pdfDoc.save({ useObjectStreams: false }));
 
-    // Store each signature in metadata
-    for (let i = 0; i < sigEntries.length; i++) {
-      const entry = sigEntries[i];
-      sigMetadata[`CertySign-Signature-${i}`] = entry.signature;
-      if (entry.certSerialNumber) {
-        sigMetadata[`CertySign-CertSerial-${i}`] = entry.certSerialNumber;
+    // ── Phase 2: Patch ByteRange and compute hash of signed regions ──
+    const pdfStr = pdfBytes.toString('latin1');
+    const placeholderHex = '0'.repeat(SIG_PLACEHOLDER_LENGTH);
+    const placeholderIdx = pdfStr.indexOf(placeholderHex);
+    if (placeholderIdx === -1) {
+      throw new Error('embedInPdf: could not find signature placeholder in saved PDF');
+    }
+
+    const contentsStart = placeholderIdx - 1;  // byte offset of '<'
+    const contentsEnd   = placeholderIdx + SIG_PLACEHOLDER_LENGTH + 1; // byte after '>'
+    const totalLen      = pdfBytes.length;
+
+    const br0 = 0;
+    const br1 = contentsStart;
+    const br2 = contentsEnd;
+    const br3 = totalLen - contentsEnd;
+
+    // Patch ByteRange values in-place
+    const searchStart = Math.max(0, placeholderIdx - 500);
+    const searchRegion = pdfStr.substring(searchStart, placeholderIdx);
+    const brRelIdx = searchRegion.lastIndexOf('/ByteRange');
+    if (brRelIdx !== -1) {
+      const absIdx = searchStart + brRelIdx;
+      const closeBracket = pdfStr.indexOf(']', absIdx);
+      if (closeBracket !== -1) {
+        const oldBrLen = closeBracket + 1 - absIdx;
+        const newBrValue = `/ByteRange [${br0} ${br1} ${br2} ${br3}]`;
+        const newBr = newBrValue.padEnd(oldBrLen, ' ');
+        pdfBytes.write(newBr, absIdx, oldBrLen, 'latin1');
       }
-      const signer = entry.signerEmail || entry.recipientEmail || entry.signerName || '';
-      if (signer) sigMetadata[`CertySign-Signer-${i}`] = signer;
     }
 
-    if (primary.certificate) {
-      sigMetadata['CertySign-Certificate'] = primary.certificate.replace(/\n/g, '\\n');
+    // ── Phase 3: Compute hash of the ByteRange regions (everything except /Contents hex) ──
+    const byteRangeHash = crypto.createHash('sha256');
+    byteRangeHash.update(pdfBytes.subarray(br0, br0 + br1));          // before <Contents>
+    byteRangeHash.update(pdfBytes.subarray(br2, br2 + br3));          // after <Contents>
+    const hashHex = byteRangeHash.digest('hex');
+
+    // ── Phase 4: Get the signature ──
+    let rawSigBase64;
+    let sigCertPem = certPem;
+    let sigChainPem = chainPem;
+
+    if (signCallback) {
+      // Call the HSM to sign the ByteRange hash — produces a valid PAdES signature
+      const signResult = await signCallback(hashHex);
+      rawSigBase64 = signResult.data?.signature || signResult.signature;
+      sigCertPem   = sigCertPem || signResult.data?.certificate || signResult.certificate;
+      sigChainPem  = sigChainPem || signResult.data?.chain || signResult.chain;
+    } else {
+      // Legacy: use pre-computed signature (won't validate against ByteRange)
+      rawSigBase64 = precomputedSig;
     }
-    if (primary.chain) {
-      sigMetadata['CertySign-Chain'] = primary.chain.replace(/\n/g, '\\n');
+
+    // ── 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);
     }
 
-    const infoDict = pdfDoc.context.lookup(pdfDoc.context.trailerInfo.Info);
-    if (infoDict instanceof PDFDict) {
-      for (const [key, value] of Object.entries(sigMetadata)) {
-        infoDict.set(PDFName.of(key), PDFHexString.fromText(value));
-      }
+    // ── 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');
+
+    if (p7Hex.length > SIG_PLACEHOLDER_LENGTH) {
+      throw new Error(
+        `PKCS#7 signature too large (${p7Hex.length} hex chars > ${SIG_PLACEHOLDER_LENGTH} placeholder). ` +
+        'Increase SIG_PLACEHOLDER_LENGTH.'
+      );
     }
 
-    pdfDoc.setProducer('CertySign Trust Services');
-    pdfDoc.setModificationDate(new Date());
+    // Write PKCS#7 hex into the /Contents placeholder
+    const paddedHex = p7Hex.padEnd(SIG_PLACEHOLDER_LENGTH, '0');
+    pdfBytes.write(paddedHex, placeholderIdx, SIG_PLACEHOLDER_LENGTH, 'latin1');
 
-    const signedBytes = await pdfDoc.save();
-    return Buffer.from(signedBytes);
+    return pdfBytes;
   }
 
   /**
@@ -356,6 +470,293 @@ function _xmlEscape(str) {
     .replace(/'/g, '&apos;');
 }
 
+/**
+ * Build a PKCS#7 SignedData ASN.1 structure wrapping the raw RSA signature
+ * and the signer certificate (+ optional chain).
+ *
+ * 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, timestampTokenAsn1) {
+  const rawSigBytes = forge.util.decode64(rawSigBase64);
+
+  // Parse the signing certificate
+  const certs = [];
+  if (certPem) {
+    certs.push(forge.pki.certificateFromPem(certPem));
+  }
+  if (chainPem) {
+    // Chain may contain multiple PEM blocks
+    const chainBlocks = chainPem.match(/-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----/g) || [];
+    for (const block of chainBlocks) {
+      try { certs.push(forge.pki.certificateFromPem(block)); } catch { /* skip invalid */ }
+    }
+  }
+
+  const signerCert = certs[0] || null;
+
+  // ── Build ASN.1 SignedData manually ──
+  // OID: 1.2.840.113549.1.7.2 (signedData)
+  const contentType = forge.asn1.oidToDer('1.2.840.113549.1.7.2').getBytes();
+  // OID: 1.2.840.113549.1.7.1 (data)
+  const dataType = forge.asn1.oidToDer('1.2.840.113549.1.7.1').getBytes();
+  // OID: 2.16.840.1.101.3.4.2.1 (sha-256)
+  const sha256Oid = forge.asn1.oidToDer('2.16.840.1.101.3.4.2.1').getBytes();
+
+  // Create certificate SET
+  const certSet = [];
+  for (const cert of certs) {
+    certSet.push(forge.asn1.fromDer(forge.asn1.toDer(forge.pki.certificateToAsn1(cert))));
+  }
+
+  // Build SignerInfo
+  const signerInfoSets = [];
+  if (signerCert) {
+    const issuerSeq = forge.asn1.fromDer(
+      forge.asn1.toDer(forge.pki.distinguishedNameToAsn1(signerCert.issuer))
+    );
+    const serialInt = forge.asn1.create(
+      forge.asn1.Class.UNIVERSAL, forge.asn1.Type.INTEGER, false,
+      forge.util.hexToBytes(signerCert.serialNumber)
+    );
+
+    // Authenticated attributes
+    const signingTime = forge.asn1.create(
+      forge.asn1.Class.UNIVERSAL, forge.asn1.Type.SET, true, [
+        forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.SEQUENCE, true, [
+          forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.OID, false,
+            forge.asn1.oidToDer('1.2.840.113549.1.9.5').getBytes()), // signingTime OID
+          forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.SET, true, [
+            forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.UTCTIME, false,
+              _asn1UtcTime(signDate))
+          ])
+        ])
+      ]
+    );
+
+    const signerInfo = forge.asn1.create(
+      forge.asn1.Class.UNIVERSAL, forge.asn1.Type.SEQUENCE, true, [
+        // version
+        forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.INTEGER, false,
+          forge.util.hexToBytes('01')),
+        // issuerAndSerialNumber
+        forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.SEQUENCE, true, [
+          issuerSeq,
+          serialInt
+        ]),
+        // digestAlgorithm
+        forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.SEQUENCE, true, [
+          forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.OID, false, sha256Oid),
+          forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.NULL, false, '')
+        ]),
+        // signatureAlgorithm (rsaEncryption)
+        forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.SEQUENCE, true, [
+          forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.OID, false,
+            forge.asn1.oidToDer('1.2.840.113549.1.1.1').getBytes()),
+          forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.NULL, false, '')
+        ]),
+        // signature
+        forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.OCTETSTRING, false,
+          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);
+  }
+
+  // SignedData SEQUENCE
+  const signedData = forge.asn1.create(
+    forge.asn1.Class.UNIVERSAL, forge.asn1.Type.SEQUENCE, true, [
+      // version
+      forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.INTEGER, false,
+        forge.util.hexToBytes('01')),
+      // digestAlgorithms SET
+      forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.SET, true, [
+        forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.SEQUENCE, true, [
+          forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.OID, false, sha256Oid),
+          forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.NULL, false, '')
+        ])
+      ]),
+      // contentInfo (empty data — detached signature)
+      forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.SEQUENCE, true, [
+        forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.OID, false, dataType)
+      ]),
+      // certificates [0] IMPLICIT
+      ...(certSet.length > 0 ? [
+        forge.asn1.create(forge.asn1.Class.CONTEXT_SPECIFIC, 0, true, certSet)
+      ] : []),
+      // signerInfos SET
+      forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.SET, true, signerInfoSets)
+    ]
+  );
+
+  // Wrap in ContentInfo
+  const contentInfo = forge.asn1.create(
+    forge.asn1.Class.UNIVERSAL, forge.asn1.Type.SEQUENCE, true, [
+      forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.OID, false, contentType),
+      forge.asn1.create(forge.asn1.Class.CONTEXT_SPECIFIC, 0, true, [signedData])
+    ]
+  );
+
+  return contentInfo;
+}
+
+/**
+ * Convert a Date to ASN.1 UTCTime format (YYMMDDHHmmssZ)
+ */
+function _asn1UtcTime(date) {
+  const pad = n => String(n).padStart(2, '0');
+  const y = date.getUTCFullYear() % 100;
+  return `${pad(y)}${pad(date.getUTCMonth() + 1)}${pad(date.getUTCDate())}` +
+         `${pad(date.getUTCHours())}${pad(date.getUTCMinutes())}${pad(date.getUTCSeconds())}Z`;
+}
+
+/**
+ * Convert a Date to PDF date format (D:YYYYMMDDHHmmss+00'00')
+ */
+function _pdfDate(date) {
+  const pad = n => String(n).padStart(2, '0');
+  return `D:${date.getUTCFullYear()}${pad(date.getUTCMonth() + 1)}${pad(date.getUTCDate())}` +
+         `${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.
+ */
+function _patchSignatureContents(pdfBytes, p7Hex) {
+  // The placeholder is a hex string of null bytes (00) of length SIG_PLACEHOLDER_LENGTH
+  const placeholderHex = '0'.repeat(SIG_PLACEHOLDER_LENGTH);
+  const pdfStr = pdfBytes.toString('latin1');
+
+  // Find the placeholder in the PDF — it appears inside angle brackets: <0000...0000>
+  const placeholderIdx = pdfStr.indexOf(placeholderHex);
+  if (placeholderIdx === -1) {
+    return pdfBytes;
+  }
+
+  // Pad the actual signature hex to fill the full placeholder length
+  const paddedHex = p7Hex.padEnd(SIG_PLACEHOLDER_LENGTH, '0');
+
+  // Replace in a mutable buffer
+  const result = Buffer.from(pdfBytes);
+  result.write(paddedHex, placeholderIdx, SIG_PLACEHOLDER_LENGTH, 'latin1');
+
+  // Calculate actual ByteRange values
+  // '<' is at placeholderIdx - 1, '>' is at placeholderIdx + SIG_PLACEHOLDER_LENGTH
+  const contentsStart = placeholderIdx - 1;  // byte offset of '<'
+  const contentsEnd   = placeholderIdx + SIG_PLACEHOLDER_LENGTH + 1; // byte after '>'
+  const totalLen      = result.length;
+
+  // ByteRange: [before_sig_start, before_sig_len, after_sig_start, after_sig_len]
+  const br0 = 0;
+  const br1 = contentsStart;
+  const br2 = contentsEnd;
+  const br3 = totalLen - contentsEnd;
+
+  // Find /ByteRange [...] near the signature and patch it
+  const searchStart = Math.max(0, placeholderIdx - 500);
+  const searchRegion = pdfStr.substring(searchStart, placeholderIdx);
+  const brRelIdx = searchRegion.lastIndexOf('/ByteRange');
+  if (brRelIdx !== -1) {
+    const absIdx = searchStart + brRelIdx;
+    const closeBracket = pdfStr.indexOf(']', absIdx);
+    if (closeBracket !== -1) {
+      const oldBrLen = closeBracket + 1 - absIdx;
+      const newBrValue = `/ByteRange [${br0} ${br1} ${br2} ${br3}]`;
+      // Pad with spaces to exactly match original length — prevents shifting bytes
+      const newBr = newBrValue.padEnd(oldBrLen, ' ');
+      result.write(newBr, absIdx, oldBrLen, 'latin1');
+    }
+  }
+
+  return result;
+}
+
 /**
  * @typedef {Object} SignatureEntry
  * @property {string}  signature            - Base64 CMS/PKCS#7 from CertySign