@certysign/sdk 2.3.0 → 2.5.0

package/README.md

@@ -19,6 +19,7 @@ Official Node.js SDK for **CertySign Trust Services** — hash-based digital sig
   - [client.hasher — Local Document Hashing](#clienthasher--local-document-hashing)
   - [client.embedder — Local Signature Embedding](#clientembedder--local-signature-embedding)
   - [client.dashboard — SDK Analytics](#clientdashboard--sdk-analytics)
+  - [client.identity — Identity Verification](#clientidentity--identity-verification)
   - [client.certificates — X.509 Certificate Management](#clientcertificates--x509-certificate-management)
   - [client.pki — PKI Infrastructure](#clientpki--pki-infrastructure)
   - [client.envelopes — Envelope Management](#clientenvelopes--envelope-management)
@@ -862,6 +863,81 @@ const { data } = await client.dashboard.getDocuments({
 
 ---
 
+### `client.identity` — Identity Verification
+
+Verify a national ID against the issuing authority (IPRS for Kenya) and get the
+biographic record — 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. A *rejected* ID is
+cached briefly too, so repeated lookups of the same bad number don't incur repeated
+charges. Pass `forceRefresh: true` to bypass both.
+
+Requires the **`identity:verify`** scope, which is **not granted by default** — enable it
+under *Settings → Security → SDK API Keys → Permissions*.
+
+> **Consent is mandatory.** This processes another person's personal data, so
+> `consent.obtained: true` is required — the SDK throws *before* making the call if it's
+> missing. Your attestation, API key and IP are written to your tenant's audit trail on
+> every call, evidencing a lawful basis under the Kenya Data Protection Act 2019.
+> Store the returned `identityReference` instead of the raw ID number — the full number
+> is never returned to you.
+
+#### `verify(params)` — Verify a national ID
+
+```js
+const { data } = await client.identity.verify({
+  country:  'KE',
+  idNumber: '12345678',
+  idType:   'NATIONAL_ID',      // optional — this is the default
+  consent: {
+    obtained:  true,             // REQUIRED
+    reference: 'loan-app-8821',  // optional — your own consent record id
+    purpose:   'KYC onboarding'  // optional
+  },
+  // Optional cross-check hints: firstName, lastName, dob
+  // forceRefresh: true          // skip caches, go straight to the authority
+});
+
+// data.verified          — true when the authority confirmed the ID
+// data.decision          — 'verified' | 'rejected' | 'provisional' | 'unknown'
+// data.identityReference — privacy-preserving reference; store THIS
+// data.idLast4           — last 4 digits only
+// data.person            — fullName, firstName, middleName, lastName,
+//                          dob, gender, nationality
+// data.source            — 'registry' (cached) | 'authority' (fresh lookup)
+// data.cached            — true when served without an authority call
+// data.resultCode        — authority code, e.g. '1012' = valid ID
+// data.checkedAt         — ISO timestamp
+```
+
+#### `isVerified(params)` — Boolean convenience wrapper
+
+```js
+const ok = await client.identity.isVerified({
+  country: 'KE', idNumber: '12345678',
+  consent: { obtained: true, purpose: 'KYC onboarding' }
+});
+```
+
+> A thrown error means **"we couldn't check"**, which is *not* the same as
+> **"not verified"**. Never collapse the two — treat an error as retry/escalate,
+> not as a failed identity.
+
+#### Errors
+
+| Code | HTTP | Meaning |
+|---|---|---|
+| `CONSENT_REQUIRED` | 403 | Consent attestation missing |
+| `INSUFFICIENT_BALANCE` | 402 | Checked *before* any authority call — you're never charged for a lookup you couldn't afford |
+| `COUNTRY_NOT_SUPPORTED` / `ID_TYPE_NOT_SUPPORTED` | 422 | Only `KE` / `NATIONAL_ID` today |
+| `VERIFICATION_UNAVAILABLE` | 502 | Authority unreachable — not billed, retry later |
+
+**Billing:** one `ekyc_check` per distinct ID per day. A *negative* result is billable
+(the authority was queried); an *outage* is never billed.
+
+---
+
 ### `client.certificates` — X.509 Certificate Management
 
 #### `getActive()` — Get your tenant's active signing certificate

package/package.json

@@ -1,54 +1,54 @@
-{
-  "name": "@certysign/sdk",
-  "version": "2.3.0",
-  "description": "Official Node.js SDK for CertySign — hash-based digital signing, X.509 certificates, and PKI services. Documents never leave your system.",
-  "main": "src/index.js",
-  "types": "src/index.d.ts",
-  "files": [
-    "src/",
-    "README.md"
-  ],
-  "scripts": {
-    "test": "jest --coverage",
-    "lint": "eslint src/**/*.js",
-    "build:types": "npx tsc --emitDeclarationOnly"
-  },
-  "keywords": [
-    "certysign",
-    "digital-signature",
-    "pki",
-    "x509",
-    "pdf-signing",
-    "document-signing",
-    "hash-based-signing",
-    "kenya",
-    "pades",
-    "xmldsig",
-    "otp"
-  ],
-  "author": "CertySign Limited <sdk@certysign.io>",
-  "license": "MIT",
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "dependencies": {
-    "axios": "^1.6.0",
-    "form-data": "^4.0.0",
-    "node-forge": "^1.3.3",
-    "pdf-lib": "^1.17.1"
-  },
-  "devDependencies": {
-    "jest": "^29.7.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/certysign/sdk-node.git"
-  },
-  "homepage": "https://docs.certysign.io/sdk",
-  "bugs": {
-    "url": "https://github.com/certysign/sdk-node/issues"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@certysign/sdk",
+  "version": "2.5.0",
+  "description": "Official Node.js SDK for CertySign — hash-based digital signing, X.509 certificates, and PKI services. Documents never leave your system.",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "jest --coverage",
+    "lint": "eslint src/**/*.js",
+    "build:types": "npx tsc --emitDeclarationOnly"
+  },
+  "keywords": [
+    "certysign",
+    "digital-signature",
+    "pki",
+    "x509",
+    "pdf-signing",
+    "document-signing",
+    "hash-based-signing",
+    "kenya",
+    "pades",
+    "xmldsig",
+    "otp"
+  ],
+  "author": "CertySign Limited <sdk@certysign.io>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "axios": "^1.6.0",
+    "form-data": "^4.0.0",
+    "node-forge": "^1.3.3",
+    "pdf-lib": "^1.17.1"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/certysign/sdk-node.git"
+  },
+  "homepage": "https://docs.certysign.io/sdk",
+  "bugs": {
+    "url": "https://github.com/certysign/sdk-node/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.js

@@ -1,214 +1,228 @@
-/**
- * @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 { 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.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 };
+    }
+  }
+}
+
+/**
+ * @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,
+  // Legacy exports
+  SigningResource,
+  CertificateResource,
+  PkiResource,
+  EnvelopeResource
+};