@classytic/primitives 0.9.1 → 0.11.0

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 adhering to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.11.0] - 2026-07-08
+
+### Added — eKYC vocabulary + secure OTP primitive
+
+- **`@classytic/primitives/identity-verification`** — cross-package eKYC data shapes:
+  `IdentityDocumentType`, `VerificationCheck`, `VerificationLevel`, `SubjectKind`,
+  `IdentitySubject`, `DocumentReference`, `IdentityProviderCapabilities`,
+  `VerificationStatus`, `CheckResult`, `CreateVerificationParams`,
+  `VerificationSession`, `VerificationWebhookEvent`. Pure helpers: `isVerified`,
+  `checksSatisfy`, `deriveStatus`. The identity twin of `payment-gateway` — shapes
+  here, contracts in engines, provider implementations anywhere. Serves `@classytic/esign`
+  (IdentityBridge port), `@classytic/payee` (ComplianceBridge), and PSP merchant KYC.
+- **`@classytic/primitives/otp`** — secure OTP challenge lifecycle. Guarantees: code
+  never persisted (only HMAC-SHA256 digest stored), constant-time `timingSafeEqual`
+  comparison, rejection-free `randomInt` CSPRNG (no modulo bias), bounded attempt
+  counter, TTL expiry, single-use verified state. Exports: `createOtpChallenge`,
+  `verifyOtpChallenge`, `isOtpVerified`, `isOtpActive`. Delivery stays in
+  `@classytic/notifications` — this primitive owns only the verify half.
+
 ## [0.9.1] - 2026-07-04
 
 ### Added

package/dist/identity-verification.d.mts

@@ -0,0 +1,113 @@
+import { PersonName } from "./person.mjs";
+
+//#region src/identity/identity-verification.d.ts
+/**
+ * Government / institutional identity documents. `trade_license` and
+ * `tin_certificate` support MERCHANT (business) onboarding — a payment gateway
+ * KYBs the business, not just a person.
+ */
+type IdentityDocumentType = 'nid' | 'passport' | 'driving_license' | 'birth_certificate' | 'residence_permit' | 'trade_license' | 'tin_certificate' | 'other';
+/** A single verification check a session can run. Providers advertise support. */
+type VerificationCheck = 'document' | 'liveness' | 'face_match' | 'database' | 'address' | 'sanctions' | 'pep' | 'adverse_media';
+/**
+ * Assurance tier — mirrors the market (Stripe Identity / Persona levels).
+ * Higher tiers imply a superset of checks; the exact mapping is host policy.
+ */
+type VerificationLevel = 'basic' | 'standard' | 'enhanced';
+/** The kind of subject under verification — a natural person or a business. */
+type SubjectKind = 'individual' | 'business';
+interface DocumentReference {
+  readonly type: IdentityDocumentType;
+  /** Document number (NID/passport no.). May be redacted/tokenized at rest. */
+  readonly number?: string;
+  /** ISO 3166-1 alpha-2 issuing country. */
+  readonly country?: string;
+  /** ISO date (YYYY-MM-DD). */
+  readonly expiresOn?: string;
+}
+interface IdentitySubject {
+  readonly kind: SubjectKind;
+  readonly name?: PersonName;
+  /** Legal/business name when `kind === 'business'`. */
+  readonly legalName?: string;
+  /** ISO date (YYYY-MM-DD). */
+  readonly dateOfBirth?: string;
+  /** ISO 3166-1 alpha-2. */
+  readonly country?: string;
+}
+interface IdentityProviderCapabilities {
+  readonly checks: readonly VerificationCheck[];
+  readonly documents: readonly IdentityDocumentType[];
+  /** ISO 3166-1 alpha-2 codes; empty ⇒ global. */
+  readonly countries: readonly string[];
+  /** Delivers async results via webhook (vs poll-only). */
+  readonly webhooks: boolean;
+  /** Supports business/KYB flows, not just individuals. */
+  readonly business: boolean;
+}
+type VerificationStatus = 'pending' | 'processing' | 'verified' | 'rejected' | 'review' | 'expired';
+type CheckOutcome = 'pass' | 'fail' | 'manual' | 'skipped';
+interface CheckResult {
+  readonly check: VerificationCheck;
+  readonly outcome: CheckOutcome;
+  /** Provider-specific reason/code for a fail/manual outcome. */
+  readonly reason?: string;
+}
+interface CreateVerificationParams {
+  readonly subject: IdentitySubject;
+  readonly level: VerificationLevel;
+  /** Checks the host requires to consider the subject verified. */
+  readonly requiredChecks?: readonly VerificationCheck[];
+  readonly documents?: readonly DocumentReference[];
+  /** Where the provider redirects the subject after a hosted flow. */
+  readonly redirectUrl?: string;
+  /** Correlates the session back to a host entity (payee id, signer id, …). */
+  readonly reference?: string;
+  readonly metadata?: Readonly<Record<string, string>>;
+}
+interface VerificationSession {
+  /** Provider-side session id — the handle a host stores and polls. */
+  readonly id: string;
+  readonly provider: string;
+  readonly level: VerificationLevel;
+  readonly status: VerificationStatus;
+  readonly checks: readonly CheckResult[];
+  /** Hosted-flow URL for the subject, when the provider uses one. */
+  readonly url?: string;
+  readonly reference?: string;
+  /** ISO timestamp the verification was decided. */
+  readonly decidedAt?: string;
+  /**
+   * ISO timestamp the verification lapses and re-KYC is required. Periodic
+   * re-KYC is an AML requirement; consumers gate on this (payee pauses
+   * payability, esign re-verifies before signing).
+   */
+  readonly expiresAt?: string;
+  /** Raw provider payload for audit/debugging. */
+  readonly raw?: unknown;
+}
+/** Normalized provider webhook — the async-decision callback shape. */
+interface VerificationWebhookEvent {
+  readonly sessionId: string;
+  readonly provider: string;
+  readonly status: VerificationStatus;
+  readonly checks?: readonly CheckResult[];
+  readonly occurredAt: string;
+  readonly raw?: unknown;
+}
+/** A session is usable when it passed and has not lapsed at `now`. */
+declare function isVerified(session: VerificationSession, now?: Date): boolean;
+/**
+ * Do the check RESULTS satisfy the REQUIRED checks? Every required check must
+ * have a `pass`. Missing or non-pass required checks ⇒ false. Extra results
+ * are ignored.
+ */
+declare function checksSatisfy(required: readonly VerificationCheck[], results: readonly CheckResult[]): boolean;
+/**
+ * Derive a session status from check results alone (for providers that return
+ * raw checks without a verdict): any `fail` ⇒ rejected; any `manual` ⇒ review;
+ * all required present and `pass` ⇒ verified; otherwise processing.
+ */
+declare function deriveStatus(results: readonly CheckResult[], required?: readonly VerificationCheck[]): VerificationStatus;
+//#endregion
+export { CheckOutcome, CheckResult, CreateVerificationParams, DocumentReference, IdentityDocumentType, IdentityProviderCapabilities, IdentitySubject, SubjectKind, VerificationCheck, VerificationLevel, VerificationSession, VerificationStatus, VerificationWebhookEvent, checksSatisfy, deriveStatus, isVerified };

package/dist/identity-verification.mjs

@@ -0,0 +1,30 @@
+//#region src/identity/identity-verification.ts
+/** A session is usable when it passed and has not lapsed at `now`. */
+function isVerified(session, now) {
+	if (session.status !== "verified") return false;
+	if (!session.expiresAt) return true;
+	const at = (now ?? /* @__PURE__ */ new Date()).toISOString();
+	return session.expiresAt > at;
+}
+/**
+* Do the check RESULTS satisfy the REQUIRED checks? Every required check must
+* have a `pass`. Missing or non-pass required checks ⇒ false. Extra results
+* are ignored.
+*/
+function checksSatisfy(required, results) {
+	const passed = new Set(results.filter((r) => r.outcome === "pass").map((r) => r.check));
+	return required.every((c) => passed.has(c));
+}
+/**
+* Derive a session status from check results alone (for providers that return
+* raw checks without a verdict): any `fail` ⇒ rejected; any `manual` ⇒ review;
+* all required present and `pass` ⇒ verified; otherwise processing.
+*/
+function deriveStatus(results, required = []) {
+	if (results.some((r) => r.outcome === "fail")) return "rejected";
+	if (results.some((r) => r.outcome === "manual")) return "review";
+	if (required.length > 0 && checksSatisfy(required, results)) return "verified";
+	return "processing";
+}
+//#endregion
+export { checksSatisfy, deriveStatus, isVerified };

package/dist/otp.d.mts

@@ -0,0 +1,96 @@
+//#region src/identity/otp.d.ts
+/**
+ * OTP challenge — the pure, secure *verify* half of one-time-code verification.
+ *
+ * This primitive owns SECURITY, never delivery. Delivery (SMS / email / push /
+ * WhatsApp, templates, retry, fallback) is `@classytic/notifications`; the host
+ * passes the returned `code` to whichever channel/provider it likes. This file
+ * only guarantees the code cannot be forged, replayed, brute-forced, or leaked:
+ *
+ *   - the plaintext code is NEVER persisted — only its HMAC-SHA256 digest is
+ *     (a stolen challenge row cannot reveal the code);
+ *   - comparison is constant-time (`timingSafeEqual`) — no timing oracle;
+ *   - the code is drawn from a CSPRNG with rejection-free `randomInt` — no
+ *     modulo bias;
+ *   - a bounded attempt counter locks the challenge — no online brute force;
+ *   - a TTL expires the challenge — no indefinite window;
+ *   - a verified challenge is single-use — no replay.
+ *
+ * The shape is a plain value object: create it, persist `challenge`, and on each
+ * attempt feed the stored challenge back through `verifyOtpChallenge` and persist
+ * the returned next state. No I/O, no clock capture beyond an injectable `now`.
+ *
+ * Resend throttling (don't mint a new code too soon) is a host / arc-layer
+ * concern — rate-limit calls to `createOtpChallenge`; it is deliberately not
+ * modeled here so the verify primitive stays stateless between attempts.
+ */
+/** Terminal + in-flight states a persisted challenge can hold. */
+type OtpStatus = 'pending' | 'verified' | 'failed' | 'expired';
+/** The result of a single `verifyOtpChallenge` call. */
+type OtpOutcome = 'verified' | 'incorrect' | 'expired' | 'locked' | 'already_used';
+/**
+ * The persistable challenge. Contains no secret material: `hash` is an HMAC of
+ * the code under a server-side `secret`, so the row is useless to a thief who
+ * lacks the secret. Persist this verbatim; never add the plaintext code to it.
+ */
+interface OtpChallenge {
+  /** HMAC-SHA256(code, secret) as hex. The plaintext code is never stored. */
+  readonly hash: string;
+  /** ISO-8601 instant after which the challenge is dead. */
+  readonly expiresAt: string;
+  /** Failed attempts so far. */
+  readonly attempts: number;
+  /** Attempts allowed before the challenge locks (`failed`). */
+  readonly maxAttempts: number;
+  /** Lifecycle state. */
+  readonly status: OtpStatus;
+}
+interface CreateOtpOptions {
+  /** Server-side HMAC key. Required — a challenge with no secret is forgeable. */
+  readonly secret: string;
+  /** Number of digits in the code. Default 6. */
+  readonly length?: number;
+  /** Time-to-live in ms. Default 5 minutes. */
+  readonly ttlMs?: number;
+  /** Failed attempts before lock. Default 5. */
+  readonly maxAttempts?: number;
+  /** Injectable clock for deterministic tests. Default `new Date()`. */
+  readonly now?: Date;
+}
+interface CreatedOtp {
+  /** Persist this. Contains only the HMAC digest, never the code. */
+  readonly challenge: OtpChallenge;
+  /** Deliver this via `@classytic/notifications`. NEVER persist it. */
+  readonly code: string;
+}
+interface VerifyOtpOptions {
+  /** The same server-side HMAC key used at creation. */
+  readonly secret: string;
+  /** Injectable clock for deterministic tests. Default `new Date()`. */
+  readonly now?: Date;
+}
+interface OtpVerification {
+  /** The next challenge state to persist (attempt count / status advanced). */
+  readonly challenge: OtpChallenge;
+  /** What happened on this attempt. */
+  readonly outcome: OtpOutcome;
+}
+/**
+ * Mint a challenge + its one-time code. Persist `challenge`; hand `code` to the
+ * delivery layer. The code exists only in this return value and in the delivered
+ * message — it is never recoverable from the persisted challenge.
+ */
+declare function createOtpChallenge(options: CreateOtpOptions): CreatedOtp;
+/**
+ * Check `input` against a persisted challenge and return the next state. This is
+ * a pure transition — the caller persists `result.challenge`. Fail-closed: any
+ * non-`pending` challenge, an expired window, or an over-limit attempt yields a
+ * non-`verified` outcome and never re-opens a settled challenge.
+ */
+declare function verifyOtpChallenge(challenge: OtpChallenge, input: string, options: VerifyOtpOptions): OtpVerification;
+/** True once a challenge has been successfully verified. */
+declare function isOtpVerified(challenge: OtpChallenge): boolean;
+/** True while a challenge can still accept an attempt (pending + unexpired). */
+declare function isOtpActive(challenge: OtpChallenge, now?: Date): boolean;
+//#endregion
+export { CreateOtpOptions, CreatedOtp, OtpChallenge, OtpOutcome, OtpStatus, OtpVerification, VerifyOtpOptions, createOtpChallenge, isOtpActive, isOtpVerified, verifyOtpChallenge };

package/dist/otp.mjs

@@ -0,0 +1,132 @@
+import { createHmac, randomInt, timingSafeEqual } from "node:crypto";
+//#region src/identity/otp.ts
+/**
+* OTP challenge — the pure, secure *verify* half of one-time-code verification.
+*
+* This primitive owns SECURITY, never delivery. Delivery (SMS / email / push /
+* WhatsApp, templates, retry, fallback) is `@classytic/notifications`; the host
+* passes the returned `code` to whichever channel/provider it likes. This file
+* only guarantees the code cannot be forged, replayed, brute-forced, or leaked:
+*
+*   - the plaintext code is NEVER persisted — only its HMAC-SHA256 digest is
+*     (a stolen challenge row cannot reveal the code);
+*   - comparison is constant-time (`timingSafeEqual`) — no timing oracle;
+*   - the code is drawn from a CSPRNG with rejection-free `randomInt` — no
+*     modulo bias;
+*   - a bounded attempt counter locks the challenge — no online brute force;
+*   - a TTL expires the challenge — no indefinite window;
+*   - a verified challenge is single-use — no replay.
+*
+* The shape is a plain value object: create it, persist `challenge`, and on each
+* attempt feed the stored challenge back through `verifyOtpChallenge` and persist
+* the returned next state. No I/O, no clock capture beyond an injectable `now`.
+*
+* Resend throttling (don't mint a new code too soon) is a host / arc-layer
+* concern — rate-limit calls to `createOtpChallenge`; it is deliberately not
+* modeled here so the verify primitive stays stateless between attempts.
+*/
+const DEFAULT_LENGTH = 6;
+const DEFAULT_TTL_MS = 300 * 1e3;
+const DEFAULT_MAX_ATTEMPTS = 5;
+function hmac(code, secret) {
+	return createHmac("sha256", secret).update(code).digest("hex");
+}
+/** CSPRNG numeric code with no modulo bias (`randomInt` rejection-samples). */
+function generateCode(length) {
+	let code = "";
+	for (let i = 0; i < length; i += 1) code += randomInt(0, 10).toString();
+	return code;
+}
+/** Constant-time compare of two equal-length hex digests. */
+function constantTimeEqualHex(a, b) {
+	const ab = Buffer.from(a, "hex");
+	const bb = Buffer.from(b, "hex");
+	return ab.length === bb.length && timingSafeEqual(ab, bb);
+}
+/**
+* Mint a challenge + its one-time code. Persist `challenge`; hand `code` to the
+* delivery layer. The code exists only in this return value and in the delivered
+* message — it is never recoverable from the persisted challenge.
+*/
+function createOtpChallenge(options) {
+	if (!options.secret) throw new Error("[otp] a `secret` is required to HMAC the code.");
+	const length = options.length ?? DEFAULT_LENGTH;
+	if (length < 4) throw new Error("[otp] `length` must be at least 4 digits.");
+	const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+	if (ttlMs <= 0) throw new Error("[otp] `ttlMs` must be positive.");
+	const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+	if (maxAttempts < 1) throw new Error("[otp] `maxAttempts` must be at least 1.");
+	const now = options.now ?? /* @__PURE__ */ new Date();
+	const code = generateCode(length);
+	return {
+		code,
+		challenge: {
+			hash: hmac(code, options.secret),
+			expiresAt: new Date(now.getTime() + ttlMs).toISOString(),
+			attempts: 0,
+			maxAttempts,
+			status: "pending"
+		}
+	};
+}
+/**
+* Check `input` against a persisted challenge and return the next state. This is
+* a pure transition — the caller persists `result.challenge`. Fail-closed: any
+* non-`pending` challenge, an expired window, or an over-limit attempt yields a
+* non-`verified` outcome and never re-opens a settled challenge.
+*/
+function verifyOtpChallenge(challenge, input, options) {
+	if (!options.secret) throw new Error("[otp] a `secret` is required to verify the code.");
+	if (challenge.status === "verified") return {
+		challenge,
+		outcome: "already_used"
+	};
+	if (challenge.status === "failed") return {
+		challenge,
+		outcome: "locked"
+	};
+	if (challenge.status === "expired") return {
+		challenge,
+		outcome: "expired"
+	};
+	if ((options.now ?? /* @__PURE__ */ new Date()).getTime() > Date.parse(challenge.expiresAt)) return {
+		challenge: {
+			...challenge,
+			status: "expired"
+		},
+		outcome: "expired"
+	};
+	if (constantTimeEqualHex(hmac(input, options.secret), challenge.hash)) return {
+		challenge: {
+			...challenge,
+			status: "verified"
+		},
+		outcome: "verified"
+	};
+	const attempts = challenge.attempts + 1;
+	if (attempts >= challenge.maxAttempts) return {
+		challenge: {
+			...challenge,
+			attempts,
+			status: "failed"
+		},
+		outcome: "locked"
+	};
+	return {
+		challenge: {
+			...challenge,
+			attempts
+		},
+		outcome: "incorrect"
+	};
+}
+/** True once a challenge has been successfully verified. */
+function isOtpVerified(challenge) {
+	return challenge.status === "verified";
+}
+/** True while a challenge can still accept an attempt (pending + unexpired). */
+function isOtpActive(challenge, now = /* @__PURE__ */ new Date()) {
+	return challenge.status === "pending" && now.getTime() <= Date.parse(challenge.expiresAt);
+}
+//#endregion
+export { createOtpChallenge, isOtpActive, isOtpVerified, verifyOtpChallenge };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",
@@ -97,6 +97,14 @@
       "types": "./dist/person.d.mts",
       "default": "./dist/person.mjs"
     },
+    "./identity-verification": {
+      "types": "./dist/identity-verification.d.mts",
+      "default": "./dist/identity-verification.mjs"
+    },
+    "./otp": {
+      "types": "./dist/otp.d.mts",
+      "default": "./dist/otp.mjs"
+    },
     "./state-machine": {
       "types": "./dist/state-machine.d.mts",
       "default": "./dist/state-machine.mjs"