@certysign/sdk 1.0.0

package/examples/dha-integration.js

@@ -0,0 +1,208 @@
+/**
+ * DHA Kenya — Health Claims Quick-Sign Integration
+ *
+ * This example demonstrates the standard integration pattern for the
+ * Department of Health Affairs (DHA) Kenya claims processing system.
+ *
+ * Workflow:
+ *  1. Load a health claim PDF
+ *  2. Sign it using quickSign() — creates envelope, uploads, signs in one call
+ *  3. Issue a per-document X.509 certificate bound to the claim
+ *  4. Store the envelopeId and certificate serial number in the claims DB
+ *  5. Optionally verify the certificate via OCSP before archiving
+ *
+ * Prerequisites:
+ *   npm install @certysign/sdk
+ *   export CERTYSIGN_PUBLIC_KEY="cs_pk_..."
+ *   export CERTYSIGN_SECRET_KEY="cs_sk_..."
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { CertySignClient } = require('@certysign/sdk');
+
+// ── Initialise client ────────────────────────────────────────────────────────
+
+const client = new CertySignClient({
+  publicKey:   process.env.CERTYSIGN_PUBLIC_KEY,
+  secretKey:   process.env.CERTYSIGN_SECRET_KEY,
+  environment: 'production'                         // 'staging' for UAT
+});
+
+// ── Simulated DHA claim record ───────────────────────────────────────────────
+
+const claim = {
+  id:          'CLM-2026-003421',
+  patientName: 'John Kamau Njoroge',
+  facility:    'Kenyatta National Hospital',
+  approvedBy:  'Dr. Amina Okonkwo',
+  approverEmail: 'amina.okonkwo@dha.go.ke',
+  department:  'Primary Health Outreach',
+  amount:      45_000            // KES
+};
+
+// ── Main integration function ────────────────────────────────────────────────
+
+async function processClaim(claim) {
+  console.log(`\n[DHA] Processing claim ${claim.id} — ${claim.facility}`);
+  console.log('─'.repeat(60));
+
+  // Step 1: Load the generated claim PDF (your system produces this)
+  const pdfPath = path.join(__dirname, 'sample-claim.pdf');
+  let pdfBuffer;
+  try {
+    pdfBuffer = fs.readFileSync(pdfPath);
+  } catch {
+    // Create a minimal placeholder for demo purposes
+    pdfBuffer = Buffer.from('%PDF-1.4 sample claim document');
+    console.warn('[DHA] Using placeholder PDF — replace with real claim PDF in production');
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Step 2: Sign the claim document
+  // ─────────────────────────────────────────────────────────────────────────
+  console.log('\n[DHA] Signing claim document...');
+
+  const signResult = await client.sign.quickSign({
+    document:    pdfBuffer,
+    filename:    `claim-${claim.id}.pdf`,
+    signerName:  claim.approvedBy,
+    signerEmail: claim.approverEmail,
+    reason:      `Health claim approval — DHA Kenya (${claim.id})`,
+    location:    'Nairobi, Kenya',
+    metadata: {
+      claimId:    claim.id,
+      patientName: claim.patientName,
+      facility:   claim.facility,
+      department: claim.department,
+      amount:     claim.amount,
+      currency:   'KES',
+      system:     'DHA-CLAIMS-PROD'
+    }
+  });
+
+  const { envelopeId, certificate: sigCert } = signResult.data;
+  console.log(`[DHA] ✓ Document signed`);
+  console.log(`      envelopeId : ${envelopeId}`);
+  console.log(`      sigCert SN : ${sigCert?.serialNumber || '(embedded in PDF)'}`);
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Step 3: Issue a per-document X.509 certificate for the claim
+  // This cert is used by the HIE system to grant document access
+  // ─────────────────────────────────────────────────────────────────────────
+  console.log('\n[DHA] Issuing per-document X.509 certificate...');
+
+  const certResult = await client.certificates.issue({
+    commonName:   `DHA-${claim.id}`,
+    organisation: 'Department of Health Affairs Kenya',
+    country:      'KE',
+    state:        'Nairobi',
+    locality:     'Nairobi',
+    email:        claim.approverEmail,
+    validityDays: 365,
+    metadata: {
+      claimId:    claim.id,
+      envelopeId,
+      facility:   claim.facility,
+      issuedAt:   new Date().toISOString()
+    }
+  });
+
+  const cert = certResult.data;
+  console.log(`[DHA] ✓ Certificate issued`);
+  console.log(`      serialNumber : ${cert.serialNumber}`);
+  console.log(`      fingerprint  : ${cert.fingerprint}`);
+  console.log(`      validUntil   : ${cert.validUntil}`);
+  console.log(`      privateKey   : [SHOW ONCE — store securely]`);
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Step 4: Verify the certificate is good via OCSP
+  // (optional but recommended before archiving)
+  // ─────────────────────────────────────────────────────────────────────────
+  console.log('\n[DHA] Verifying certificate via OCSP...');
+
+  const ocspResult = await client.pki.ocsp(cert.serialNumber, 'json');
+  const ocspStatus = ocspResult.data;
+
+  console.log(`[DHA] OCSP status  : ${ocspStatus.status}`);
+  console.log(`      responderId  : ${ocspStatus.responderId}`);
+  console.log(`      nextUpdate   : ${ocspStatus.nextUpdate}`);
+
+  if (ocspStatus.status !== 'good') {
+    throw new Error(`[DHA] Unexpected OCSP status: ${ocspStatus.status}`);
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Step 5: Store claim record with signing proof
+  // ─────────────────────────────────────────────────────────────────────────
+  const claimRecord = {
+    claimId:           claim.id,
+    envelopeId,
+    certificateSerial: cert.serialNumber,
+    certificateExpiry: cert.validUntil,
+    signedAt:          new Date().toISOString(),
+    status:            'SIGNED',
+    // Store PEM cert for offline verification (NOT the private key in production DB)
+    pemCertificate:    cert.pemCertificate
+  };
+
+  console.log('\n[DHA] ✓ Claim processed successfully');
+  console.log('─'.repeat(60));
+  console.log('[DHA] Claim record:', JSON.stringify(claimRecord, null, 2));
+
+  return claimRecord;
+}
+
+// ── Retrieve and verify an archived claim ────────────────────────────────────
+
+async function verifyClaim(claimRecord) {
+  console.log(`\n[DHA] Verifying archived claim ${claimRecord.claimId}`);
+  console.log('─'.repeat(60));
+
+  // Check signing envelope still has valid signatures
+  const envelopeResult = await client.sign.verifyById(claimRecord.envelopeId);
+  const env = envelopeResult.data;
+
+  console.log(`[DHA] Envelope status   : ${env.status}`);
+  console.log(`[DHA] Signature valid   : ${env.valid}`);
+  console.log(`[DHA] Signed by         : ${env.signerName}`);
+  console.log(`[DHA] Signed at         : ${env.signedAt}`);
+
+  // Check certificate status
+  const certStatus = await client.certificates.status(claimRecord.certificateSerial);
+  console.log(`[DHA] Certificate status: ${certStatus.data.status}`);
+
+  // Point-in-time verification — was cert valid when signing happened?
+  const certAtTime = await client.certificates.verify(
+    claimRecord.certificateSerial,
+    claimRecord.signedAt
+  );
+  console.log(`[DHA] Cert valid-at-signing: ${certAtTime.data.valid}`);
+
+  return {
+    envelopeValid:    env.valid,
+    certificateStatus: certStatus.data.status,
+    certValidAtSigning: certAtTime.data.valid
+  };
+}
+
+// ── Run example ──────────────────────────────────────────────────────────────
+
+(async () => {
+  try {
+    const record = await processClaim(claim);
+    await verifyClaim(record);
+  } catch (err) {
+    if (err.code === 'INVALID_API_KEY') {
+      console.error('\n[DHA] Authentication failed — check CERTYSIGN_PUBLIC_KEY / CERTYSIGN_SECRET_KEY');
+    } else if (err.code === 'RATE_LIMIT_EXCEEDED') {
+      console.error('\n[DHA] Rate limit reached — implement request throttling');
+    } else {
+      console.error('\n[DHA] Error:', err.message);
+      if (err.details) console.error('[DHA] Details:', JSON.stringify(err.details, null, 2));
+    }
+    process.exit(1);
+  }
+})();

package/examples/nhif-batch-sign.js

@@ -0,0 +1,216 @@
+/**
+ * NHIF Kenya — Batch Invoice Signing Integration
+ *
+ * This example shows how NHIF's automated invoicing system uses batchSign()
+ * to sign hundreds of provider reimbursement invoices in a single API call
+ * during the nightly batch run.
+ *
+ * Workflow:
+ *  1. Collect pending invoices from the DB (up to 25 per API call)
+ *  2. Sign all documents in one batchSign() call
+ *  3. For each signed invoice: store envelopeId, certificate serial
+ *  4. Retrieve audit trails for compliance archiving
+ *  5. Download signed PDFs from the envelopes
+ *
+ * Rate limits:
+ *  The SDK automatically handles 429 responses with exponential back-off.
+ *  For very large batches, use the BATCH_SIZE constant to chunk requests.
+ *
+ * Prerequisites:
+ *   npm install @certysign/sdk
+ *   export CERTYSIGN_PUBLIC_KEY="cs_pk_..."
+ *   export CERTYSIGN_SECRET_KEY="cs_sk_..."
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const { CertySignClient, CertySignError } = require('@certysign/sdk');
+
+// ── Config ───────────────────────────────────────────────────────────────────
+
+const BATCH_SIZE = 10;          // Sign up to 10 invoices per API call (max 25)
+const SIGNER_NAME  = 'NHIF Finance System';
+const SIGNER_EMAIL = 'invoicing-batch@nhif.or.ke';
+
+const client = new CertySignClient({
+  publicKey:   process.env.CERTYSIGN_PUBLIC_KEY,
+  secretKey:   process.env.CERTYSIGN_SECRET_KEY,
+  environment: 'production'
+});
+
+// ── Simulated pending invoices ────────────────────────────────────────────────
+
+function getPendingInvoices() {
+  // In production: fetch from your DB
+  return [
+    { id: 'INV-2026-0441', provider: 'Aga Khan University Hospital', amount: 1_250_000 },
+    { id: 'INV-2026-0442', provider: 'Nairobi Hospital',             amount:   875_000 },
+    { id: 'INV-2026-0443', provider: 'Karen Hospital',               amount:   430_000 },
+    { id: 'INV-2026-0444', provider: 'MP Shah Hospital',             amount:   995_000 },
+    { id: 'INV-2026-0445', provider: 'Mater Hospital',               amount:   660_000 }
+  ];
+}
+
+function loadInvoicePdf(invoice) {
+  // In production: load from document store / generate from template
+  const filePath = path.join(__dirname, `invoice-${invoice.id}.pdf`);
+  if (fs.existsSync(filePath)) return fs.readFileSync(filePath);
+  // Placeholder for demo
+  return Buffer.from(`%PDF-1.4 NHIF Invoice ${invoice.id} — ${invoice.provider}`);
+}
+
+// ── Chunk array helper ────────────────────────────────────────────────────────
+
+function* chunks(arr, size) {
+  for (let i = 0; i < arr.length; i += size) {
+    yield arr.slice(i, i + size);
+  }
+}
+
+// ── Batch signing ─────────────────────────────────────────────────────────────
+
+async function runNightlyBatch() {
+  console.log('\n[NHIF] Starting nightly invoice signing batch');
+  console.log(`[NHIF] Timestamp: ${new Date().toISOString()}`);
+  console.log('─'.repeat(60));
+
+  const invoices = getPendingInvoices();
+  console.log(`[NHIF] ${invoices.length} invoices pending signature`);
+
+  const signedRecords = [];
+  const failedInvoices = [];
+  let batchNumber = 0;
+
+  for (const batch of chunks(invoices, BATCH_SIZE)) {
+    batchNumber++;
+    console.log(`\n[NHIF] Batch ${batchNumber} — signing ${batch.length} invoices...`);
+
+    // Build document list for this batch
+    const documents = batch.map(invoice => ({
+      data:     loadInvoicePdf(invoice),
+      filename: `nhif-invoice-${invoice.id}.pdf`
+    }));
+
+    try {
+      const result = await client.sign.batchSign({
+        documents,
+        signerName:  SIGNER_NAME,
+        signerEmail: SIGNER_EMAIL,
+        reason:      `NHIF provider reimbursement batch — ${new Date().toISOString().slice(0, 10)}`,
+        location:    'Nairobi, Kenya',
+        metadata: {
+          batchNumber:  batchNumber,
+          invoiceCount: batch.length,
+          system:       'NHIF-FINANCE-BATCH'
+        }
+      });
+
+      // Map results back to invoice records
+      const results = result.data.results;  // Array, one per document
+      for (let i = 0; i < batch.length; i++) {
+        const invoice = batch[i];
+        const res     = results[i];
+
+        if (res.success) {
+          signedRecords.push({
+            invoiceId:         invoice.id,
+            provider:          invoice.provider,
+            amount:            invoice.amount,
+            envelopeId:        res.envelopeId,
+            certificateSerial: res.certificate?.serialNumber,
+            signedAt:          new Date().toISOString(),
+            status:            'SIGNED'
+          });
+
+          console.log(`  ✓ ${invoice.id} → env: ${res.envelopeId}`);
+        } else {
+          failedInvoices.push({ invoice, reason: res.error });
+          console.warn(`  ✗ ${invoice.id} → ${res.error}`);
+        }
+      }
+
+    } catch (err) {
+      if (err instanceof CertySignError) {
+        console.error(`[NHIF] Batch ${batchNumber} API error (${err.statusCode}): ${err.message}`);
+        if (err.statusCode === 429) {
+          // Rate limited — wait and log (SDK already retried 3 times)
+          console.error('[NHIF] Rate limit exhausted — will retry this batch in next run');
+        }
+        batch.forEach(inv => failedInvoices.push({ invoice: inv, reason: err.message }));
+      } else {
+        throw err;
+      }
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Step 2: Retrieve audit trails for compliance
+  // ─────────────────────────────────────────────────────────────────────────
+  console.log(`\n[NHIF] Retrieving audit trails for ${signedRecords.length} signed invoices...`);
+
+  for (const record of signedRecords.slice(0, 3)) {  // Demo: first 3 only
+    try {
+      const auditResult = await client.envelopes.getAuditTrail(record.envelopeId);
+      const { auditTrail, chainIntegrity } = auditResult.data;
+
+      record.auditEntries    = auditTrail.length;
+      record.auditChainValid = chainIntegrity?.valid;
+
+      console.log(`  ✓ ${record.invoiceId}: ${auditTrail.length} events, chain=${chainIntegrity?.valid}`);
+    } catch (err) {
+      console.warn(`  ✗ Audit trail for ${record.invoiceId}: ${err.message}`);
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Step 3: Download first signed PDF as a demo
+  // ─────────────────────────────────────────────────────────────────────────
+  if (signedRecords.length > 0) {
+    const sample = signedRecords[0];
+    try {
+      console.log(`\n[NHIF] Downloading signed PDF for ${sample.invoiceId}...`);
+      // First get the envelope to find the document ID
+      const env = await client.envelopes.get(sample.envelopeId);
+      const docId = env.data?.envelope?.documents?.[0]?._id;
+
+      if (docId) {
+        const pdfBuffer = await client.envelopes.getDocument(sample.envelopeId, docId);
+        const outPath = path.join(__dirname, `signed-${sample.invoiceId}.pdf`);
+        fs.writeFileSync(outPath, pdfBuffer);
+        console.log(`[NHIF] ✓ Saved signed PDF to ${outPath} (${pdfBuffer.length} bytes)`);
+      }
+    } catch (err) {
+      console.warn(`[NHIF] Could not download signed PDF: ${err.message}`);
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Summary
+  // ─────────────────────────────────────────────────────────────────────────
+  console.log('\n' + '─'.repeat(60));
+  console.log(`[NHIF] Batch complete`);
+  console.log(`       Signed   : ${signedRecords.length}`);
+  console.log(`       Failed   : ${failedInvoices.length}`);
+
+  if (failedInvoices.length) {
+    console.log('[NHIF] Failed invoices:');
+    failedInvoices.forEach(({ invoice, reason }) => {
+      console.log(`  - ${invoice.id}: ${reason}`);
+    });
+  }
+
+  return { signed: signedRecords, failed: failedInvoices };
+}
+
+// ── Run ───────────────────────────────────────────────────────────────────────
+
+(async () => {
+  try {
+    await runNightlyBatch();
+  } catch (err) {
+    console.error('\n[NHIF] Fatal error:', err.message);
+    process.exit(1);
+  }
+})();

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@certysign/sdk",
+  "version": "1.0.0",
+  "description": "Official Node.js SDK for CertySign — digital signing, X.509 certificates, and PKI services",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "scripts": {
+    "test": "jest --coverage",
+    "lint": "eslint src/**/*.js",
+    "build:types": "npx tsc --emitDeclarationOnly"
+  },
+  "keywords": [
+    "certysign",
+    "digital-signature",
+    "pki",
+    "x509",
+    "pdf-signing",
+    "document-signing",
+    "kenya",
+    "pades"
+  ],
+  "author": "CertySign Limited <sdk@certysign.com>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "axios": "^1.6.0",
+    "form-data": "^4.0.0"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/certysign/sdk-node.git"
+  },
+  "homepage": "https://docs.certysign.com/sdk",
+  "bugs": {
+    "url": "https://github.com/certysign/sdk-node/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.js

@@ -0,0 +1,161 @@
+/**
+ * @fileoverview CertySign SDK for Node.js
+ *
+ * Official client library for CertySign Trust Services — digital document
+ * signing, X.509 certificate issuance, and PKI operations for East Africa.
+ *
+ * @example Basic setup
+ * ```js
+ * const { CertySignClient } = require('@certysign/sdk');
+ *
+ * const client = new CertySignClient({
+ *   publicKey: 'cs_pk_...',
+ *   secretKey: 'cs_sk_...'
+ * });
+ * ```
+ */
+
+'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');
+
+/**
+ * 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.pki           — PKI infrastructure (CRL, OCSP, CA chain, info)
+ *  - client.envelopes     — envelope management (create, upload, send, sign, audit)
+ *
+ * @example
+ * 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'
+ * });
+ *
+ * // 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'
+ * });
+ *
+ * console.log(result.data.envelopeId);
+ * console.log(result.data.certificate.serialNumber);
+ */
+class CertySignClient {
+  /**
+   * @param {ClientOptions} options
+   */
+  constructor(options = {}) {
+    const {
+      publicKey,
+      secretKey,
+      baseUrl,
+      environment = 'production',
+      timeout,
+      retries,
+      debug = false
+    } = options;
+
+    if (!publicKey) throw new Error('CertySignClient: publicKey is required');
+    if (!secretKey) throw new Error('CertySignClient: secretKey is required');
+
+    // Resolve base URL from environment if not explicitly provided
+    const resolvedBaseUrl = baseUrl ?? CertySignClient.BASE_URLS[environment];
+    if (!resolvedBaseUrl) {
+      throw new Error(
+        `CertySignClient: unknown environment "${environment}". ` +
+        `Expected one of: ${Object.keys(CertySignClient.BASE_URLS).join(', ')} ` +
+        `or provide baseUrl directly.`
+      );
+    }
+
+    this._http = new HttpClient({
+      publicKey,
+      secretKey,
+      baseUrl: resolvedBaseUrl,
+      timeout,
+      retries,
+      debug
+    });
+
+    // ── Resource objects ──
+    this.sign         = new SigningResource(this._http);
+    this.certificates = new CertificateResource(this._http);
+    this.pki          = new PkiResource(this._http);
+    this.envelopes    = new EnvelopeResource(this._http);
+
+    this.publicKey   = publicKey;
+    this.environment = environment;
+    this.baseUrl     = resolvedBaseUrl;
+  }
+
+  /**
+   * Environment → base URL mapping.
+   * Override any entry via the `baseUrl` constructor option.
+   */
+  static get BASE_URLS() {
+    return {
+      production:  'https://api.certysign.com',
+      staging:     'https://api-staging.certysign.com',
+      development: 'http://localhost:8000',
+      test:        'http://localhost:8000'
+    };
+  }
+
+  /**
+   * Verify that the API key is valid and return the key metadata.
+   * Useful as a "ping" / health check at startup.
+   *
+   * @returns {Promise<{ success: boolean, data: { keyName, permissions, environment, tenantId } }>}
+   *
+   * @example
+   * const { data } = await client.ping();
+   * console.log('Connected as:', data.keyName);
+   * console.log('Permissions:', data.permissions);
+   */
+  async ping() {
+    // Issue a lightweight request; GET /pki/info is cheap and requires pki:info
+    try {
+      const result = await this._http.get('/sdk/v1/pki/info');
+      return {
+        success: true,
+        data: {
+          keyName:      result.data?.keyName,
+          permissions:  result.data?.permissions,
+          environment:  result.data?.environment ?? this.environment,
+          tenantId:     result.data?.tenantId,
+          caInitialized: result.data?.status?.initialized
+        }
+      };
+    } catch (err) {
+      return { success: false, error: err.message, code: err.code };
+    }
+  }
+}
+
+/**
+ * @typedef {Object} ClientOptions
+ * @property {string}  publicKey              - API public key (cs_pk_...)
+ * @property {string}  secretKey              - API secret key (cs_sk_...)
+ * @property {'production'|'staging'|'development'|'test'} [environment] - Target environment (default: 'production')
+ * @property {string}  [baseUrl]              - Override the API base URL (e.g. for self-hosted)
+ * @property {number}  [timeout]              - Request timeout in ms (default: 30000)
+ * @property {number}  [retries]              - Max retries on transient errors (default: 3)
+ * @property {boolean} [debug]                - Log HTTP requests/responses (default: false)
+ */
+
+module.exports = {
+  CertySignClient,
+  CertySignError
+};