@certysign/sdk 1.0.0

package/src/lib/CertificateResource.js

@@ -0,0 +1,146 @@
+/**
+ * @fileoverview CertificateResource — X.509 certificate operations
+ *
+ * Covers:
+ *  - issue()   POST /sdk/v1/certificates/issue
+ *  - verify()  GET  /sdk/v1/certificates/:sn/verify
+ *  - status()  GET  /sdk/v1/certificates/:sn/status
+ *
+ * Per-document X.509 certificates are issued by CertySign Intermediate CA
+ * and include CRL Distribution Points and OCSP AIA extensions for
+ * programmatic revocation checking by relying parties (e.g. HIEs).
+ */
+
+'use strict';
+
+class CertificateResource {
+  /** @param {import('../lib/HttpClient').HttpClient} http */
+  constructor(http) {
+    this._http = http;
+  }
+
+  // ── Issue ──────────────────────────────────────────────────────────────────
+
+  /**
+   * Issue a per-document X.509 certificate signed by CertySign Intermediate CA.
+   *
+   * 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
+   *
+   * The private key is returned ONCE in the response (PEM). CertySign does not
+   * retain the private key after issuance.
+   *
+   * @param {IssueCertificateOptions} options
+   * @returns {Promise<IssueCertificateResult>}
+   *
+   * @example
+   * const cert = await client.certificates.issue({
+   *   commonName:   'DHA Kenya Claims System',
+   *   organisation: 'Department of Health Affairs',
+   *   country:      'KE',
+   *   locality:     'Nairobi',
+   *   email:        'pki@dha.go.ke',
+   *   validityDays: 365,
+   *   metadata:     { systemId: 'DHA-CLAIMS-PROD', claimId: 'CLM-2026-003421' }
+   * });
+   *
+   * // cert.data.serialNumber   — store this for future status checks
+   * // cert.data.pemCertificate — PEM cert to embed in signed PDF
+   * // cert.data.privateKey     — PEM private key (shown ONCE)
+   * // cert.data.validUntil     — ISO 8601 expiry
+   */
+  issue(options) {
+    const {
+      commonName,
+      organisation,
+      country       = 'KE',
+      state         = 'Nairobi',
+      locality      = 'Nairobi',
+      email,
+      validityDays  = 365,
+      keySize       = 2048,
+      metadata      = {}
+    } = options || {};
+
+    if (!commonName)   throw new Error('certificates.issue: commonName is required');
+    if (!organisation) throw new Error('certificates.issue: organisation is required');
+
+    return this._http.post('/sdk/v1/certificates/issue', {
+      data: { commonName, organisation, country, state, locality, email, validityDays, keySize, metadata }
+    });
+  }
+
+  // ── Verify ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Verify a certificate's validity at a specific point in time.
+   *
+   * Checks:
+   *  - Certificate chain back to CertySign Root CA
+   *  - Revocation status (CRL + OCSP)
+   *  - Validity period
+   *  - Key usage constraints
+   *
+   * @param {string} serialNumber - Certificate serial number (hex)
+   * @param {Date|string} [atTime] - Point-in-time check (default: now)
+   * @returns {Promise<VerifyCertResult>}
+   *
+   * @example
+   * // Verify if a cert was valid at the time the document was signed
+   * const result = await client.certificates.verify(
+   *   'A1B2C3D4E5F6...',
+   *   new Date('2026-01-15T10:30:00Z')
+   * );
+   * if (result.data.valid) console.log('Certificate was valid at signing time');
+   */
+  verify(serialNumber, atTime) {
+    if (!serialNumber) throw new Error('certificates.verify: serialNumber is required');
+    const params = atTime
+      ? { atTime: (atTime instanceof Date ? atTime.toISOString() : atTime) }
+      : undefined;
+    return this._http.get(`/sdk/v1/certificates/${encodeURIComponent(serialNumber)}/verify`, { params });
+  }
+
+  // ── Status ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Get the current status of a certificate (good / revoked / expired / unknown).
+   *
+   * @param {string} serialNumber
+   * @returns {Promise<CertStatusResult>}
+   *
+   * @example
+   * const { data } = await client.certificates.status('A1B2C3...');
+   * // data.status        → 'good' | 'revoked' | 'expired' | 'unknown'
+   * // data.revocationDate → ISO 8601 if revoked
+   * // data.revocationReason → RFC 5280 reason string if revoked
+   */
+  status(serialNumber) {
+    if (!serialNumber) throw new Error('certificates.status: serialNumber is required');
+    return this._http.get(`/sdk/v1/certificates/${encodeURIComponent(serialNumber)}/status`);
+  }
+}
+
+/**
+ * @typedef {Object} IssueCertificateOptions
+ * @property {string} commonName       - Subject CN (e.g. 'DHA Kenya Claims System')
+ * @property {string} organisation     - Subject O (e.g. 'Department of Health Affairs')
+ * @property {string} [country]        - ISO 3166 alpha-2 (default: 'KE')
+ * @property {string} [state]          - State/province (default: 'Nairobi')
+ * @property {string} [locality]       - City (default: 'Nairobi')
+ * @property {string} [email]          - Subscriber email address
+ * @property {number} [validityDays]   - Cert validity in days (default: 365)
+ * @property {number} [keySize]        - RSA key size in bits (default: 2048)
+ * @property {Object} [metadata]       - Custom metadata stored with the cert record
+ */
+
+/**
+ * @typedef {Object} IssueCertificateResult
+ * @property {boolean} success
+ * @property {{ serialNumber, fingerprint, validFrom, validUntil, pemCertificate, pemChain, privateKey }} data
+ */
+
+module.exports = { CertificateResource };

package/src/lib/EnvelopeResource.js

@@ -0,0 +1,249 @@
+/**
+ * @fileoverview EnvelopeResource — full envelope lifecycle management
+ *
+ * Covers the complete envelope CRUD plus document management:
+ *  - create()          POST /sdk/v1/envelopes
+ *  - get()             GET  /sdk/v1/envelopes/:id
+ *  - list()            GET  /sdk/v1/envelopes
+ *  - uploadDocuments() POST /sdk/v1/envelopes/:id/documents
+ *  - send()            POST /sdk/v1/envelopes/:id/send
+ *  - sign()            POST /sdk/v1/envelopes/:id/sign
+ *  - getDocument()     GET  /sdk/v1/envelopes/:id/documents/:docId
+ *  - getAuditTrail()   GET  /sdk/v1/envelopes/:id/audit
+ */
+
+'use strict';
+
+const FormData = require('form-data');
+
+class EnvelopeResource {
+  /** @param {import('../lib/HttpClient').HttpClient} http */
+  constructor(http) {
+    this._http = http;
+  }
+
+  // ── Create ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Create a new signing envelope.
+   *
+   * Envelopes are containers for documents and signature requests.
+   * After creation, upload documents (uploadDocuments), then send
+   * the envelope (send) to make it ready for signing.
+   *
+   * @param {CreateEnvelopeOptions} options
+   * @returns {Promise<EnvelopeResult>}
+   *
+   * @example
+   * const { data } = await client.envelopes.create({
+   *   title:       'NHIF Reimbursement Claim Q1-2026',
+   *   signers: [{
+   *     name:  'Dr. Grace Mwangi',
+   *     email: 'g.mwangi@nhif.or.ke',
+   *     role:  'primary'
+   *   }],
+   *   metadata: { claimPeriod: 'Q1-2026', department: 'Reimbursements' }
+   * });
+   * const envelopeId = data.envelope._id;
+   */
+  create(options = {}) {
+    const { title, signers = [], message, metadata = {} } = options;
+    if (!title) throw new Error('envelopes.create: title is required');
+    return this._http.post('/sdk/v1/envelopes', {
+      data: { title, signers, message, metadata }
+    });
+  }
+
+  // ── Get ────────────────────────────────────────────────────────────────────
+
+  /**
+   * Get a single envelope by ID with full status, signers, and document list.
+   *
+   * @param {string} envelopeId
+   * @returns {Promise<EnvelopeResult>}
+   */
+  get(envelopeId) {
+    if (!envelopeId) throw new Error('envelopes.get: envelopeId is required');
+    return this._http.get(`/sdk/v1/envelopes/${encodeURIComponent(envelopeId)}`);
+  }
+
+  // ── List ───────────────────────────────────────────────────────────────────
+
+  /**
+   * List envelopes for the authenticated tenant.
+   *
+   * @param {ListEnvelopesOptions} [options]
+   * @returns {Promise<ListEnvelopesResult>}
+   *
+   * @example
+   * const { data } = await client.envelopes.list({ status: 'completed', limit: 20 });
+   * data.envelopes.forEach(env => console.log(env._id, env.status));
+   */
+  list(options = {}) {
+    const { status, page = 1, limit = 20, search } = options;
+    return this._http.get('/sdk/v1/envelopes', {
+      params: { status, page, limit, search }
+    });
+  }
+
+  // ── Upload Documents ───────────────────────────────────────────────────────
+
+  /**
+   * Upload one or more PDF documents to an existing envelope.
+   *
+   * Must be called after create() and before send().
+   *
+   * @param {string}   envelopeId
+   * @param {DocumentUpload[]} documents
+   * @returns {Promise<UploadResult>}
+   *
+   * @example
+   * await client.envelopes.uploadDocuments('env_abc123', [
+   *   { data: fs.readFileSync('./report.pdf'), filename: 'Q1-report.pdf' }
+   * ]);
+   */
+  uploadDocuments(envelopeId, documents) {
+    if (!envelopeId)        throw new Error('envelopes.uploadDocuments: envelopeId is required');
+    if (!documents?.length) throw new Error('envelopes.uploadDocuments: documents array is required');
+
+    const form = new FormData();
+    for (const doc of documents) {
+      const buf = doc.data;
+      const name = doc.filename || 'document.pdf';
+      if (Buffer.isBuffer(buf)) {
+        form.append('documents', buf, { filename: name, contentType: 'application/pdf' });
+      } else if (buf && typeof buf.pipe === 'function') {
+        form.append('documents', buf, { filename: name, contentType: 'application/pdf' });
+      } else {
+        throw new Error(`Document "${name}" must be a Buffer or ReadStream`);
+      }
+    }
+
+    return this._http.post(`/sdk/v1/envelopes/${encodeURIComponent(envelopeId)}/documents`, {
+      formData: form
+    });
+  }
+
+  // ── Send ───────────────────────────────────────────────────────────────────
+
+  /**
+   * Transition an envelope to 'sent' status, making it ready for signing.
+   *
+   * @param {string} envelopeId
+   * @returns {Promise<EnvelopeResult>}
+   */
+  send(envelopeId) {
+    if (!envelopeId) throw new Error('envelopes.send: envelopeId is required');
+    return this._http.post(`/sdk/v1/envelopes/${encodeURIComponent(envelopeId)}/send`);
+  }
+
+  // ── Sign ───────────────────────────────────────────────────────────────────
+
+  /**
+   * Apply a cryptographic signature to all documents in the envelope.
+   *
+   * This is the core signing step. For SDK requests, interactive 2FA is
+   * bypassed — the API key alone authorises the signature.
+   *
+   * The resulting signatures are PAdES-LTV compliant (PDF Advanced Electronic
+   * Signatures with Long-Term Validation).
+   *
+   * @param {string} envelopeId
+   * @param {SignEnvelopeOptions} [options]
+   * @returns {Promise<SignResult>}
+   *
+   * @example
+   * const result = await client.envelopes.sign('env_abc123', {
+   *   reason:   'Claims approval — NHIF Kenya',
+   *   location: 'Nairobi, Kenya'
+   * });
+   * console.log(result.data.signatures[0].certificate.serialNumber);
+   */
+  sign(envelopeId, options = {}) {
+    if (!envelopeId) throw new Error('envelopes.sign: envelopeId is required');
+    const { reason = 'Digital signature', location = 'Nairobi, Kenya' } = options;
+    return this._http.post(`/sdk/v1/envelopes/${encodeURIComponent(envelopeId)}/sign`, {
+      data: { reason, location }
+    });
+  }
+
+  // ── Download Document ──────────────────────────────────────────────────────
+
+  /**
+   * Download a signed document as a Buffer.
+   *
+   * @param {string} envelopeId
+   * @param {string} documentId
+   * @returns {Promise<Buffer>}  Raw PDF bytes
+   *
+   * @example
+   * const pdfBuffer = await client.envelopes.getDocument('env_abc123', 'doc_xyz789');
+   * fs.writeFileSync('./signed-claim.pdf', pdfBuffer);
+   */
+  async getDocument(envelopeId, documentId) {
+    if (!envelopeId)  throw new Error('envelopes.getDocument: envelopeId is required');
+    if (!documentId)  throw new Error('envelopes.getDocument: documentId is required');
+
+    const response = await this._http.get(
+      `/sdk/v1/envelopes/${encodeURIComponent(envelopeId)}/documents/${encodeURIComponent(documentId)}`,
+      { responseType: 'arraybuffer' }
+    );
+    return Buffer.isBuffer(response) ? response : Buffer.from(response);
+  }
+
+  // ── Audit Trail ────────────────────────────────────────────────────────────
+
+  /**
+   * Retrieve the cryptographically verifiable audit trail for an envelope.
+   *
+   * The audit chain is a Merkle-linked log of all envelope events:
+   *  - created, document_uploaded, sent, signed, certificate_issued, completed
+   *
+   * Each entry includes a SHA-256 event hash and chain hash linking it to
+   * the previous entry, making the log tamper-evident.
+   *
+   * @param {string} envelopeId
+   * @returns {Promise<AuditTrailResult>}
+   *
+   * @example
+   * const { data } = await client.envelopes.getAuditTrail('env_abc123');
+   * data.auditTrail.forEach(event => {
+   *   console.log(event.timestamp, event.action, event.eventHash);
+   * });
+   * if (data.chainIntegrity.valid) console.log('Audit chain intact');
+   */
+  getAuditTrail(envelopeId) {
+    if (!envelopeId) throw new Error('envelopes.getAuditTrail: envelopeId is required');
+    return this._http.get(`/sdk/v1/envelopes/${encodeURIComponent(envelopeId)}/audit`);
+  }
+}
+
+/**
+ * @typedef {Object} CreateEnvelopeOptions
+ * @property {string}   title       - Envelope title
+ * @property {{ name: string, email?: string, role?: string }[]} [signers]
+ * @property {string}   [message]   - Message to signers
+ * @property {Object}   [metadata]
+ */
+
+/**
+ * @typedef {Object} DocumentUpload
+ * @property {Buffer|import('fs').ReadStream} data
+ * @property {string} [filename]
+ */
+
+/**
+ * @typedef {Object} SignEnvelopeOptions
+ * @property {string} [reason]
+ * @property {string} [location]
+ */
+
+/**
+ * @typedef {Object} ListEnvelopesOptions
+ * @property {'draft'|'sent'|'in_progress'|'completed'|'cancelled'} [status]
+ * @property {number} [page]
+ * @property {number} [limit]
+ * @property {string} [search]
+ */
+
+module.exports = { EnvelopeResource };

package/src/lib/HttpClient.js

@@ -0,0 +1,198 @@
+/**
+ * @fileoverview CertySign SDK — HTTP client layer
+ *
+ * Wraps axios with:
+ *  - Automatic API key header injection
+ *  - Idempotency key support
+ *  - Retry with exponential back-off (network errors, 429, 503)
+ *  - Consistent error normalisation
+ */
+
+'use strict';
+
+const axios = require('axios');
+const FormData = require('form-data');
+const crypto = require('crypto');
+
+/** Default base URL — override per environment */
+const DEFAULT_BASE_URL = 'https://api.certysign.com';
+
+/** Statuses that should trigger a retry */
+const RETRYABLE_STATUS = new Set([429, 502, 503, 504]);
+
+/**
+ * @typedef {Object} HttpClientOptions
+ * @property {string}  publicKey   - API public key  (cs_pk_...)
+ * @property {string}  secretKey   - API secret key  (cs_sk_...)
+ * @property {string}  [baseUrl]   - Override default gateway URL
+ * @property {number}  [timeout]   - Request timeout ms (default 30000)
+ * @property {number}  [retries]   - Max retries on transient errors (default 3)
+ * @property {boolean} [debug]     - Log requests/responses
+ */
+
+class HttpClient {
+  /**
+   * @param {HttpClientOptions} options
+   */
+  constructor(options) {
+    if (!options.publicKey)  throw new Error('CertySign SDK: publicKey is required');
+    if (!options.secretKey)  throw new Error('CertySign SDK: secretKey is required');
+
+    this.publicKey = options.publicKey;
+    this.secretKey = options.secretKey;
+    this.baseUrl   = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, '');
+    this.timeout   = options.timeout ?? 30_000;
+    this.retries   = options.retries ?? 3;
+    this.debug     = options.debug   ?? false;
+
+    this._client = axios.create({
+      baseURL: this.baseUrl,
+      timeout: this.timeout,
+      headers: {
+        'Content-Type': 'application/json',
+        'Accept':       'application/json',
+        'User-Agent':   `CertySign-SDK-Node/1.0.0 Node/${process.version}`
+      }
+    });
+  }
+
+  // ── Core request execution ───────────────────────────────────────────────
+
+  /**
+   * Execute an HTTP request with retry logic.
+   *
+   * @param {string} method      - HTTP verb (GET, POST, PUT, DELETE, PATCH)
+   * @param {string} path        - Path relative to baseUrl
+   * @param {Object} [options]
+   * @param {Object} [options.data]             - JSON body
+   * @param {Object} [options.params]           - Query params
+   * @param {Object} [options.headers]          - Extra headers
+   * @param {FormData} [options.formData]       - Multipart form (takes precedence over data)
+   * @param {string}  [options.idempotencyKey]  - Idempotency key (auto-generated if omitted)
+   * @param {string}  [options.accept]          - Override Accept header
+   * @param {'json'|'arraybuffer'|'text'} [options.responseType] - Expected response type
+   * @returns {Promise<any>}
+   */
+  async request(method, path, options = {}) {
+    const {
+      data,
+      params,
+      headers: extraHeaders = {},
+      formData,
+      idempotencyKey,
+      accept,
+      responseType = 'json'
+    } = options;
+
+    const idempKey = idempotencyKey || `sdk_${crypto.randomBytes(16).toString('hex')}`;
+
+    const headers = {
+      'X-API-Key-Id':      this.publicKey,
+      'X-API-Key-Secret':  this.secretKey,
+      'X-Idempotency-Key': idempKey,
+      ...extraHeaders
+    };
+
+    if (accept) headers['Accept'] = accept;
+
+    const config = {
+      method,
+      url: path,
+      headers,
+      params,
+      responseType
+    };
+
+    if (formData) {
+      config.data    = formData;
+      config.headers = { ...config.headers, ...formData.getHeaders() };
+      delete config.headers['Content-Type']; // Let axios set multipart boundary
+    } else if (data !== undefined) {
+      config.data = data;
+    }
+
+    let attempt = 0;
+
+    while (true) {                          // eslint-disable-line no-constant-condition
+      attempt++;
+
+      if (this.debug) {
+        console.debug(`[CertySign SDK] ${method.toUpperCase()} ${path} (attempt ${attempt})`);
+      }
+
+      try {
+        const response = await this._client.request(config);
+        return response.data;
+
+      } catch (err) {
+        const status  = err.response?.status;
+        const canRetry = RETRYABLE_STATUS.has(status) || !status; // network error
+
+        if (canRetry && attempt <= this.retries) {
+          const delay = Math.min(200 * 2 ** (attempt - 1), 4000);
+          if (this.debug) console.debug(`[CertySign SDK] Retrying in ${delay}ms (status=${status})`);
+          await _sleep(delay);
+          continue;
+        }
+
+        throw _normaliseError(err);
+      }
+    }
+  }
+
+  get(path, options)          { return this.request('GET',    path, options); }
+  post(path, options)         { return this.request('POST',   path, options); }
+  put(path, options)          { return this.request('PUT',    path, options); }
+  patch(path, options)        { return this.request('PATCH',  path, options); }
+  delete(path, options)       { return this.request('DELETE', path, options); }
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function _sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Normalise an axios error into a plain CertySignError.
+ * @param {Error} err
+ * @returns {CertySignError}
+ */
+function _normaliseError(err) {
+  if (err.response) {
+    const body = err.response.data;
+    const e = new CertySignError(
+      body?.message || `HTTP ${err.response.status}`,
+      err.response.status,
+      body?.code
+    );
+    e.details = body;
+    e.headers = err.response.headers;
+    return e;
+  }
+
+  if (err.request) {
+    return new CertySignError(`No response received: ${err.message}`, 0, 'NETWORK_ERROR');
+  }
+
+  return new CertySignError(err.message, 0, 'SDK_INTERNAL_ERROR');
+}
+
+/**
+ * Error class thrown by all SDK methods on failure.
+ *
+ * @property {number} statusCode  - HTTP status code (0 for network errors)
+ * @property {string} code        - Machine-readable error code (e.g. 'INVALID_API_KEY')
+ * @property {Object} details     - Full error body from the API
+ */
+class CertySignError extends Error {
+  constructor(message, statusCode, code) {
+    super(message);
+    this.name       = 'CertySignError';
+    this.statusCode = statusCode;
+    this.code       = code;
+    this.details    = null;
+  }
+}
+
+module.exports = { HttpClient, CertySignError };