@certysign/sdk 1.0.0

package/README.md

@@ -0,0 +1,398 @@
+# @certysign/sdk
+
+Official Node.js SDK for **CertySign Trust Services** — digital document signing, X.509 certificate issuance, and PKI operations built for East Africa.
+
+## Installation
+
+### Local / internal use (current)
+
+The SDK is not yet published to the public npm registry. Use one of the methods below.
+
+**Option A — file path dependency** (recommended for services in this monorepo):
+
+```bash
+# From any service directory, e.g. a DHA integration project:
+npm install ../../sdk
+```
+
+This adds the following to the consuming project's `package.json`:
+
+```json
+"dependencies": {
+  "@certysign/sdk": "file:../../sdk"
+}
+```
+
+**Option B — `npm link`** (for local development outside the monorepo):
+
+```bash
+# In the sdk/ directory — register it globally once:
+cd sdk
+npm link
+
+# In any other project:
+npm link @certysign/sdk
+```
+
+**Option C — install directly from the folder path**:
+
+```bash
+npm install /absolute/path/to/Certy_Sign/sdk
+```
+
+### Publishing to npm (when ready)
+
+```bash
+# Log in to npm:
+npm login
+
+# From the sdk/ directory:
+npm publish --access public
+```
+
+After publishing, standard installation will work:
+
+```bash
+npm install @certysign/sdk
+```
+
+Node.js >= 18 required.
+
+## Quick start
+
+```js
+const { CertySignClient } = require('@certysign/sdk');
+
+const client = new CertySignClient({
+  publicKey:   process.env.CERTYSIGN_PUBLIC_KEY,   // cs_pk_...
+  secretKey:   process.env.CERTYSIGN_SECRET_KEY,   // cs_sk_...
+  environment: 'production'   // 'staging' | 'development'
+});
+
+// Sign a document
+const result = await client.sign.quickSign({
+  document:    require('fs').readFileSync('./claim.pdf'),
+  filename:    'claim.pdf',
+  signerName:  'Dr. Amina Okonkwo',
+  signerEmail: 'amina.okonkwo@dha.go.ke',
+  reason:      'Health claim approval — DHA Kenya'
+});
+
+console.log(result.data.envelopeId);
+console.log(result.data.certificate.serialNumber);
+```
+
+---
+
+## Authentication
+
+API keys are managed in the CertySign portal under **Settings → API Keys**.
+
+Each key pair consists of:
+
+| Value | Header | Format |
+|-------|--------|--------|
+| Public key | `X-API-Key-Id` | `cs_pk_<48 hex chars>` |
+| Secret key | `X-API-Key-Secret` | `cs_sk_<64 hex chars>` |
+
+The secret key is shown **once** at creation. Store it in a secrets manager (Vault, AWS Secrets Manager, GCP Secret Manager) — never in source code.
+
+---
+
+## Environments
+
+| Environment | Base URL |
+|-------------|----------|
+| `production` | `https://api.certysign.com` |
+| `staging` | `https://api-staging.certysign.com` |
+| `development` | `http://localhost:8000` |
+
+---
+
+## API Resources
+
+### `client.sign` — Document Signing
+
+#### `quickSign(options)` — Sign a PDF in one call
+
+```js
+const result = await client.sign.quickSign({
+  document:    Buffer,              // Required — PDF buffer or ReadStream
+  filename:    'document.pdf',      // Optional — default: 'document.pdf'
+  signerName:  'Full Name',         // Required
+  signerEmail: 'email@example.com', // Optional
+  reason:      'Approval',          // Optional
+  location:    'Nairobi, Kenya',    // Optional
+  metadata:    { claimId: '...' }   // Optional — stored with envelope
+});
+// result.data.envelopeId
+// result.data.certificate.serialNumber
+// result.data.signedDocumentUrl
+```
+
+#### `batchSign(options)` — Sign multiple PDFs at once
+
+```js
+const result = await client.sign.batchSign({
+  documents: [
+    { data: fs.readFileSync('./invoice-1.pdf'), filename: 'invoice-1.pdf' },
+    { data: fs.readFileSync('./invoice-2.pdf'), filename: 'invoice-2.pdf' }
+  ],
+  signerName:  'NHIF Finance System',
+  signerEmail: 'invoicing@nhif.or.ke',
+  reason:      'Batch provider reimbursement'
+});
+// result.data.results[].envelopeId
+// result.data.results[].success
+```
+
+#### `verifyById(envelopeId)` — Verify a signed envelope
+
+```js
+const result = await client.sign.verifyById('env_abc123');
+// result.data.valid           true/false
+// result.data.signerName
+// result.data.signedAt
+```
+
+#### `verifyDocument(document, filename)` — Verify by uploading
+
+```js
+const result = await client.sign.verifyDocument(fs.readFileSync('./signed.pdf'));
+```
+
+---
+
+### `client.certificates` — X.509 Certificate Management
+
+#### `issue(options)` — Issue a per-document certificate
+
+```js
+const result = await client.certificates.issue({
+  commonName:   'DHA Claims System',        // Required — Subject CN
+  organisation: 'Dept of Health Affairs',   // Required — Subject O
+  country:      'KE',                       // Default: 'KE'
+  state:        'Nairobi',                  // Default: 'Nairobi'
+  locality:     'Nairobi',                  // Default: 'Nairobi'
+  email:        'pki@dha.go.ke',
+  validityDays: 365,
+  metadata:     { claimId: '...' }
+});
+// result.data.serialNumber      — store for future status checks
+// result.data.fingerprint       — SHA-256 hex fingerprint
+// result.data.validFrom
+// result.data.validUntil
+// result.data.pemCertificate    — PEM certificate (store this)
+// result.data.pemChain          — Full trust chain PEM
+// result.data.privateKey        — PEM private key (shown ONCE — store securely)
+```
+
+Issued certificates include:
+- **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`
+
+#### `verify(serialNumber, atTime?)` — Verify certificate validity
+
+```js
+// Current-time check
+const result = await client.certificates.verify('A1B2C3...');
+
+// Point-in-time check (was it valid when the document was signed?)
+const result = await client.certificates.verify('A1B2C3...', new Date('2026-01-15T10:30:00Z'));
+
+// result.data.valid
+// result.data.chainVerified
+// result.data.revocationChecked
+// result.data.certStatus   'good' | 'revoked' | 'expired'
+```
+
+#### `status(serialNumber)` — Current revocation status
+
+```js
+const result = await client.certificates.status('A1B2C3...');
+// result.data.status           'good' | 'revoked' | 'expired' | 'unknown'
+// result.data.revocationDate   ISO 8601 (if revoked)
+// result.data.revocationReason  RFC 5280 reason string (if revoked)
+```
+
+---
+
+### `client.pki` — PKI Infrastructure
+
+#### `crl(format?)` — Download the Certificate Revocation List
+
+```js
+// PEM (default)
+const pem = await client.pki.crl('pem');
+fs.writeFileSync('/etc/pki/certysign.crl.pem', pem);
+
+// DER binary (for nginx/caddy stapling)
+const der = await client.pki.crl('der');
+fs.writeFileSync('/etc/pki/certysign.crl', der);
+
+// JSON — for application-level revocation checks
+const { data } = await client.pki.crl('json');
+const revokedSerials = new Set(data.crl.map(e => e.serialNumber));
+```
+
+CRL properties: RFC 5280 X.509 v2 CRL, signed by CertySign Intermediate CA, valid 7 days, issued every 24 hours.
+
+#### `ocsp(serialNumber, format?)` — OCSP query
+
+```js
+// JSON
+const { data } = await client.pki.ocsp('A1B2C3...', 'json');
+// data.status       'good' | 'revoked' | 'unknown'
+// data.thisUpdate   ISO 8601
+// data.nextUpdate   ISO 8601  ← cache response until this time
+// data.responderId  CA subject DN
+
+// DER binary (RFC 6960 BasicOCSPResponse — for OCSP stapling)
+const buf = await client.pki.ocsp('A1B2C3...', 'der');
+```
+
+#### `chain()` — Download CA certificate chain
+
+```js
+const pem = await client.pki.chain();
+// Returns PEM bundle:  Intermediate CA cert + Root CA cert
+fs.writeFileSync('/etc/ssl/certs/certysign-chain.pem', pem);
+```
+
+#### `info()` — CA hierarchy metadata
+
+```js
+const { data } = await client.pki.info();
+// data.rootCA.subject.commonName
+// data.intermediateCA.validity.notAfter
+// data.intermediateCA.crlUrl
+// data.intermediateCA.ocspUrl
+// data.status.initialized
+```
+
+---
+
+### `client.envelopes` — Envelope Management
+
+For integrations that need full control over the envelope lifecycle (instead of `quickSign`).
+
+```js
+// 1. Create envelope
+const { data: { envelope } } = await client.envelopes.create({
+  title:   'NHIF Claims Q1-2026',
+  signers: [{ name: 'Director Finance', email: 'df@nhif.or.ke' }]
+});
+
+// 2. Upload documents
+await client.envelopes.uploadDocuments(envelope._id, [
+  { data: fs.readFileSync('./report.pdf'), filename: 'Q1-report.pdf' }
+]);
+
+// 3. Send envelope (transitions to 'sent' status)
+await client.envelopes.send(envelope._id);
+
+// 4. Sign
+const signed = await client.envelopes.sign(envelope._id, {
+  reason:   'NHIF Q1 approval',
+  location: 'Nairobi, Kenya'
+});
+
+// 5. Download signed PDF
+const pdfBuffer = await client.envelopes.getDocument(envelope._id, docId);
+
+// 6. Audit trail
+const { data } = await client.envelopes.getAuditTrail(envelope._id);
+// data.auditTrail[].action, .timestamp, .eventHash, .chainHash
+// data.chainIntegrity.valid
+```
+
+---
+
+## Error Handling
+
+All SDK methods throw `CertySignError` on failure:
+
+```js
+const { CertySignClient, CertySignError } = require('@certysign/sdk');
+
+try {
+  await client.sign.quickSign({ ... });
+} catch (err) {
+  if (err instanceof CertySignError) {
+    console.error(err.message);       // Human-readable message
+    console.error(err.statusCode);    // HTTP status (0 for network errors)
+    console.error(err.code);          // Machine-readable code, e.g. 'INVALID_API_KEY'
+    console.error(err.details);       // Full API error body
+  }
+}
+```
+
+Common error codes:
+
+| Code | Status | Meaning |
+|------|--------|---------|
+| `INVALID_API_KEY` | 401 | Key not found or secret mismatch |
+| `API_KEY_EXPIRED` | 401 | Key has passed its `expiresAt` date |
+| `INSUFFICIENT_SDK_PERMISSIONS` | 403 | Key lacks required permission |
+| `IP_NOT_ALLOWED` | 403 | Request IP not in IP allowlist |
+| `RATE_LIMIT_EXCEEDED` | 429 | Requests per minute exceeded |
+| `NETWORK_ERROR` | 0 | Could not reach the API |
+
+The SDK automatically retries `429`, `502`, `503`, `504` responses up to 3 times with exponential back-off.
+
+---
+
+## Rate Limiting
+
+Each API key has a configurable rate limit (requests per minute, set in the CertySign portal). When the limit is exceeded:
+
+- HTTP `429` is returned
+- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` headers are set
+- SDK retries automatically (up to 3 times) if the issue is transient
+- After retries are exhausted, `CertySignError` with code `RATE_LIMIT_EXCEEDED` is thrown
+
+For batch workloads, use `batchSign()` to sign multiple documents in a single API call rather than calling `quickSign()` in a loop.
+
+---
+
+## Examples
+
+| File | Description |
+|------|-------------|
+| [examples/dha-integration.js](examples/dha-integration.js) | DHA Kenya claims quick-sign + certificate issuance |
+| [examples/nhif-batch-sign.js](examples/nhif-batch-sign.js) | NHIF nightly invoice batch signing |
+| [examples/certificate-flow.js](examples/certificate-flow.js) | Full X.509 lifecycle: issue, verify, CRL, OCSP, chain |
+
+---
+
+## PKI Trust Chain
+
+```
+CertySign Root CA (C=KE, RSA-4096, 20yr)
+  └── CertySign Intermediate CA (C=KE, RSA-4096, 10yr, pathLen=0)
+        ├── Per-document X.509 certs  (issued via /sdk/v1/certificates/issue)
+        └── Tenant signing certs      (managed in CertySign portal)
+```
+
+CA bundle: `https://pki.certysign.com/certs/chain.pem`  
+CRL: `https://pki.certysign.com/crl/intermediate.crl`  
+OCSP: `https://pki.certysign.com/ocsp`
+
+---
+
+## Security Best Practices
+
+- **Rotate keys** every 90 days: use the CertySign portal → API Keys → Rotate
+- **IP allowlist** every production key to your deployment's egress IPs
+- **Use `staging` environment** for development and CI pipelines (separate key pair)
+- **Store the private key** from `certificates.issue()` response in a HSM or secrets manager — CertySign does not retain it
+- **Cache CRL / OCSP responses** up to `nextUpdate` to reduce latency in HIE systems
+
+---
+
+## Support
+
+- Docs: https://docs.certysign.com/sdk
+- Issues: https://github.com/certysign/sdk-node/issues
+- Email: sdk@certysign.com

package/examples/certificate-flow.js

@@ -0,0 +1,198 @@
+/**
+ * Full PKI Certificate Lifecycle Example
+ *
+ * Demonstrates the complete X.509 certificate workflow:
+ *  1. Issue a per-document certificate
+ *  2. Check current status (should be 'good')
+ *  3. Verify the certificate (chain, revocation, validity)
+ *  4. Download CA chain and save it locally
+ *  5. Perform a point-in-time verification
+ *  6. Fetch and cache the CRL locally
+ *  7. Check a serial number directly against the CRL JSON
+ *  8. Perform an OCSP query
+ *
+ * This pattern is used by HIE systems that need to:
+ *  - Verify document signing certificates before granting access
+ *  - Cache CRL/OCSP responses to meet response time SLAs
+ *
+ * Prerequisites:
+ *   npm install @certysign/sdk
+ *   export CERTYSIGN_PUBLIC_KEY="cs_pk_..."
+ *   export CERTYSIGN_SECRET_KEY="cs_sk_..."
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const { CertySignClient, CertySignError } = require('@certysign/sdk');
+
+const client = new CertySignClient({
+  publicKey:   process.env.CERTYSIGN_PUBLIC_KEY,
+  secretKey:   process.env.CERTYSIGN_SECRET_KEY,
+  environment: 'production'
+});
+
+async function runCertificateFlow() {
+  console.log('\n[PKI] CertySign Certificate Lifecycle Demo');
+  console.log('─'.repeat(60));
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // 1. Issue a certificate
+  // ─────────────────────────────────────────────────────────────────────────
+  console.log('\n[PKI] 1. Issuing X.509 certificate...');
+
+  const issueResult = await client.certificates.issue({
+    commonName:   'HIE Integration Node — KNH',
+    organisation: 'Kenyatta National Hospital',
+    country:      'KE',
+    state:        'Nairobi',
+    locality:     'Nairobi',
+    email:        'pki@knh.or.ke',
+    validityDays: 365,
+    metadata:     { system: 'HIE-NODE-KNH-PROD', issuedAt: new Date().toISOString() }
+  });
+
+  const cert = issueResult.data;
+  console.log(`  serialNumber : ${cert.serialNumber}`);
+  console.log(`  fingerprint  : ${cert.fingerprint}`);
+  console.log(`  validFrom    : ${cert.validFrom}`);
+  console.log(`  validUntil   : ${cert.validUntil}`);
+  console.log(`  Subject CN   : ${cert.subject?.cn}`);
+
+  // Store private key securely (shown ONCE — CertySign does not retain it)
+  const keyPath = path.join(__dirname, 'hie-node-knh.key.pem');
+  fs.writeFileSync(keyPath, cert.privateKey, { mode: 0o600 });
+  console.log(`  privateKey   → ${keyPath}  (mode 600)`);
+
+  const certPath = path.join(__dirname, 'hie-node-knh.crt.pem');
+  fs.writeFileSync(certPath, cert.pemCertificate);
+  console.log(`  certificate  → ${certPath}`);
+
+  const { serialNumber } = cert;
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // 2. Real-time status check (should be 'good')
+  // ─────────────────────────────────────────────────────────────────────────
+  console.log('\n[PKI] 2. Certificate status check...');
+  const statusResult = await client.certificates.status(serialNumber);
+  const status = statusResult.data;
+  console.log(`  status         : ${status.status}`);
+  if (status.status === 'revoked') {
+    console.log(`  revocationDate : ${status.revocationDate}`);
+    console.log(`  reason         : ${status.revocationReason}`);
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // 3. Full certificate verification (chain + revocation)
+  // ─────────────────────────────────────────────────────────────────────────
+  console.log('\n[PKI] 3. Full certificate verification...');
+  const verifyResult = await client.certificates.verify(serialNumber);
+  const verification = verifyResult.data;
+  console.log(`  valid              : ${verification.valid}`);
+  console.log(`  chainVerified      : ${verification.chainVerified}`);
+  console.log(`  revocationChecked  : ${verification.revocationChecked}`);
+  console.log(`  certStatus         : ${verification.certStatus}`);
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // 4. Download CA chain and install in local trust store
+  // ─────────────────────────────────────────────────────────────────────────
+  console.log('\n[PKI] 4. Downloading CA chain...');
+  const chainPem = await client.pki.chain();
+  const chainPath = path.join(__dirname, 'certysign-chain.pem');
+  fs.writeFileSync(chainPath, chainPem);
+  console.log(`  CA chain → ${chainPath}`);
+  console.log(`  (${chainPem.split('-----BEGIN CERTIFICATE-----').length - 1} cert(s) in bundle)`);
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // 5. Point-in-time verification
+  //    Used by HIE to check if a cert was valid at the time a document was signed
+  // ─────────────────────────────────────────────────────────────────────────
+  console.log('\n[PKI] 5. Point-in-time verification...');
+  const signingTime = new Date(Date.now() - 5 * 60 * 1000);   // 5 minutes ago
+  const ptResult = await client.certificates.verify(serialNumber, signingTime);
+  console.log(`  valid at ${signingTime.toISOString()} : ${ptResult.data.valid}`);
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // 6. Fetch and cache CRL (JSON format for application-level checks)
+  // ─────────────────────────────────────────────────────────────────────────
+  console.log('\n[PKI] 6. Fetching CRL (JSON)...');
+  const crlJson = await client.pki.crl('json');
+  const crl = crlJson.data;
+  console.log(`  issuer        : ${crl.issuer}`);
+  console.log(`  thisUpdate    : ${crl.thisUpdate}`);
+  console.log(`  nextUpdate    : ${crl.nextUpdate}`);
+  console.log(`  revokedCount  : ${crl.revokedCount}`);
+
+  // Build a Set of revoked serial numbers for fast in-process lookups
+  const revokedSet = new Set((crl.crl || []).map(e => e.serialNumber));
+  console.log(`  Revoked set   : ${revokedSet.size} entries loaded`);
+
+  // Cache on disk until nextUpdate
+  fs.writeFileSync(
+    path.join(__dirname, 'crl-cache.json'),
+    JSON.stringify({ ...crl, cachedAt: new Date().toISOString() }, null, 2)
+  );
+
+  // Also download DER CRL for systems that need binary format
+  console.log('\n[PKI] 6b. Downloading DER CRL...');
+  const crlDer = await client.pki.crl('der');
+  fs.writeFileSync(path.join(__dirname, 'certysign-intermediate.crl'), crlDer);
+  console.log(`  certysign-intermediate.crl — ${crlDer.length} bytes`);
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // 7. In-process revocation check using cached CRL
+  // ─────────────────────────────────────────────────────────────────────────
+  console.log('\n[PKI] 7. Local CRL check...');
+  const isRevoked = revokedSet.has(serialNumber);
+  console.log(`  Serial ${serialNumber.slice(0, 12)}... : ${isRevoked ? 'REVOKED' : 'not in CRL'}`);
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // 8. OCSP query — freshest revocation status
+  // ─────────────────────────────────────────────────────────────────────────
+  console.log('\n[PKI] 8. OCSP query...');
+  const ocspResult = await client.pki.ocsp(serialNumber, 'json');
+  const ocsp = ocspResult.data;
+  console.log(`  status         : ${ocsp.status}`);
+  console.log(`  producedAt     : ${ocsp.producedAt}`);
+  console.log(`  responderId    : ${ocsp.responderId}`);
+  console.log(`  nextUpdate     : ${ocsp.nextUpdate}`);
+  console.log(`  signatureAlgo  : ${ocsp.signatureAlgorithm}`);
+  if (ocsp.certIdHash) {
+    console.log(`  CertID algo    : ${ocsp.certIdHash.algorithm}`);
+    console.log(`  issuerNameHash : ${ocsp.certIdHash.issuerNameHash?.slice(0, 16)}...`);
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // 9. CA Info — inspect the trust hierarchy
+  // ─────────────────────────────────────────────────────────────────────────
+  console.log('\n[PKI] 9. CA hierarchy info...');
+  const info = await client.pki.info();
+  const caInfo = info.data;
+  console.log(`  Root CA        : ${caInfo.rootCA?.subject?.commonName}`);
+  console.log(`  Root CA expiry : ${caInfo.rootCA?.validity?.notAfter}`);
+  console.log(`  Inter CA       : ${caInfo.intermediateCA?.subject?.commonName}`);
+  console.log(`  Inter CA expiry: ${caInfo.intermediateCA?.validity?.notAfter}`);
+  console.log(`  CRL URL        : ${caInfo.intermediateCA?.crlUrl}`);
+  console.log(`  OCSP URL       : ${caInfo.intermediateCA?.ocspUrl}`);
+  console.log(`  Initialised    : ${caInfo.status?.initialized}`);
+
+  console.log('\n[PKI] ✓ Certificate lifecycle demo complete');
+  console.log('─'.repeat(60));
+}
+
+// ── Run ───────────────────────────────────────────────────────────────────────
+
+(async () => {
+  try {
+    await runCertificateFlow();
+  } catch (err) {
+    if (err instanceof CertySignError) {
+      console.error(`\n[PKI] API Error (${err.statusCode}): ${err.message}`);
+      if (err.details) console.error('[PKI] Details:', JSON.stringify(err.details, null, 2));
+    } else {
+      console.error('\n[PKI] Error:', err.message);
+    }
+    process.exit(1);
+  }
+})();