@certysign/sdk 2.4.0 → 2.5.1

package/src/index.js

@@ -1,214 +1,372 @@
-/**
- * @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 { 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          — 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 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'
- * });
- *
- * // 1. Hash locally → sign remotely → embed locally
- * const result = await client.sign.hashAndSign({
- *   document: fs.readFileSync('./contract.pdf'),
- *   fileName: 'contract.pdf',
- *   reason:   'Contract approval'
- * });
- *
- * // 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 {
-  /**
-   * @param {ClientOptions} options
-   */
-  constructor(options = {}) {
-    const {
-      publicKey,
-      secretKey,
-      baseUrl,
-      environment = 'production',
-      timeout,
-      retries,
-      debug = false,
-      tsaUrl,
-    } = 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 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
-
-    // TSA URL: explicit > environment-derived
-    const resolvedTsaUrl = tsaUrl ?? CertySignClient.TSA_URLS[environment] ?? null;
-    this.embedder     = new SignatureEmbedder({ tsaUrl: resolvedTsaUrl }); // PAdES-T when TSA URL available
-
-    this.publicKey   = publicKey;
-    this.environment = environment;
-    this.baseUrl     = resolvedBaseUrl;
-    this.tsaUrl      = resolvedTsaUrl;
-  }
-
-  /**
-   * Environment → base URL mapping.
-   * Override any entry via the `baseUrl` constructor option.
-   */
-  static get BASE_URLS() {
-    return {
-      production:  'https://core.certysign.io',
-      staging:     'https://service.certysign.io',
-      development: 'http://localhost:8000',
-      test:        'http://localhost:8000'
-    };
-  }
-
-  /**
-   * Environment → TSA URL mapping.
-   * Override via the `tsaUrl` constructor option.
-   */
-  static get TSA_URLS() {
-    return {
-      production:  'https://tsa.certysign.io',
-      staging:     'https://tsa-staging.certysign.io',
-      development: 'http://localhost:5015',
-      test:        'http://localhost:5015'
-    };
-  }
-
-  /**
-   * 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,
-  DocumentHasher,
-  SignatureEmbedder,
-  HashSigningResource,
-  SigningSessionResource,
-  DashboardResource,
-  // Legacy exports
-  SigningResource,
-  CertificateResource,
-  PkiResource,
-  EnvelopeResource
-};
+/**
+ * @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 { 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 { IdentityResource }        = require('./lib/IdentityResource');
+const { BillingResource }         = require('./lib/BillingResource');
+const { SignerResource }          = require('./lib/SignerResource');
+const { WebhookResource }         = require('./lib/WebhookResource');
+const { DocumentHasher }          = require('./lib/DocumentHasher');
+const { SignatureEmbedder }       = require('./lib/SignatureEmbedder');
+
+/**
+ * CertySign API client.
+ *
+ * Resources are accessed as properties:
+ *  - 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 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'
+ * });
+ *
+ * // 1. Hash locally → sign remotely → embed locally
+ * const result = await client.sign.hashAndSign({
+ *   document: fs.readFileSync('./contract.pdf'),
+ *   fileName: 'contract.pdf',
+ *   reason:   'Contract approval'
+ * });
+ *
+ * // 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 {
+  /**
+   * @param {ClientOptions} options
+   */
+  constructor(options = {}) {
+    const {
+      publicKey,
+      secretKey,
+      baseUrl,
+      environment = 'production',
+      timeout,
+      retries,
+      debug = false,
+      tsaUrl,
+    } = 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 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.identity     = new IdentityResource(this._http);       // National-ID verification (IPRS)
+    this.billing      = new BillingResource(this._http);        // Balance, quotes, plan (read-only)
+    this.signers      = new SignerResource(this._http);         // Sponsor + check the people you sign for
+    this.webhooks     = new WebhookResource(this._http);        // Be told, instead of polling
+    this.hasher       = new DocumentHasher();                   // Local document hashing
+
+    // TSA URL: explicit > environment-derived
+    const resolvedTsaUrl = tsaUrl ?? CertySignClient.TSA_URLS[environment] ?? null;
+    this.embedder     = new SignatureEmbedder({ tsaUrl: resolvedTsaUrl }); // PAdES-T when TSA URL available
+
+    this.publicKey   = publicKey;
+    this.environment = environment;
+    this.baseUrl     = resolvedBaseUrl;
+    this.tsaUrl      = resolvedTsaUrl;
+  }
+
+  /**
+   * Environment → base URL mapping.
+   * Override any entry via the `baseUrl` constructor option.
+   */
+  static get BASE_URLS() {
+    return {
+      production:  'https://core.certysign.io',
+      staging:     'https://service.certysign.io',
+      development: 'http://localhost:8000',
+      test:        'http://localhost:8000'
+    };
+  }
+
+  /**
+   * Environment → TSA URL mapping.
+   * Override via the `tsaUrl` constructor option.
+   */
+  static get TSA_URLS() {
+    return {
+      production:  'https://tsa.certysign.io',
+      staging:     'https://tsa-staging.certysign.io',
+      development: 'http://localhost:5015',
+      test:        'http://localhost:5015'
+    };
+  }
+
+  /**
+   * Check that the API key works, as a startup health check.
+   *
+   * There is no dedicated identity endpoint, so this issues the cheapest
+   * authenticated call there is — GET /sdk/v1/pki/info — and reports whether it was
+   * accepted. A true `ok` means the credentials authenticated and the key holds
+   * `pki:info`; it does NOT prove any other scope is granted.
+   *
+   * It used to claim to return keyName, permissions and tenantId. /pki/info returns
+   * CA metadata and has never carried any of them, so every one of those fields came
+   * back undefined — a health check that silently reported nothing about the key it
+   * was supposed to be checking.
+   *
+   * @returns {Promise<{ ok: boolean, environment: string, caInitialized?: boolean, error?: string, code?: string }>}
+   *
+   * @example
+   * const res = await client.ping();
+   * if (!res.ok) throw new Error(`CertySign unreachable: ${res.error}`);
+   */
+  async ping() {
+    try {
+      const result = await this._http.get('/sdk/v1/pki/info');
+      const info = result?.data ?? result;
+      return {
+        ok: true,
+        environment: this.environment,
+        caInitialized: info?.initialized ?? info?.status?.initialized,
+      };
+    } catch (err) {
+      return { ok: false, environment: this.environment, error: err.message, code: err.code };
+    }
+  }
+
+  /**
+   * Call any CertySign endpoint, including ones this SDK version has no method for.
+   *
+   * This exists so the backend can ship an endpoint and you can use it the same
+   * day, without waiting for an SDK release. Everything a typed resource gives you
+   * still applies: authentication, retries, idempotency-conflict handling, the
+   * error shape and the User-Agent. The only thing you give up is the named
+   * method and its JSDoc.
+   *
+   * Prefer a typed resource where one exists — it documents the shape and will keep
+   * working if a path changes. Reach for this when there is no resource yet.
+   *
+   * @param {'GET'|'POST'|'PUT'|'PATCH'|'DELETE'} method
+   * @param {string} path                     e.g. '/sdk/v1/some-new-endpoint'
+   * @param {object} [options]
+   * @param {object} [options.data]           JSON body
+   * @param {object} [options.params]         query string
+   * @param {object} [options.headers]        extra headers
+   * @param {string} [options.idempotencyKey]
+   * @returns {Promise<any>} the parsed response body
+   *
+   * @example
+   * // An endpoint added to the API after this SDK was published:
+   * const res = await client.request('POST', '/sdk/v1/envelopes/bulk-void', {
+   *   data: { envelopeIds: ids, reason: 'duplicate batch' },
+   * });
+   */
+  request(method, path, options = {}) {
+    if (!method) throw new Error('client.request: method is required (GET, POST, PUT, PATCH, DELETE)');
+    if (!path)   throw new Error('client.request: path is required (e.g. "/sdk/v1/...")');
+    if (!String(path).startsWith('/')) {
+      throw new Error(`client.request: path must start with "/" — got "${path}"`);
+    }
+    return this._http.request(String(method).toUpperCase(), path, options);
+  }
+
+  /**
+   * Verify an incoming webhook delivery.
+   *
+   * Every integrator otherwise hand-writes this, and the two ways to get it wrong
+   * both fail silently rather than loudly:
+   *
+   *   - signing the body alone instead of `timestamp + "." + body`, which leaves a
+   *     captured delivery replayable forever; and
+   *   - verifying after `JSON.parse`, because re-serialising changes the bytes the
+   *     signature was computed over.
+   *
+   * So pass the RAW body: a Buffer or the original string, never a parsed object.
+   * With Express that means `express.raw({ type: 'application/json' })`, not
+   * `express.json()`.
+   *
+   * Comparison is timing-safe, and a delivery older than `toleranceSeconds` is
+   * rejected even when the signature is good.
+   *
+   * @param {object} opts
+   * @param {string} opts.secret                  the whsec_... shown once at creation
+   * @param {object} opts.headers                 the request headers (case-insensitive)
+   * @param {Buffer|string} opts.rawBody          the body exactly as received
+   * @param {number} [opts.toleranceSeconds=300]  reject deliveries older than this
+   * @returns {{ valid: boolean, reason?: string, event?: object }}
+   *          `event` is the parsed payload, present only when valid is true.
+   *
+   * @example
+   * app.post('/hooks', express.raw({ type: 'application/json' }), (req, res) => {
+   *   const { valid, reason, event } = CertySignClient.verifyWebhookSignature({
+   *     secret: process.env.CERTYSIGN_WEBHOOK_SECRET,
+   *     headers: req.headers,
+   *     rawBody: req.body,
+   *   });
+   *   if (!valid) return res.status(401).send(reason);
+   *
+   *   if (alreadyHandled(event.eventId)) return res.sendStatus(200);  // at-least-once
+   *   handle(event);
+   *   res.sendStatus(200);
+   * });
+   */
+  static verifyWebhookSignature({ secret, headers, rawBody, toleranceSeconds = 300 } = {}) {
+    const crypto = require('crypto');
+
+    if (!secret)  return { valid: false, reason: 'secret is required' };
+    if (!headers) return { valid: false, reason: 'headers are required' };
+    if (rawBody === undefined || rawBody === null) {
+      return { valid: false, reason: 'rawBody is required' };
+    }
+
+    // A parsed object means express.json() ran and the original bytes are gone.
+    // Say so plainly, because the signature would simply never match and the
+    // cause is not obvious from a bare "invalid signature".
+    if (typeof rawBody === 'object' && !Buffer.isBuffer(rawBody)) {
+      return {
+        valid: false,
+        reason: 'rawBody looks parsed, not raw. The signature covers the bytes as sent, '
+              + "so use express.raw({ type: 'application/json' }) and pass req.body "
+              + 'unmodified.',
+      };
+    }
+
+    // Headers arrive lower-cased from Node, but a framework may not.
+    const pick = (name) => {
+      const want = name.toLowerCase();
+      if (typeof headers.get === 'function') return headers.get(name) ?? undefined;
+      const hit = Object.keys(headers).find((k) => k.toLowerCase() === want);
+      return hit ? headers[hit] : undefined;
+    };
+
+    const timestamp = pick('X-CertySign-Timestamp');
+    const signature = String(pick('X-CertySign-Signature') || '').replace(/^sha256=/, '');
+
+    if (!timestamp) return { valid: false, reason: 'missing X-CertySign-Timestamp header' };
+    if (!signature) return { valid: false, reason: 'missing X-CertySign-Signature header' };
+
+    const ts = Number(timestamp);
+    if (!Number.isFinite(ts)) return { valid: false, reason: 'X-CertySign-Timestamp is not a number' };
+
+    if (toleranceSeconds > 0) {
+      const age = Math.abs(Date.now() / 1000 - ts);
+      if (age > toleranceSeconds) {
+        return { valid: false, reason: `delivery is ${Math.round(age)}s old, outside the ${toleranceSeconds}s tolerance` };
+      }
+    }
+
+    const body = Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(String(rawBody), 'utf8');
+    const expected = crypto
+      .createHmac('sha256', secret)
+      .update(Buffer.concat([Buffer.from(`${timestamp}.`, 'utf8'), body]))
+      .digest('hex');
+
+    // timingSafeEqual throws on a length mismatch, so compare digests of a fixed
+    // length rather than the raw hex.
+    const a = crypto.createHash('sha256').update(signature, 'utf8').digest();
+    const b = crypto.createHash('sha256').update(expected, 'utf8').digest();
+    if (!crypto.timingSafeEqual(a, b)) return { valid: false, reason: 'signature does not match' };
+
+    try {
+      return { valid: true, event: JSON.parse(body.toString('utf8')) };
+    } catch {
+      // Signature is good, so this came from us; the caller still gets the bytes.
+      return { valid: true, event: undefined, reason: 'signature valid but body is not JSON' };
+    }
+  }
+}
+
+/**
+ * @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,
+  DocumentHasher,
+  SignatureEmbedder,
+  HashSigningResource,
+  SigningSessionResource,
+  DashboardResource,
+  IdentityResource,
+  // Added in 2.5.0. Exported like every other resource so a caller can type-check
+  // or extend them; the client wires them up as client.signers / client.billing.
+  SignerResource,
+  BillingResource,
+  WebhookResource,
+  // Legacy exports
+  SigningResource,
+  CertificateResource,
+  PkiResource,
+  EnvelopeResource
+};