@certysign/sdk 1.0.0 → 2.0.0

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@certysign/sdk",
-  "version": "1.0.0",
-  "description": "Official Node.js SDK for CertySign — digital signing, X.509 certificates, and PKI services",
+  "version": "2.0.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",
+  "files": [
+    "src/",
+    "README.md"
+  ],
   "scripts": {
     "test": "jest --coverage",
     "lint": "eslint src/**/*.js",
@@ -16,17 +20,21 @@
     "x509",
     "pdf-signing",
     "document-signing",
+    "hash-based-signing",
     "kenya",
-    "pades"
+    "pades",
+    "xmldsig",
+    "otp"
   ],
-  "author": "CertySign Limited <sdk@certysign.com>",
+  "author": "CertySign Limited <sdk@certysign.io>",
   "license": "MIT",
   "engines": {
     "node": ">=18.0.0"
   },
   "dependencies": {
     "axios": "^1.6.0",
-    "form-data": "^4.0.0"
+    "form-data": "^4.0.0",
+    "pdf-lib": "^1.17.1"
   },
   "devDependencies": {
     "jest": "^29.7.0"
@@ -35,7 +43,7 @@
     "type": "git",
     "url": "git+https://github.com/certysign/sdk-node.git"
   },
-  "homepage": "https://docs.certysign.com/sdk",
+  "homepage": "https://docs.certysign.io/sdk",
   "bugs": {
     "url": "https://github.com/certysign/sdk-node/issues"
   },

package/src/index.js

@@ -18,39 +18,59 @@
 'use strict';
 
 const { HttpClient, CertySignError } = require('./lib/HttpClient');
-const { SigningResource }     = require('./lib/SigningResource');
-const { CertificateResource } = require('./lib/CertificateResource');
-const { PkiResource }         = require('./lib/PkiResource');
-const { EnvelopeResource }    = require('./lib/EnvelopeResource');
+const { SigningResource }         = require('./lib/SigningResource');
+const { HashSigningResource }     = require('./lib/HashSigningResource');
+const { CertificateResource }     = require('./lib/CertificateResource');
+const { PkiResource }             = require('./lib/PkiResource');
+const { EnvelopeResource }        = require('./lib/EnvelopeResource');
+const { SigningSessionResource }  = require('./lib/SigningSessionResource');
+const { DashboardResource }       = require('./lib/DashboardResource');
+const { DocumentHasher }          = require('./lib/DocumentHasher');
+const { SignatureEmbedder }       = require('./lib/SignatureEmbedder');
 
 /**
  * CertySign API client.
  *
  * Resources are accessed as properties:
- *  - client.sign          — document signing (quickSign, batchSign, verify)
- *  - client.certificates  — X.509 certificate lifecycle (issue, verify, status)
+ *  - client.sign          — hash-based document signing (documents stay local)
+ *  - client.sessions      — multi-recipient signing sessions with OTP verification
+ *  - client.dashboard     — SDK usage analytics (stats, recipients, documents)
+ *  - client.certificates  — X.509 certificate lifecycle (issue, verify, status, getActive)
  *  - client.pki           — PKI infrastructure (CRL, OCSP, CA chain, info)
  *  - client.envelopes     — envelope management (create, upload, send, sign, audit)
+ *  - client.hasher        — local document hashing utility
+ *  - client.embedder      — local signature embedding (PDF, XML, JSON)
+ *  - client.legacySign    — legacy file-upload signing (deprecated)
  *
- * @example
+ * @example Hash-based signing (documents never leave your system)
  * const { CertySignClient } = require('@certysign/sdk');
  *
  * const client = new CertySignClient({
  *   publicKey:   process.env.CERTYSIGN_PUBLIC_KEY,
  *   secretKey:   process.env.CERTYSIGN_SECRET_KEY,
- *   environment: 'production'   // or 'staging', 'development'
+ *   environment: 'production'
  * });
  *
- * // Sign a document
- * const result = await client.sign.quickSign({
- *   document:    fs.readFileSync('./claim.pdf'),
- *   filename:    'claim.pdf',
- *   signerName:  'Dr. Amina Okonkwo',
- *   reason:      'Health records approval'
+ * // 1. Hash locally → sign remotely → embed locally
+ * const result = await client.sign.hashAndSign({
+ *   document: fs.readFileSync('./contract.pdf'),
+ *   fileName: 'contract.pdf',
+ *   reason:   'Contract approval'
  * });
  *
- * console.log(result.data.envelopeId);
- * console.log(result.data.certificate.serialNumber);
+ * // 2. Embed signature into the PDF on your system
+ * const signedPdf = await client.embedder.embedInPdf(
+ *   fs.readFileSync('./contract.pdf'),
+ *   {
+ *     signature:      result.data.signature,
+ *     certificate:    result.data.certificate,
+ *     chain:          result.data.chain,
+ *     signerName:     'Dr. Amina Okonkwo',
+ *     reason:         'Contract approval',
+ *     certSerialNumber: result.data.certSerialNumber
+ *   }
+ * );
+ * fs.writeFileSync('./contract-signed.pdf', signedPdf);
  */
 class CertySignClient {
   /**
@@ -90,10 +110,15 @@ class CertySignClient {
     });
 
     // ── Resource objects ──
-    this.sign         = new SigningResource(this._http);
+    this.sign         = new HashSigningResource(this._http);   // Hash-based signing (documents stay local)
+    this.legacySign   = new SigningResource(this._http);       // Legacy file-upload signing
     this.certificates = new CertificateResource(this._http);
     this.pki          = new PkiResource(this._http);
     this.envelopes    = new EnvelopeResource(this._http);
+    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
 
     this.publicKey   = publicKey;
     this.environment = environment;
@@ -106,8 +131,8 @@ class CertySignClient {
    */
   static get BASE_URLS() {
     return {
-      production:  'https://api.certysign.com',
-      staging:     'https://api-staging.certysign.com',
+      production:  'https://core.certysign.io',
+      staging:     'https://service.certysign.io',
       development: 'http://localhost:8000',
       test:        'http://localhost:8000'
     };
@@ -157,5 +182,15 @@ class CertySignClient {
 
 module.exports = {
   CertySignClient,
-  CertySignError
+  CertySignError,
+  DocumentHasher,
+  SignatureEmbedder,
+  HashSigningResource,
+  SigningSessionResource,
+  DashboardResource,
+  // Legacy exports
+  SigningResource,
+  CertificateResource,
+  PkiResource,
+  EnvelopeResource
 };

package/src/lib/CertificateResource.js

@@ -26,9 +26,9 @@ class CertificateResource {
    *
    * The certificate is bound to the subscriber's organisation and the specific
    * document. It includes:
-   *  - CRL Distribution Point  → https://pki.certysign.com/crl/intermediate.crl
-   *  - OCSP AIA                → https://pki.certysign.com/ocsp
-   *  - CA Issuers AIA          → https://pki.certysign.com/certs/intermediate.crt
+   *  - CRL Distribution Point  → https://pki.certysign.io/crl/intermediate.crl
+   *  - OCSP AIA                → https://pki.certysign.io/ocsp
+   *  - CA Issuers AIA          → https://pki.certysign.io/certs/intermediate.crt
    *
    * The private key is returned ONCE in the response (PEM). CertySign does not
    * retain the private key after issuance.
@@ -122,6 +122,27 @@ class CertificateResource {
     if (!serialNumber) throw new Error('certificates.status: serialNumber is required');
     return this._http.get(`/sdk/v1/certificates/${encodeURIComponent(serialNumber)}/status`);
   }
+
+  // ── Active Certificate ─────────────────────────────────────────────────────
+
+  /**
+   * Get the tenant's active signing certificate.
+   * The certificate is resolved based on the API keys used for authentication.
+   *
+   * Returns the PEM certificate, chain, serial number, fingerprint,
+   * and validity information.
+   *
+   * @returns {Promise<Object>}
+   *
+   * @example
+   * const { data } = await client.certificates.getActive();
+   * console.log(data.certSerialNumber);
+   * console.log(data.certificate);   // PEM
+   * console.log(data.validUntil);
+   */
+  getActive() {
+    return this._http.get('/sdk/v1/certificates/active');
+  }
 }
 
 /**

package/src/lib/DashboardResource.js

@@ -0,0 +1,91 @@
+/**
+ * @fileoverview DashboardResource — SDK usage analytics
+ *
+ * Access dashboard statistics for your SDK-based signing operations:
+ *  - Documents signed (total, today, this month)
+ *  - Unique recipients across all signing sessions
+ *  - Success / failure rates
+ *  - Daily signing trends
+ *  - Signed document listing with recipient details
+ */
+
+'use strict';
+
+class DashboardResource {
+  /** @param {import('./HttpClient').HttpClient} http */
+  constructor(http) {
+    this._http = http;
+  }
+
+  /**
+   * Get aggregate statistics for SDK signing activity.
+   *
+   * @param {Object}  [options]
+   * @param {string}  [options.from]  - ISO date — start of range (default: 30 days ago)
+   * @param {string}  [options.to]    - ISO date — end of range (default: now)
+   * @returns {Promise<Object>}
+   *
+   * @example
+   * const { data } = await client.dashboard.getStats();
+   * console.log('Documents signed today:', data.documentsSignedToday);
+   * console.log('Unique recipients:', data.uniqueRecipientsCount);
+   * console.log('Success rate:', data.successRate + '%');
+   */
+  getStats(options = {}) {
+    const params = {};
+    if (options.from) params.from = options.from;
+    if (options.to)   params.to   = options.to;
+
+    return this._http.get('/sdk/v1/dashboard/stats', { params });
+  }
+
+  /**
+   * List unique recipients across all signing sessions.
+   *
+   * @param {Object}  [options]
+   * @param {number}  [options.page]    - Page number (default: 1)
+   * @param {number}  [options.limit]   - Results per page (default: 50)
+   * @param {string}  [options.search]  - Search by email or name
+   * @returns {Promise<Object>}
+   *
+   * @example
+   * const { data } = await client.dashboard.getRecipients({ search: 'ceo' });
+   * for (const r of data.recipients) {
+   *   console.log(`${r.email}: signed ${r.signedSessions} sessions`);
+   * }
+   */
+  getRecipients(options = {}) {
+    const params = {};
+    if (options.page)   params.page   = options.page;
+    if (options.limit)  params.limit  = options.limit;
+    if (options.search) params.search = options.search;
+
+    return this._http.get('/sdk/v1/dashboard/recipients', { params });
+  }
+
+  /**
+   * List documents across all signing sessions with signature details.
+   *
+   * @param {Object}  [options]
+   * @param {number}  [options.page]    - Page number (default: 1)
+   * @param {number}  [options.limit]   - Results per page (default: 20)
+   * @param {string}  [options.status]  - Filter by session status: 'active' | 'completed' | 'expired'
+   * @returns {Promise<Object>}
+   *
+   * @example
+   * const { data } = await client.dashboard.getDocuments({ status: 'completed' });
+   * for (const doc of data.documents) {
+   *   console.log(`${doc.fileName}: ${doc.signatureCount} signatures`);
+   * }
+   */
+  getDocuments(options = {}) {
+    const params = {};
+    if (options.page)   params.page   = options.page;
+    if (options.limit)  params.limit  = options.limit;
+    if (options.status) params.status = options.status;
+
+    return this._http.get('/sdk/v1/dashboard/documents', { params });
+  }
+}
+
+module.exports = { DashboardResource };

package/src/lib/DocumentHasher.js

@@ -0,0 +1,123 @@
+/**
+ * @fileoverview DocumentHasher — local document hashing
+ *
+ * Hashes documents on the subscriber's system so the raw document
+ * NEVER leaves their infrastructure. Only the hash is sent to CertySign.
+ *
+ * Supports: SHA-256, SHA-384, SHA-512
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+const fs     = require('fs');
+const path   = require('path');
+
+const SUPPORTED_ALGORITHMS = ['sha256', 'sha384', 'sha512'];
+
+class DocumentHasher {
+  /**
+   * @param {Object} [options]
+   * @param {string} [options.algorithm='sha256'] - Hash algorithm
+   */
+  constructor(options = {}) {
+    this.algorithm = (options.algorithm || 'sha256').toLowerCase();
+    if (!SUPPORTED_ALGORITHMS.includes(this.algorithm)) {
+      throw new Error(`Unsupported algorithm: ${this.algorithm}. Use: ${SUPPORTED_ALGORITHMS.join(', ')}`);
+    }
+  }
+
+  /**
+   * Hash a document from a Buffer or string.
+   *
+   * @param {Buffer|string} data - Document contents
+   * @param {string} [algorithm] - Override default algorithm
+   * @returns {{ hash: string, algorithm: string, size: number }}
+   *
+   * @example
+   * const hasher = new DocumentHasher();
+   * const result = hasher.hash(fs.readFileSync('./contract.pdf'));
+   * console.log(result.hash); // "a1b2c3..."
+   */
+  hash(data, algorithm) {
+    const algo = (algorithm || this.algorithm).toLowerCase();
+    if (!SUPPORTED_ALGORITHMS.includes(algo)) {
+      throw new Error(`Unsupported algorithm: ${algo}`);
+    }
+
+    const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+    const hash = crypto.createHash(algo).update(buf).digest('hex');
+
+    return { hash, algorithm: algo, size: buf.length };
+  }
+
+  /**
+   * Hash a document from a file path.
+   *
+   * Uses streaming to handle large files without loading the entire
+   * file into memory.
+   *
+   * @param {string} filePath - Absolute or relative file path
+   * @param {string} [algorithm] - Override default algorithm
+   * @returns {Promise<{ hash: string, algorithm: string, size: number, fileName: string }>}
+   *
+   * @example
+   * const hasher = new DocumentHasher();
+   * const result = await hasher.hashFile('./contract.pdf');
+   * console.log(result.hash);
+   * console.log(result.fileName); // "contract.pdf"
+   */
+  hashFile(filePath, algorithm) {
+    const algo = (algorithm || this.algorithm).toLowerCase();
+    if (!SUPPORTED_ALGORITHMS.includes(algo)) {
+      return Promise.reject(new Error(`Unsupported algorithm: ${algo}`));
+    }
+
+    return new Promise((resolve, reject) => {
+      const hash = crypto.createHash(algo);
+      let size = 0;
+
+      const stream = fs.createReadStream(filePath);
+      stream.on('data', (chunk) => {
+        hash.update(chunk);
+        size += chunk.length;
+      });
+      stream.on('end', () => {
+        resolve({
+          hash: hash.digest('hex'),
+          algorithm: algo,
+          size,
+          fileName: path.basename(filePath)
+        });
+      });
+      stream.on('error', reject);
+    });
+  }
+
+  /**
+   * Hash multiple documents (Buffers).
+   *
+   * @param {{ data: Buffer, fileName: string }[]} documents
+   * @param {string} [algorithm]
+   * @returns {{ hash: string, algorithm: string, size: number, fileName: string }[]}
+   */
+  hashMany(documents, algorithm) {
+    return documents.map(doc => {
+      const result = this.hash(doc.data, algorithm);
+      return { ...result, fileName: doc.fileName };
+    });
+  }
+
+  /**
+   * Hash multiple files by path.
+   *
+   * @param {string[]} filePaths
+   * @param {string} [algorithm]
+   * @returns {Promise<{ hash: string, algorithm: string, size: number, fileName: string }[]>}
+   */
+  hashFiles(filePaths, algorithm) {
+    return Promise.all(filePaths.map(fp => this.hashFile(fp, algorithm)));
+  }
+}
+
+module.exports = { DocumentHasher };

package/src/lib/HashSigningResource.js

@@ -0,0 +1,220 @@
+/**
+ * @fileoverview HashSigningResource — hash-based document signing
+ *
+ * Documents NEVER leave the subscriber's system.
+ * Flow: hash locally → send hash to CertySign → receive signature → embed locally.
+ *
+ * Covers:
+ *  - hashAndSign()       Hash a document and sign in one call
+ *  - signHash()          Sign a pre-computed hash
+ *  - batchHashAndSign()  Hash and sign multiple documents
+ *  - batchSignHashes()   Sign multiple pre-computed hashes
+ *  - verifyById()        Verify an envelope's signatures
+ */
+
+'use strict';
+
+const { DocumentHasher } = require('./DocumentHasher');
+
+class HashSigningResource {
+  /**
+   * @param {import('./HttpClient').HttpClient} http
+   */
+  constructor(http) {
+    this._http   = http;
+    this._hasher = new DocumentHasher();
+  }
+
+  // ── Hash + Sign (single document) ─────────────────────────────────────────
+
+  /**
+   * Hash a document locally and send the hash to CertySign for signing.
+   * The document never leaves your system.
+   *
+   * @param {HashAndSignOptions} options
+   * @returns {Promise<HashSignResult>}
+   *
+   * @example
+   * const result = await client.sign.hashAndSign({
+   *   document:  fs.readFileSync('./contract.pdf'),
+   *   fileName:  'contract.pdf',
+   *   reason:    'Contract approval',
+   *   location:  'Nairobi, Kenya'
+   * });
+   *
+   * console.log(result.data.signature);      // Base64 CMS/PKCS#7
+   * console.log(result.data.certificate);    // PEM certificate
+   * console.log(result.data.documentHash);   // SHA-256 hex
+   */
+  async hashAndSign(options) {
+    const {
+      document,
+      fileName   = 'document.pdf',
+      reason     = 'Digital signature',
+      location   = 'Nairobi, Kenya',
+      hashAlgorithm = 'sha256',
+      metadata   = {}
+    } = options;
+
+    if (!document) throw new Error('hashAndSign: document (Buffer) is required');
+
+    // Hash locally — document stays on subscriber system
+    const { hash } = this._hasher.hash(document, hashAlgorithm);
+
+    // Send only the hash to CertySign
+    return this._http.post('/sdk/v1/sign/hash', {
+      data: {
+        documentHash: hash,
+        hashAlgorithm,
+        fileName,
+        reason,
+        location,
+        metadata
+      }
+    });
+  }
+
+  // ── Sign pre-computed hash ─────────────────────────────────────────────────
+
+  /**
+   * Sign a pre-computed document hash.
+   * Use this when you've already computed the hash yourself.
+   *
+   * @param {SignHashOptions} options
+   * @returns {Promise<HashSignResult>}
+   *
+   * @example
+   * const hash = crypto.createHash('sha256').update(pdfBuffer).digest('hex');
+   * const result = await client.sign.signHash({
+   *   documentHash: hash,
+   *   hashAlgorithm: 'sha256',
+   *   fileName: 'invoice.pdf',
+   *   reason: 'Invoice approval'
+   * });
+   */
+  async signHash(options) {
+    const {
+      documentHash,
+      hashAlgorithm = 'sha256',
+      fileName,
+      reason  = 'Digital signature',
+      location = 'Nairobi, Kenya',
+      metadata = {}
+    } = options;
+
+    if (!documentHash) throw new Error('signHash: documentHash is required');
+
+    return this._http.post('/sdk/v1/sign/hash', {
+      data: { documentHash, hashAlgorithm, fileName, reason, location, metadata }
+    });
+  }
+
+  // ── Batch hash + sign ──────────────────────────────────────────────────────
+
+  /**
+   * Hash and sign multiple documents in one API call.
+   * All documents are hashed locally — none leave your system.
+   *
+   * @param {BatchHashAndSignOptions} options
+   * @returns {Promise<BatchHashSignResult>}
+   *
+   * @example
+   * const result = await client.sign.batchHashAndSign({
+   *   documents: [
+   *     { data: fs.readFileSync('./doc1.pdf'), fileName: 'doc1.pdf' },
+   *     { data: fs.readFileSync('./doc2.pdf'), fileName: 'doc2.pdf' }
+   *   ],
+   *   reason: 'Batch approval'
+   * });
+   */
+  async batchHashAndSign(options) {
+    const {
+      documents,
+      reason        = 'Batch digital signature',
+      hashAlgorithm = 'sha256',
+      metadata      = {}
+    } = options;
+
+    if (!documents?.length) throw new Error('batchHashAndSign: documents array is required');
+
+    // Hash all documents locally
+    const hashed = documents.map(doc => {
+      const { hash } = this._hasher.hash(doc.data, hashAlgorithm);
+      return {
+        documentHash: hash,
+        hashAlgorithm,
+        fileName: doc.fileName || 'document.pdf'
+      };
+    });
+
+    return this._http.post('/sdk/v1/sign/hash/batch', {
+      data: { documents: hashed, reason, metadata }
+    });
+  }
+
+  /**
+   * Sign multiple pre-computed hashes in one API call.
+   *
+   * @param {BatchSignHashesOptions} options
+   * @returns {Promise<BatchHashSignResult>}
+   */
+  async batchSignHashes(options) {
+    const { documents, reason = 'Batch digital signature', metadata = {} } = options;
+
+    if (!documents?.length) throw new Error('batchSignHashes: documents array is required');
+
+    return this._http.post('/sdk/v1/sign/hash/batch', {
+      data: { documents, reason, metadata }
+    });
+  }
+
+  // ── Verify ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Verify the signature of a previously signed envelope.
+   *
+   * @param {string} envelopeId
+   * @returns {Promise<Object>}
+   */
+  verifyById(envelopeId) {
+    if (!envelopeId) throw new Error('verifyById: envelopeId is required');
+    return this._http.get(`/sdk/v1/verify/${encodeURIComponent(envelopeId)}`);
+  }
+}
+
+/**
+ * @typedef {Object} HashAndSignOptions
+ * @property {Buffer}  document       - Document contents (stays local)
+ * @property {string}  [fileName]     - File name
+ * @property {string}  [reason]       - Signing reason
+ * @property {string}  [location]     - Signing location
+ * @property {string}  [hashAlgorithm] - sha256 | sha384 | sha512
+ * @property {Object}  [metadata]     - Custom key/value metadata
+ */
+
+/**
+ * @typedef {Object} SignHashOptions
+ * @property {string}  documentHash  - Hex-encoded hash
+ * @property {string}  [hashAlgorithm] - sha256 | sha384 | sha512
+ * @property {string}  [fileName]
+ * @property {string}  [reason]
+ * @property {string}  [location]
+ * @property {Object}  [metadata]
+ */
+
+/**
+ * @typedef {Object} BatchHashAndSignOptions
+ * @property {{ data: Buffer, fileName?: string }[]} documents
+ * @property {string}  [reason]
+ * @property {string}  [hashAlgorithm]
+ * @property {Object}  [metadata]
+ */
+
+/**
+ * @typedef {Object} BatchSignHashesOptions
+ * @property {{ documentHash: string, hashAlgorithm?: string, fileName?: string }[]} documents
+ * @property {string}  [reason]
+ * @property {Object}  [metadata]
+ */
+
+module.exports = { HashSigningResource };

package/src/lib/HttpClient.js

@@ -15,7 +15,7 @@ const FormData = require('form-data');
 const crypto = require('crypto');
 
 /** Default base URL — override per environment */
-const DEFAULT_BASE_URL = 'https://api.certysign.com';
+const DEFAULT_BASE_URL = 'https://core.certysign.io';
 
 /** Statuses that should trigger a retry */
 const RETRYABLE_STATUS = new Set([429, 502, 503, 504]);