@certysign/sdk 1.0.0

package/src/lib/PkiResource.js

@@ -0,0 +1,170 @@
+/**
+ * @fileoverview PkiResource — PKI infrastructure endpoints
+ *
+ * Covers:
+ *  - crl()   GET /sdk/v1/pki/crl      — X.509 v2 CRL (RFC 5280)
+ *  - ocsp()  GET /sdk/v1/pki/ocsp/:sn — OCSP response (RFC 6960)
+ *  - chain() GET /sdk/v1/pki/chain    — CA certificate chain (PEM bundle)
+ *  - info()  GET /sdk/v1/pki/info     — CA hierarchy metadata
+ *
+ * Typical use cases:
+ *  - Cache the CRL locally in HIE systems for offline revocation checking
+ *  - Perform in-process OCSP stapling
+ *  - Download CA chain to install in a local trust store
+ */
+
+'use strict';
+
+class PkiResource {
+  /** @param {import('../lib/HttpClient').HttpClient} http */
+  constructor(http) {
+    this._http = http;
+  }
+
+  // ── CRL ────────────────────────────────────────────────────────────────────
+
+  /**
+   * Download the current Certificate Revocation List from CertySign Intermediate CA.
+   *
+   * The CRL is an RFC 5280 X.509 v2 CRL, signed by the Intermediate CA.
+   *  - Valid for 7 days
+   *  - Issued every 24 hours
+   *  - Includes reasonCode per revoked certificate
+   *
+   * @param {'der'|'pem'|'json'} [format] - Response format (default: 'pem')
+   * @returns {Promise<Buffer|string|Object>}
+   *   - 'der'  → Buffer containing DER-encoded CRL binary
+   *   - 'pem'  → string with PEM-encoded CRL
+   *   - 'json' → structured JSON with revocation list
+   *
+   * @example
+   * // Download DER CRL and write to disk for caddy/nginx OCSP stapling cache
+   * const derBuf = await client.pki.crl('der');
+   * fs.writeFileSync('/etc/pki/certysign-intermediate.crl', derBuf);
+   *
+   * @example
+   * // Get JSON for application-level revocation checks
+   * const { data } = await client.pki.crl('json');
+   * const revokedSerials = new Set(data.crl.map(e => e.serialNumber));
+   * if (revokedSerials.has(myCertSn)) throw new Error('Certificate has been revoked');
+   */
+  async crl(format = 'pem') {
+    if (format === 'der') {
+      const response = await this._http.get('/sdk/v1/pki/crl', {
+        accept:       'application/pkix-crl',
+        responseType: 'arraybuffer'
+      });
+      return Buffer.isBuffer(response) ? response : Buffer.from(response);
+    }
+
+    if (format === 'pem') {
+      return this._http.get('/sdk/v1/pki/crl', {
+        accept:       'application/x-pem-file',
+        responseType: 'text'
+      });
+    }
+
+    // Default: JSON
+    return this._http.get('/sdk/v1/pki/crl');
+  }
+
+  // ── OCSP ───────────────────────────────────────────────────────────────────
+
+  /**
+   * Query the OCSP responder for a specific certificate.
+   *
+   * Returns an RFC 6960 BasicOCSPResponse — signed by CertySign Intermediate CA
+   * using SHA-256 with RSA. The CertID uses SHA-1 hashes as required by RFC 6960.
+   *
+   * @param {string} serialNumber  - Certificate serial number (hex string)
+   * @param {'der'|'json'} [format] - Response format (default: 'json')
+   * @returns {Promise<Buffer|OcspJsonResult>}
+   *
+   * @example
+   * // Check revocation status for a certificate
+   * const { data } = await client.pki.ocsp('A1B2C3D4E5F6...', 'json');
+   * console.log(data.status);          // 'good', 'revoked', or 'unknown'
+   * console.log(data.thisUpdate);      // ISO 8601
+   * console.log(data.nextUpdate);      // ISO 8601 — cache until this time
+   *
+   * @example
+   * // Get DER response for OCSP stapling
+   * const derBuf = await client.pki.ocsp('A1B2C3D4E5F6...', 'der');
+   */
+  async ocsp(serialNumber, format = 'json') {
+    if (!serialNumber) throw new Error('pki.ocsp: serialNumber is required');
+
+    if (format === 'der') {
+      const response = await this._http.get(`/sdk/v1/pki/ocsp/${encodeURIComponent(serialNumber)}`, {
+        accept:       'application/ocsp-response',
+        responseType: 'arraybuffer'
+      });
+      return Buffer.isBuffer(response) ? response : Buffer.from(response);
+    }
+
+    return this._http.get(`/sdk/v1/pki/ocsp/${encodeURIComponent(serialNumber)}`);
+  }
+
+  // ── CA Chain ───────────────────────────────────────────────────────────────
+
+  /**
+   * Download the CertySign CA certificate chain as a PEM bundle.
+   *
+   * The bundle contains (in order):
+   *  1. CertySign Intermediate CA certificate
+   *  2. CertySign Root CA certificate
+   *
+   * Install this bundle in your trust store to verify all certificates
+   * issued by CertySign.
+   *
+   * @returns {Promise<string>}  PEM-encoded certificate chain
+   *
+   * @example
+   * const chain = await client.pki.chain();
+   * fs.writeFileSync('/etc/ssl/certs/certysign-chain.pem', chain);
+   *
+   * // Verify a PEM cert against the chain (using openssl):
+   * // openssl verify -CAfile certysign-chain.pem your-cert.pem
+   */
+  chain() {
+    return this._http.get('/sdk/v1/pki/chain', {
+      accept:       'application/x-pem-file',
+      responseType: 'text'
+    });
+  }
+
+  // ── CA Info ────────────────────────────────────────────────────────────────
+
+  /**
+   * Get metadata about the CertySign CA hierarchy.
+   *
+   * Returns information about the Root CA and Intermediate CA including:
+   *  - Subject DN
+   *  - Validity period
+   *  - Key algorithm and size
+   *  - CRL and OCSP URLs
+   *  - Serial number
+   *
+   * @returns {Promise<CaInfoResult>}
+   *
+   * @example
+   * const { data } = await client.pki.info();
+   * console.log(data.intermediateCA.subject.commonName);
+   * console.log(data.intermediateCA.crlUrl);
+   * console.log(data.status.initialized);
+   */
+  info() {
+    return this._http.get('/sdk/v1/pki/info');
+  }
+}
+
+/**
+ * @typedef {Object} OcspJsonResult
+ * @property {boolean} success
+ * @property {{ status: 'good'|'revoked'|'unknown', serialNumber: string,
+ *              producedAt: string, thisUpdate: string, nextUpdate: string,
+ *              responderId: string, revocationDate: string|null,
+ *              revocationReason: string|null, der: string|null }} data
+ */
+
+module.exports = { PkiResource };

package/src/lib/SigningResource.js

@@ -0,0 +1,192 @@
+/**
+ * @fileoverview SigningResource — document signing operations
+ *
+ * Covers:
+ *  - quickSign()      POST /sdk/v1/sign
+ *  - batchSign()      POST /sdk/v1/sign/batch
+ *  - verifyById()     GET  /sdk/v1/verify/:envelopeId
+ *  - verifyDocument() POST /sdk/v1/verify
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const FormData = require('form-data');
+
+class SigningResource {
+  /** @param {import('../lib/HttpClient').HttpClient} http */
+  constructor(http) {
+    this._http = http;
+  }
+
+  // ── Quick Sign ─────────────────────────────────────────────────────────────
+
+  /**
+   * Sign a single document in one call.
+   *
+   * Uploads the document, creates an envelope, sends it, and signs it —
+   * all in a single API round-trip. Ideal for automation pipelines.
+   *
+   * @param {QuickSignOptions} options
+   * @returns {Promise<QuickSignResult>}
+   *
+   * @example
+   * const result = await client.sign.quickSign({
+   *   document: fs.readFileSync('./claim-form.pdf'),
+   *   filename: 'claim-form.pdf',
+   *   signerName:  'Dr. Amina Okonkwo',
+   *   signerEmail: 'amina.okonkwo@dha.go.ke',
+   *   reason:   'Health records approval — DHA Kenya',
+   *   location: 'Nairobi, Kenya',
+   *   metadata: { claimId: 'CLM-2026-003421', department: 'PHO' }
+   * });
+   *
+   * console.log(result.data.envelopeId);         // Track the signed envelope
+   * console.log(result.data.certificate.serialNumber); // Per-doc X.509 cert
+   */
+  async quickSign(options) {
+    const {
+      document,
+      filename   = 'document.pdf',
+      signerName,
+      signerEmail,
+      reason     = 'Digital signature',
+      location   = 'Nairobi, Kenya',
+      metadata   = {}
+    } = options;
+
+    if (!document)   throw new Error('quickSign: document (Buffer|ReadStream) is required');
+    if (!signerName) throw new Error('quickSign: signerName is required');
+
+    const form = new FormData();
+    _appendDocument(form, document, filename);
+    form.append('signerName',  signerName);
+    if (signerEmail) form.append('signerEmail', signerEmail);
+    form.append('reason',   reason);
+    form.append('location', location);
+    if (Object.keys(metadata).length) {
+      form.append('metadata', JSON.stringify(metadata));
+    }
+
+    return this._http.post('/sdk/v1/sign', { formData: form });
+  }
+
+  // ── Batch Sign ─────────────────────────────────────────────────────────────
+
+  /**
+   * Sign multiple documents in a single API call.
+   *
+   * Returns one result per document. Each document gets its own
+   * envelope and per-document X.509 certificate.
+   *
+   * @param {BatchSignOptions} options
+   * @returns {Promise<BatchSignResult>}
+   *
+   * @example
+   * const result = await client.sign.batchSign({
+   *   documents: [
+   *     { data: fs.readFileSync('./invoice-001.pdf'), filename: 'invoice-001.pdf' },
+   *     { data: fs.readFileSync('./invoice-002.pdf'), filename: 'invoice-002.pdf' }
+   *   ],
+   *   signerName:  'NHIF Finance System',
+   *   signerEmail: 'invoicing@nhif.or.ke',
+   *   reason:      'Batch invoice processing'
+   * });
+   */
+  async batchSign(options) {
+    const {
+      documents,
+      signerName,
+      signerEmail,
+      reason   = 'Batch digital signature',
+      location = 'Nairobi, Kenya',
+      metadata = {}
+    } = options;
+
+    if (!documents?.length) throw new Error('batchSign: documents array is required');
+    if (!signerName)        throw new Error('batchSign: signerName is required');
+
+    const form = new FormData();
+    for (const doc of documents) {
+      _appendDocument(form, doc.data, doc.filename || 'document.pdf');
+    }
+    form.append('signerName',  signerName);
+    if (signerEmail) form.append('signerEmail', signerEmail);
+    form.append('reason',   reason);
+    form.append('location', location);
+    if (Object.keys(metadata).length) {
+      form.append('metadata', JSON.stringify(metadata));
+    }
+
+    return this._http.post('/sdk/v1/sign/batch', { formData: form });
+  }
+
+  // ── Verify ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Verify the signature and certificate status of a previously signed envelope.
+   *
+   * @param {string} envelopeId
+   * @returns {Promise<VerifyResult>}
+   *
+   * @example
+   * const result = await client.sign.verifyById('env_abc123');
+   * if (result.data.valid) {
+   *   console.log('Signature verified:', result.data.signerName);
+   * }
+   */
+  verifyById(envelopeId) {
+    if (!envelopeId) throw new Error('verifyById: envelopeId is required');
+    return this._http.get(`/sdk/v1/verify/${encodeURIComponent(envelopeId)}`);
+  }
+
+  /**
+   * Verify a document by uploading it (checks embedded signature).
+   *
+   * @param {Buffer|ReadStream} document
+   * @param {string} [filename]
+   * @returns {Promise<VerifyResult>}
+   */
+  verifyDocument(document, filename = 'document.pdf') {
+    const form = new FormData();
+    _appendDocument(form, document, filename);
+    return this._http.post('/sdk/v1/verify', { formData: form });
+  }
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function _appendDocument(form, document, filename) {
+  if (Buffer.isBuffer(document)) {
+    form.append('document', document, { filename, contentType: 'application/pdf' });
+  } else if (document && typeof document.pipe === 'function') {
+    // ReadStream
+    form.append('document', document, { filename, contentType: 'application/pdf' });
+  } else {
+    throw new Error(`Document must be a Buffer or ReadStream, got ${typeof document}`);
+  }
+}
+
+/**
+ * @typedef {Object} QuickSignOptions
+ * @property {Buffer|import('fs').ReadStream} document  - PDF file contents
+ * @property {string}  [filename]     - Filename for storage (default: 'document.pdf')
+ * @property {string}  signerName     - Full name of the signer
+ * @property {string}  [signerEmail]  - Email address of the signer
+ * @property {string}  [reason]       - Reason for signing
+ * @property {string}  [location]     - Physical signing location
+ * @property {Object}  [metadata]     - Custom key/value metadata stored with the envelope
+ */
+
+/**
+ * @typedef {Object} BatchSignOptions
+ * @property {{ data: Buffer|import('fs').ReadStream, filename?: string }[]} documents
+ * @property {string}  signerName
+ * @property {string}  [signerEmail]
+ * @property {string}  [reason]
+ * @property {string}  [location]
+ * @property {Object}  [metadata]
+ */
+
+module.exports = { SigningResource };