export interface Challenge { codeChallenge?: CodeChallenge; parameters: ChallengeParameters; signature?: string; } export interface ChallengeParameters { algorithm: string; nonce: string; salt: string; cost: number; keyLength: number; keyPrefix: string; keySignature?: string; memoryCost?: number; parallelism?: number; expiresAt?: number; data?: Record; } export interface CodeChallenge { image: string; audio?: string; length?: number; } export interface CreateChallengeOptions { /** * Key derivation algorithm used for the challenge. The built-in `deriveKey` functions accept * exactly `'SHA-256'`, `'SHA-384'`, `'SHA-512'`, `'PBKDF2/SHA-256'`, `'PBKDF2/SHA-384'`, * `'PBKDF2/SHA-512'`, `'SCRYPT'` and `'ARGON2ID'` (each its own), and throw for anything else. */ algorithm: string; /** * Randomly selected integer used as the starting counter in deterministic mode. * Must be an integer from 0 to 2^32 - 1 (`'uint32'`) or `Number.MAX_SAFE_INTEGER` (`'string'`); throws otherwise. */ counter?: number; /** * Encoding format for the counter value. * V2 uses `'uint32'`; `'string'` is supported for backward compatibility with V1. */ counterMode?: 'uint32' | 'string'; /** * Algorithm-specific cost parameter controlling computational difficulty * (e.g., iteration count for PBKDF2, time cost for Argon2id). */ cost: number; /** * Arbitrary key-value metadata embedded in the challenge. */ data?: Record; /** * Algorithm-specific key derivation function used to generate challenge keys. */ deriveKey: DeriveKeyFunction; /** * Timestamp in seconds or Date after which the challenge is no longer valid. */ expiresAt?: number | Date; /** * HMAC digest algorithm used for signing challenges. * Defaults to `'SHA-256'`. */ hmacAlgorithm?: HmacAlgorithm; /** * HMAC secret used to sign derived keys in deterministic mode. * Requires `hmacSignatureSecret`. Throws if empty. */ hmacKeySignatureSecret?: string; /** * HMAC secret used to sign the challenge payload. * Omit to create an unsigned challenge; throws if empty or `null`. */ hmacSignatureSecret?: string; /** * Length of the derived key in bytes. * Defaults to `32`. */ keyLength?: number; /** * Required prefix that the derived key must match for the challenge to be solved. * Defaults to `'00'`. Must be a non-empty hex string no longer than the key (`2 × keyLength` characters); throws otherwise. * Lowercased before signing. Replaced by the derived prefix when `counter` is set. */ keyPrefix?: string; /** * Number of bytes from the derived key used as the prefix in deterministic mode. * Defaults to `floor(keyLength / 2)`. Must be a positive integer smaller than the * derived key length (throws otherwise); values above half the derived key are capped at half. */ keyPrefixLength?: number; /** * Algorithm-specific memory cost in KiB (applicable to Argon2id and scrypt). */ memoryCost?: number; /** * Algorithm-specific parallelism setting controlling the parallelism * (applicable to Argon2id and scrypt). */ parallelism?: number; } export type DeriveKeyFunction = (parameters: ChallengeParameters, salt: Uint8Array, password: Uint8Array) => Promise; export interface DeriveKeyFunctionResult { parameters?: Partial; derivedKey: Uint8Array; } export declare enum HmacAlgorithm { SHA_256 = "SHA-256", SHA_384 = "SHA-384", SHA_512 = "SHA-512" } export interface Payload { challenge: Omit; solution: Solution; } export interface PayloadV1 { algorithm: string; challenge: string; number: number; salt: string; signature?: string; took: number; } export interface SetCookieOptions { domain?: string; name?: string; maxAge?: number; path?: string; sameSite?: string; secure?: boolean; } export type ServerClassification = 'BAD' | 'GOOD' | 'NEUTRAL'; export interface ServerSignaturePayload { algorithm: string; apiKey?: string; id?: string; signature: string; verificationData: string; verified: boolean; } /** * Parsed `verificationData`, keyed by the flat form field names Sentinel signs * (e.g. `data['device.browser']`), for both local and remote verification. */ export interface ServerSignatureVerificationData { [key: string]: string | unknown; classification?: ServerClassification; email?: string; expire?: number; fields?: string[]; fieldsHash?: string; id?: string; ipAddress?: string; reasons?: string[]; score?: number; time?: number; verified?: boolean; } export interface ServerVerificationResult { algorithm?: string; apiKey?: string; id?: string; payload?: string; reason?: string; score?: number; signature?: string; verificationData?: string; verified?: boolean; } export interface SolveChallengeOptions { /** * Challenge object to solve, either decoded from a server payload * or as originally returned by `createChallenge`. */ challenge: Challenge; /** * AbortController for cancelling the solve operation before completion. */ controller?: AbortController; /** * Initial counter value to begin iterating from. * Useful for resuming or partitioning work across multiple solvers. */ counterStart?: number; /** * Increment between counter attempts. * Defaults to `1`. */ counterStep?: number; /** * Encoding format for the counter value. * V2 uses `'uint32'`; `'string'` is supported for backward compatibility with V1. */ counterMode?: 'uint32' | 'string'; /** * Algorithm-specific key derivation function used to compute candidate keys * for each counter value until a match is found. */ deriveKey: DeriveKeyFunction; /** * Maximum time in milliseconds before the solve attempt is aborted. * Defaults to `90_000` (90 seconds). */ timeout?: number; } export interface Strings { ariaLinkLabel: string; enterCode: string; enterCodeAria: string; error: string; expired: string; footer: string; getAudioChallenge: string; label: string; loading: string; reload: string; verify: string; verificationRequired: string; verified: string; verifying: string; waitAlert: string; } export declare enum State { CODE = "code", ERROR = "error", VERIFIED = "verified", VERIFYING = "verifying", UNVERIFIED = "unverified", EXPIRED = "expired" } export interface Solution { counter: number; derivedKey: string; time?: number; } export interface VerifyOptions { concurrency?: number; controller?: AbortController; minDuration?: number; } export interface VerifyResult { challenge?: Challenge; payload: string; solution?: Solution; } export interface VerifyServerSignatureResult extends VerifySolutionResult { verificationData?: ServerSignatureVerificationData | null; } export interface VerifyServerApiKey { /** * API key id (`key_...`). */ id: string; /** * API key secret. */ secret: string; } export interface VerifyServerOptions { /** * The payload to verify, as received from `POST /v2/verify` (Sentinel v2) or * `POST /v1/verify` (Sentinel v1), either the raw string or the decoded object. */ payload: string | ServerSignaturePayload | Record; /** * Full URL of the Sentinel verify signature endpoint: `/v2/verify/signature` * (Sentinel v2, with `apiKey`) or `/v1/verify/signature` (Sentinel v1, with optional `secret`). */ url: string; /** * Restricted or full API key of the account that owns the payload's API key, sent as * `Authorization: Basic base64(id:secret)`. Required by Sentinel v2's `/v2/verify/signature`. */ apiKey?: VerifyServerApiKey; /** * API key secret, sent in the request body. Only for a v1 Sentinel's * `/v1/verify/signature`, which checks it against the payload's API key. * Not sent when `apiKey` is set; Sentinel v2 rejects it on `/v2`. */ secret?: string; /** * Custom fetch implementation. Defaults to the global `fetch`. */ fetch?: typeof fetch; /** * Additional headers to send with the request. Override the `Authorization` header * set from `apiKey`. */ headers?: Record; /** * AbortController for cancelling the verification request. */ controller?: AbortController; /** * Per-attempt request timeout in milliseconds. * Defaults to `10_000` (10 seconds). */ timeout?: number; /** * Number of retry attempts after the first try. Network errors, timeouts and 5xx * responses are retried; 4xx responses are not. */ retries?: number; /** * Base delay in milliseconds between retry attempts. * Defaults to `300`. */ retryDelay?: number; /** * Backoff strategy applied to `retryDelay` between retries. * Defaults to `'exponential'`. */ retryBackoff?: 'fixed' | 'exponential'; } export interface VerifyServerResult { apiKey?: string | null; /** * Why verification failed: Sentinel's `reason` (e.g. `PAYLOAD_ALREADY_USED`), the * `code` of an error response (e.g. `UNAUTHORIZED`), `HTTP_`, `ABORTED` * or a network error message. */ reason?: string; /** * Verification data returned by Sentinel, flattened to the same shape as * `verifyServerSignature` returns (`data['device.browser']`). */ verificationData?: ServerSignatureVerificationData | null; verified: boolean; } export interface VerifySolutionOptions { /** * Challenge object to verify against, either decoded from the client payload * or as originally returned by `createChallenge`. */ challenge: Challenge; /** * Encoding format for the counter value. * V2 uses `'uint32'`; `'string'` is supported for backward compatibility with V1. */ counterMode?: 'uint32' | 'string'; /** * Algorithm-specific key derivation function used to recompute the expected key * during verification. */ deriveKey: DeriveKeyFunction; /** * HMAC digest algorithm used when verifying challenge signatures. * Defaults to `'SHA-256'`. */ hmacAlgorithm?: HmacAlgorithm; /** * HMAC secret used to verify derived-key signatures in deterministic mode. */ hmacKeySignatureSecret?: string; /** * HMAC secret used to verify the challenge payload signature. */ hmacSignatureSecret: string; /** * Solution object to validate, either decoded from the client payload * or as returned by `solveChallenge`. */ solution: Solution; } export interface VerifySolutionResult { expired: boolean; invalidSignature: boolean | null; invalidSolution: boolean | null; time: number; verified: boolean; }