audit-device-tracker 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+Licence MIT
+
+Copyright (c) 2026 Adiko Elie
+
+L'autorisation est accordée par la présente, à titre gratuit, à toute personne obtenant une copie
+de ce logiciel et des fichiers de documentation associés (le « Logiciel »), d'utiliser
+le Logiciel sans restriction, y compris, sans s'y limiter, les droits
+d'utiliser, de copier, de modifier, de fusionner, de publier, de distribuer, de concéder des sous-licences et/ou de vendre
+des copies du Logiciel, et d'autoriser les personnes auxquelles le Logiciel est
+fourni à le faire, sous réserve des conditions suivantes :
+
+La mention de copyright ci-dessus et la présente autorisation doivent être incluses dans toutes
+les copies ou parties substantielles du Logiciel.
+
+LE LOGICIEL EST FOURNI « EN L'ÉTAT », SANS GARANTIE D'AUCUNE SORTE, EXPRESSE OU
+IMPLICITE, Y COMPRIS, SANS S'Y LIMITER, LES GARANTIES DE QUALITÉ MARCHANDE,
+D'ADÉQUATION À UN USAGE PARTICULIER ET D'ABSENCE DE CONTREFAÇON. EN AUCUN CAS LES
+AUTEURS OU TITULAIRES DU DROIT D'AUTEUR NE SAURAIENT ÊTRE TENUS RESPONSABLES DE TOUTE RÉCLAMATION, DE TOUT DOMMAGE OU DE TOUTE AUTRE
+RESPONSABILITÉ, QUE CE SOIT DANS LE CADRE D'UNE ACTION CONTRACTUELLE, DÉLICTUELLE OU AUTRE, DÉCOULANT
+DU LOGICIEL, DE SON UTILISATION OU DE TOUTE AUTRE OPÉRATION LE CONCERNANT.

package/README.md

@@ -0,0 +1,280 @@
+# audit-device-tracker
+[![CI](https://github.com/eliedvp/audit-device-tracker/actions/workflows/ci.yml/badge.svg)](https://github.com/eliedvp/audit-device-tracker/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/audit-device-tracker.svg)](https://www.npmjs.com/package/audit-device-tracker)
+[![license](https://img.shields.io/npm/l/audit-device-tracker.svg)](LICENSE)
+
+Identifiez et auditez les appareils utilisés par vos utilisateurs pour se connecter. Détectez les **identifiants partagés** (par exemple, un collègue utilisant le compte d'une autre personne depuis un autre ordinateur), les **nouveaux appareils**, les **déplacements impossibles** et les **connexions simultanées**, tout en intégrant la protection de la vie privée.
+
+## Pourquoi ?
+
+Un mot de passe partagé paraît parfaitement valide pour un système d'authentification classique. Ce package ajoute une question importante : **quel appareil utilise cet utilisateur et l'a-t-il déjà utilisé auparavant ?**
+
+```text
+alice  faible   0   premier_appareil
+
+bob    élevé   60   premier_appareil, appareil_partage_avec_autres_utilisateurs
+                     - Appareil également utilisé par : alice
+
+alice  élevé  100   nouvel_appareil, déplacement_impossible, connexion_simultanée
+                     - Nouvel appareil : Safari sur iOS
+                     - Abidjan -> Paris : 4874 km en 0 min
+```
+
+Vous pouvez tester le fonctionnement avec :
+
+```bash
+npm run demo
+```
+
+## Installation
+
+```bash
+npm install audit-device-tracker
+```
+
+Nécessite **Node.js 22 ou supérieur**.
+
+Le stockage SQLite nécessite un pilote SQLite : `node:sqlite` intégré à Node.js **22.13+ sans option supplémentaire**, ou `better-sqlite3`.
+
+Ce package ne vous impose aucune dépendance native.
+
+## Utilisation rapide avec Express
+
+```ts
+import express from 'express';
+import { DatabaseSync } from 'node:sqlite';
+import {
+  DeviceTracker,
+  SqliteStorage,
+  trackLogin
+} from 'audit-device-tracker';
+
+const tracker = new DeviceTracker({
+  storage: new SqliteStorage(new DatabaseSync('devices.db')),
+  secret: process.env.DEVICE_SECRET!, // au moins 16 caractères
+  ipAnonymization: 'partial',
+
+  onNewDevice: (result, userId) =>
+    notifyUser(userId, result.device),
+
+  onSuspicious: (result, userId) =>
+    alertSecurityTeam(userId, result),
+
+  onError: (error) =>
+    console.error(error),
+});
+
+const app = express();
+
+app.use(express.json());
+
+app.post('/login', async (req, res) => {
+  const user = await authenticate(req.body); // votre propre authentification
+
+  const result = await trackLogin(
+    tracker,
+    req,
+    res,
+    user.id
+  );
+
+  if (result.riskLevel === 'high') {
+    return res.status(403).json({
+      mfaRequired: true
+    });
+  }
+
+  res.json({ ok: true });
+});
+```
+
+Appelez `trackLogin` **uniquement après une authentification réussie**.
+
+`result.findings` explique le score obtenu en termes simples et peut être utilisé directement dans un journal d'audit.
+
+## Comment un appareil est reconnu
+
+Le package utilise principalement deux mécanismes :
+
+1. **Cookie signé (HMAC-SHA256)** : signal fort qui ne peut pas être falsifié sans votre clé secrète. Un cookie valide est considéré comme fiable.
+
+2. **Fingerprint de secours** : empreinte basée sur le navigateur, le système d'exploitation, le type d'appareil et la langue, avec éventuellement le fingerprint fourni par le navigateur. L'adresse IP et la version du navigateur ne sont pas utilisées. Ce mécanisme est moins fiable et est utilisé uniquement lorsqu'aucun cookie valide n'est disponible.
+
+## Règles et calcul du risque
+
+Chaque règle est un petit objet indépendant. Les points des règles déclenchées sont additionnés jusqu'à un maximum de 100.
+
+| Règle                                                           | Motif                            | Points |
+| --------------------------------------------------------------- | -------------------------------- | -----: |
+| Appareil déjà utilisé par **un autre utilisateur**              | `device_shared_with_other_users` |    +60 |
+| Nouvel appareil alors que l'utilisateur en possédait déjà       | `new_device`                     |    +35 |
+| Nouvelle IP sur un appareil connu                               | `new_ip`                         |    +10 |
+| Déplacement impossible sur un nouvel appareil                   | `impossible_travel`              |    +60 |
+| Déplacement impossible sur un appareil connu                    | `impossible_travel`              |    +40 |
+| Connexion simultanée (autre appareil, autre IP, moins de 5 min) | `simultaneous_login`             |    +20 |
+
+### Niveaux de risque
+
+* **Faible** : < 30
+* **Moyen** : 30 à 59
+* **Élevé** : ≥ 60
+
+Le tout premier appareil d'un utilisateur sert de référence et obtient un score de **0**.
+
+### Ajouter sa propre règle
+
+Vous pouvez ajouter vos propres règles ou remplacer celles fournies par défaut :
+
+```ts
+import {
+  defaultRules,
+  type Rule
+} from 'audit-device-tracker';
+
+const nightLogin: Rule = {
+  name: 'night-login',
+
+  evaluate: (ctx) =>
+    ctx.now.getUTCHours() < 5
+      ? {
+          reason: 'night_login',
+          points: 15,
+          detail: 'Connexion effectuée pendant la nuit'
+        }
+      : null,
+};
+
+new DeviceTracker({
+  storage,
+  secret,
+  rules: [
+    ...defaultRules(),
+    nightLogin
+  ]
+});
+```
+
+## Géolocalisation et déplacements impossibles
+
+Vous pouvez fournir une option `geo` avec une méthode `lookup(ip)`.
+
+Sans fournisseur de géolocalisation, les règles liées à la localisation restent désactivées.
+
+```ts
+import maxmind, { type CityResponse } from 'maxmind';
+import { MaxMindGeo } from 'audit-device-tracker';
+
+const reader = await maxmind.open<CityResponse>(
+  './GeoLite2-City.mmdb'
+);
+
+const tracker = new DeviceTracker({
+  storage,
+  secret,
+  geo: new MaxMindGeo(reader)
+});
+```
+
+La base **GeoLite2** est gratuite, mais nécessite un compte MaxMind pour être téléchargée et n'est pas incluse dans le package.
+
+`StaticGeo` permet d'utiliser une table de localisation fixe pour les tests et les démonstrations.
+
+## Fingerprint côté navigateur (optionnel)
+
+```ts
+import {
+  fingerprintHeaders
+} from 'audit-device-tracker/client';
+
+await fetch('/login', {
+  method: 'POST',
+  headers: {
+    ...(await fingerprintHeaders())
+  },
+  body
+});
+```
+
+Le fingerprint utilise uniquement quelques informations à faible pouvoir d'identification :
+
+* résolution de l'écran ;
+* fuseau horaire ;
+* nombre de cœurs ;
+* plateforme ;
+* langues.
+
+Le package n'utilise volontairement **ni Canvas, ni WebGL, ni analyse des polices**.
+
+Ces techniques peuvent être utilisées pour suivre les personnes plutôt que pour auditer les appareils.
+
+Le serveur considère le fingerprint comme **un simple indice et non comme une identité**.
+
+## Options
+
+| Option                         | Valeur par défaut | Description                                                                                                  |
+| ------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------ |
+| `storage`                      | obligatoire       | Un `StorageAdapter` : `MemoryStorage`, `SqliteStorage` ou votre propre stockage                              |
+| `secret`                       | obligatoire       | Sert à signer le cookie de l'appareil (minimum 16 caractères)                                                |
+| `cookieName`                   | `adt_did`         | Nom du cookie de l'appareil                                                                                  |
+| `cookieSecure`                 | `true`            | Mettre `false` uniquement en développement local avec HTTP                                                   |
+| `ipAnonymization`              | `none`            | `partial` masque la dernière partie d'une IPv4 / le suffixe d'une IPv6                                       |
+| `geo`                          | -                 | Un `GeoProvider` pour activer les règles de localisation                                                     |
+| `rules`                        | règles intégrées  | Remplace les règles ou les combine avec `defaultRules()`                                                     |
+| `suspiciousThreshold`          | `60`              | Score à partir duquel `onSuspicious` est déclenché                                                           |
+| `onNewDevice` / `onSuspicious` | -                 | Hooks permettant de déclencher des alertes                                                                   |
+| `onError`                      | -                 | Appelé lorsqu'un hook, une règle ou le fournisseur Geo génère une erreur ; la connexion n'est jamais bloquée |
+
+Vous pouvez également utiliser :
+
+```ts
+tracker.getDevices(userId)
+tracker.getLoginHistory(userId)
+tracker.revokeDevice(userId, id)
+tracker.trustDevice(userId, id)
+```
+
+Cela permet notamment de créer une page **« Mes appareils »**.
+
+`trustDevice` permet de déclarer comme légitime un appareil partagé, par exemple un ordinateur d'accueil ou de réception.
+
+## Créer son propre stockage
+
+Vous pouvez implémenter l'interface `StorageAdapter` composée de 8 méthodes.
+
+Utilisez ensuite la suite de tests commune pour vérifier que votre stockage se comporte comme les stockages intégrés :
+
+```text
+tests/storage-contract.ts
+```
+
+## Limites et précautions
+
+* `MemoryStorage` perd toutes ses données au redémarrage. Utilisez `SqliteStorage` ou votre propre stockage pour conserver les données.
+* La détection des appareils partagés dépend de la conservation du cookie. Utilisez HTTPS en production.
+* Un navigateur qui refuse ou supprime le cookie réduit l'efficacité de cette détection.
+* La géolocalisation par IP reste approximative et un VPN peut modifier la localisation détectée.
+* Un déplacement impossible constitue **un signal à examiner et non une preuve de fraude**.
+* Les déplacements courts de moins de 300 km sont ignorés.
+* Derrière un proxy, configurez Express afin que `req.ip` corresponde à l'adresse réelle du client :
+
+```ts
+app.set('trust proxy', 1);
+```
+
+Ne faites pas confiance à `X-Forwarded-For` sans configuration appropriée du proxy.
+
+* Un appareil partagé peut être parfaitement légitime, par exemple dans une salle de formation ou une réception. Utilisez `trustDevice` dans ce cas.
+* Les données relatives aux appareils peuvent constituer des données personnelles. Vous êtes responsable de la base légale, de la durée de conservation et de l'information des utilisateurs requises par la réglementation applicable.
+* Utilisez notamment `ipAnonymization` et `revokeDevice` lorsque cela est approprié.
+
+## Développement
+
+```bash
+npm test
+npm run build
+npm run demo
+```
+
+## Licence
+
+MIT — voir le fichier `LICENSE`.

package/dist/adapters/geo/maxmind.d.ts

@@ -0,0 +1,31 @@
+import type { GeoLocation, GeoProvider } from '../../types.js';
+/** The part of a MaxMind GeoLite2-City record we read. */
+export interface MaxMindCityRecord {
+    country?: {
+        iso_code?: string;
+    };
+    city?: {
+        names?: Record<string, string | undefined>;
+    };
+    location?: {
+        latitude?: number;
+        longitude?: number;
+    };
+}
+/**
+ * Anything with a `get(ip)` method: the reader returned by `maxmind.open()`.
+ *
+ *   import maxmind, { CityResponse } from 'maxmind';
+ *   const reader = await maxmind.open<CityResponse>('./GeoLite2-City.mmdb');
+ *   const geo = new MaxMindGeo(reader);
+ *
+ * The GeoLite2 database is free but requires a MaxMind account to download.
+ */
+export interface MaxMindReader {
+    get(ip: string): MaxMindCityRecord | null;
+}
+export declare class MaxMindGeo implements GeoProvider {
+    private readonly reader;
+    constructor(reader: MaxMindReader);
+    lookup(ip: string): GeoLocation | null;
+}

package/dist/adapters/geo/maxmind.js

@@ -0,0 +1,25 @@
+export class MaxMindGeo {
+    reader;
+    constructor(reader) {
+        this.reader = reader;
+    }
+    lookup(ip) {
+        let record;
+        try {
+            record = this.reader.get(ip);
+        }
+        catch {
+            return null; // not a valid IP address
+        }
+        const latitude = record?.location?.latitude;
+        const longitude = record?.location?.longitude;
+        if (typeof latitude !== 'number' || typeof longitude !== 'number')
+            return null;
+        return {
+            country: record?.country?.iso_code ?? null,
+            city: record?.city?.names?.en ?? null,
+            latitude,
+            longitude,
+        };
+    }
+}

package/dist/adapters/geo/static.d.ts

@@ -0,0 +1,7 @@
+import type { GeoLocation, GeoProvider } from '../../types.js';
+/** A fixed IP -> location table: for tests and demos, no database needed. */
+export declare class StaticGeo implements GeoProvider {
+    private readonly table;
+    constructor(table: Record<string, GeoLocation>);
+    lookup(ip: string): GeoLocation | null;
+}

package/dist/adapters/geo/static.js

@@ -0,0 +1,10 @@
+/** A fixed IP -> location table: for tests and demos, no database needed. */
+export class StaticGeo {
+    table;
+    constructor(table) {
+        this.table = table;
+    }
+    lookup(ip) {
+        return this.table[ip] ?? null;
+    }
+}

package/dist/adapters/storage/memory.d.ts

@@ -0,0 +1,14 @@
+import type { DeviceRecord, LoginEvent, StorageAdapter } from '../../types.js';
+export declare class MemoryStorage implements StorageAdapter {
+    private devices;
+    private logins;
+    private key;
+    getDevice(userId: string, deviceId: string): Promise<DeviceRecord | null>;
+    findDeviceByFingerprint(userId: string, fingerprint: string): Promise<DeviceRecord | null>;
+    saveDevice(device: DeviceRecord): Promise<void>;
+    listDevices(userId: string): Promise<DeviceRecord[]>;
+    listUsersByDevice(deviceId: string): Promise<string[]>;
+    removeDevice(userId: string, deviceId: string): Promise<void>;
+    addLogin(event: LoginEvent): Promise<void>;
+    listLogins(userId: string, limit?: number): Promise<LoginEvent[]>;
+}

package/dist/adapters/storage/memory.js

@@ -0,0 +1,44 @@
+const clone = (value) => structuredClone(value);
+export class MemoryStorage {
+    devices = new Map();
+    logins = [];
+    key(userId, deviceId) {
+        return JSON.stringify([userId, deviceId]);
+    }
+    async getDevice(userId, deviceId) {
+        const found = this.devices.get(this.key(userId, deviceId));
+        return found ? clone(found) : null;
+    }
+    async findDeviceByFingerprint(userId, fingerprint) {
+        let best = null;
+        for (const device of this.devices.values()) {
+            if (device.userId !== userId || device.fingerprint !== fingerprint)
+                continue;
+            if (!best || device.lastSeen.getTime() > best.lastSeen.getTime())
+                best = device;
+        }
+        return best ? clone(best) : null;
+    }
+    async saveDevice(device) {
+        this.devices.set(this.key(device.userId, device.id), clone(device));
+    }
+    async listDevices(userId) {
+        return [...this.devices.values()].filter((d) => d.userId === userId).map(clone);
+    }
+    async listUsersByDevice(deviceId) {
+        return [...this.devices.values()].filter((d) => d.id === deviceId).map((d) => d.userId);
+    }
+    async removeDevice(userId, deviceId) {
+        this.devices.delete(this.key(userId, deviceId));
+    }
+    async addLogin(event) {
+        this.logins.push(clone(event));
+    }
+    async listLogins(userId, limit = 50) {
+        return this.logins
+            .filter((l) => l.userId === userId)
+            .slice(-limit)
+            .reverse()
+            .map(clone);
+    }
+}

package/dist/adapters/storage/sqlite.d.ts

@@ -0,0 +1,30 @@
+import type { DeviceRecord, LoginEvent, StorageAdapter } from '../../types.js';
+/** The part of a prepared statement we use. Matches `node:sqlite` and `better-sqlite3`. */
+export interface SqliteStatement {
+    run(...params: unknown[]): unknown;
+    get(...params: unknown[]): unknown;
+    all(...params: unknown[]): unknown[];
+}
+/**
+ * The part of a SQLite database we use. Pass either
+ *   new DatabaseSync('devices.db')   // from 'node:sqlite' (Node 22.5+, nothing to install)
+ *   new Database('devices.db')       // from 'better-sqlite3'
+ * so this package never forces a native dependency on you.
+ */
+export interface SqliteDatabase {
+    exec(sql: string): unknown;
+    prepare(sql: string): SqliteStatement;
+}
+/** Persistent storage on SQLite. Creates its tables on first use. */
+export declare class SqliteStorage implements StorageAdapter {
+    private readonly db;
+    constructor(db: SqliteDatabase);
+    getDevice(userId: string, deviceId: string): Promise<DeviceRecord | null>;
+    findDeviceByFingerprint(userId: string, fingerprint: string): Promise<DeviceRecord | null>;
+    saveDevice(d: DeviceRecord): Promise<void>;
+    listDevices(userId: string): Promise<DeviceRecord[]>;
+    listUsersByDevice(deviceId: string): Promise<string[]>;
+    removeDevice(userId: string, deviceId: string): Promise<void>;
+    addLogin(e: LoginEvent): Promise<void>;
+    listLogins(userId: string, limit?: number): Promise<LoginEvent[]>;
+}

package/dist/adapters/storage/sqlite.js

@@ -0,0 +1,120 @@
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS adt_devices (
+  user_id TEXT NOT NULL,
+  device_id TEXT NOT NULL,
+  fingerprint TEXT NOT NULL,
+  id_source TEXT NOT NULL,
+  browser TEXT NOT NULL,
+  browser_version TEXT NOT NULL,
+  os TEXT NOT NULL,
+  os_version TEXT NOT NULL,
+  device_type TEXT NOT NULL,
+  language TEXT,
+  first_seen TEXT NOT NULL,
+  last_seen TEXT NOT NULL,
+  login_count INTEGER NOT NULL,
+  last_ip TEXT NOT NULL,
+  known_ips TEXT NOT NULL,
+  trusted INTEGER NOT NULL,
+  PRIMARY KEY (user_id, device_id)
+);
+CREATE INDEX IF NOT EXISTS adt_devices_by_device ON adt_devices (device_id);
+CREATE INDEX IF NOT EXISTS adt_devices_by_fingerprint ON adt_devices (user_id, fingerprint);
+CREATE TABLE IF NOT EXISTS adt_logins (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_id TEXT NOT NULL,
+  device_id TEXT NOT NULL,
+  ip TEXT NOT NULL,
+  user_agent TEXT NOT NULL,
+  at TEXT NOT NULL,
+  risk_score INTEGER NOT NULL,
+  reasons TEXT NOT NULL,
+  location TEXT
+);
+CREATE INDEX IF NOT EXISTS adt_logins_by_user ON adt_logins (user_id, at, id);
+`;
+function toDevice(row) {
+    return {
+        id: row.device_id,
+        userId: row.user_id,
+        fingerprint: row.fingerprint,
+        idSource: row.id_source,
+        browser: row.browser,
+        browserVersion: row.browser_version,
+        os: row.os,
+        osVersion: row.os_version,
+        deviceType: row.device_type,
+        language: row.language ?? null,
+        firstSeen: new Date(row.first_seen),
+        lastSeen: new Date(row.last_seen),
+        loginCount: Number(row.login_count),
+        lastIp: row.last_ip,
+        knownIps: JSON.parse(row.known_ips),
+        trusted: Number(row.trusted) === 1,
+    };
+}
+function toLogin(row) {
+    return {
+        userId: row.user_id,
+        deviceId: row.device_id,
+        ip: row.ip,
+        userAgent: row.user_agent,
+        at: new Date(row.at),
+        riskScore: Number(row.risk_score),
+        reasons: JSON.parse(row.reasons),
+        location: row.location ? JSON.parse(row.location) : null,
+    };
+}
+/** Persistent storage on SQLite. Creates its tables on first use. */
+export class SqliteStorage {
+    db;
+    constructor(db) {
+        this.db = db;
+        db.exec(SCHEMA);
+    }
+    async getDevice(userId, deviceId) {
+        const row = this.db
+            .prepare('SELECT * FROM adt_devices WHERE user_id = ? AND device_id = ?')
+            .get(userId, deviceId);
+        return row ? toDevice(row) : null;
+    }
+    async findDeviceByFingerprint(userId, fingerprint) {
+        const row = this.db
+            .prepare('SELECT * FROM adt_devices WHERE user_id = ? AND fingerprint = ? ORDER BY last_seen DESC LIMIT 1')
+            .get(userId, fingerprint);
+        return row ? toDevice(row) : null;
+    }
+    async saveDevice(d) {
+        this.db
+            .prepare(`INSERT OR REPLACE INTO adt_devices (
+          user_id, device_id, fingerprint, id_source, browser, browser_version, os, os_version,
+          device_type, language, first_seen, last_seen, login_count, last_ip, known_ips, trusted
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(d.userId, d.id, d.fingerprint, d.idSource, d.browser, d.browserVersion, d.os, d.osVersion, d.deviceType, d.language, d.firstSeen.toISOString(), d.lastSeen.toISOString(), d.loginCount, d.lastIp, JSON.stringify(d.knownIps), d.trusted ? 1 : 0);
+    }
+    async listDevices(userId) {
+        const rows = this.db.prepare('SELECT * FROM adt_devices WHERE user_id = ?').all(userId);
+        return rows.map(toDevice);
+    }
+    async listUsersByDevice(deviceId) {
+        const rows = this.db
+            .prepare('SELECT DISTINCT user_id FROM adt_devices WHERE device_id = ?')
+            .all(deviceId);
+        return rows.map((row) => row.user_id);
+    }
+    async removeDevice(userId, deviceId) {
+        this.db.prepare('DELETE FROM adt_devices WHERE user_id = ? AND device_id = ?').run(userId, deviceId);
+    }
+    async addLogin(e) {
+        this.db
+            .prepare(`INSERT INTO adt_logins (user_id, device_id, ip, user_agent, at, risk_score, reasons, location)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(e.userId, e.deviceId, e.ip, e.userAgent, e.at.toISOString(), e.riskScore, JSON.stringify(e.reasons), e.location ? JSON.stringify(e.location) : null);
+    }
+    async listLogins(userId, limit = 50) {
+        const rows = this.db
+            .prepare('SELECT * FROM adt_logins WHERE user_id = ? ORDER BY at DESC, id DESC LIMIT ?')
+            .all(userId, limit);
+        return rows.map(toLogin);
+    }
+}

package/dist/client/fingerprint.d.ts

@@ -0,0 +1,36 @@
+import { DEFAULT_FINGERPRINT_HEADER } from '../constants.js';
+/**
+ * Browser-side helper (import from 'audit-device-tracker/client').
+ *
+ * Privacy by design: only a handful of low-entropy signals are read. There is deliberately
+ * NO canvas, WebGL or font probing: those techniques track people rather than audit devices.
+ */
+export interface ClientSignals {
+    screen: string;
+    timezone: string;
+    cores: number | null;
+    platform: string;
+    languages: string;
+    touchPoints: number;
+}
+/** What we read from the browser. Injectable so the code can be tested without one. */
+export interface ClientEnvironment {
+    screen?: {
+        width: number;
+        height: number;
+        colorDepth: number;
+    };
+    navigator?: {
+        hardwareConcurrency?: number;
+        platform?: string;
+        languages?: readonly string[];
+        maxTouchPoints?: number;
+    };
+    timeZone?: string;
+}
+export { DEFAULT_FINGERPRINT_HEADER as FINGERPRINT_HEADER };
+export declare function collectSignals(env?: ClientEnvironment): ClientSignals;
+/** A 32-character hex hash of the signals. */
+export declare function getClientFingerprint(env?: ClientEnvironment): Promise<string>;
+/** Headers to add to your login request:  fetch('/login', { headers: await fingerprintHeaders() }) */
+export declare function fingerprintHeaders(env?: ClientEnvironment): Promise<Record<string, string>>;

package/dist/client/fingerprint.js

@@ -0,0 +1,37 @@
+import { DEFAULT_FINGERPRINT_HEADER } from '../constants.js';
+export { DEFAULT_FINGERPRINT_HEADER as FINGERPRINT_HEADER };
+function browserEnvironment() {
+    const g = globalThis;
+    let timeZone;
+    try {
+        timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    }
+    catch {
+        timeZone = undefined;
+    }
+    return { screen: g.screen, navigator: g.navigator, timeZone };
+}
+export function collectSignals(env = browserEnvironment()) {
+    const { screen, navigator } = env;
+    return {
+        screen: screen ? `${screen.width}x${screen.height}x${screen.colorDepth}` : 'unknown',
+        timezone: env.timeZone ?? 'unknown',
+        cores: navigator?.hardwareConcurrency ?? null,
+        platform: navigator?.platform ?? 'unknown',
+        languages: (navigator?.languages ?? []).join(','),
+        touchPoints: navigator?.maxTouchPoints ?? 0,
+    };
+}
+/** A 32-character hex hash of the signals. */
+export async function getClientFingerprint(env) {
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle)
+        throw new Error('audit-device-tracker/client: Web Crypto is not available (HTTPS required)');
+    const data = new TextEncoder().encode(JSON.stringify(collectSignals(env)));
+    const digest = new Uint8Array(await subtle.digest('SHA-256', data));
+    return Array.from(digest, (byte) => byte.toString(16).padStart(2, '0')).join('').slice(0, 32);
+}
+/** Headers to add to your login request:  fetch('/login', { headers: await fingerprintHeaders() }) */
+export async function fingerprintHeaders(env) {
+    return { [DEFAULT_FINGERPRINT_HEADER]: await getClientFingerprint(env) };
+}

package/dist/constants.d.ts

@@ -0,0 +1,2 @@
+/** Header carrying the optional browser-side fingerprint (see audit-device-tracker/client). */
+export declare const DEFAULT_FINGERPRINT_HEADER = "x-adt-fp";

package/dist/constants.js

@@ -0,0 +1,2 @@
+/** Header carrying the optional browser-side fingerprint (see audit-device-tracker/client). */
+export const DEFAULT_FINGERPRINT_HEADER = 'x-adt-fp';

package/dist/core/geo-distance.d.ts

@@ -0,0 +1,5 @@
+import type { GeoLocation } from '../types.js';
+type Point = Pick<GeoLocation, 'latitude' | 'longitude'>;
+/** Great-circle distance between two points on Earth (Haversine formula), in kilometres. */
+export declare function distanceKm(a: Point, b: Point): number;
+export {};