audit-device-tracker 0.1.0

package/dist/core/geo-distance.js

@@ -0,0 +1,10 @@
+const EARTH_RADIUS_KM = 6371;
+const toRadians = (degrees) => (degrees * Math.PI) / 180;
+/** Great-circle distance between two points on Earth (Haversine formula), in kilometres. */
+export function distanceKm(a, b) {
+    const dLat = toRadians(b.latitude - a.latitude);
+    const dLon = toRadians(b.longitude - a.longitude);
+    const h = Math.sin(dLat / 2) ** 2 +
+        Math.cos(toRadians(a.latitude)) * Math.cos(toRadians(b.latitude)) * Math.sin(dLon / 2) ** 2;
+    return 2 * EARTH_RADIUS_KM * Math.asin(Math.min(1, Math.sqrt(h)));
+}

package/dist/core/parser.d.ts

@@ -0,0 +1,7 @@
+import type { RequestContext, RequestLike } from '../types.js';
+export declare function extractIp(req: RequestLike): string;
+export declare function anonymizeIp(ip: string): string;
+export declare function readCookie(header: string, name: string): string | undefined;
+export declare function sign(value: string, secret: string): string;
+export declare function verify(signed: string | undefined, secret: string): string | null;
+export declare function buildContext(req: RequestLike, cookieName: string, secret: string, fingerprintHeader?: string): RequestContext;

package/dist/core/parser.js

@@ -0,0 +1,78 @@
+import Bowser from 'bowser';
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+import { DEFAULT_FINGERPRINT_HEADER } from '../constants.js';
+/** Node may give a header as string, string[] or undefined: normalise to string. */
+const first = (v) => Array.isArray(v) ? (v[0] ?? '') : (v ?? '');
+const CLIENT_FINGERPRINT_PATTERN = /^[a-f0-9]{16,64}$/i;
+export function extractIp(req) {
+    const forwarded = first(req.headers['x-forwarded-for']).split(',')[0]?.trim();
+    return req.ip || forwarded || req.socket?.remoteAddress || 'unknown';
+}
+export function anonymizeIp(ip) {
+    if (ip.includes(':'))
+        return ip.split(':').slice(0, 3).join(':') + '::';
+    const parts = ip.split('.');
+    return parts.length === 4 ? `${parts[0]}.${parts[1]}.${parts[2]}.0` : ip;
+}
+export function readCookie(header, name) {
+    for (const part of header.split(';')) {
+        const [key, ...value] = part.trim().split('=');
+        if (key === name)
+            return decodeURIComponent(value.join('='));
+    }
+    return undefined;
+}
+export function sign(value, secret) {
+    const signature = createHmac('sha256', secret).update(value).digest('base64url');
+    return `${value}.${signature}`;
+}
+export function verify(signed, secret) {
+    if (!signed)
+        return null;
+    const dot = signed.lastIndexOf('.');
+    if (dot < 1)
+        return null;
+    const value = signed.slice(0, dot);
+    const expected = Buffer.from(sign(value, secret));
+    const given = Buffer.from(signed);
+    return expected.length === given.length && timingSafeEqual(expected, given)
+        ? value
+        : null;
+}
+function toDeviceType(type) {
+    if (type === 'desktop' || type === 'mobile' || type === 'tablet' || type === 'bot') {
+        return type;
+    }
+    return 'unknown';
+}
+export function buildContext(req, cookieName, secret, fingerprintHeader = DEFAULT_FINGERPRINT_HEADER) {
+    const userAgent = first(req.headers['user-agent']);
+    const language = first(req.headers['accept-language']).split(',')[0]?.trim() || null;
+    // Bowser throws on an empty string, so we only parse when there is something to parse.
+    const ua = userAgent ? Bowser.parse(userAgent) : null;
+    const browser = ua?.browser.name ?? 'unknown';
+    const os = ua?.os.name ?? 'unknown';
+    const deviceType = toDeviceType(ua?.platform.type);
+    // The client fingerprint is only a hint (anyone can send anything): we accept a
+    // well-formed hex string and mix it in, we never trust it for identity.
+    const rawClient = first(req.headers[fingerprintHeader.toLowerCase()]);
+    const clientFingerprint = CLIENT_FINGERPRINT_PATTERN.test(rawClient) ? rawClient.toLowerCase() : null;
+    const traits = [browser, os, deviceType, language].join('|');
+    const fingerprint = createHash('sha256')
+        .update(clientFingerprint ? `${traits}|${clientFingerprint}` : traits)
+        .digest('hex')
+        .slice(0, 32);
+    return {
+        ip: extractIp(req),
+        userAgent,
+        language,
+        browser,
+        browserVersion: ua?.browser.version ?? '',
+        os,
+        osVersion: ua?.os.version ?? '',
+        deviceType,
+        cookieDeviceId: verify(readCookie(first(req.headers.cookie), cookieName), secret),
+        clientFingerprint,
+        fingerprint,
+    };
+}

package/dist/core/rules/impossible-travel.d.ts

@@ -0,0 +1,12 @@
+import type { Rule } from '../../types.js';
+export interface ImpossibleTravelOptions {
+    /** Faster than this is considered impossible. Default: 900 km/h (an airliner). */
+    maxSpeedKmh?: number;
+    /** Ignore short hops, where IP geolocation is too imprecise. Default: 300 km. */
+    minDistanceKm?: number;
+}
+/**
+ * Two logins too far apart for the time elapsed between them.
+ * A known device scores less than a new one: a VPN can explain the first, hardly the second.
+ */
+export declare function impossibleTravelRule(options?: ImpossibleTravelOptions): Rule;

package/dist/core/rules/impossible-travel.js

@@ -0,0 +1,30 @@
+import { distanceKm } from '../geo-distance.js';
+const label = (l) => l.city ?? l.country ?? 'unknown place';
+/**
+ * Two logins too far apart for the time elapsed between them.
+ * A known device scores less than a new one: a VPN can explain the first, hardly the second.
+ */
+export function impossibleTravelRule(options = {}) {
+    const maxSpeedKmh = options.maxSpeedKmh ?? 900;
+    const minDistanceKm = options.minDistanceKm ?? 300;
+    return {
+        name: 'impossible-travel',
+        evaluate(ctx) {
+            const previous = ctx.previousLogin;
+            if (!ctx.location || !previous?.location)
+                return null;
+            const km = distanceKm(previous.location, ctx.location);
+            if (km < minDistanceKm)
+                return null;
+            const hours = Math.max((ctx.now.getTime() - previous.at.getTime()) / 3_600_000, 1 / 3600);
+            const speed = km / hours;
+            if (speed <= maxSpeedKmh)
+                return null;
+            return {
+                reason: 'impossible_travel',
+                points: ctx.isNewDevice ? 60 : 40,
+                detail: `${label(previous.location)} -> ${label(ctx.location)}: ${Math.round(km)} km in ${Math.round(hours * 60)} min`,
+            };
+        },
+    };
+}

package/dist/core/rules/index.d.ts

@@ -0,0 +1,11 @@
+import type { Finding, Rule, RuleContext } from '../../types.js';
+import { impossibleTravelRule } from './impossible-travel.js';
+import { newDeviceRule } from './new-device.js';
+import { newIpRule } from './new-ip.js';
+import { sharedDeviceRule } from './shared-device.js';
+import { simultaneousLoginRule } from './simultaneous-login.js';
+export { impossibleTravelRule, newDeviceRule, newIpRule, sharedDeviceRule, simultaneousLoginRule };
+/** The built-in rules, in the order their reasons are reported. */
+export declare function defaultRules(): Rule[];
+/** Runs every rule. A rule that throws is reported and skipped: it never blocks a login. */
+export declare function runRules(rules: readonly Rule[], ctx: RuleContext, onError?: (error: unknown) => void): Finding[];

package/dist/core/rules/index.js

@@ -0,0 +1,25 @@
+import { impossibleTravelRule } from './impossible-travel.js';
+import { newDeviceRule } from './new-device.js';
+import { newIpRule } from './new-ip.js';
+import { sharedDeviceRule } from './shared-device.js';
+import { simultaneousLoginRule } from './simultaneous-login.js';
+export { impossibleTravelRule, newDeviceRule, newIpRule, sharedDeviceRule, simultaneousLoginRule };
+/** The built-in rules, in the order their reasons are reported. */
+export function defaultRules() {
+    return [newDeviceRule, sharedDeviceRule, newIpRule, impossibleTravelRule(), simultaneousLoginRule()];
+}
+/** Runs every rule. A rule that throws is reported and skipped: it never blocks a login. */
+export function runRules(rules, ctx, onError) {
+    const findings = [];
+    for (const rule of rules) {
+        try {
+            const finding = rule.evaluate(ctx);
+            if (finding)
+                findings.push(finding);
+        }
+        catch (error) {
+            onError?.(error);
+        }
+    }
+    return findings;
+}

package/dist/core/rules/new-device.d.ts

@@ -0,0 +1,3 @@
+import type { Rule } from '../../types.js';
+/** A user's very first device is a baseline (0 points); any later new device is suspicious. */
+export declare const newDeviceRule: Rule;

package/dist/core/rules/new-device.js

@@ -0,0 +1,16 @@
+/** A user's very first device is a baseline (0 points); any later new device is suspicious. */
+export const newDeviceRule = {
+    name: 'new-device',
+    evaluate(ctx) {
+        if (!ctx.isNewDevice)
+            return null;
+        if (!ctx.userHadDevices) {
+            return { reason: 'first_device', points: 0, detail: 'First device seen for this user (baseline)' };
+        }
+        return {
+            reason: 'new_device',
+            points: 35,
+            detail: `New device: ${ctx.device.browser} on ${ctx.device.os}`,
+        };
+    },
+};

package/dist/core/rules/new-ip.d.ts

@@ -0,0 +1,3 @@
+import type { Rule } from '../../types.js';
+/** A known device seen from an address it never used before (a new device is already flagged). */
+export declare const newIpRule: Rule;

package/dist/core/rules/new-ip.js

@@ -0,0 +1,9 @@
+/** A known device seen from an address it never used before (a new device is already flagged). */
+export const newIpRule = {
+    name: 'new-ip',
+    evaluate(ctx) {
+        if (ctx.isNewDevice || !ctx.isNewIp)
+            return null;
+        return { reason: 'new_ip', points: 10, detail: `Known device seen from a new IP (${ctx.ip})` };
+    },
+};

package/dist/core/rules/shared-device.d.ts

@@ -0,0 +1,6 @@
+import type { Rule } from '../../types.js';
+/**
+ * The same device already logged in as another user: the signature of shared credentials.
+ * Marking a device as trusted (tracker.trustDevice) silences this rule for that user.
+ */
+export declare const sharedDeviceRule: Rule;

package/dist/core/rules/shared-device.js

@@ -0,0 +1,16 @@
+/**
+ * The same device already logged in as another user: the signature of shared credentials.
+ * Marking a device as trusted (tracker.trustDevice) silences this rule for that user.
+ */
+export const sharedDeviceRule = {
+    name: 'shared-device',
+    evaluate(ctx) {
+        if (ctx.sharedWithUsers.length === 0 || ctx.device.trusted)
+            return null;
+        return {
+            reason: 'device_shared_with_other_users',
+            points: 60,
+            detail: `Device also used by: ${ctx.sharedWithUsers.join(', ')}`,
+        };
+    },
+};

package/dist/core/rules/simultaneous-login.d.ts

@@ -0,0 +1,7 @@
+import type { Rule } from '../../types.js';
+export interface SimultaneousLoginOptions {
+    /** Two logins closer than this, from different devices and IPs, are "simultaneous". Default: 5. */
+    windowMinutes?: number;
+}
+/** The same account active on two different devices, on two different networks, at once. */
+export declare function simultaneousLoginRule(options?: SimultaneousLoginOptions): Rule;

package/dist/core/rules/simultaneous-login.js

@@ -0,0 +1,22 @@
+/** The same account active on two different devices, on two different networks, at once. */
+export function simultaneousLoginRule(options = {}) {
+    const windowMs = (options.windowMinutes ?? 5) * 60_000;
+    return {
+        name: 'simultaneous-login',
+        evaluate(ctx) {
+            const previous = ctx.previousLogin;
+            if (!previous)
+                return null;
+            const elapsed = ctx.now.getTime() - previous.at.getTime();
+            if (elapsed > windowMs)
+                return null;
+            if (previous.deviceId === ctx.device.id || previous.ip === ctx.ip)
+                return null;
+            return {
+                reason: 'simultaneous_login',
+                points: 20,
+                detail: `Another device logged in ${Math.round(elapsed / 1000)} s ago from a different IP`,
+            };
+        },
+    };
+}

package/dist/core/scoring.d.ts

@@ -0,0 +1,10 @@
+import type { Finding, RiskLevel, RiskReason } from '../types.js';
+export interface ScoreResult {
+    riskScore: number;
+    riskLevel: RiskLevel;
+    reasons: RiskReason[];
+    findings: Finding[];
+}
+export declare function riskLevelFor(score: number): RiskLevel;
+/** Adds up the findings of all rules into one score between 0 and 100. */
+export declare function combine(findings: Finding[]): ScoreResult;

package/dist/core/scoring.js

@@ -0,0 +1,14 @@
+export function riskLevelFor(score) {
+    return score >= 60 ? 'high' : score >= 30 ? 'medium' : 'low';
+}
+/** Adds up the findings of all rules into one score between 0 and 100. */
+export function combine(findings) {
+    const total = findings.reduce((sum, finding) => sum + finding.points, 0);
+    const riskScore = Math.min(100, Math.max(0, total));
+    return {
+        riskScore,
+        riskLevel: riskLevelFor(riskScore),
+        reasons: findings.map((finding) => finding.reason),
+        findings,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { DeviceTracker } from './tracker.js';
+export { MemoryStorage } from './adapters/storage/memory.js';
+export { SqliteStorage } from './adapters/storage/sqlite.js';
+export type { SqliteDatabase, SqliteStatement } from './adapters/storage/sqlite.js';
+export { StaticGeo } from './adapters/geo/static.js';
+export { MaxMindGeo } from './adapters/geo/maxmind.js';
+export type { MaxMindCityRecord, MaxMindReader } from './adapters/geo/maxmind.js';
+export { distanceKm } from './core/geo-distance.js';
+export { defaultRules, impossibleTravelRule, newDeviceRule, newIpRule, sharedDeviceRule, simultaneousLoginRule, } from './core/rules/index.js';
+export type { ImpossibleTravelOptions } from './core/rules/impossible-travel.js';
+export type { SimultaneousLoginOptions } from './core/rules/simultaneous-login.js';
+export { trackLogin } from './middleware/express.js';
+export * from './types.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+export { DeviceTracker } from './tracker.js';
+export { MemoryStorage } from './adapters/storage/memory.js';
+export { SqliteStorage } from './adapters/storage/sqlite.js';
+export { StaticGeo } from './adapters/geo/static.js';
+export { MaxMindGeo } from './adapters/geo/maxmind.js';
+export { distanceKm } from './core/geo-distance.js';
+export { defaultRules, impossibleTravelRule, newDeviceRule, newIpRule, sharedDeviceRule, simultaneousLoginRule, } from './core/rules/index.js';
+export { trackLogin } from './middleware/express.js';
+export * from './types.js';

package/dist/middleware/express.d.ts

@@ -0,0 +1,12 @@
+import type { DeviceTracker } from '../tracker.js';
+import type { RequestLike, TrackResult } from '../types.js';
+/** The two response methods we need: Express and Node's http both provide them. */
+export interface ResponseLike {
+    getHeader(name: string): number | string | string[] | undefined;
+    setHeader(name: string, value: string | string[]): unknown;
+}
+/**
+ * Track a successful login AND hand the device cookie to the browser.
+ * Existing Set-Cookie headers (e.g. a session cookie) are preserved.
+ */
+export declare function trackLogin(tracker: DeviceTracker, req: RequestLike, res: ResponseLike, userId: string): Promise<TrackResult>;

package/dist/middleware/express.js

@@ -0,0 +1,11 @@
+/**
+ * Track a successful login AND hand the device cookie to the browser.
+ * Existing Set-Cookie headers (e.g. a session cookie) are preserved.
+ */
+export async function trackLogin(tracker, req, res, userId) {
+    const result = await tracker.track(req, userId);
+    const current = res.getHeader('Set-Cookie');
+    const existing = current === undefined ? [] : Array.isArray(current) ? current : [String(current)];
+    res.setHeader('Set-Cookie', [...existing, result.deviceCookie]);
+    return result;
+}

package/dist/tracker.d.ts

@@ -0,0 +1,23 @@
+import type { DeviceRecord, DeviceTrackerOptions, RequestLike, TrackResult } from './types.js';
+export declare class DeviceTracker {
+    readonly cookieName: string;
+    private readonly options;
+    private readonly rules;
+    constructor(options: DeviceTrackerOptions);
+    /** A failing alert must never break a login: report the error and carry on. */
+    private runHook;
+    /** A failing geo provider must never break a login either: no location, that's all. */
+    private locate;
+    private buildCookie;
+    /** Call once a user has authenticated successfully. */
+    track(req: RequestLike, userId: string): Promise<TrackResult>;
+    getDevices(userId: string): Promise<DeviceRecord[]>;
+    getLoginHistory(userId: string, limit?: number): Promise<import("./types.js").LoginEvent[]>;
+    revokeDevice(userId: string, deviceId: string): Promise<void>;
+    /**
+     * Mark a device as trusted (or not) for one user, e.g. a reception desk computer.
+     * A trusted device no longer triggers the shared-device rule for that user.
+     * Returns false when the user has no such device.
+     */
+    trustDevice(userId: string, deviceId: string, trusted?: boolean): Promise<boolean>;
+}

package/dist/tracker.js

@@ -0,0 +1,157 @@
+import { randomUUID } from 'node:crypto';
+import { DEFAULT_FINGERPRINT_HEADER } from './constants.js';
+import { anonymizeIp, buildContext, sign } from './core/parser.js';
+import { defaultRules, runRules } from './core/rules/index.js';
+import { combine } from './core/scoring.js';
+export class DeviceTracker {
+    cookieName;
+    options;
+    rules;
+    constructor(options) {
+        if (!options.secret || options.secret.length < 16) {
+            throw new Error('audit-device-tracker: "secret" must be at least 16 characters');
+        }
+        this.options = options;
+        this.cookieName = options.cookieName ?? 'adt_did';
+        this.rules = options.rules ?? defaultRules();
+    }
+    /** A failing alert must never break a login: report the error and carry on. */
+    async runHook(hook) {
+        try {
+            await hook();
+        }
+        catch (error) {
+            this.options.onError?.(error);
+        }
+    }
+    /** A failing geo provider must never break a login either: no location, that's all. */
+    async locate(ip) {
+        if (!this.options.geo)
+            return null;
+        try {
+            return (await this.options.geo.lookup(ip)) ?? null;
+        }
+        catch (error) {
+            this.options.onError?.(error);
+            return null;
+        }
+    }
+    buildCookie(deviceId) {
+        const value = encodeURIComponent(sign(deviceId, this.options.secret));
+        const secure = this.options.cookieSecure === false ? '' : '; Secure';
+        return `${this.cookieName}=${value}; Max-Age=31536000; Path=/; HttpOnly; SameSite=Lax${secure}`;
+    }
+    /** Call once a user has authenticated successfully. */
+    async track(req, userId) {
+        const { storage } = this.options;
+        const ctx = buildContext(req, this.cookieName, this.options.secret, this.options.clientFingerprintHeader ?? DEFAULT_FINGERPRINT_HEADER);
+        const ip = this.options.ipAnonymization === 'partial' ? anonymizeIp(ctx.ip) : ctx.ip;
+        const now = new Date();
+        // 1. Which device is this? A valid cookie is authoritative: the fingerprint
+        //    is only a fallback when there is no cookie at all.
+        const previousDevices = await storage.listDevices(userId);
+        const existing = ctx.cookieDeviceId
+            ? await storage.getDevice(userId, ctx.cookieDeviceId)
+            : await storage.findDeviceByFingerprint(userId, ctx.fingerprint);
+        const isNewDevice = existing === null;
+        const isNewIp = existing !== null && !existing.knownIps.includes(ip);
+        // 2. Build the updated (or brand new) device record.
+        const device = existing
+            ? {
+                ...existing,
+                browserVersion: ctx.browserVersion,
+                osVersion: ctx.osVersion,
+                lastSeen: now,
+                loginCount: existing.loginCount + 1,
+                lastIp: ip,
+                knownIps: isNewIp ? [...existing.knownIps, ip].slice(-20) : existing.knownIps,
+            }
+            : {
+                id: ctx.cookieDeviceId ?? randomUUID(),
+                userId,
+                fingerprint: ctx.fingerprint,
+                idSource: ctx.cookieDeviceId ? 'cookie' : 'fingerprint',
+                browser: ctx.browser,
+                browserVersion: ctx.browserVersion,
+                os: ctx.os,
+                osVersion: ctx.osVersion,
+                deviceType: ctx.deviceType,
+                language: ctx.language,
+                firstSeen: now,
+                lastSeen: now,
+                loginCount: 1,
+                lastIp: ip,
+                knownIps: [ip],
+                trusted: false,
+            };
+        // 3. Gather what the rules need: other users of this device, location, previous login.
+        const sharedWithUsers = (await storage.listUsersByDevice(device.id)).filter((id) => id !== userId);
+        const location = await this.locate(ctx.ip);
+        const [previousLogin = null] = await storage.listLogins(userId, 1);
+        // 4. Let every rule judge the login, then add the points up.
+        const findings = runRules(this.rules, {
+            userId,
+            now,
+            ip,
+            device,
+            isNewDevice,
+            userHadDevices: previousDevices.length > 0,
+            isNewIp,
+            sharedWithUsers,
+            location,
+            previousLogin,
+        }, this.options.onError);
+        const { riskScore, riskLevel, reasons } = combine(findings);
+        // 5. Persist, then notify.
+        await storage.saveDevice(device);
+        await storage.addLogin({
+            userId,
+            deviceId: device.id,
+            ip,
+            userAgent: ctx.userAgent,
+            at: now,
+            riskScore,
+            reasons,
+            location,
+        });
+        const result = {
+            device,
+            isNewDevice,
+            riskScore,
+            riskLevel,
+            reasons,
+            findings,
+            location,
+            sharedWithUsers,
+            deviceCookie: this.buildCookie(device.id),
+        };
+        if (isNewDevice && previousDevices.length > 0) {
+            await this.runHook(() => this.options.onNewDevice?.(result, userId));
+        }
+        if (riskScore >= (this.options.suspiciousThreshold ?? 60)) {
+            await this.runHook(() => this.options.onSuspicious?.(result, userId));
+        }
+        return result;
+    }
+    getDevices(userId) {
+        return this.options.storage.listDevices(userId);
+    }
+    getLoginHistory(userId, limit) {
+        return this.options.storage.listLogins(userId, limit);
+    }
+    revokeDevice(userId, deviceId) {
+        return this.options.storage.removeDevice(userId, deviceId);
+    }
+    /**
+     * Mark a device as trusted (or not) for one user, e.g. a reception desk computer.
+     * A trusted device no longer triggers the shared-device rule for that user.
+     * Returns false when the user has no such device.
+     */
+    async trustDevice(userId, deviceId, trusted = true) {
+        const device = await this.options.storage.getDevice(userId, deviceId);
+        if (!device)
+            return false;
+        await this.options.storage.saveDevice({ ...device, trusted });
+        return true;
+    }
+}