digital-corporation-sign

A standalone, zero-hardcoding Node.js module for adding Adobe-compliant visible digital signatures to PDF documents using PKCS#12 (.pfx / .p12) certificates.

Features

• Adobe-Compliant Visible Signatures: Generates proper AcroForm signature fields, appearance streams (layers n0 - n4 with signature status icons), and ByteRange/Contents placeholders using pdf-lib.
• Cryptographic Signing: Signs PDF buffers with PKCS#12 certificates via @signpdf/signpdf and @signpdf/signer-p12.
• PFX Parsing: Extracts Common Name (CN) and Subject details directly from .pfx/.p12 certificates (file paths or binary Buffers).
• Dynamic Input: Zero hardcoded values, corporation names, passwords, or file paths. All parameters are passed dynamically by caller.
• Puppeteer Anchor Auto-Detection: Optional auto-placement of signature boxes over DOM elements (#signature-anchor) in Puppeteer HTML-to-PDF rendering pipelines.

Installation

Within your project, install digital-corporation-sign or include it in your dependencies:

npm install digital-corporation-sign

Peer Dependencies

Ensure you have the required core dependencies installed:

npm install pdf-lib @signpdf/signpdf @signpdf/signer-p12 node-forge

(Optional for Puppeteer anchor detection):

npm install puppeteer mupdf

Quick Start

1. Sign a PDF Buffer

const fs = require("fs");
const { signPdf, extractSignerNameFromPfx, formatSignedDate } = require("digital-corporation-sign");

async function example() {
  const pdfBuffer = fs.readFileSync("./sample.pdf");
  const pfxPath = "./certificate.pfx"; // Or pass Buffer: fs.readFileSync("./cert.pfx")
  const pfxPassword = "UserPassword123";

  // Extract signer name from PFX certificate
  const signerName = extractSignerNameFromPfx(pfxPath, pfxPassword);
  console.log("Signer Name:", signerName);

  // Format signature date
  const signedDate = formatSignedDate();
  console.log("Signed Date:", signedDate);

  // Define signature box coordinates [x1, y1, x2, y2] on Page 1
  const widgetRect = [400, 50, 490, 140];
  const pageNumber = 1;

  // Generate cryptographically signed PDF
  const signedPdfBuffer = await signPdf(
    pdfBuffer,
    pfxPath,
    pfxPassword,
    pageNumber,
    widgetRect,
    {
      reason: "Approved Certificate",
      location: "Mumbai",
    }
  );

  fs.writeFileSync("./sample_signed.pdf", signedPdfBuffer);
  console.log("PDF successfully signed!");
}

example().catch(console.error);

Signature Positioning & Placement

You can adjust signature placement on the PDF page using 3 flexible methods:

Method 1: Bounding Box Coordinates [x1, y1, x2, y2]

Specify exact PDF point coordinates [left, bottom, right, top] (bottom-left origin):

// Bottom-right box: 400pt from left, 50pt from bottom, 490pt right, 140pt top
const widgetRect = [400, 50, 490, 140];
await signPdf(pdfBuffer, pfxPath, pfxPassword, 1, widgetRect);

Method 2: Object Format { x, y, width, height }

Specify X, Y position along with signature box width and height:

const position = { x: 420, y: 60, width: 100, height: 80 };
await signPdf(pdfBuffer, pfxPath, pfxPassword, 1, position);

Method 3: Position Presets

Pass null for coordinates and use built-in presets:

// Available presets: 'bottom-right', 'bottom-left', 'top-right', 'top-left', 'bottom-center'
await signPdf(pdfBuffer, pfxPath, pfxPassword, 1, null, {
  positionPreset: "bottom-right",
  margin: 30, // margin from page edge in points
  width: 90,
  height: 90,
});

2. Using with Puppeteer Anchor Auto-Detection

const puppeteer = require("puppeteer");
const { locateSignatureWidget, signPdf } = require("digital-corporation-sign");

async function signPuppeteerPdf(htmlContent, pfxPath, pfxPassword) {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.setContent(htmlContent);

  // Auto-detect #signature-anchor in HTML page and compute PDF coordinates
  const location = await locateSignatureWidget(page, {
    anchorId: "signature-anchor", // DOM element ID
    sigSize: 90,                  // Widget box size in PDF points
    offsetLeft: 60,               // Left offset in points
    offsetUp: 20,                 // Up offset in points
  });

  // Render clean PDF from Puppeteer
  const cleanPdfBuffer = await page.pdf({ format: "A4", printBackground: true });
  await browser.close();

  if (!location) {
    throw new Error("Signature anchor element not found in HTML!");
  }

  // Sign PDF at detected page and coordinates
  const signedPdfBuffer = await signPdf(
    cleanPdfBuffer,
    pfxPath,
    pfxPassword,
    location.pageNumber,
    location.widgetRect
  );

  return signedPdfBuffer;
}

API Reference

signPdf(pdfBuffer, pfxInput, password, pageNumber, widgetRect, options)

High-level signature function that prepares the PDF placeholder and cryptographically signs it.

• pdfBuffer (Buffer): Original PDF buffer.
• pfxInput (string | Buffer): Path to .pfx/.p12 file OR Buffer containing binary PFX data.
• password (string): Passphrase for PFX certificate.
• pageNumber (number, optional): 1-based target page number (default: 1).
• widgetRect (number[], optional): Box coordinates [x1, y1, x2, y2].
• options (object, optional):
  • reason (string): Signature reason.
  • location (string): Signature location.
  • contactInfo (string): Contact information.
  • signatureFieldName (string): Custom AcroForm field name (default: "Signature1").
  • signatureLength (number): Reserved signature hex size in bytes (default: 15000).

extractSignerNameFromPfx(pfxInput, password)

Extracts Common Name (CN) or subject attributes from PKCS#12 credentials.

• pfxInput (string | Buffer): PFX file path or Buffer.
• password (string): Passphrase for PFX certificate.
• Returns: string (Signer Common Name or Subject details).

formatSignedDate(date)

Formats Date into standard signature format (YYYY.MM.DD HH:mm:ss +TZ).

• date (Date, optional): Date object (default: new Date()).
• Returns: string (e.g., "2026.08.20 12:17:05 +05:30").

locateSignatureWidget(puppeteerPage, options)

Locates an HTML element anchor in Puppeteer rendered output and returns PDF coordinates.

• puppeteerPage (import('puppeteer').Page): Active Puppeteer page.
• options (object, optional):
  • anchorId (string): HTML ID (default: "signature-anchor").
  • sigSize (number): Size in PDF points (default: 90).
  • offsetLeft (number): Offset left in points (default: 60).
  • offsetUp (number): Offset up in points (default: 20).
  • rasterScale (number): Detection scale (default: 2).

createVisibleSignature(pdfBuffer, pageNumber, widgetRect, options)

Low-level method to insert Adobe-compliant AcroForm visible signature placeholders without signing.

License

ISC