Class BbasManager

BbasManager — bot blocking and anti-scrape plugin for the FP-Devicer Suite.

Computes a botScore (0–100) from three signal tiers:

UA analysis — headless browsers, scrapers, HTTP clients
Header anomaly detection — missing browser headers, debug headers
Request velocity — sliding-window rate limiting per device
Cross-plugin correlation — ip-devicer / tls-devicer / peer-devicer signals (Pro/Enterprise only)

A configurable rule engine translates the score into a BotDecision (allow | challenge | block).

Integration

// Register ip-devicer and tls-devicer FIRST so cross-plugin signals are
// available when bbas-devicer runs.
ipManager.registerWith(deviceManager);
tlsManager.registerWith(deviceManager);
peerManager.registerWith(deviceManager);
bbasManager.registerWith(deviceManager);

const result = await deviceManager.identify(req.body, req.bbasContext);
// result.bbasDecision — 'allow' | 'challenge' | 'block'
// result.bbasEnrichment — full enrichment payload

Implements

DeviceManagerPlugin

Index

Constructors

constructor

new BbasManager(options?: BbasManagerOptions): BbasManager
Create a BBAS manager with optional scoring, rule, storage, and license configuration.

When a license key is supplied the constructor optimistically uses the paid-tier history depth until init validates the key. If validation fails, the instance falls back to the free-tier limits.
Parameters
- options: BbasManagerOptions = {}
  Optional runtime configuration.
  
  Options accepted by the BbasManager constructor.
  - OptionalblockThreshold?: number
    Bot score threshold at which requests are blocked. Default: 75.
  - OptionalchallengeThreshold?: number
    Bot score threshold at which requests are challenged. Default: 50.
  - OptionalenableBehavioralAnalysis?: boolean
    Enable advanced behavioral biometrics analysis (mouse/typing dynamics). Session-level behavioral heuristics still run when metrics are present. Advanced analysis requires Pro or Enterprise. Default: true.
  - OptionalenableCrossPlugin?: boolean
    Enable cross-plugin signal enrichment from ip-devicer, tls-devicer, and peer-devicer. Requires Pro or Enterprise license. Default: true.
  - OptionalenableUaAnalysis?: boolean
    Enable user-agent analysis. Default: true.
  - OptionalenableVelocity?: boolean
    Enable request velocity tracking. Default: true.
  - OptionallicenseKey?: string
    Polar license key that unlocks Pro or Enterprise tier features.
    
    Tier Price Device limit Servers
    
    Free $0/mo 10,000 —
    
    Pro $49/mo Unlimited 1 server
    
    Enterprise $299/mo Unlimited Unlimited
    
    Cross-plugin signal enrichment (enableCrossPlugin) requires Pro or Enterprise. Obtain a key at https://polar.sh.
  - OptionalmaxHistoryPerDevice?: number
    Maximum number of BBAS snapshots stored per device. Default: 50 (Pro/Enterprise) or 10 (free tier).
  - OptionalmaxRequestsPerWindow?: number
    Maximum allowed requests per velocityWindowMs before the velocity signal fires. Default: 120.
  - Optionalrules?: BbasRule[]
    Custom rules to merge with the default rule set. Custom rules are evaluated before default rules when their priority is < 100. See BbasRule.
  - Optionalstorage?: BbasStorage | AsyncBbasStorage
    Custom storage backend. Defaults to the built-in in-memory store. Use createSqliteBbasStorage, createPostgresBbasStorage, or createRedisBbasStorage for persistent backends.
  - OptionalvelocityWindowMs?: number
    Length of the request velocity sliding window in milliseconds. Default: 60_000 (1 minute).
Returns BbasManager
- Defined in core/BbasManager.ts:178

Tier	Price	Device limit	Servers
Free	$0/mo	10,000	—
Pro	$49/mo	Unlimited	1 server
Enterprise	$299/mo	Unlimited	Unlimited

Accessors

tier

get tier(): LicenseTier
Active license tier. Resolves to 'free' until init completes.

Returns LicenseTier
- Defined in core/BbasManager.ts:211

Methods

analyze

analyze(
    deviceId: string,
    context: BbasIdentifyContext,
    crossPlugin?: CrossPluginSignals,
    behavioralMetrics?: BehavioralMetrics,
): Promise<{ decision: BotDecision; enrichment: BbasEnrichment }>
Analyse a request for bot signals and return the enrichment + decision.

Call this directly or let registerWith call it automatically via the DeviceManager post-processor pipeline.
Parameters
- deviceId: string
  The deviceId resolved by fp-devicer.
- context: BbasIdentifyContext
  Request context (IP, headers, userId).
- OptionalcrossPlugin: CrossPluginSignals
  Pre-extracted cross-plugin signals (optional; populated automatically in the post-processor path).
- OptionalbehavioralMetrics: BehavioralMetrics
Returns Promise<{ decision: BotDecision; enrichment: BbasEnrichment }>
- Defined in core/BbasManager.ts:270

close

close(): Promise<void>
Release storage connections.

Returns Promise<void>
- Defined in core/BbasManager.ts:452

getHistory

getHistory(deviceId: string, limit?: number): Promise<BbasSnapshot[]>
Return the stored BBAS snapshot history for a device.
Parameters
- deviceId: string
- Optionallimit: number
Returns Promise<BbasSnapshot[]>
- Defined in core/BbasManager.ts:392

init

init(): Promise<void>
Initialise the manager and validate the Polar license key if supplied.

Call once at application startup. Safe to await multiple times — subsequent calls return the cached promise.

Returns Promise<void>
- Defined in core/BbasManager.ts:223

registerWith

registerWith(deviceManager: DeviceManagerLike): void | (() => void)
Register this BbasManager as a DeviceManager post-processor plugin.

Plugin ordering matters. Register ip-devicer, tls-devicer, and peer-devicer before calling this method so that their signals are available in result.enrichmentInfo.details when bbas-devicer runs.
Parameters
- deviceManager: DeviceManagerLike
Returns void | (() => void)
Implementation of DeviceManagerPlugin.registerWith
- Defined in core/BbasManager.ts:404

Class BbasManager

Integration

Implements

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

OptionalblockThreshold?: number

OptionalchallengeThreshold?: number

OptionalenableBehavioralAnalysis?: boolean

OptionalenableCrossPlugin?: boolean

OptionalenableUaAnalysis?: boolean

OptionalenableVelocity?: boolean

OptionallicenseKey?: string

OptionalmaxHistoryPerDevice?: number

OptionalmaxRequestsPerWindow?: number

Optionalrules?: BbasRule[]

Optionalstorage?: BbasStorage | AsyncBbasStorage

OptionalvelocityWindowMs?: number

Returns BbasManager

Accessors

tier

Returns LicenseTier

Methods

analyze

Parameters

Returns Promise<{ decision: BotDecision; enrichment: BbasEnrichment }>

close

Returns Promise<void>

getHistory

Parameters

Returns Promise<BbasSnapshot[]>

init

Returns Promise<void>

registerWith

Parameters

Returns void | (() => void)

Settings

On This Page

`Optional`blockThreshold?: number

`Optional`challengeThreshold?: number

`Optional`enableBehavioralAnalysis?: boolean

`Optional`enableCrossPlugin?: boolean

`Optional`enableUaAnalysis?: boolean

`Optional`enableVelocity?: boolean

`Optional`licenseKey?: string

`Optional`maxHistoryPerDevice?: number

`Optional`maxRequestsPerWindow?: number

`Optional`rules?: BbasRule[]

`Optional`storage?: BbasStorage | AsyncBbasStorage

`Optional`velocityWindowMs?: number