@certysign/sdk 1.0.0 → 2.1.0

package/src/lib/SignatureEmbedder.js

@@ -0,0 +1,723 @@
+/**
+ * @fileoverview SignatureEmbedder — local signature embedding
+ *
+ * Embeds CMS/PKCS#7 signatures into documents on the subscriber's system.
+ * Documents NEVER leave the subscriber's infrastructure.
+ *
+ * Supports:
+ *  - PDF (PAdES-style with cryptographic PKCS#7 embedding) — single or multi-recipient visual stamps
+ *  - XML (XMLDSig enveloped signature)
+ *  - JSON (JWS-like detached signature)
+ *
+ * Visual stamp format (matches the CertySign platform):
+ *  ┌──────────────────────────────────────────┐
+ *  │ Digitally signed by: user@example.com    │
+ *  │ Date: 2026-03-13T11:07:28.927Z          │
+ *  │ Certificate: 9EF9C8E88478FC08C6759942   │
+ *  │ Standard: PAdES Baseline B-B             │
+ *  └──────────────────────────────────────────┘
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+
+// ── Constants ──
+const STAMP_FONT_SIZE = 7;
+const STAMP_LINE_HEIGHT = 10;
+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;
+
+class SignatureEmbedder {
+  /**
+   * Embed one or more digital signatures into a PDF document with
+   * proper PKCS#7/CMS cryptographic embedding (PAdES compliant).
+   *
+   * Creates a PDF /Sig dictionary with /ByteRange and /Contents
+   * that Adobe Reader, Foxit, and other PDF readers recognise as
+   * a valid digital signature.
+   *
+   * **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
+   *
+   * 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
+   * @returns {Promise<Buffer>} - Signed PDF buffer
+   */
+  async embedInPdf(pdfBuffer, options) {
+    if (!pdfBuffer) throw new Error('embedInPdf: pdfBuffer is required');
+
+    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 {
+      throw new Error(
+        'pdf-lib is required for PDF signature embedding. Install it: npm install pdf-lib'
+      );
+    }
+
+    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 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 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;
+
+    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
+    });
+
+    // ── 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;
+    }
+
+    // ── 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)
+    });
+
+    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));
+    }
+
+    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);
+
+    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 }));
+
+    // ── 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');
+      }
+    }
+
+    // ── 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;
+    }
+
+    // ── Phase 5: Build PKCS#7 and patch into /Contents ──
+    const p7 = _buildPkcs7(forge, rawSigBase64, sigCertPem, sigChainPem, signDate, {
+      signerEmail, reason, location, certSerial
+    });
+    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.'
+      );
+    }
+
+    // Write PKCS#7 hex into the /Contents placeholder
+    const paddedHex = p7Hex.padEnd(SIG_PLACEHOLDER_LENGTH, '0');
+    pdfBytes.write(paddedHex, placeholderIdx, SIG_PLACEHOLDER_LENGTH, 'latin1');
+
+    return pdfBytes;
+  }
+
+  /**
+   * Embed digital signatures into an XML document.
+   *
+   * Uses XMLDSig enveloped signature format.
+   * Supports multiple signatures — each signer gets their own <ds:Signature> element.
+   *
+   * @param {string} xmlString - Original XML content
+   * @param {EmbedXmlOptions} options
+   * @returns {string} - Signed XML string
+   */
+  embedInXml(xmlString, options) {
+    if (!xmlString) throw new Error('embedInXml: xmlString is required');
+
+    const sigEntries = options.signatures ? options.signatures : [options];
+
+    let result = xmlString;
+
+    for (let idx = 0; idx < sigEntries.length; idx++) {
+      const entry = sigEntries[idx];
+      const {
+        signature,
+        certificate,
+        documentHash,
+        hashAlgorithm = 'sha256',
+        certSerialNumber = '',
+        timestamp
+      } = entry;
+
+      if (!signature) throw new Error(`embedInXml: signature is required (entry ${idx})`);
+
+      const signerEmail = entry.signerEmail || entry.recipientEmail || entry.signerName || 'CertySign';
+      const standard    = entry.standard || 'PAdES Baseline B-B';
+      const signDate    = timestamp ? new Date(timestamp) : entry.signedAt ? new Date(entry.signedAt) : new Date();
+
+      const algorithmUri = {
+        sha256: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',
+        sha384: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha384',
+        sha512: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha512'
+      }[hashAlgorithm] || 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256';
+
+      const digestUri = {
+        sha256: 'http://www.w3.org/2001/04/xmlenc#sha256',
+        sha384: 'http://www.w3.org/2001/04/xmldsig-more#sha384',
+        sha512: 'http://www.w3.org/2001/04/xmlenc#sha512'
+      }[hashAlgorithm] || 'http://www.w3.org/2001/04/xmlenc#sha256';
+
+      const certValue = certificate
+        ? certificate.replace(/-----BEGIN CERTIFICATE-----/g, '')
+            .replace(/-----END CERTIFICATE-----/g, '')
+            .replace(/\s/g, '')
+        : '';
+
+      const signatureXml = `
+  <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#" Id="CertySign-Signature-${idx}">
+    <ds:SignedInfo>
+      <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
+      <ds:SignatureMethod Algorithm="${algorithmUri}"/>
+      <ds:Reference URI="">
+        <ds:Transforms>
+          <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
+        </ds:Transforms>
+        <ds:DigestMethod Algorithm="${digestUri}"/>
+        <ds:DigestValue>${documentHash ? Buffer.from(documentHash, 'hex').toString('base64') : ''}</ds:DigestValue>
+      </ds:Reference>
+    </ds:SignedInfo>
+    <ds:SignatureValue>${signature}</ds:SignatureValue>
+    <ds:KeyInfo>
+      <ds:X509Data>
+        <ds:X509Certificate>${certValue}</ds:X509Certificate>
+        <ds:X509SerialNumber>${certSerialNumber}</ds:X509SerialNumber>
+      </ds:X509Data>
+    </ds:KeyInfo>
+    <ds:Object>
+      <SignatureProperties xmlns="urn:certysign:signature:1.0">
+        <SignerEmail>${_xmlEscape(signerEmail)}</SignerEmail>
+        <Timestamp>${signDate.toISOString()}</Timestamp>
+        <CertSerial>${_xmlEscape(certSerialNumber)}</CertSerial>
+        <Standard>${_xmlEscape(standard)}</Standard>
+        <Provider>CertySign</Provider>
+      </SignatureProperties>
+    </ds:Object>
+  </ds:Signature>`;
+
+      // Insert before closing root tag
+      const closingTagMatch = result.match(/<\/([^\s>]+)\s*>\s*$/);
+      if (closingTagMatch) {
+        const insertPos = result.lastIndexOf(closingTagMatch[0]);
+        result = result.substring(0, insertPos) + signatureXml + '\n' + closingTagMatch[0];
+      } else {
+        result += signatureXml;
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Create a signed JSON envelope with one or more signatures.
+   *
+   * Supports multiple signers — each signer's signature is stored
+   * in the `signatures[]` array alongside the original data.
+   *
+   * @param {Object|string} jsonData - Original JSON content
+   * @param {EmbedJsonOptions} options
+   * @returns {Object} - Signed JSON envelope
+   */
+  embedInJson(jsonData, options) {
+    const data = typeof jsonData === 'string' ? JSON.parse(jsonData) : jsonData;
+    const sigEntries = options.signatures ? options.signatures : [options];
+
+    const signaturesArray = sigEntries.map((entry, idx) => {
+      if (!entry.signature) throw new Error(`embedInJson: signature is required (entry ${idx})`);
+
+      const signerEmail = entry.signerEmail || entry.recipientEmail || entry.signerName || 'CertySign';
+      const signDate = entry.timestamp ? new Date(entry.timestamp) : entry.signedAt ? new Date(entry.signedAt) : new Date();
+
+      return {
+        value: entry.signature,
+        algorithm: entry.algorithm || 'SHA256withRSA',
+        hashAlgorithm: entry.hashAlgorithm || 'sha256',
+        documentHash: entry.documentHash || '',
+        timestamp: signDate.toISOString(),
+        signer: {
+          email: signerEmail,
+          name: entry.recipientName || entry.signerName || signerEmail,
+          certSerialNumber: entry.certSerialNumber || ''
+        },
+        certificate: entry.certificate || null,
+        chain: entry.chain || null,
+        standard: entry.standard || 'PAdES Baseline B-B'
+      };
+    });
+
+    return {
+      data,
+      signatures: signaturesArray,
+      metadata: {
+        provider: 'CertySign Trust Services',
+        version: '2.0.0',
+        signatureCount: signaturesArray.length,
+        signedAt: new Date().toISOString()
+      }
+    };
+  }
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function _xmlEscape(str) {
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .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.
+ */
+function _buildPkcs7(forge, rawSigBase64, certPem, chainPem, signDate, meta) {
+  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)
+      ]
+    );
+    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'`;
+}
+
+/**
+ * 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
+ * @property {string}  [signerEmail]        - Signer email (used for visual stamp)
+ * @property {string}  [recipientEmail]     - Alias for signerEmail
+ * @property {string}  [signerName]         - Fallback signer name
+ * @property {string}  [recipientName]      - Signer display name
+ * @property {string}  [certSerialNumber]   - Certificate serial number
+ * @property {string}  [certificate]        - PEM certificate
+ * @property {string}  [chain]             - PEM chain
+ * @property {string}  [documentHash]       - Hex document hash
+ * @property {string}  [hashAlgorithm]
+ * @property {string}  [algorithm]
+ * @property {string}  [reason]
+ * @property {string}  [location]
+ * @property {string}  [standard]           - Default: 'PAdES Baseline B-B'
+ * @property {string}  [timestamp]
+ * @property {string}  [signedAt]
+ * @property {{ page?: number, x?: number, y?: number, width?: number }} [signaturePosition]
+ */
+
+/**
+ * @typedef {Object} EmbedPdfOptions
+ * @property {string}  [signature]         - Single signature (use this OR signatures[])
+ * @property {SignatureEntry[]} [signatures] - Multiple signatures for multi-recipient
+ * @property {string}  [signerEmail]
+ * @property {string}  [certificate]
+ * @property {string}  [chain]
+ * @property {string}  [reason]
+ * @property {string}  [signerName]
+ * @property {string}  [location]
+ * @property {string}  [certSerialNumber]
+ * @property {string}  [documentHash]
+ * @property {string}  [hashAlgorithm]
+ * @property {string}  [algorithm]
+ * @property {string}  [standard]
+ * @property {string}  [timestamp]
+ * @property {{ page?: number, x?: number, y?: number, width?: number }} [signaturePosition]
+ */
+
+/**
+ * @typedef {Object} EmbedXmlOptions
+ * @property {string}  [signature]
+ * @property {SignatureEntry[]} [signatures]
+ * @property {string}  [certificate]
+ * @property {string}  [chain]
+ * @property {string}  [documentHash]
+ * @property {string}  [hashAlgorithm]
+ * @property {string}  [signerEmail]
+ * @property {string}  [certSerialNumber]
+ * @property {string}  [timestamp]
+ */
+
+/**
+ * @typedef {Object} EmbedJsonOptions
+ * @property {string}  [signature]
+ * @property {SignatureEntry[]} [signatures]
+ * @property {string}  [certificate]
+ * @property {string}  [chain]
+ * @property {string}  [documentHash]
+ * @property {string}  [hashAlgorithm]
+ * @property {string}  [algorithm]
+ * @property {string}  [signerEmail]
+ * @property {string}  [certSerialNumber]
+ * @property {string}  [timestamp]
+ */
+
+module.exports = { SignatureEmbedder };