haveibeenfiltered 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mihail Fedorov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,254 @@
+# haveibeenfiltered
+
+[![npm version](https://img.shields.io/npm/v/haveibeenfiltered.svg)](https://www.npmjs.com/package/haveibeenfiltered)
+[![license](https://img.shields.io/npm/l/haveibeenfiltered.svg)](https://github.com/kolobus/haveibeenfiltered/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/haveibeenfiltered.svg)](https://nodejs.org)
+
+Offline password breach checking using [ribbon filters](https://engineering.fb.com/2021/07/09/core-infra/ribbon-filter/). Check passwords against the [Have I Been Pwned](https://haveibeenpwned.com/) dataset (2B+ passwords) locally, with no API calls.
+
+See [haveibeenfiltered.com](https://haveibeenfiltered.com) for more information about the project.
+
+## Why?
+
+| Approach | Speed | Privacy | Offline | Size |
+|----------|-------|---------|---------|------|
+| HIBP API | ~200ms/req | Partial (k-anonymity) | No | 0 |
+| Full hash DB | Fast | Full | Yes | 30+ GB |
+| **haveibeenfiltered** | **~14 microseconds** | **Full** | **Yes** | **1.8 GB** |
+
+A ribbon filter compresses 2 billion SHA-1 hashes into 1.8 GB with a ~0.78% false positive rate and zero false negatives.
+
+## Quick Start
+
+### Install
+
+```bash
+npm install haveibeenfiltered
+```
+
+### Download the filter data
+
+```bash
+npx haveibeenfiltered download
+```
+
+This downloads the HIBP dataset (~1.8 GB) to `~/.haveibeenfiltered/` with SHA-256 integrity verification.
+
+For a smaller dataset to try first:
+
+```bash
+npx haveibeenfiltered download --dataset rockyou
+```
+
+### Use in your app
+
+```js
+const hbf = require('haveibeenfiltered')
+
+const filter = await hbf.load({ dataset: 'rockyou' })
+
+filter.check('password123')  // true  — breached!
+filter.check('Tr0ub4dor&3')  // false — not found
+```
+
+## API
+
+### `hbf.load(options?)`
+
+Loads a ribbon filter and returns a `RibbonFilter` instance.
+
+```js
+// Default dataset (HIBP)
+const filter = await hbf.load()
+
+// Specific dataset
+const filter = await hbf.load({ dataset: 'rockyou' })
+
+// Custom file path
+const filter = await hbf.load({ path: '/opt/data/ribbon-hibp-v1.bin' })
+
+// Auto-download if missing (opt-in)
+const filter = await hbf.load({ autoDownload: true })
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `dataset` | `string` | `'hibp'` | Dataset name (`hibp`, `rockyou`) |
+| `path` | `string` | — | Explicit path to `.bin` file |
+| `autoDownload` | `boolean` | `false` | Download from CDN if file is missing |
+
+**Path resolution order:**
+
+1. `opts.path` — explicit path
+2. `$HAVEIBEENFILTERED_PATH` — environment variable
+3. `~/.haveibeenfiltered/<filename>` — default directory
+
+### `filter.check(password)`
+
+Check a plaintext password. Returns `true` if found in the breach dataset.
+
+```js
+filter.check('password123')  // true
+filter.check('correcthorsebatterystaple')  // depends on dataset
+```
+
+### `filter.checkHash(sha1hex)`
+
+Check a pre-computed SHA-1 hash (hex string, case-insensitive).
+
+```js
+filter.checkHash('5BAA61E4C9B93F3F0682250B6CF8331B7EE68FD8')  // true ("password")
+filter.checkHash('5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8')  // also works
+```
+
+### `filter.meta`
+
+Returns filter metadata.
+
+```js
+filter.meta
+// {
+//   version: 1,
+//   totalKeys: 2048908128,
+//   fpBits: 7,
+//   numShards: 256,
+//   ...
+// }
+```
+
+### `filter.close()`
+
+Releases the in-memory buffer. Call when done.
+
+## CLI
+
+```bash
+npx haveibeenfiltered <command> [options]
+```
+
+### Download filter data
+
+```bash
+# Download HIBP dataset (~1.8 GB)
+npx haveibeenfiltered download
+
+# Download RockYou dataset (~13 MB)
+npx haveibeenfiltered download --dataset rockyou
+```
+
+### Check passwords
+
+```bash
+# Check a single password
+npx haveibeenfiltered check password123
+
+# Check multiple passwords
+npx haveibeenfiltered check password 123456 iloveyou
+
+# Check from stdin (batch mode)
+cat passwords.txt | npx haveibeenfiltered check --stdin
+
+# Check pre-computed SHA-1 hashes
+npx haveibeenfiltered check --hash 5BAA61E4C9B93F3F0682250B6CF8331B7EE68FD8
+
+# Batch hash checking
+cat sha1-hashes.txt | npx haveibeenfiltered check --stdin --hash
+```
+
+### Output formats
+
+```bash
+# Default: human-readable
+npx haveibeenfiltered check password123
+# password123: FOUND
+
+# JSON output
+npx haveibeenfiltered check password123 --json
+# {"input":"password123","found":true}
+
+# Quiet mode (exit code only — 1 if found, 0 if not)
+npx haveibeenfiltered check password123 --quiet && echo "safe" || echo "breached"
+```
+
+### Check status
+
+```bash
+npx haveibeenfiltered status
+# hibp: READY
+#   Path: /home/user/.haveibeenfiltered/ribbon-hibp-v1.bin
+#   Size: 1830.9 MB (1,918,974,105 bytes)
+#   Keys: 2,048,908,128
+#   Version: 1
+#   FP bits: 7
+#   Shards: 256
+```
+
+## Datasets
+
+| Dataset | Passwords | Filter Size | FP Rate | Description |
+|---------|-----------|-------------|---------|-------------|
+| `hibp` | 2,048,908,128 | 1.8 GB | ~0.78% | [Have I Been Pwned](https://haveibeenpwned.com/) full password list |
+| `rockyou` | 14,344,391 | 12.8 MB | ~0.78% | [RockYou](https://en.wikipedia.org/wiki/RockYou#Data_breach) breach (2009) |
+
+### CDN
+
+Filter binaries are hosted at `https://download.haveibeenfiltered.com/`:
+
+| File | Size | SHA-256 |
+|------|------|---------|
+| [`ribbon-hibp-v1.bin`](https://download.haveibeenfiltered.com/ribbon-hibp-v1.bin) | 1.8 GB | `4eeb8608fa8541a51a952ecda91ad2f86e6f7457b0dbe34b88ba8a7ed33750ce` |
+| [`ribbon-rockyou-v1.bin`](https://download.haveibeenfiltered.com/ribbon-rockyou-v1.bin) | 12.8 MB | `777d3c1640e7067bc7fb222488199c3371de5360639561f1f082db6b7c16a447` |
+
+The CLI downloads to `~/.haveibeenfiltered/` by default. Integrity is verified via SHA-256 after each download.
+
+### False Positive Rate
+
+The filter uses 7-bit fingerprints, giving a theoretical false positive rate of 1/128 (~0.78%). This means:
+
+- Zero false negatives — every breached password is detected
+- ~0.78% of safe passwords will incorrectly report as breached
+
+## How It Works
+
+haveibeenfiltered uses [ribbon filters](https://engineering.fb.com/2021/07/09/core-infra/ribbon-filter/), a space-efficient probabilistic data structure (similar to Bloom filters but ~20% smaller).
+
+1. **Build** — All 2B+ password SHA-1 hashes are inserted into a ribbon filter, sharded by the first byte (256 shards)
+2. **Query** — Your password is SHA-1 hashed, then checked against the filter using MurmurHash3 for the internal lookup
+3. **Result** — `true` means definitely breached (or ~0.78% chance of false positive). `false` means definitely not in the dataset.
+
+The filter data is stored as a single binary file with a custom format (magic: `RBBN`), containing bit-packed solution vectors and overflow tables per shard.
+
+## Security
+
+- All checking is local — passwords never leave your machine
+- Downloads are SHA-256 verified
+- HTTPS only — redirects are refused
+- Zero npm dependencies — only Node.js builtins
+
+## Performance
+
+| Operation | Time | Throughput |
+|-----------|------|------------|
+| `check(password)` | ~14 us | ~72,000/sec |
+| `checkHash(sha1hex)` | ~8 us | ~121,000/sec |
+
+Benchmarked on a single core. The filter loads into memory once (~1.8 GB RAM for HIBP) and all subsequent lookups are in-memory.
+
+## Requirements
+
+- **Node.js** >= 16.0.0
+- **Disk space** — 1.8 GB for HIBP, 13 MB for RockYou
+- **RAM** — same as disk (filter is loaded into memory)
+
+## Links
+
+- [haveibeenfiltered.com](https://haveibeenfiltered.com) — Project homepage
+- [GitHub](https://github.com/kolobus/haveibeenfiltered) — Source code
+- [npm](https://www.npmjs.com/package/haveibeenfiltered) — Package registry
+- [Have I Been Pwned](https://haveibeenpwned.com/) — Password breach data source
+
+## License
+
+[MIT](LICENSE)

package/bin/cli.js

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+const { RibbonFilter } = require('../lib/filter');
+const { DATASETS } = require('../lib/datasets');
+const { download } = require('../lib/download');
+
+const BOOLEAN_FLAGS = new Set(['stdin', 'hash', 'json', 'quiet']);
+
+function parseArgs(argv) {
+    const args = Object.create(null);
+    args._ = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith('--')) {
+            const key = arg.slice(2);
+            if (key === '__proto__' || key === 'constructor' || key === 'prototype') continue;
+            if (BOOLEAN_FLAGS.has(key)) {
+                args[key] = true;
+            } else {
+                const next = argv[i + 1];
+                if (next && !next.startsWith('--')) {
+                    args[key] = next;
+                    i++;
+                } else {
+                    args[key] = true;
+                }
+            }
+        } else {
+            args._.push(arg);
+        }
+    }
+    return args;
+}
+
+function resolveDataset(name) {
+    const ds = DATASETS[name];
+    if (!ds) {
+        console.error('Unknown dataset: ' + name + '. Available: ' + Object.keys(DATASETS).join(', '));
+        process.exit(1);
+    }
+    return ds;
+}
+
+function resolveFilterPath(args) {
+    if (args.path) return path.resolve(args.path);
+    const dsName = args.dataset || 'hibp';
+    const ds = resolveDataset(dsName);
+    if (process.env.HAVEIBEENFILTERED_PATH) return path.resolve(process.env.HAVEIBEENFILTERED_PATH);
+    return path.join(os.homedir(), '.haveibeenfiltered', ds.filename);
+}
+
+async function cmdDownload(args) {
+    const dsName = args.dataset || 'hibp';
+    const ds = resolveDataset(dsName);
+    const filterPath = resolveFilterPath(args);
+
+    if (fs.existsSync(filterPath)) {
+        console.log(ds.name + ' filter already exists at ' + filterPath);
+        return;
+    }
+
+    console.log('Downloading ' + ds.name + ' filter...');
+    console.log('  URL: ' + ds.url);
+    console.log('  Destination: ' + filterPath);
+    console.log('  Expected size: ' + (ds.expectedBytes / 1048576).toFixed(1) + ' MB');
+    console.log('  SHA-256: ' + ds.sha256);
+
+    await download(ds.url, filterPath, {
+        expectedBytes: ds.expectedBytes,
+        sha256: ds.sha256,
+        onProgress: ({ downloaded, total, percent }) => {
+            const mb = (downloaded / 1048576).toFixed(1);
+            const totalMb = (total / 1048576).toFixed(1);
+            process.stdout.write('\r  ' + mb + ' / ' + totalMb + ' MB (' + percent + '%)');
+        },
+    });
+    console.log('\nDone. Integrity verified.');
+}
+
+function cmdStatus(args) {
+    const dsName = args.dataset || 'hibp';
+    const ds = resolveDataset(dsName);
+    const filterPath = resolveFilterPath(args);
+
+    if (!fs.existsSync(filterPath)) {
+        console.log(ds.name + ': NOT DOWNLOADED');
+        console.log('  Expected path: ' + filterPath);
+        console.log('  Run: npx haveibeenfiltered download --dataset ' + dsName);
+        return;
+    }
+
+    const stat = fs.statSync(filterPath);
+    const buffer = fs.readFileSync(filterPath);
+    const filter = new RibbonFilter(buffer);
+    const meta = filter.meta;
+    filter.close();
+
+    console.log(ds.name + ': READY');
+    console.log('  Path: ' + filterPath);
+    console.log('  Size: ' + (stat.size / 1048576).toFixed(1) + ' MB (' + stat.size.toLocaleString() + ' bytes)');
+    console.log('  Keys: ' + meta.totalKeys.toLocaleString());
+    console.log('  Version: ' + meta.version);
+    console.log('  FP bits: ' + meta.fpBits);
+    console.log('  Shards: ' + meta.numShards);
+}
+
+async function cmdCheck(args) {
+    const filterPath = resolveFilterPath(args);
+
+    if (!fs.existsSync(filterPath)) {
+        console.error('Filter not found: ' + filterPath);
+        console.error('Run: npx haveibeenfiltered download --dataset ' + (args.dataset || 'hibp'));
+        process.exit(1);
+    }
+
+    const buffer = fs.readFileSync(filterPath);
+    const filter = new RibbonFilter(buffer);
+    const useHash = !!args.hash;
+    const useJson = !!args.json;
+    const useQuiet = !!args.quiet;
+
+    const lookup = useHash
+        ? (v) => filter.checkHash(v)
+        : (v) => filter.check(v);
+
+    let anyFound = false;
+    const inputs = [];
+
+    if (args.stdin) {
+        const rl = readline.createInterface({ input: process.stdin, terminal: false });
+        for await (const line of rl) {
+            const v = line.trim();
+            if (v) inputs.push(v);
+        }
+    } else {
+        if (args._.length === 0) {
+            console.error('Usage: haveibeenfiltered check <password> [--hash] [--json] [--quiet]');
+            process.exit(1);
+        }
+        inputs.push(...args._);
+    }
+
+    const results = [];
+    for (const v of inputs) {
+        const found = lookup(v);
+        if (found) anyFound = true;
+        results.push({ input: v, found });
+    }
+
+    if (useJson) {
+        console.log(JSON.stringify(results.length === 1 ? results[0] : results));
+    } else if (!useQuiet) {
+        for (const r of results) {
+            console.log(r.input + ': ' + (r.found ? 'FOUND' : 'NOT FOUND'));
+        }
+    }
+
+    filter.close();
+    if (useQuiet) process.exit(anyFound ? 1 : 0);
+}
+
+function usage() {
+    console.log('Usage: haveibeenfiltered <command> [options]');
+    console.log('');
+    console.log('Commands:');
+    console.log('  download   Download filter data for a dataset');
+    console.log('  status     Check if filter data is available');
+    console.log('  check      Check password(s) against the filter');
+    console.log('');
+    console.log('Options:');
+    console.log('  --dataset <name>   Dataset to use (hibp, rockyou). Default: hibp');
+    console.log('  --path <path>      Custom path to filter file');
+    console.log('  --stdin            Read input from stdin (check command)');
+    console.log('  --hash             Input is SHA-1 hex, not plaintext (check command)');
+    console.log('  --json             Output results as JSON (check command)');
+    console.log('  --quiet            No output, exit code 1 if any found (check command)');
+    console.log('');
+    console.log('Examples:');
+    console.log('  npx haveibeenfiltered download --dataset rockyou');
+    console.log('  npx haveibeenfiltered status');
+    console.log('  npx haveibeenfiltered check password123');
+    console.log('  npx haveibeenfiltered check --hash 5BAA61E4C9B93F3F0682250B6CF8331B7EE68FD8');
+    console.log('  npx haveibeenfiltered check --stdin < passwords.txt');
+    console.log('  npx haveibeenfiltered check --stdin --hash < hashes.txt');
+    console.log('  npx haveibeenfiltered check password123 --json');
+    console.log('  npx haveibeenfiltered check password123 --quiet && echo "safe" || echo "breached"');
+}
+
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    const command = args._.shift();
+
+    switch (command) {
+        case 'download': return cmdDownload(args);
+        case 'status':   return cmdStatus(args);
+        case 'check':    return cmdCheck(args);
+        default:
+            usage();
+            if (command) {
+                console.error('\nUnknown command: ' + command);
+                process.exit(1);
+            }
+    }
+}
+
+main().catch((err) => {
+    console.error('Error: ' + err.message);
+    process.exit(1);
+});

package/lib/datasets.js

@@ -0,0 +1,22 @@
+'use strict';
+
+const DATASETS = {
+    hibp: {
+        name: 'hibp',
+        version: 1,
+        filename: 'ribbon-hibp-v1.bin',
+        url: 'https://download.haveibeenfiltered.com/ribbon-hibp-v1.bin',
+        expectedBytes: 1918974105,
+        sha256: '4eeb8608fa8541a51a952ecda91ad2f86e6f7457b0dbe34b88ba8a7ed33750ce',
+    },
+    rockyou: {
+        name: 'rockyou',
+        version: 1,
+        filename: 'ribbon-rockyou-v1.bin',
+        url: 'https://download.haveibeenfiltered.com/ribbon-rockyou-v1.bin',
+        expectedBytes: 13456384,
+        sha256: '777d3c1640e7067bc7fb222488199c3371de5360639561f1f082db6b7c16a447',
+    },
+};
+
+module.exports = { DATASETS };

package/lib/download.js

@@ -0,0 +1,126 @@
+'use strict';
+
+const https = require('https');
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const MAX_DOWNLOAD_BYTES = 4 * 1024 * 1024 * 1024; // 4 GB absolute cap
+
+function download(url, destPath, opts) {
+    opts = opts || {};
+    const onProgress = opts.onProgress || null;
+    const expectedBytes = opts.expectedBytes || 0;
+    const expectedSha256 = opts.sha256 || null;
+
+    if (!url.startsWith('https://')) {
+        return Promise.reject(new Error('Refusing non-HTTPS download URL: ' + url));
+    }
+
+    const sizeLimit = expectedBytes > 0 ? expectedBytes + 1024 : MAX_DOWNLOAD_BYTES;
+
+    return new Promise((resolve, reject) => {
+        const dir = path.dirname(destPath);
+        fs.mkdirSync(dir, { recursive: true });
+
+        const tmpPath = destPath + '.tmp';
+        const file = fs.createWriteStream(tmpPath);
+
+        function cleanup(err) {
+            try { fs.unlinkSync(tmpPath); } catch (_) {}
+            reject(err);
+        }
+
+        https.get(url, (res) => {
+            /* Refuse redirects — the CDN URL must resolve directly */
+            if (res.statusCode >= 300 && res.statusCode < 400) {
+                res.resume();
+                cleanup(new Error('Download refused redirect (HTTP ' + res.statusCode + ' → ' + (res.headers.location || '?') + '). Update the dataset URL.'));
+                return;
+            }
+
+            if (res.statusCode !== 200) {
+                res.resume();
+                cleanup(new Error('Download failed: HTTP ' + res.statusCode));
+                return;
+            }
+
+            /* Check Content-Length against expected size if available */
+            const contentLength = parseInt(res.headers['content-length'], 10) || 0;
+            if (expectedBytes > 0 && contentLength > 0 && contentLength !== expectedBytes) {
+                res.resume();
+                cleanup(new Error('Content-Length mismatch: expected ' + expectedBytes + ' bytes, server reports ' + contentLength));
+                return;
+            }
+
+            let downloaded = 0;
+
+            res.on('data', (chunk) => {
+                downloaded += chunk.length;
+                if (downloaded > sizeLimit) {
+                    res.destroy();
+                    cleanup(new Error('Download exceeded size limit (' + sizeLimit + ' bytes). Aborting.'));
+                    return;
+                }
+                if (onProgress && contentLength > 0) {
+                    onProgress({
+                        downloaded,
+                        total: contentLength,
+                        percent: Math.round(downloaded / contentLength * 100),
+                    });
+                }
+            });
+
+            res.pipe(file);
+
+            file.on('finish', () => {
+                file.close(() => {
+                    /* Validate file size */
+                    const stat = fs.statSync(tmpPath);
+                    if (expectedBytes > 0 && stat.size !== expectedBytes) {
+                        cleanup(new Error('Downloaded file size mismatch: expected ' + expectedBytes + ' bytes, got ' + stat.size));
+                        return;
+                    }
+
+                    /* Validate RBBN magic */
+                    const fd = fs.openSync(tmpPath, 'r');
+                    const magic = Buffer.alloc(4);
+                    fs.readSync(fd, magic, 0, 4, 0);
+                    fs.closeSync(fd);
+
+                    if (magic.toString('ascii') !== 'RBBN') {
+                        cleanup(new Error('Downloaded file is not a valid ribbon filter (bad magic)'));
+                        return;
+                    }
+
+                    /* Validate SHA-256 */
+                    if (expectedSha256) {
+                        const hash = crypto.createHash('sha256');
+                        const stream = fs.createReadStream(tmpPath);
+                        stream.on('data', (chunk) => hash.update(chunk));
+                        stream.on('end', () => {
+                            const actual = hash.digest('hex');
+                            if (actual !== expectedSha256) {
+                                cleanup(new Error(
+                                    'SHA-256 mismatch!\n' +
+                                    '  Expected: ' + expectedSha256 + '\n' +
+                                    '  Got:      ' + actual + '\n' +
+                                    'The downloaded file may have been tampered with.'
+                                ));
+                                return;
+                            }
+                            fs.renameSync(tmpPath, destPath);
+                            resolve(destPath);
+                        });
+                        stream.on('error', cleanup);
+                    } else {
+                        fs.renameSync(tmpPath, destPath);
+                        resolve(destPath);
+                    }
+                });
+            });
+        }).on('error', cleanup);
+    });
+}
+
+module.exports = { download };

package/lib/filter.js

@@ -0,0 +1,175 @@
+'use strict';
+
+const crypto = require('crypto');
+const { murmurhash3_x64_128 } = require('./murmurhash3');
+
+const HEADER_SIZE = 5168;
+const RIBBON_W = 64;
+const HEX_CHARS = [48,49,50,51,52,53,54,55,56,57,65,66,67,68,69,70]; // '0'-'9','A'-'F'
+
+class RibbonFilter {
+    constructor(buffer) {
+        this._buf = buffer;
+        this.shardM = new Array(256);
+        this.shardStartRange = new Array(256);
+        this.shardOverflowCount = new Array(256);
+        this.shardSolOffset = new Array(256);
+        this.shardOvfOffset = new Array(256);
+        this._keyBuf = Buffer.alloc(40);
+        this._solBuf = Buffer.alloc(66); /* max readLen 64 + 2 sentinel bytes */
+        this._readHeader();
+    }
+
+    _readHeader() {
+        const buf = this._buf;
+
+        const magic = buf.toString('ascii', 0, 4);
+        if (magic !== 'RBBN') throw new Error('Not a ribbon filter file (magic: ' + magic + ')');
+
+        this.version    = buf.readUInt32LE(4);
+        this.numShards  = buf.readUInt32LE(8);
+        this.ribbonW    = buf.readUInt32LE(12);
+        this.hashSeed   = buf.readUInt32LE(16);
+        this.fpBits     = buf.readUInt32LE(20);
+        this.fpMask     = (1 << this.fpBits) - 1;
+        this.totalKeys  = Number(buf.readBigUInt64LE(24));
+        this.totalSolution = Number(buf.readBigUInt64LE(32));
+        this.totalOverflow = Number(buf.readBigUInt64LE(40));
+
+        /* Pre-compute BigInt constants */
+        this._fpShift = BigInt(64 - this.fpBits);
+        this._fpMaskBig = BigInt(this.fpMask);
+        this._shardStartRangeBig = new Array(256);
+
+        for (let i = 0; i < 256; i++) {
+            this.shardM[i]             = Number(buf.readBigUInt64LE(48 + i * 8));
+            this.shardStartRange[i]    = Number(buf.readBigUInt64LE(2096 + i * 8));
+            this.shardOverflowCount[i] = buf.readUInt32LE(4144 + i * 4);
+            this._shardStartRangeBig[i] = BigInt(this.shardStartRange[i]);
+        }
+
+        let offset = HEADER_SIZE;
+        for (let i = 0; i < 256; i++) {
+            this.shardSolOffset[i] = offset;
+            const packedBytes = Math.ceil(this.shardM[i] * this.fpBits / 8);
+            offset += packedBytes;
+            this.shardOvfOffset[i] = offset;
+            offset += this.shardOverflowCount[i] * 16;
+        }
+    }
+
+    check(password) {
+        const digest = crypto.createHash('sha1').update(password).digest();
+        const shard = digest[0];
+        const keyBuf = this._keyBuf;
+        for (let i = 0; i < 20; i++) {
+            keyBuf[i * 2]     = HEX_CHARS[digest[i] >> 4];
+            keyBuf[i * 2 + 1] = HEX_CHARS[digest[i] & 0xf];
+        }
+        return this._query(shard, keyBuf);
+    }
+
+    checkHash(sha1hex) {
+        const shard = parseInt(sha1hex.substring(0, 2), 16);
+        const keyBuf = this._keyBuf;
+        for (let i = 0; i < 40; i++) {
+            let c = sha1hex.charCodeAt(i);
+            if (c >= 97) c -= 32; /* a-f → A-F */
+            keyBuf[i] = c;
+        }
+        return this._query(shard, keyBuf);
+    }
+
+    _query(shard, keyBuf) {
+        const buf = this._buf;
+        const m = this.shardM[shard];
+        if (m === 0 || this.shardStartRange[shard] === 0) return false;
+
+        const fpBits = this.fpBits;
+        const fpMask = this.fpMask;
+
+        const [h1, h2] = murmurhash3_x64_128(keyBuf, this.hashSeed);
+
+        const start = Number(h1 % this._shardStartRangeBig[shard]);
+        const coeff = h2 | 1n;
+        const fp    = Number((h1 >> this._fpShift) & this._fpMaskBig);
+
+        /* Split coeff into two 32-bit halves for fast inner loop */
+        const coeffLo = Number(coeff & 0xFFFFFFFFn);
+        const coeffHi = Number((coeff >> 32n) & 0xFFFFFFFFn);
+
+        /* Copy packed solution bytes into reusable buffer */
+        const firstBit   = start * fpBits;
+        const firstByte  = Math.floor(firstBit / 8);
+        const packedSize = Math.ceil(m * fpBits / 8);
+        const readLen    = Math.min(64, packedSize - firstByte);
+        const solOff     = this.shardSolOffset[shard] + firstByte;
+        const solBuf     = this._solBuf;
+        buf.copy(solBuf, 0, solOff, solOff + readLen);
+        solBuf[readLen] = 0;     /* sentinel for 2-byte unpack at boundary */
+        solBuf[readLen + 1] = 0;
+
+        /* XOR unpacked values — two 32-bit loops instead of one BigInt loop */
+        const startBitRem = firstBit & 7;
+        let result = 0;
+
+        let cLo = coeffLo;
+        for (let pos = 0; pos < 32 && cLo !== 0; pos++) {
+            if (cLo & 1) {
+                const relBitOff = startBitRem + pos * fpBits;
+                const byteIdx = relBitOff >> 3;
+                const shift   = relBitOff & 7;
+                result ^= ((solBuf[byteIdx] | (solBuf[byteIdx + 1] << 8)) >> shift) & fpMask;
+            }
+            cLo >>>= 1;
+        }
+
+        let cHi = coeffHi;
+        for (let pos = 32; pos < RIBBON_W && cHi !== 0; pos++) {
+            if (cHi & 1) {
+                const relBitOff = startBitRem + pos * fpBits;
+                const byteIdx = relBitOff >> 3;
+                const shift   = relBitOff & 7;
+                result ^= ((solBuf[byteIdx] | (solBuf[byteIdx + 1] << 8)) >> shift) & fpMask;
+            }
+            cHi >>>= 1;
+        }
+
+        if (result === fp) return true;
+
+        /* Check overflow (bumped entries) */
+        const nOvf = this.shardOverflowCount[shard];
+        if (nOvf > 0) {
+            const ovfOff = this.shardOvfOffset[shard];
+            for (let i = 0; i < nOvf; i++) {
+                const off = ovfOff + i * 16;
+                const oCoeff = buf.readBigUInt64LE(off);
+                const oStart = buf.readUInt32LE(off + 8);
+                const oFp    = buf[off + 12];
+                if (oStart === start && oCoeff === coeff && oFp === fp)
+                    return true;
+            }
+        }
+
+        return false;
+    }
+
+    get meta() {
+        return {
+            version: this.version,
+            numShards: this.numShards,
+            ribbonW: this.ribbonW,
+            hashSeed: this.hashSeed,
+            fpBits: this.fpBits,
+            totalKeys: this.totalKeys,
+            totalSolution: this.totalSolution,
+            totalOverflow: this.totalOverflow,
+        };
+    }
+
+    close() {
+        this._buf = null;
+    }
+}
+
+module.exports = { RibbonFilter };

package/lib/index.js

@@ -0,0 +1,64 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { RibbonFilter } = require('./filter');
+const { DATASETS } = require('./datasets');
+const { download } = require('./download');
+
+const _cache = Object.create(null);
+
+function resolveDataset(name) {
+    const ds = DATASETS[name];
+    if (!ds) throw new Error('Unknown dataset: ' + name + '. Available: ' + Object.keys(DATASETS).join(', '));
+    return ds;
+}
+
+function defaultDir() {
+    return path.join(os.homedir(), '.haveibeenfiltered');
+}
+
+async function load(opts) {
+    opts = opts || {};
+    const datasetName = opts.dataset || 'hibp';
+    const ds = resolveDataset(datasetName);
+    const autoDownload = opts.autoDownload === true;
+
+    // Resolve filter path
+    let filterPath;
+    if (opts.path) {
+        filterPath = path.resolve(opts.path);
+    } else if (process.env.HAVEIBEENFILTERED_PATH) {
+        filterPath = path.resolve(process.env.HAVEIBEENFILTERED_PATH);
+    } else {
+        filterPath = path.join(defaultDir(), ds.filename);
+    }
+
+    // Return cached filter if already loaded
+    if (_cache[filterPath]) return _cache[filterPath];
+
+    // Check if file exists
+    if (!fs.existsSync(filterPath)) {
+        if (!autoDownload) {
+            throw new Error('Filter not found: ' + filterPath + '. Download it first:\n  npx haveibeenfiltered download --dataset ' + datasetName);
+        }
+        // Download from CDN
+        process.stderr.write('Downloading ' + ds.name + ' filter to ' + filterPath + '...\n');
+        await download(ds.url, filterPath, {
+            expectedBytes: ds.expectedBytes,
+            sha256: ds.sha256,
+            onProgress: ({ percent }) => {
+                process.stderr.write('\r  ' + percent + '%');
+            },
+        });
+        process.stderr.write('\n');
+    }
+
+    const buffer = fs.readFileSync(filterPath);
+    const filter = new RibbonFilter(buffer);
+    _cache[filterPath] = filter;
+    return filter;
+}
+
+module.exports = { load };

package/lib/murmurhash3.js

@@ -0,0 +1,69 @@
+'use strict';
+
+const MASK64 = (1n << 64n) - 1n;
+
+function rotl64(x, r) {
+    const br = BigInt(r);
+    return ((x << br) | (x >> (64n - br))) & MASK64;
+}
+
+function fmix64(k) {
+    k ^= k >> 33n;
+    k = (k * 0xff51afd7ed558ccdn) & MASK64;
+    k ^= k >> 33n;
+    k = (k * 0xc4ceb9fe1a85ec53n) & MASK64;
+    k ^= k >> 33n;
+    return k;
+}
+
+function murmurhash3_x64_128(buf, seed) {
+    const len = buf.length;
+    const nblocks = Math.floor(len / 16);
+
+    let h1 = BigInt(seed);
+    let h2 = BigInt(seed);
+
+    const c1 = 0x87c37b91114253d5n;
+    const c2 = 0x4cf5ad432745937fn;
+
+    for (let i = 0; i < nblocks; i++) {
+        let k1 = buf.readBigUInt64LE(i * 16);
+        let k2 = buf.readBigUInt64LE(i * 16 + 8);
+
+        k1 = (k1 * c1) & MASK64; k1 = rotl64(k1, 31); k1 = (k1 * c2) & MASK64;
+        h1 ^= k1;
+        h1 = rotl64(h1, 27); h1 = (h1 + h2) & MASK64; h1 = (h1 * 5n + 0x52dce729n) & MASK64;
+
+        k2 = (k2 * c2) & MASK64; k2 = rotl64(k2, 33); k2 = (k2 * c1) & MASK64;
+        h2 ^= k2;
+        h2 = rotl64(h2, 31); h2 = (h2 + h1) & MASK64; h2 = (h2 * 5n + 0x38495ab5n) & MASK64;
+    }
+
+    const tailOff = nblocks * 16;
+    const tlen = len & 15;
+    let k1 = 0n, k2 = 0n;
+
+    if (tlen > 8) {
+        for (let i = tlen - 1; i >= 8; i--)
+            k2 ^= BigInt(buf[tailOff + i]) << (BigInt(i - 8) * 8n);
+        k2 = (k2 * c2) & MASK64; k2 = rotl64(k2, 33); k2 = (k2 * c1) & MASK64;
+        h2 ^= k2;
+    }
+
+    if (tlen > 0) {
+        const end = Math.min(tlen - 1, 7);
+        for (let i = end; i >= 0; i--)
+            k1 ^= BigInt(buf[tailOff + i]) << (BigInt(i) * 8n);
+        k1 = (k1 * c1) & MASK64; k1 = rotl64(k1, 31); k1 = (k1 * c2) & MASK64;
+        h1 ^= k1;
+    }
+
+    h1 ^= BigInt(len); h2 ^= BigInt(len);
+    h1 = (h1 + h2) & MASK64; h2 = (h2 + h1) & MASK64;
+    h1 = fmix64(h1); h2 = fmix64(h2);
+    h1 = (h1 + h2) & MASK64; h2 = (h2 + h1) & MASK64;
+
+    return [h1, h2];
+}
+
+module.exports = { murmurhash3_x64_128 };

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "haveibeenfiltered",
+  "version": "0.1.0",
+  "description": "Offline password breach checking using ribbon filters. Check passwords against HIBP (2B+ passwords) and other breach datasets locally, with zero API calls.",
+  "main": "lib/index.js",
+  "bin": {
+    "haveibeenfiltered": "bin/cli.js"
+  },
+  "files": [
+    "lib/",
+    "bin/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node test.js"
+  },
+  "keywords": [
+    "hibp",
+    "haveibeenpwned",
+    "password",
+    "breach",
+    "security",
+    "ribbon-filter",
+    "offline",
+    "password-check",
+    "pwned",
+    "data-breach",
+    "sha1",
+    "filter"
+  ],
+  "author": "Mihail Fedorov <mihail@fedorov.net>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kolobus/haveibeenfiltered.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kolobus/haveibeenfiltered/issues"
+  },
+  "homepage": "https://haveibeenfiltered.com",
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}