@certilayer/node

Official Node.js SDK for CertiLayer — behavioral biometrics authentication. Verify human identity through behavioral patterns without storing PII.

Installation

npm install @certilayer/node

Quick Start

import { CertiLayerClient } from '@certilayer/node';

const client = new CertiLayerClient({
  apiKey: process.env.CERTILAYER_SECRET_KEY, // certilayer_live_sk_...
});

// Full result
const result = await client.verifySession(sessionId);
console.log(result.score);    // 0.97
console.log(result.verdict);  // human_verified

// Quick pass/fail
const { passed, verdict } = await client.quickCheck(sessionId);
if (!passed) return res.status(403).json({ error: 'bot_detected' });

Express Middleware

import express from 'express';
import { CertiLayerClient } from '@certilayer/node';

const app = express();
const client = new CertiLayerClient({ apiKey: process.env.CERTILAYER_SECRET_KEY });

// Blocks requests with HCS < 0.90 on this route
app.post('/login', client.middleware.express({ minScore: 0.90 }), loginHandler);

// Access result in your handler
app.post('/checkout', client.middleware.express(), (req, res) => {
  console.log(req.certilayer.verdict); // human_verified
  res.json({ ok: true });
});

Fastify Middleware

import Fastify from 'fastify';
import { CertiLayerClient } from '@certilayer/node';

const fastify = Fastify();
const client = new CertiLayerClient({ apiKey: process.env.CERTILAYER_SECRET_KEY });

fastify.addHook('preHandler', client.middleware.fastify({ minScore: 0.65 }));

API Reference

new CertiLayerClient(options)

| Option | Type | Required | Default | |--------|------|----------|---------| | apiKey | string | Yes | — | | baseUrl | string | No | https://api.certilayer.net/v1 | | timeoutMs | number | No | 10000 | | maxRetries | number | No | 2 |

client.verifySession(sessionId)

Returns full VerifyResult:

{
  score: number;         // 0.0 – 1.0
  verdict: 'human_verified' | 'human_likely' | 'synthetic';
  sessionId: string;
  scoredAt: string;      // ISO-8601
  sessionActive: boolean;
}

client.quickCheck(sessionId, minScore?)

Returns lightweight QuickCheckResult:

{
  score: number;
  verdict: HCSVerdict;
  passed: boolean;       // true if score >= minScore
}

client.middleware.express(opts?)

client.middleware.fastify(opts?)

| Option | Type | Default | |--------|------|---------| | sessionHeader | string | x-certilayer-session | | minScore | number | 0.65 | | rejectStatus | number | 403 |

HCS Thresholds

| Score | Verdict | Recommended Action | |-------|---------|-------------------| | ≥ 0.90 | human_verified | Allow | | 0.65 – 0.90 | human_likely | Step-up auth / soft friction | | < 0.65 | synthetic | Block |

Error Handling

import { CertiLayerClient, CertiLayerError } from '@certilayer/node';

try {
  const result = await client.verifySession(sessionId);
} catch (err) {
  if (err instanceof CertiLayerError) {
    console.error(err.code);    // SESSION_NOT_FOUND | RATE_LIMITED | TIMEOUT ...
    console.error(err.message);
  }
}

API Keys

| Prefix | Type | Use | |--------|------|-----| | certilayer_live_sk_... | Secret / Live | Production server-side | | certilayer_test_sk_... | Secret / Test | Sandbox server-side |

Never expose secret keys in browser or mobile code.

License

MIT © CertiLayer