@certysign/sdk 1.0.0 → 2.0.0

package/src/lib/SignatureEmbedder.js

@@ -0,0 +1,426 @@
+/**
+ * @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 pdf-lib) — 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
+
+class SignatureEmbedder {
+  /**
+   * Embed one or more digital signatures into a PDF document.
+   *
+   * Supports two call patterns:
+   *   1. Single signature  — pass options with a single `signature` field
+   *   2. Multiple signer   — pass options with a `signatures[]` array
+   *
+   * 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
+   *
+   * Multiple stamps are stacked from the bottom of the page upward,
+   * or positioned explicitly via `signaturePosition`.
+   *
+   * @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, PDFDict, rgb, StandardFonts;
+    try {
+      const pdfLib = require('pdf-lib');
+      PDFDocument  = pdfLib.PDFDocument;
+      PDFName      = pdfLib.PDFName;
+      PDFHexString = pdfLib.PDFHexString;
+      PDFDict      = pdfLib.PDFDict;
+      rgb          = pdfLib.rgb;
+      StandardFonts = pdfLib.StandardFonts;
+    } catch {
+      throw new Error(
+        'pdf-lib is required for PDF signature embedding. Install it: npm install pdf-lib'
+      );
+    }
+
+    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];
+
+    if (sigEntries.length === 0) {
+      throw new Error('embedInPdf: at least one signature is required');
+    }
+
+    // Track how many stamps we've drawn per page for auto-stacking
+    const pageStampCounts = {};
+
+    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
+      });
+
+      // ── 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;
+      }
+    }
+
+    // ── 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'
+    };
+
+    // 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;
+      }
+      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');
+    }
+    if (primary.chain) {
+      sigMetadata['CertySign-Chain'] = primary.chain.replace(/\n/g, '\\n');
+    }
+
+    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));
+      }
+    }
+
+    pdfDoc.setProducer('CertySign Trust Services');
+    pdfDoc.setModificationDate(new Date());
+
+    const signedBytes = await pdfDoc.save();
+    return Buffer.from(signedBytes);
+  }
+
+  /**
+   * 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;');
+}
+
+/**
+ * @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 };

package/src/lib/SigningSessionResource.js

@@ -0,0 +1,183 @@
+/**
+ * @fileoverview SigningSessionResource — multi-recipient hash-based signing
+ *
+ * Manages signing sessions where:
+ *  - Document hashes are registered (documents stay local)
+ *  - Recipients are added with sequential or parallel signing order
+ *  - OTP verification is required before each recipient can sign
+ *  - HSM signs the hash for each verified recipient
+ *
+ * Covers:
+ *  - create()         Create a signing session
+ *  - get()            Get session status
+ *  - list()           List sessions
+ *  - sendOtp()        Send OTP to a recipient
+ *  - verifyOtp()      Verify recipient OTP
+ *  - recipientSign()  Recipient signs after OTP verification
+ */
+
+'use strict';
+
+class SigningSessionResource {
+  /** @param {import('./HttpClient').HttpClient} http */
+  constructor(http) {
+    this._http = http;
+  }
+
+  /**
+   * Create a signing session with document hashes and recipients.
+   *
+   * @param {CreateSessionOptions} options
+   * @returns {Promise<Object>}
+   *
+   * @example
+   * const session = await client.sessions.create({
+   *   name: 'Q1 Contract',
+   *   documents: [
+   *     { hash: 'abc123...', fileName: 'contract.pdf', hashAlgorithm: 'sha256' }
+   *   ],
+   *   recipients: [
+   *     { email: 'ceo@example.com', name: 'Jane CEO', role: 'signer', order: 1 },
+   *     { email: 'cfo@example.com', name: 'John CFO', role: 'signer', order: 2 }
+   *   ],
+   *   signingOrder: 'sequential'
+   * });
+   *
+   * console.log(session.data._id);                  // Session ID
+   * console.log(session.data.recipients[0].recipientId); // Use for OTP/sign
+   */
+  create(options) {
+    const {
+      name,
+      description,
+      documents,
+      recipients,
+      signingOrder = 'parallel',
+      expiresAt
+    } = options;
+
+    if (!name)          throw new Error('create: name is required');
+    if (!documents?.length) throw new Error('create: documents array is required');
+    if (!recipients?.length) throw new Error('create: recipients array is required');
+
+    return this._http.post('/sdk/v1/signing-sessions', {
+      data: { name, description, documents, recipients, signingOrder, expiresAt }
+    });
+  }
+
+  /**
+   * Get a signing session by ID.
+   *
+   * @param {string} sessionId
+   * @returns {Promise<Object>}
+   */
+  get(sessionId) {
+    if (!sessionId) throw new Error('get: sessionId is required');
+    return this._http.get(`/sdk/v1/signing-sessions/${encodeURIComponent(sessionId)}`);
+  }
+
+  /**
+   * List signing sessions with pagination.
+   *
+   * @param {Object} [options]
+   * @param {number} [options.page=1]
+   * @param {number} [options.limit=20]
+   * @param {string} [options.status]
+   * @returns {Promise<Object>}
+   */
+  list(options = {}) {
+    return this._http.get('/sdk/v1/signing-sessions', { params: options });
+  }
+
+  /**
+   * Send an OTP verification code to a recipient's email.
+   *
+   * @param {string} sessionId
+   * @param {string} recipientId
+   * @returns {Promise<Object>}
+   *
+   * @example
+   * await client.sessions.sendOtp(sessionId, recipientId);
+   * // Recipient receives a 6-digit code via email
+   */
+  sendOtp(sessionId, recipientId) {
+    if (!sessionId)   throw new Error('sendOtp: sessionId is required');
+    if (!recipientId) throw new Error('sendOtp: recipientId is required');
+    return this._http.post(
+      `/sdk/v1/signing-sessions/${encodeURIComponent(sessionId)}/recipients/${encodeURIComponent(recipientId)}/send-otp`
+    );
+  }
+
+  /**
+   * Verify a recipient's OTP code.
+   * On success, returns a short-lived signing token.
+   *
+   * @param {string} sessionId
+   * @param {string} recipientId
+   * @param {string} code - 6-digit OTP from email
+   * @returns {Promise<Object>} - { signingToken, expiresAt }
+   *
+   * @example
+   * const result = await client.sessions.verifyOtp(sessionId, recipientId, '123456');
+   * const signingToken = result.data.signingToken;
+   */
+  verifyOtp(sessionId, recipientId, code) {
+    if (!sessionId)   throw new Error('verifyOtp: sessionId is required');
+    if (!recipientId) throw new Error('verifyOtp: recipientId is required');
+    if (!code)        throw new Error('verifyOtp: code is required');
+
+    return this._http.post(
+      `/sdk/v1/signing-sessions/${encodeURIComponent(sessionId)}/recipients/${encodeURIComponent(recipientId)}/verify-otp`,
+      { data: { code: String(code) } }
+    );
+  }
+
+  /**
+   * Recipient signs all documents in the session.
+   * Requires the signing token obtained from verifyOtp().
+   *
+   * @param {string} sessionId
+   * @param {string} recipientId
+   * @param {string} signingToken - Token from verifyOtp()
+   * @returns {Promise<Object>} - { signedDocuments, certificate, chain }
+   *
+   * @example
+   * const result = await client.sessions.recipientSign(
+   *   sessionId, recipientId, signingToken
+   * );
+   *
+   * // Use SignatureEmbedder to embed signatures into local documents
+   * for (const doc of result.data.signedDocuments) {
+   *   const signedPdf = await client.embedder.embedInPdf(pdfBuffer, {
+   *     signature:   doc.signature,
+   *     certificate: result.data.certificate,
+   *     chain:       result.data.chain,
+   *     reason:      'Contract signing',
+   *     signerName:  'Jane CEO'
+   *   });
+   *   fs.writeFileSync(`./signed-${doc.fileName}`, signedPdf);
+   * }
+   */
+  recipientSign(sessionId, recipientId, signingToken) {
+    if (!sessionId)    throw new Error('recipientSign: sessionId is required');
+    if (!recipientId)  throw new Error('recipientSign: recipientId is required');
+    if (!signingToken) throw new Error('recipientSign: signingToken is required');
+
+    return this._http.post(
+      `/sdk/v1/signing-sessions/${encodeURIComponent(sessionId)}/recipients/${encodeURIComponent(recipientId)}/sign`,
+      { data: { signingToken } }
+    );
+  }
+}
+
+/**
+ * @typedef {Object} CreateSessionOptions
+ * @property {string} name - Session name
+ * @property {string} [description]
+ * @property {{ hash: string, fileName: string, hashAlgorithm?: string, mimeType?: string }[]} documents
+ * @property {{ email: string, name: string, role?: string, order?: number }[]} recipients
+ * @property {'sequential'|'parallel'} [signingOrder='parallel']
+ * @property {string} [expiresAt] - ISO date
+ */
+
+module.exports = { SigningSessionResource };