@certysign/sdk 2.4.0 → 2.5.0

package/src/lib/HashSigningResource.js

@@ -105,13 +105,20 @@ class HashSigningResource {
       location = 'Nairobi, Kenya',
       signerName,
       signerEmail,
-      metadata = {}
+      metadata = {},
+      // Second factor. Single-document signing challenges the named signer: the
+      // first call returns 2FA_REQUIRED with a verificationNonce and sends them a
+      // code; re-send the same request carrying both. Batch signing is exempt.
+      twoFactorCode,
+      twoFactorMethod,
+      verificationNonce
     } = options;
 
     if (!documentHash) throw new Error('signHash: documentHash is required');
 
     return this._http.post('/sdk/v1/sign/hash', {
-      data: { documentHash, hashAlgorithm, fileName, reason, location, signerName, signerEmail, metadata }
+      data: { documentHash, hashAlgorithm, fileName, reason, location, signerName, signerEmail, metadata,
+        twoFactorCode, twoFactorMethod, verificationNonce }
     });
   }
 

package/src/lib/HttpClient.js

@@ -1,198 +1,211 @@
-/**
- * @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://core.certysign.io';
-
-/** 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 };
+/**
+ * @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://core.certysign.io';
+
+/** 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 code    = err.response?.data?.code;
+
+        // A 409 usually means "your request conflicts with reality" and retrying is
+        // pointless. IDEMPOTENCY_IN_PROGRESS is the exception: an identical request
+        // with this same key is mid-flight, and the right move is to wait for it
+        // rather than fail. Retrying is safe precisely BECAUSE the key is the same —
+        // the server will hand back that request's result, not run a second one.
+        const waitingOnTwin = status === 409 && code === 'IDEMPOTENCY_IN_PROGRESS';
+
+        const canRetry = RETRYABLE_STATUS.has(status) || waitingOnTwin || !status;
+
+        if (canRetry && attempt <= this.retries) {
+          // Honour Retry-After when the server states one, rather than guessing.
+          const retryAfter = Number(err.response?.headers?.['retry-after']);
+          const delay = Number.isFinite(retryAfter) && retryAfter > 0
+            ? Math.min(retryAfter * 1000, 10000)
+            : 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 };

package/src/lib/IdentityResource.js

@@ -0,0 +1,143 @@
+/**
+ * @fileoverview IdentityResource — Identity-as-a-Service
+ *
+ * Verify a national ID against the issuing authority (IPRS for Kenya) and get
+ * the biographic record back — the same pipeline CertySign uses to onboard its
+ * own signers.
+ *
+ * Registry-first: an ID already verified anywhere on the CertySign network is
+ * served from our registry (`source: 'registry'`) with no authority call.
+ *
+ * Requires the `identity:verify` scope on your API key. That scope is NOT granted
+ * by default — enable it under Settings → Security → SDK API Keys → Permissions.
+ *
+ * PRIVACY: this endpoint processes another person's personal data. You must
+ * attest that the data subject consented; the attestation is recorded in your
+ * tenant's audit trail on every call. The full ID number is never echoed back —
+ * store the returned `identityReference` instead of the raw number.
+ */
+
+'use strict';
+
+/** Countries / ID types the service can reach today. */
+const SUPPORTED = Object.freeze({ KE: Object.freeze(['NATIONAL_ID']) });
+
+class IdentityResource {
+  /** @param {import('./HttpClient').HttpClient} http */
+  constructor(http) {
+    this._http = http;
+  }
+
+  /**
+   * Verify a national ID against the issuing authority.
+   *
+   * @param {Object}  params
+   * @param {string}  params.country      - ISO-3166 alpha-2, e.g. 'KE'
+   * @param {string}  params.idNumber     - The subject's national ID number
+   * @param {string}  [params.idType]     - Defaults to 'NATIONAL_ID'
+   * @param {Object}  params.consent      - Lawful-basis attestation (REQUIRED)
+   * @param {boolean} params.consent.obtained   - Must be true
+   * @param {string}  [params.consent.reference] - Your own record id for the consent
+   * @param {string}  [params.consent.purpose]   - Why you're verifying, e.g. 'KYC onboarding'
+   * @param {string}  [params.firstName]  - Optional cross-check hint
+   * @param {string}  [params.lastName]   - Optional cross-check hint
+   * @param {string}  [params.dob]        - Optional cross-check hint (YYYY-MM-DD)
+   * @param {boolean} [params.forceRefresh] - Skip the registry/negative cache and
+   *                                          go straight to the authority
+   * @param {string}  [params.idempotencyKey] - Sent as X-Idempotency-Key
+   *
+   * @returns {Promise<Object>} `{ success, data }` where data contains
+   *   `verified`, `decision`, `identityReference`, `idLast4`, `person`,
+   *   `source` ('registry' | 'authority'), `cached`, `resultCode`, `checkedAt`.
+   *
+   * @throws {CertySignError} 403 CONSENT_REQUIRED, 402 INSUFFICIENT_BALANCE,
+   *   422 COUNTRY_NOT_SUPPORTED / ID_TYPE_NOT_SUPPORTED, 502 VERIFICATION_UNAVAILABLE
+   *
+   * @example
+   * const { data } = await client.identity.verify({
+   *   country: 'KE',
+   *   idNumber: '12345678',
+   *   consent: { obtained: true, reference: 'loan-8821', purpose: 'KYC onboarding' }
+   * });
+   *
+   * if (data.verified) {
+   *   console.log('Verified:', data.person.fullName, data.person.dob);
+   *   // Store this instead of the raw ID number:
+   *   await db.users.update(userId, { identityRef: data.identityReference });
+   * } else {
+   *   console.log('Not verified:', data.decision, data.resultText);
+   * }
+   */
+  verify(params = {}) {
+    const {
+      country, idNumber, idType = 'NATIONAL_ID', consent,
+      firstName, lastName, middleName, dob, phoneNumber,
+      forceRefresh, idempotencyKey,
+    } = params;
+
+    // Fail fast on the client so an obviously-malformed call never costs a
+    // round-trip (or a charge).
+    if (!country)  throw new Error('identity.verify: country is required (e.g. "KE")');
+    if (!idNumber) throw new Error('identity.verify: idNumber is required');
+    if (!consent || consent.obtained !== true) {
+      throw new Error(
+        'identity.verify: consent.obtained must be true — you must attest that the data ' +
+        'subject consented to this verification. Pass consent: { obtained: true, reference?, purpose? }'
+      );
+    }
+
+    const ctry = String(country).toUpperCase().trim();
+    const type = String(idType).toUpperCase().trim();
+    if (SUPPORTED[ctry] && !SUPPORTED[ctry].includes(type)) {
+      throw new Error(`identity.verify: idType '${type}' is not supported for ${ctry} (supported: ${SUPPORTED[ctry].join(', ')})`);
+    }
+
+    const body = {
+      country: ctry,
+      idType: type,
+      idNumber: String(idNumber).trim(),
+      consent: {
+        obtained: true,
+        ...(consent.reference ? { reference: consent.reference } : {}),
+        ...(consent.purpose ? { purpose: consent.purpose } : {}),
+      },
+    };
+    if (firstName)   body.firstName   = firstName;
+    if (lastName)    body.lastName    = lastName;
+    if (middleName)  body.middleName  = middleName;
+    if (dob)         body.dob         = dob;
+    if (phoneNumber) body.phoneNumber = phoneNumber;
+    if (forceRefresh === true) body.forceRefresh = true;
+
+    return this._http.post('/sdk/v1/identity/verify', {
+      data: body,
+      ...(idempotencyKey ? { idempotencyKey } : {}),
+    });
+  }
+
+  /**
+   * Convenience wrapper: resolve to `true` / `false` instead of the full record.
+   * Any API error still throws — a thrown error means "we could not check",
+   * which is NOT the same as "not verified", so don't collapse the two.
+   *
+   * @param {Object} params - Same shape as {@link IdentityResource#verify}
+   * @returns {Promise<boolean>}
+   *
+   * @example
+   * if (await client.identity.isVerified({
+   *   country: 'KE', idNumber: '12345678',
+   *   consent: { obtained: true, purpose: 'KYC onboarding' }
+   * })) { … }
+   */
+  async isVerified(params = {}) {
+    const res = await this.verify(params);
+    return res?.data?.verified === true;
+  }
+
+  /** Countries and ID types this SDK build knows the service supports. */
+  static get supported() {
+    return SUPPORTED;
+  }
+}
+
+module.exports = { IdentityResource };