@certysign/sdk 2.4.0 → 2.5.1

package/README.md

@@ -19,10 +19,15 @@ 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)
-  - [client.legacySign — Legacy Document Signing](#clientlegacysign--legacy-document-signing)
+  - [client.legacySign — Legacy Document Signing](#clientlegacysign--legacy-document-signing)
+    - [client.webhooks — Event Notifications](#clientwebhooks--event-notifications)
+  - [client.billing — Wallet, Quotes and Pricing](#clientbilling--wallet-quotes-and-pricing)
+  - [client.signers — Sponsored Signer Certificates](#clientsigners--sponsored-signer-certificates)
+  - [client.request — Any Endpoint](#clientrequest--any-endpoint)
 - [Complete Examples](#complete-examples)
 - [Error Handling](#error-handling)
 - [Rate Limiting](#rate-limiting)
@@ -862,6 +867,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
@@ -1041,6 +1121,272 @@ Legacy methods: `quickSign()`, `batchSign()`, `verifyById()`, `verifyDocument()`
 
 ---
 
+### `client.webhooks` — Event Notifications
+
+Register an endpoint and CertySign calls you when something finishes, instead of you
+asking repeatedly. Requires the `webhook:manage` permission on your API key.
+**Deliveries are not charged**, and neither are the status endpoints.
+
+#### `create({ url, events, description? })` — Register an endpoint
+
+```js
+const { data } = await client.webhooks.create({
+  url: 'https://api.example.com/hooks/certysign',
+  events: ['envelope.completed', 'envelope.declined'],   // omit for all events
+  description: 'Production order pipeline',
+});
+
+// data.secret is returned ONCE and is never readable again. Store it now.
+process.env.CERTYSIGN_WEBHOOK_SECRET = data.secret;
+```
+
+Events: `envelope.sent`, `envelope.viewed`, `envelope.signed` (per signature),
+`envelope.completed`, `envelope.declined`, `envelope.voided`, `envelope.expired`,
+`signing_session.completed`, `sponsorship.created`,
+`sponsorship.certificate_issued`, `sponsorship.verification_rejected`,
+`sponsorship.failed`, `webhook.test`.
+
+#### `list()`, `remove(webhookId)`, `test(webhookId)`
+
+```js
+const { data } = await client.webhooks.list();
+await client.webhooks.test(data.webhooks[0].webhookId);   // sends a webhook.test delivery
+await client.webhooks.remove(data.webhooks[0].webhookId);
+```
+
+#### `deliveries({ webhookId?, status?, limit? })`, `redeliver(deliveryId)`
+
+```js
+// What did we send, and what did your endpoint say?
+const { data } = await client.webhooks.deliveries({ status: 'failed', limit: 50 });
+for (const d of data.deliveries) {
+  console.log(d.event, d.responseStatus, d.error);
+  await client.webhooks.redeliver(d.deliveryId);
+}
+```
+
+#### Verifying the signature
+
+Use the built-in helper. It is timing-safe, enforces a freshness window, and reports
+the two mistakes that otherwise fail silently — signing the body alone (which leaves a
+captured delivery replayable forever) and verifying after `JSON.parse` (which changes
+the bytes the signature covers).
+
+```js
+const { CertySignClient } = require('@certysign/sdk');
+
+// express.raw, NOT express.json — the signature covers the bytes as sent.
+app.post('/hooks/certysign', 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,          // Buffer or string, never a parsed object
+    toleranceSeconds: 300,      // default
+  });
+
+  if (!valid) return res.status(401).send(reason);
+
+  if (alreadyHandled(event.eventId)) return res.sendStatus(200);  // at-least-once
+  handle(event);
+  res.sendStatus(200);          // answer fast; do the work afterwards
+});
+```
+
+If you would rather implement it yourself: the signature is HMAC-SHA256 over
+`"<timestamp>.<raw body>"` — **not the body alone** — compared timing-safely, over the
+raw bytes, before any JSON parsing.
+
+```js
+const crypto = require('crypto');
+
+// express.raw, NOT express.json — the signature covers the bytes as sent.
+app.post('/hooks/certysign', express.raw({ type: 'application/json' }), (req, res) => {
+  const ts  = req.get('X-CertySign-Timestamp');
+  const sig = (req.get('X-CertySign-Signature') || '').replace('sha256=', '');
+
+  // Reject anything older than 5 minutes.
+  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(400);
+
+  const expected = crypto
+    .createHmac('sha256', process.env.CERTYSIGN_WEBHOOK_SECRET)
+    .update(ts + '.' + req.body.toString())
+    .digest('hex');
+
+  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
+    return res.sendStatus(401);
+  }
+
+  const event = JSON.parse(req.body.toString());
+  if (alreadyHandled(event.eventId)) return res.sendStatus(200);  // at-least-once
+
+  handle(event);
+  res.sendStatus(200);   // answer fast; do the work afterwards
+});
+```
+
+#### Delivery, retries and duplicates
+
+- Respond **2xx** quickly. Anything else counts as a failure.
+- Retries on network errors, timeouts and 5xx: 10s, 1m, 5m, 30m, 2h, then stop.
+- A **4xx other than 429 is not retried** — your endpoint rejected the shape, and the
+  same bytes would be rejected again.
+- Delivery is **at-least-once**. De-duplicate on `eventId`, which is stable across
+  retries and redeliveries.
+- After 20 consecutive failures the webhook is disabled and the reason recorded.
+
+**Webhooks do not replace polling.** A delivery you never received is unrecoverable
+unless you can ask for the current state, so the status endpoints remain — and they
+are free to call.
+
+---
+
+### `client.billing` — Wallet, Quotes and Pricing
+
+Read-only, and every call here is free — checking a balance must never itself cost
+money.
+
+#### `wallet()` — Token balance and standing
+
+```js
+const { data } = await client.billing.wallet();
+console.log(`${data.availableBalance} ${data.currency} available`);
+```
+
+Spend against **`availableBalance`**, not `balance`: `balance` includes tokens already
+reserved by operations in flight. A `status` of `'suspended'` means chargeable calls
+are refused even when the balance looks healthy, so check it before concluding you can
+afford something.
+
+#### `quote({ operationType, operationSubType?, quantity?, additionalSigners? })`
+
+What an operation will cost, and whether you can currently cover it. Call it **before**
+a large batch: one answer up front beats `INSUFFICIENT_BALANCE` halfway through, with
+some documents signed and charged and the rest not.
+
+```js
+const { data } = await client.billing.quote({
+  operationType: 'document_signing',      // or 'certificate_issuance'
+  operationSubType: 'ADVANCED',           // e.g. 'ADVANCED', 'ADES'
+  quantity: documents.length,
+});
+
+if (!data.canAfford) {
+  throw new Error(`Need ${data.tokensTotal}, have ${data.availableBalance}`);
+}
+```
+
+#### `transactions({ limit?, skip?, type?, status? })`, `plan()`, `pricing()`
+
+```js
+const { data } = await client.billing.transactions({ limit: 100, type: 'debit' });
+const { data: plan } = await client.billing.plan();       // your tier and its limits
+const { data: rates } = await client.billing.pricing();   // the full price list
+```
+
+---
+
+### `client.signers` — Sponsored Signer Certificates
+
+A person cannot sign until they hold a certificate. These let you pay for one on their
+behalf and watch it become usable, instead of discovering at signing time that it is
+not there.
+
+#### `signingStatus(email, { issueCompletionUrl? })` — Can this person sign yet?
+
+Requires `cert:status`. Free to call, so it is safe in front of every send.
+
+```js
+const { data } = await client.signers.signingStatus('jane@example.com');
+
+if (!data.canSign) {
+  // data.reason is NO_SIGNING_CERTIFICATE or AWAITING_IDENTITY_VERIFICATION
+  console.log(data.reason);
+}
+```
+
+Worth calling **before** a batch: it turns a per-document failure — discovered halfway
+through, after the wallet has been charged — into one answer up front.
+
+For someone stuck at `AWAITING_IDENTITY_VERIFICATION`, ask for a link you can redirect
+them to, so they need not hunt for the invitation email:
+
+```js
+const { data } = await client.signers.signingStatus(email, { issueCompletionUrl: true });
+if (data.pendingSponsorship?.completionUrl) {
+  return redirect(data.pendingSponsorship.completionUrl);
+}
+```
+
+`issueCompletionUrl` **mints a new link and the previous one stops working**, including
+the one already in their inbox. Ask for it when you are about to redirect someone, not
+on every poll. It needs `signer:sponsor`, because minting an onboarding credential is
+the same class of act as sponsoring one.
+
+#### `sponsor({ email, name?, tier?, restrictToSponsor? })` — Pay for their certificate
+
+Requires `signer:sponsor`, a paid plan and a funded wallet.
+
+```js
+const { data } = await client.signers.sponsor({
+  email: 'jane@example.com',
+  name: 'Jane Mwangi',        // shown on the invitation; the certificate carries the
+                              // name on their verified ID
+  tier: 'ades',               // 'ses' | 'ades' (default) | 'qes'
+  restrictToSponsor: true,    // only signs your documents (default)
+});
+
+return redirect(data.completionUrl);
+```
+
+They **cannot sign when this returns** — `status` is `awaiting_member` until they
+complete identity verification. Subscribe to `sponsorship.certificate_issued` rather
+than polling for it.
+
+This also makes them a **member of your organisation** once the certificate issues:
+they get an account, appear in your member list, and their certificate falls under your
+governance.
+
+`restrictToSponsor: false` gives them a certificate usable anywhere, including with
+your competitors. That is a deliberate choice, not a default.
+
+#### `resendSetup(email)` — Send the setup link again
+
+```js
+await client.signers.resendSetup('jane@example.com');
+```
+
+**This rotates the token**, which invalidates the link in any email already sent. That
+is the point — an old link that still works is an old link someone else can use — but
+it does mean the earlier email stops working the moment you call this.
+
+---
+
+### `client.request` — Any Endpoint
+
+The API can gain an endpoint at any time. This calls one that has no typed method yet,
+so you are never blocked waiting for an SDK release.
+
+```js
+const res = await client.request('POST', '/sdk/v1/some-new-endpoint', {
+  data: { foo: 'bar' },
+  params: { verbose: true },      // query string
+  idempotencyKey: 'batch-2026-10-01',
+});
+```
+
+Authentication, retries, idempotency-conflict handling, the error shape and the
+User-Agent all behave exactly as they do for a typed resource. The only thing you give
+up is the named method and its documentation.
+
+Prefer a typed resource where one exists — it records the shape and keeps working if a
+path changes. Use this when there is no resource yet.
+
+> New response fields need nothing at all: responses are passed through untouched, so
+> a field added server-side is readable immediately on whatever version you have
+> installed.
+
+---
+
 ## Complete Examples
 
 ### PDF: PAdES Sign with signCallback (Recommended)
@@ -1311,6 +1657,14 @@ For batch workloads, use `batchHashAndSign()` or `batchSignHashes()` to sign up
 
 ## Migration from v1
 
+### What's New in v2.5.1
+
+- **`client.webhooks`** — register an endpoint and be told when envelopes and
+  sponsorships change state, instead of polling. See
+  [client.webhooks](#clientwebhooks--event-notifications).
+- The `User-Agent` now reports the real package version. It had been pinned at
+  `1.0.0` for the whole 2.x line, so server logs could not tell SDK versions apart.
+
 ### What's New in v2.2.0
 
 | Feature | Description |

package/package.json

@@ -1,54 +1,55 @@
-{
-  "name": "@certysign/sdk",
-  "version": "2.4.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.1",
+  "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",
+    "test:durability": "node test/durability.test.js"
+  },
+  "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"
+  }
+}