Class DeviceManager

High-level device identification service.

DeviceManager orchestrates the full fingerprint matching pipeline:

Pre-filter – calls adapter.findCandidates() to retrieve a small set of candidate devices whose stored fingerprints are broadly similar to the incoming data.
Full scoring – re-scores each candidate against its most-recent stored snapshot using calculateConfidence.
Decision – if the best candidate exceeds matchThreshold, its device ID is reused; otherwise a new UUID-based device ID is minted.
Persistence – saves the incoming snapshot via adapter.save().
Observability – emits structured log lines and records metrics through the injected Logger and Metrics instances.

Example

const manager = new DeviceManager(adapter, { matchThreshold: 50 });
const result = await manager.identify(fingerprintData, { userId: 'u_123' });
console.log(result.deviceId, result.confidence);

Index

Constructors

constructor

Methods

analyzeDeviceDrift buildLshIndex clearDedupCache findRelatedDevices getIdentityGraph getLshIndexSize getMetricsSummary getPlugins identify identifyMany registerIdentifyPostProcessor use

Constructors

constructor

new DeviceManager(
    adapter: StorageAdapter,
    context?: {
        candidateMinScore?: number;
        dedupWindowMs?: number;
        matchThreshold?: number;
        stabilityWindowSize?: number;
    } & ObservabilityOptions,
): DeviceManager
Parameters
- adapter: StorageAdapter
  Storage backend used for all persistence operations.
- context: {
      candidateMinScore?: number;
      dedupWindowMs?: number;
      matchThreshold?: number;
      stabilityWindowSize?: number;
  } & ObservabilityOptions = {}
  Optional tuning parameters and observability overrides.
  - OptionalcandidateMinScore?: number
    Minimum score (0–100) passed to the adapter's pre-filter step. Defaults to 30.
  - OptionaldedupWindowMs?: number
    Dedup window in ms; repeated identifies within this window skip DB writes. Default 5000. Set 0 to disable.
  - OptionalmatchThreshold?: number
    Minimum confidence score (0–100) required to consider two fingerprints the same device. Defaults to 50.
  - OptionalstabilityWindowSize?: number
    Number of historical snapshots used for adaptive weight computation. Default 5.
  Optional observability overrides passed to DeviceManager. When omitted, defaultLogger and defaultMetrics are used.
  - Optionallogger?: Logger
  - Optionalmetrics?: Metrics
Returns DeviceManager
- Defined in core/DeviceManager.ts:155

Methods

analyzeDeviceDrift

analyzeDeviceDrift(
    deviceId: string,
    incoming: FPUserDataSet,
    options?: DriftAnalysisOptions,
): Promise<DriftReport | null>
Analyse how anomalous an incoming fingerprint is relative to a known device's historical baseline.

For each tracked fingerprint field, a z-score analog is computed as deviation / (1 – historicalStability + ε). Fields that have been historically stable yet are now different receive a high z-score and are listed in DriftReport.suspiciousFields. The aggregate driftScore is a weighted average of all per-field z-scores, normalised to [0, 100].

A DriftReport is classified into one of four patterns:
- NORMAL_AGING – score < 30; expected gradual change
- INCREMENTAL_DRIFT – score 30–54; broad multi-field change
- ABRUPT_CHANGE – score 55–74; concentrated in few fields
- CANONICAL_INJECTION – score ≥ 75 + high attractor risk; evasion signal
Parameters
- deviceId: string
  The stable device identifier to measure against.
- incoming: FPUserDataSet
  The new fingerprint to evaluate.
- Optionaloptions: DriftAnalysisOptions
  Optional overrides for window size and z-score threshold.
Returns Promise<DriftReport | null>
A DriftReport, or null if no history exists for the device.
- Defined in core/DeviceManager.ts:578

buildLshIndex

buildLshIndex(options?: LshOptions): Promise<void>
Build (or rebuild) the in-memory LSH candidate index from all snapshots currently held by the storage adapter.

When the index is present, every identify call merges LSH-derived candidates with those returned by the adapter's own pre-filter, giving a higher recall for devices whose similarity is concentrated in set-valued fields (fonts, plugins, mimeTypes, languages) that the adapter pre-filter may not consider.

The method subscribes to O(n) storage reads; avoid calling it on very large datasets without pagination/sampling. The index is not kept in sync automatically — call buildLshIndex again after significant dataset growth, or after bulk imports.
Parameters
- Optionaloptions: LshOptions
  Optional LSH tuning parameters.
Returns Promise<void>
- Defined in core/DeviceManager.ts:635

clearDedupCache

clearDedupCache(): void
Clear the deduplication cache immediately. Useful in tests or after a forced re-identification.

Returns void
- Defined in core/DeviceManager.ts:540

findRelatedDevices

findRelatedDevices(deviceId: string): RelatedDevice[]
Return the list of devices that are related to deviceId via the in-process identity graph, sorted by descending edge weight.

Edges are built from two signal types observed during identify() calls:
- shared-ip-subnet: two devices seen from the same IPv4 /24 subnet.
- font-overlap: two distinct devices with ≥ 80 % Jaccard font similarity in a session where they were both scored but only one matched.
Parameters
- deviceId: string
  The device to look up.
Returns RelatedDevice[]
An array of RelatedDevice, or an empty array if no edges are known for this device.
- Defined in core/DeviceManager.ts:604

getIdentityGraph

getIdentityGraph(): IdentityGraph
Return the internal IdentityGraph instance.

Useful for inspecting raw edges, serialising graph state, or pruning stale edges via IdentityGraph.prune.

Returns IdentityGraph
- Defined in core/DeviceManager.ts:614

getLshIndexSize

getLshIndexSize(): number | undefined
Return the number of devices currently indexed in the LSH index, or undefined if buildLshIndex has not yet been called.

Returns number | undefined
- Defined in core/DeviceManager.ts:660

getMetricsSummary

getMetricsSummary(): Record<string, any> | null
Return the metrics summary from the current metrics sink, if supported.

Returns Record<string, any> | null
The object returned by metrics.getSummary(), or null if the current metrics implementation does not expose a summary.
- Defined in core/DeviceManager.ts:550

getPlugins

getPlugins(): readonly DeviceManagerPlugin[]
Returns the list of currently registered plugins (those not yet unregistered).

Returns readonly DeviceManagerPlugin[]
- Defined in core/DeviceManager.ts:276

identify

identify(
incoming: FPUserDataSet,
context?: IdentifyContext,
): Promise<IdentifyResult>
Identify a device from an incoming fingerprint dataset.

Runs the full pre-filter → score → decide → save pipeline and emits observability signals before returning.
- Dedup cache – if the same fingerprint hash is seen within dedupWindowMs, the cached result is returned without a DB write.
- Adaptive weights – when a candidate has ≥ 2 historical snapshots, per-field stability is measured and low-stability fields are down-weighted before the full confidence score is computed.
Parameters
- incoming: FPUserDataSet
  The fingerprint data collected from the current request.
- Optionalcontext: IdentifyContext
  Optional per-request context.
Returns Promise<IdentifyResult>
An object describing the resolved device.
- Defined in core/DeviceManager.ts:339

identifyMany

identifyMany(
incomingList: FPUserDataSet[],
context?: IdentifyContext,
): Promise<IdentifyResult[]>
Identify multiple devices in a batch.
Parameters
- incomingList: FPUserDataSet[]
  An array of fingerprint data sets to identify.
- Optionalcontext: IdentifyContext
  Optional context including userId and IP address.
Returns Promise<IdentifyResult[]>
A promise that resolves to an array of identification results.
- Defined in core/DeviceManager.ts:527

registerIdentifyPostProcessor

registerIdentifyPostProcessor(
name: string,
processor: IdentifyPostProcessor,
): () => void
Register a named post-processor that runs after the core identify decision.

Processors are executed in registration order. The returned teardown function unregisters only this exact (name, processor) pair.
Parameters
- name: string
  Stable plugin name used for enrichment and log metadata.
- processor: IdentifyPostProcessor
  Callback that can enrich the identify result.
Returns () => void
A function that unregisters the processor.
- Defined in core/DeviceManager.ts:250

use

use(plugin: DeviceManagerPlugin): () => void
Register a plugin with this DeviceManager.

The plugin's DeviceManagerPlugin.registerWith method is called immediately with this instance. Returns an unregister function that removes the plugin and calls any teardown returned by registerWith.
Parameters
- plugin: DeviceManagerPlugin
  Any object implementing DeviceManagerPlugin.
Returns () => void
A () => void that unregisters the plugin.
- Defined in core/DeviceManager.ts:269

Class DeviceManager

Example

Index

Constructors

Methods

Constructors

constructor

Parameters

OptionalcandidateMinScore?: number

OptionaldedupWindowMs?: number

OptionalmatchThreshold?: number

OptionalstabilityWindowSize?: number

Optionallogger?: Logger

Optionalmetrics?: Metrics

Returns DeviceManager

Methods

analyzeDeviceDrift

Parameters

Returns Promise<DriftReport | null>

buildLshIndex

Parameters

Returns Promise<void>

clearDedupCache

Returns void

findRelatedDevices

Parameters

Returns RelatedDevice[]

getIdentityGraph

Returns IdentityGraph

getLshIndexSize

Returns number | undefined

getMetricsSummary

Returns Record<string, any> | null

getPlugins

Returns readonly DeviceManagerPlugin[]

identify

Parameters

Returns Promise<IdentifyResult>

identifyMany

Parameters

Returns Promise<IdentifyResult[]>

registerIdentifyPostProcessor

Parameters

Returns () => void

use

Parameters

Returns () => void

Settings

On This Page

`Optional`candidateMinScore?: number

`Optional`dedupWindowMs?: number

`Optional`matchThreshold?: number

`Optional`stabilityWindowSize?: number

`Optional`logger?: Logger

`Optional`metrics?: Metrics