devn-bot-detector-core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,312 @@
+/** Default session lifetime (30 minutes). */
+declare const DEFAULT_SESSION_DURATION_MS: number;
+/** Default client telemetry flush interval. */
+declare const DEFAULT_TELEMETRY_INTERVAL_MS = 5000;
+/** Soft max size for a telemetry JSON payload. */
+declare const MAX_TELEMETRY_BYTES: number;
+/** Default risk token lifetime (5 minutes). */
+declare const DEFAULT_RISK_TOKEN_DURATION_MS: number;
+/** Protocol version embedded in telemetry. */
+declare const TELEMETRY_VERSION: 1;
+/** HTTP header for the public site key. */
+declare const SITE_KEY_HEADER = "X-Bot-Site-Key";
+/** API path suffixes (relative to endpoint base). */
+declare const API_PATHS: {
+    readonly session: "/v1/session";
+    readonly analyze: "/v1/analyze";
+};
+/**
+ * Default human-score thresholds (higher = more human-like).
+ * allow >= 70, monitor >= 50, challenge >= 30, block < 30
+ */
+declare const DEFAULT_RISK_THRESHOLDS: {
+    readonly allow: 70;
+    readonly monitor: 50;
+    readonly challenge: 30;
+};
+declare const ERROR_CODES: readonly ["INVALID_SITE_KEY", "INVALID_HOSTNAME", "INVALID_SESSION", "SESSION_EXPIRED", "INVALID_NONCE", "INVALID_SEQUENCE", "RATE_LIMITED", "INVALID_TELEMETRY", "MALFORMED_REQUEST", "INTERNAL_ERROR", "IP_BLOCKED", "TOKEN_ALREADY_USED", "ACTION_MISMATCH"];
+type ErrorCode = (typeof ERROR_CODES)[number];
+
+type RiskDecision = 'allow' | 'monitor' | 'challenge' | 'block';
+type RiskLevel = 'low' | 'medium' | 'high';
+type SiteStatus = 'active' | 'disabled' | 'suspended';
+/** Aggregated browser environment signals (no cookies / storage / tokens). */
+interface BrowserSignals {
+    readonly userAgent: string;
+    readonly language: string;
+    readonly languagesLength: number;
+    readonly timezone: string;
+    readonly timezoneOffset: number;
+    readonly platform: string;
+    readonly screenWidth: number;
+    readonly screenHeight: number;
+    readonly colorDepth: number;
+    readonly devicePixelRatio: number;
+    readonly hardwareConcurrency: number | null;
+    readonly maxTouchPoints: number;
+    readonly cookieEnabled: boolean;
+    /** One risk signal among many — never decisive alone. */
+    readonly webdriver: boolean;
+    readonly webglRenderer?: string | null;
+    readonly webglVendor?: string | null;
+    readonly hasChrome?: boolean;
+    readonly pluginsCount?: number;
+    readonly screenOrientation?: string | null;
+}
+/** Aggregated pointer/mouse statistics (no raw coordinates retained). */
+interface PointerSignals {
+    readonly eventCount: number;
+    readonly movementDistance: number;
+    readonly averageInterval: number | null;
+    readonly minInterval: number | null;
+    readonly maxInterval: number | null;
+    readonly directionChanges: number;
+    readonly idlePeriods: number;
+    readonly activeDuration: number;
+    readonly clickCount: number;
+}
+/** Aggregated keyboard timing statistics (no keys / characters / codes). */
+interface KeyboardSignals {
+    readonly keydownCount: number;
+    readonly keyupCount: number;
+    readonly averageInterval: number | null;
+    readonly minInterval: number | null;
+    readonly maxInterval: number | null;
+    readonly timingVariance: number | null;
+    readonly pasteCount: number;
+}
+/** Aggregated touch statistics. */
+interface TouchSignals {
+    readonly touchCount: number;
+    readonly averageInterval: number | null;
+    readonly activeDuration: number;
+    readonly multiTouchCount: number;
+}
+/** Aggregated scroll statistics. */
+interface ScrollSignals {
+    readonly scrollCount: number;
+    readonly averageInterval: number | null;
+    readonly totalDistance: number;
+    readonly directionChanges: number;
+    readonly activeDuration: number;
+}
+/** Focus / blur statistics. */
+interface FocusSignals {
+    readonly focusCount: number;
+    readonly blurCount: number;
+}
+/** Page visibility statistics. */
+interface VisibilitySignals {
+    readonly visibilityChanges: number;
+    readonly visibleDuration: number;
+    readonly hiddenDuration: number;
+}
+/** High-level interaction timing (no form values). */
+interface InteractionSignals {
+    readonly pageLoadTime: number;
+    readonly firstInteractionTime: number | null;
+    readonly timeToFirstInteraction: number | null;
+    readonly clickCount: number;
+    readonly interactionCount: number;
+    readonly formInteractionCount: number;
+    readonly scrollCount: number;
+    readonly focusCount: number;
+}
+/** Privacy-safe aggregated telemetry payload. */
+interface Telemetry {
+    readonly version: 1;
+    readonly browser?: BrowserSignals;
+    readonly pointer?: PointerSignals;
+    readonly keyboard?: KeyboardSignals;
+    readonly touch?: TouchSignals;
+    readonly scroll?: ScrollSignals;
+    readonly focus?: FocusSignals;
+    readonly visibility?: VisibilitySignals;
+    readonly interaction?: InteractionSignals;
+}
+interface ClientSession {
+    readonly sessionId: string;
+    readonly nonce: string;
+    readonly createdAt: number;
+    readonly expiresAt: number;
+}
+interface SessionData {
+    readonly sessionId: string;
+    readonly siteKey: string;
+    readonly siteId: string;
+    readonly tenantId: string;
+    readonly nonce: string;
+    readonly createdAt: number;
+    readonly expiresAt: number;
+    readonly hostname: string;
+    /** Last accepted sequence number (replay protection). */
+    sequence: number;
+    /** Nonces already consumed for this session (short-lived). */
+    usedNonces: string[];
+}
+interface RequestContext {
+    readonly ip?: string;
+    readonly userAgent?: string;
+    readonly origin?: string;
+    readonly host?: string;
+    readonly forwardedFor?: string;
+}
+interface SiteInfo {
+    readonly siteId: string;
+    readonly tenantId: string;
+    readonly allowedDomains: readonly string[];
+    readonly status: SiteStatus;
+}
+interface RiskReason {
+    readonly code: string;
+    readonly weight: number;
+    readonly detail?: string;
+}
+interface RiskResult {
+    readonly requestId: string;
+    readonly score: number;
+    readonly confidence: number;
+    readonly decision: RiskDecision;
+    readonly riskLevel: RiskLevel;
+    readonly action?: string;
+    readonly riskToken?: string;
+    readonly expiresAt?: string;
+    readonly timestamp: number;
+}
+interface RiskConfig {
+    readonly allow: number;
+    readonly monitor: number;
+    readonly challenge: number;
+}
+type ClientCredentialsMode = 'omit' | 'same-origin' | 'include';
+interface ClientConfig {
+    readonly siteKey: string;
+    readonly endpoint: string;
+    readonly autoStart?: boolean;
+    readonly telemetryInterval?: number;
+    readonly sessionDuration?: number;
+    readonly collectPointer?: boolean;
+    readonly collectKeyboardTiming?: boolean;
+    readonly collectTouch?: boolean;
+    readonly collectScroll?: boolean;
+    readonly collectFocus?: boolean;
+    readonly collectVisibility?: boolean;
+    readonly collectBrowser?: boolean;
+    readonly failOpen?: boolean;
+    readonly maxTelemetryBytes?: number;
+    readonly debug?: boolean;
+    readonly headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+    readonly fetchFn?: typeof fetch;
+    readonly credentials?: ClientCredentialsMode;
+    readonly timeoutMs?: number;
+    readonly retries?: number;
+    readonly retryDelayMs?: number;
+    readonly sampleRate?: number;
+    readonly onSessionCreated?: (session: ClientSession) => void;
+    readonly onCheck?: (result: RiskResult) => void;
+    readonly onError?: (error: Error) => void;
+}
+interface ServerConfig {
+    readonly secret: string;
+    readonly sessionDuration?: number;
+    readonly riskThresholds?: Partial<RiskConfig>;
+    readonly actionThresholds?: Record<string, Partial<RiskConfig>>;
+    readonly ipAllowlist?: readonly string[];
+    readonly ipDenylist?: readonly string[];
+    readonly detectorWeights?: Record<string, number>;
+    readonly enableRiskToken?: boolean;
+    readonly riskTokenDuration?: number;
+    readonly trustProxy?: boolean;
+    readonly debug?: boolean;
+}
+interface ApiErrorBody {
+    readonly error: {
+        readonly code: ErrorCode;
+        readonly message: string;
+        readonly requestId: string;
+    };
+}
+interface CreateSessionRequest {
+    readonly hostname: string;
+    readonly userAgent?: string;
+    readonly timestamp: number;
+}
+interface CreateSessionResponse {
+    readonly sessionId: string;
+    readonly nonce: string;
+    readonly expiresAt: string;
+}
+interface AnalyzeRequest {
+    readonly sessionId: string;
+    readonly sequence: number;
+    readonly nonce?: string;
+    readonly timestamp: number;
+    readonly hostname: string;
+    readonly telemetry: Telemetry;
+    readonly action?: string;
+    readonly metadata?: Record<string, unknown>;
+}
+interface AnalyzeResponse extends RiskResult {
+}
+interface RateLimitResult {
+    readonly allowed: boolean;
+    readonly remaining: number;
+    readonly retryAfter?: number;
+}
+interface RiskTokenPayload {
+    readonly requestId: string;
+    readonly siteId: string;
+    readonly sessionId: string;
+    readonly decision: RiskDecision;
+    readonly issuedAt: number;
+    readonly expiresAt: number;
+    readonly action?: string;
+    readonly score?: number;
+}
+interface CheckOptions {
+    readonly action?: string;
+    readonly metadata?: Record<string, unknown>;
+}
+interface VerifyRiskTokenOptions {
+    readonly expectedAction?: string;
+    readonly maxAgeMs?: number;
+}
+interface TokenRevocationStore {
+    isRevoked(tokenId: string): Promise<boolean> | boolean;
+    revoke(tokenId: string, ttlMs: number): Promise<void> | void;
+}
+
+declare class BotDetectorError extends Error {
+    readonly code: ErrorCode;
+    readonly requestId: string;
+    constructor(code: ErrorCode, message: string, requestId: string);
+    toJSON(): ApiErrorBody;
+}
+declare function isBotDetectorError(value: unknown): value is BotDetectorError;
+
+declare function clamp(value: number, min: number, max: number): number;
+declare function decisionFromScore(score: number, thresholds?: RiskConfig): RiskDecision;
+declare function riskLevelFromScore(score: number): RiskLevel;
+declare function mergeRiskThresholds(partial?: Partial<RiskConfig>): RiskConfig;
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+declare function utf8ByteLength(value: string): number;
+/** Normalize hostname for allowlist comparison. */
+declare function normalizeHostname(hostname: string): string;
+/** Check whether hostname matches an allowed domain (exact or subdomain). */
+declare function hostnameAllowed(hostname: string, allowedDomains: readonly string[]): boolean;
+declare function extractHostnameFromOrigin(origin: string | undefined): string | null;
+/** Check whether an IP matches any entry in a list of exact IPs, wildcards, or IPv4 CIDR blocks. */
+declare function ipMatches(ip: string | undefined, patterns: readonly string[]): boolean;
+
+type ValidationResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+declare function validateTelemetry(raw: unknown, maxBytes?: number): ValidationResult<Telemetry>;
+declare function validateCreateSessionRequest(raw: unknown): ValidationResult<CreateSessionRequest>;
+declare function validateAnalyzeRequest(raw: unknown, maxBytes?: number): ValidationResult<AnalyzeRequest>;
+
+export { API_PATHS, type AnalyzeRequest, type AnalyzeResponse, type ApiErrorBody, BotDetectorError, type BrowserSignals, type CheckOptions, type ClientConfig, type ClientCredentialsMode, type ClientSession, type CreateSessionRequest, type CreateSessionResponse, DEFAULT_RISK_THRESHOLDS, DEFAULT_RISK_TOKEN_DURATION_MS, DEFAULT_SESSION_DURATION_MS, DEFAULT_TELEMETRY_INTERVAL_MS, ERROR_CODES, type ErrorCode, type FocusSignals, type InteractionSignals, type KeyboardSignals, MAX_TELEMETRY_BYTES, type PointerSignals, type RateLimitResult, type RequestContext, type RiskConfig, type RiskDecision, type RiskLevel, type RiskReason, type RiskResult, type RiskTokenPayload, SITE_KEY_HEADER, type ScrollSignals, type ServerConfig, type SessionData, type SiteInfo, type SiteStatus, TELEMETRY_VERSION, type Telemetry, type TokenRevocationStore, type TouchSignals, type ValidationResult, type VerifyRiskTokenOptions, type VisibilitySignals, clamp, decisionFromScore, extractHostnameFromOrigin, hostnameAllowed, ipMatches, isBotDetectorError, isPlainObject, mergeRiskThresholds, normalizeHostname, riskLevelFromScore, utf8ByteLength, validateAnalyzeRequest, validateCreateSessionRequest, validateTelemetry };

package/dist/index.d.ts

@@ -0,0 +1,312 @@
+/** Default session lifetime (30 minutes). */
+declare const DEFAULT_SESSION_DURATION_MS: number;
+/** Default client telemetry flush interval. */
+declare const DEFAULT_TELEMETRY_INTERVAL_MS = 5000;
+/** Soft max size for a telemetry JSON payload. */
+declare const MAX_TELEMETRY_BYTES: number;
+/** Default risk token lifetime (5 minutes). */
+declare const DEFAULT_RISK_TOKEN_DURATION_MS: number;
+/** Protocol version embedded in telemetry. */
+declare const TELEMETRY_VERSION: 1;
+/** HTTP header for the public site key. */
+declare const SITE_KEY_HEADER = "X-Bot-Site-Key";
+/** API path suffixes (relative to endpoint base). */
+declare const API_PATHS: {
+    readonly session: "/v1/session";
+    readonly analyze: "/v1/analyze";
+};
+/**
+ * Default human-score thresholds (higher = more human-like).
+ * allow >= 70, monitor >= 50, challenge >= 30, block < 30
+ */
+declare const DEFAULT_RISK_THRESHOLDS: {
+    readonly allow: 70;
+    readonly monitor: 50;
+    readonly challenge: 30;
+};
+declare const ERROR_CODES: readonly ["INVALID_SITE_KEY", "INVALID_HOSTNAME", "INVALID_SESSION", "SESSION_EXPIRED", "INVALID_NONCE", "INVALID_SEQUENCE", "RATE_LIMITED", "INVALID_TELEMETRY", "MALFORMED_REQUEST", "INTERNAL_ERROR", "IP_BLOCKED", "TOKEN_ALREADY_USED", "ACTION_MISMATCH"];
+type ErrorCode = (typeof ERROR_CODES)[number];
+
+type RiskDecision = 'allow' | 'monitor' | 'challenge' | 'block';
+type RiskLevel = 'low' | 'medium' | 'high';
+type SiteStatus = 'active' | 'disabled' | 'suspended';
+/** Aggregated browser environment signals (no cookies / storage / tokens). */
+interface BrowserSignals {
+    readonly userAgent: string;
+    readonly language: string;
+    readonly languagesLength: number;
+    readonly timezone: string;
+    readonly timezoneOffset: number;
+    readonly platform: string;
+    readonly screenWidth: number;
+    readonly screenHeight: number;
+    readonly colorDepth: number;
+    readonly devicePixelRatio: number;
+    readonly hardwareConcurrency: number | null;
+    readonly maxTouchPoints: number;
+    readonly cookieEnabled: boolean;
+    /** One risk signal among many — never decisive alone. */
+    readonly webdriver: boolean;
+    readonly webglRenderer?: string | null;
+    readonly webglVendor?: string | null;
+    readonly hasChrome?: boolean;
+    readonly pluginsCount?: number;
+    readonly screenOrientation?: string | null;
+}
+/** Aggregated pointer/mouse statistics (no raw coordinates retained). */
+interface PointerSignals {
+    readonly eventCount: number;
+    readonly movementDistance: number;
+    readonly averageInterval: number | null;
+    readonly minInterval: number | null;
+    readonly maxInterval: number | null;
+    readonly directionChanges: number;
+    readonly idlePeriods: number;
+    readonly activeDuration: number;
+    readonly clickCount: number;
+}
+/** Aggregated keyboard timing statistics (no keys / characters / codes). */
+interface KeyboardSignals {
+    readonly keydownCount: number;
+    readonly keyupCount: number;
+    readonly averageInterval: number | null;
+    readonly minInterval: number | null;
+    readonly maxInterval: number | null;
+    readonly timingVariance: number | null;
+    readonly pasteCount: number;
+}
+/** Aggregated touch statistics. */
+interface TouchSignals {
+    readonly touchCount: number;
+    readonly averageInterval: number | null;
+    readonly activeDuration: number;
+    readonly multiTouchCount: number;
+}
+/** Aggregated scroll statistics. */
+interface ScrollSignals {
+    readonly scrollCount: number;
+    readonly averageInterval: number | null;
+    readonly totalDistance: number;
+    readonly directionChanges: number;
+    readonly activeDuration: number;
+}
+/** Focus / blur statistics. */
+interface FocusSignals {
+    readonly focusCount: number;
+    readonly blurCount: number;
+}
+/** Page visibility statistics. */
+interface VisibilitySignals {
+    readonly visibilityChanges: number;
+    readonly visibleDuration: number;
+    readonly hiddenDuration: number;
+}
+/** High-level interaction timing (no form values). */
+interface InteractionSignals {
+    readonly pageLoadTime: number;
+    readonly firstInteractionTime: number | null;
+    readonly timeToFirstInteraction: number | null;
+    readonly clickCount: number;
+    readonly interactionCount: number;
+    readonly formInteractionCount: number;
+    readonly scrollCount: number;
+    readonly focusCount: number;
+}
+/** Privacy-safe aggregated telemetry payload. */
+interface Telemetry {
+    readonly version: 1;
+    readonly browser?: BrowserSignals;
+    readonly pointer?: PointerSignals;
+    readonly keyboard?: KeyboardSignals;
+    readonly touch?: TouchSignals;
+    readonly scroll?: ScrollSignals;
+    readonly focus?: FocusSignals;
+    readonly visibility?: VisibilitySignals;
+    readonly interaction?: InteractionSignals;
+}
+interface ClientSession {
+    readonly sessionId: string;
+    readonly nonce: string;
+    readonly createdAt: number;
+    readonly expiresAt: number;
+}
+interface SessionData {
+    readonly sessionId: string;
+    readonly siteKey: string;
+    readonly siteId: string;
+    readonly tenantId: string;
+    readonly nonce: string;
+    readonly createdAt: number;
+    readonly expiresAt: number;
+    readonly hostname: string;
+    /** Last accepted sequence number (replay protection). */
+    sequence: number;
+    /** Nonces already consumed for this session (short-lived). */
+    usedNonces: string[];
+}
+interface RequestContext {
+    readonly ip?: string;
+    readonly userAgent?: string;
+    readonly origin?: string;
+    readonly host?: string;
+    readonly forwardedFor?: string;
+}
+interface SiteInfo {
+    readonly siteId: string;
+    readonly tenantId: string;
+    readonly allowedDomains: readonly string[];
+    readonly status: SiteStatus;
+}
+interface RiskReason {
+    readonly code: string;
+    readonly weight: number;
+    readonly detail?: string;
+}
+interface RiskResult {
+    readonly requestId: string;
+    readonly score: number;
+    readonly confidence: number;
+    readonly decision: RiskDecision;
+    readonly riskLevel: RiskLevel;
+    readonly action?: string;
+    readonly riskToken?: string;
+    readonly expiresAt?: string;
+    readonly timestamp: number;
+}
+interface RiskConfig {
+    readonly allow: number;
+    readonly monitor: number;
+    readonly challenge: number;
+}
+type ClientCredentialsMode = 'omit' | 'same-origin' | 'include';
+interface ClientConfig {
+    readonly siteKey: string;
+    readonly endpoint: string;
+    readonly autoStart?: boolean;
+    readonly telemetryInterval?: number;
+    readonly sessionDuration?: number;
+    readonly collectPointer?: boolean;
+    readonly collectKeyboardTiming?: boolean;
+    readonly collectTouch?: boolean;
+    readonly collectScroll?: boolean;
+    readonly collectFocus?: boolean;
+    readonly collectVisibility?: boolean;
+    readonly collectBrowser?: boolean;
+    readonly failOpen?: boolean;
+    readonly maxTelemetryBytes?: number;
+    readonly debug?: boolean;
+    readonly headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+    readonly fetchFn?: typeof fetch;
+    readonly credentials?: ClientCredentialsMode;
+    readonly timeoutMs?: number;
+    readonly retries?: number;
+    readonly retryDelayMs?: number;
+    readonly sampleRate?: number;
+    readonly onSessionCreated?: (session: ClientSession) => void;
+    readonly onCheck?: (result: RiskResult) => void;
+    readonly onError?: (error: Error) => void;
+}
+interface ServerConfig {
+    readonly secret: string;
+    readonly sessionDuration?: number;
+    readonly riskThresholds?: Partial<RiskConfig>;
+    readonly actionThresholds?: Record<string, Partial<RiskConfig>>;
+    readonly ipAllowlist?: readonly string[];
+    readonly ipDenylist?: readonly string[];
+    readonly detectorWeights?: Record<string, number>;
+    readonly enableRiskToken?: boolean;
+    readonly riskTokenDuration?: number;
+    readonly trustProxy?: boolean;
+    readonly debug?: boolean;
+}
+interface ApiErrorBody {
+    readonly error: {
+        readonly code: ErrorCode;
+        readonly message: string;
+        readonly requestId: string;
+    };
+}
+interface CreateSessionRequest {
+    readonly hostname: string;
+    readonly userAgent?: string;
+    readonly timestamp: number;
+}
+interface CreateSessionResponse {
+    readonly sessionId: string;
+    readonly nonce: string;
+    readonly expiresAt: string;
+}
+interface AnalyzeRequest {
+    readonly sessionId: string;
+    readonly sequence: number;
+    readonly nonce?: string;
+    readonly timestamp: number;
+    readonly hostname: string;
+    readonly telemetry: Telemetry;
+    readonly action?: string;
+    readonly metadata?: Record<string, unknown>;
+}
+interface AnalyzeResponse extends RiskResult {
+}
+interface RateLimitResult {
+    readonly allowed: boolean;
+    readonly remaining: number;
+    readonly retryAfter?: number;
+}
+interface RiskTokenPayload {
+    readonly requestId: string;
+    readonly siteId: string;
+    readonly sessionId: string;
+    readonly decision: RiskDecision;
+    readonly issuedAt: number;
+    readonly expiresAt: number;
+    readonly action?: string;
+    readonly score?: number;
+}
+interface CheckOptions {
+    readonly action?: string;
+    readonly metadata?: Record<string, unknown>;
+}
+interface VerifyRiskTokenOptions {
+    readonly expectedAction?: string;
+    readonly maxAgeMs?: number;
+}
+interface TokenRevocationStore {
+    isRevoked(tokenId: string): Promise<boolean> | boolean;
+    revoke(tokenId: string, ttlMs: number): Promise<void> | void;
+}
+
+declare class BotDetectorError extends Error {
+    readonly code: ErrorCode;
+    readonly requestId: string;
+    constructor(code: ErrorCode, message: string, requestId: string);
+    toJSON(): ApiErrorBody;
+}
+declare function isBotDetectorError(value: unknown): value is BotDetectorError;
+
+declare function clamp(value: number, min: number, max: number): number;
+declare function decisionFromScore(score: number, thresholds?: RiskConfig): RiskDecision;
+declare function riskLevelFromScore(score: number): RiskLevel;
+declare function mergeRiskThresholds(partial?: Partial<RiskConfig>): RiskConfig;
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+declare function utf8ByteLength(value: string): number;
+/** Normalize hostname for allowlist comparison. */
+declare function normalizeHostname(hostname: string): string;
+/** Check whether hostname matches an allowed domain (exact or subdomain). */
+declare function hostnameAllowed(hostname: string, allowedDomains: readonly string[]): boolean;
+declare function extractHostnameFromOrigin(origin: string | undefined): string | null;
+/** Check whether an IP matches any entry in a list of exact IPs, wildcards, or IPv4 CIDR blocks. */
+declare function ipMatches(ip: string | undefined, patterns: readonly string[]): boolean;
+
+type ValidationResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+declare function validateTelemetry(raw: unknown, maxBytes?: number): ValidationResult<Telemetry>;
+declare function validateCreateSessionRequest(raw: unknown): ValidationResult<CreateSessionRequest>;
+declare function validateAnalyzeRequest(raw: unknown, maxBytes?: number): ValidationResult<AnalyzeRequest>;
+
+export { API_PATHS, type AnalyzeRequest, type AnalyzeResponse, type ApiErrorBody, BotDetectorError, type BrowserSignals, type CheckOptions, type ClientConfig, type ClientCredentialsMode, type ClientSession, type CreateSessionRequest, type CreateSessionResponse, DEFAULT_RISK_THRESHOLDS, DEFAULT_RISK_TOKEN_DURATION_MS, DEFAULT_SESSION_DURATION_MS, DEFAULT_TELEMETRY_INTERVAL_MS, ERROR_CODES, type ErrorCode, type FocusSignals, type InteractionSignals, type KeyboardSignals, MAX_TELEMETRY_BYTES, type PointerSignals, type RateLimitResult, type RequestContext, type RiskConfig, type RiskDecision, type RiskLevel, type RiskReason, type RiskResult, type RiskTokenPayload, SITE_KEY_HEADER, type ScrollSignals, type ServerConfig, type SessionData, type SiteInfo, type SiteStatus, TELEMETRY_VERSION, type Telemetry, type TokenRevocationStore, type TouchSignals, type ValidationResult, type VerifyRiskTokenOptions, type VisibilitySignals, clamp, decisionFromScore, extractHostnameFromOrigin, hostnameAllowed, ipMatches, isBotDetectorError, isPlainObject, mergeRiskThresholds, normalizeHostname, riskLevelFromScore, utf8ByteLength, validateAnalyzeRequest, validateCreateSessionRequest, validateTelemetry };