{"_id":"@buksu-devs/fingerprintjs","name":"@buksu-devs/fingerprintjs","dist-tags":{"buksu":"5.2.2-buksu.1","latest":"5.2.2-buksu.1"},"versions":{"5.2.2-buksu.1":{"name":"@buksu-devs/fingerprintjs","description":"BukSU fork of FingerprintJS — browser fingerprinting with a stability-tiered identifier that survives display changes","version":"5.2.2-buksu.1","keywords":["fraud","fraud detection","fraud prevention","browser","identification","fingerprint","fingerprinting","browser fingerprint","device fingerprint","privacy"],"author":{"name":"FingerprintJS, Inc","url":"https://fingerprint.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Bukidnon-State-University/fingerprintjs-buksu.git"},"bugs":{"url":"https://github.com/Bukidnon-State-University/fingerprintjs-buksu/issues"},"homepage":"https://github.com/Bukidnon-State-University/fingerprintjs-buksu","main":"dist/fp.cjs.js","module":"dist/fp.esm.js","types":"dist/fp.d.ts","exports":{".":{"types":"./dist/fp.d.ts","import":"./dist/fp.esm.js","require":"./dist/fp.cjs.js"},"./device-agent":"./tools/device-agent/client.mjs","./package.json":"./package.json"},"sideEffects":false,"scripts":{"build":"rimraf dist && rollup -c rollup.config.ts --configPlugin \"@rollup/plugin-typescript={tsconfig:'tsconfig.rollupConfig.json'}\"","prepack":"yarn build","build:watch":"yarn build --watch","playground:start":"cd playground && webpack-dev-server --mode development","playground:build":"cd playground && webpack --mode production","lint":"eslint --ext .js,.ts --ignore-path .gitignore --max-warnings 0 .","lint:fix":"yarn lint --fix","test:local":"karma start --preset local --single-run","test:browserstack":"karma start --preset browserstack --single-run","test:browserstack:beta":"karma start --preset browserstack-beta --single-run","check:dts":"tsc --isolatedModules --noEmit dist/fp.d.ts","check:ssr":"node --require './dist/fp.cjs.js' --eval '' || (echo \"The distributive files can't be used with server side rendering. Make sure the code doesn't use browser API until an exported function is called.\" && exit 1)"},"devDependencies":{"@fpjs-incubator/broyster":"^0.3.0","@rollup/plugin-json":"^5.0.1","@rollup/plugin-node-resolve":"^15.0.1","@rollup/plugin-terser":"^0.2.1","@rollup/plugin-typescript":"^10.0.1","@types/jasmine":"^3.10.3","@types/ua-parser-js":"^0.7.39","@typescript-eslint/eslint-plugin":"^5.62.0","@typescript-eslint/parser":"^5.62.0","eslint":"^8.27.0","eslint-config-prettier":"^8.5.0","eslint-plugin-prettier":"^4.2.1","file-loader":"^6.2.0","got":"^11.8.5","html-webpack-plugin":"^5.5.0","karma":"^6.4.1","prettier":"^2.7.1","rimraf":"^3.0.2","rollup":"^3.25.0","rollup-plugin-dts":"^5.3.1","rollup-plugin-license":"^3.0.1","terser-webpack-plugin":"^5.3.6","ts-loader":"^9.4.2","ts-node":"^10.9.1","typescript":"^5.1.6","ua-parser-js":"^1.0.39","webpack":"^5.75.0","webpack-cli":"^5.0.1","webpack-dev-server":"^5.2.1"},"publishConfig":{"registry":"https://registry.npmjs.org","access":"public"},"gitHead":"9a26a32701f26ab05c10b814224d5201cc6f4648","_id":"@buksu-devs/fingerprintjs@5.2.2-buksu.1","_nodeVersion":"24.20.0","_npmVersion":"11.19.0","dist":{"integrity":"sha512-HBjX5DEXyx51vY5+H3pbygxrxMCROFxJiSPRw3ZbPUUdefAiEDJg/HEwC9StAknD1g/agySAosb9gtBm+zJ7Og==","shasum":"f250ee11b5617109a6dcdc83c3f499e2c186526e","tarball":"https://registry.npmjs.org/@buksu-devs/fingerprintjs/-/fingerprintjs-5.2.2-buksu.1.tgz","fileCount":11,"unpackedSize":697726,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFyyMHOE5N4EiDSEEuqmZNskD7RqAAQXHiuJxpMfpUt0AiEAjPQI/OzmmWPU2xN2xJ0O5SQ2AQXhK56CBA+UgSB1OUU="}]},"_npmUser":{"name":"buksu","email":"earnieactub@buksu.edu.ph"},"directories":{},"maintainers":[{"name":"buksu","email":"earnieactub@buksu.edu.ph"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/fingerprintjs_5.2.2-buksu.1_1788771055658_0.7770237759823349"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-07T08:50:55.454Z","5.2.2-buksu.1":"2026-09-07T08:50:55.812Z","modified":"2026-09-07T08:50:56.098Z"},"maintainers":[{"name":"buksu","email":"earnieactub@buksu.edu.ph"}],"description":"BukSU fork of FingerprintJS — browser fingerprinting with a stability-tiered identifier that survives display changes","homepage":"https://github.com/Bukidnon-State-University/fingerprintjs-buksu","keywords":["fraud","fraud detection","fraud prevention","browser","identification","fingerprint","fingerprinting","browser fingerprint","device fingerprint","privacy"],"repository":{"type":"git","url":"git+https://github.com/Bukidnon-State-University/fingerprintjs-buksu.git"},"author":{"name":"FingerprintJS, Inc","url":"https://fingerprint.com"},"bugs":{"url":"https://github.com/Bukidnon-State-University/fingerprintjs-buksu/issues"},"license":"MIT","readme":"# FingerprintJS — BukSU\n\n[![Lint and test](https://github.com/Bukidnon-State-University/fingerprintjs-buksu/actions/workflows/test.yml/badge.svg)](https://github.com/Bukidnon-State-University/fingerprintjs-buksu/actions/workflows/test.yml)\n\nBrowser fingerprinting for Bukidnon State University systems, plus tooling for device\nidentification across those systems.\n\n> ## Credit\n>\n> This project is derived from **[FingerprintJS](https://github.com/fingerprintjs/fingerprintjs)**\n> by [Fingerprint, Inc](https://fingerprint.com), used and redistributed under the\n> [MIT license](LICENSE). The entropy sources, hashing, agent and the whole of `src/` except\n> `src/stable_id.ts` are their work, and the upstream copyright is retained in the license banner\n> of every built file.\n>\n> This is **not** an official Fingerprint product and is not endorsed by them. Do not report\n> problems with it to the upstream project — see [Support](#support).\n>\n> If you want the original, unmodified library, use\n> [`@fingerprintjs/fingerprintjs`](https://www.npmjs.com/package/@fingerprintjs/fingerprintjs)\n> from public npm. Their [commercial offering](https://fingerprint.com/products/identification/)\n> is considerably more accurate than anything in this repository.\n\n## What this adds\n\nEverything upstream provides, plus:\n\n| Addition | What it is |\n|---|---|\n| `hashStableComponents()` | A visitor identifier that survives display changes, zoom and accessibility toggles. See [`src/stable_id.ts`](src/stable_id.ts). |\n| [`tools/device-agent`](tools/device-agent) | A machine-local service giving **one device ID across every browser** — the thing a fingerprint alone cannot do. |\n| [`tools/identity-server`](tools/identity-server) | Device identity store and API shared across BukSU systems. |\n| [`tools/collision-study`](tools/collision-study) | Measures whether a fingerprint is usable as a device identity on your actual fleet. |\n| [`tools/cross-browser-test`](tools/cross-browser-test) | Verifies one device ID holds across browsers, private windows and VPN. |\n\nThe package ships `dist/` plus the device-agent browser client. The agent itself and the\nservers stay in the repository — they run on machines, not in a bundle.\n\nFull setup for npm, pnpm, Yarn 1, Yarn Berry and CI is in\n**[docs/installing.md](docs/installing.md)** — including the `read:packages` token every\ndeveloper needs, and why a `^5.2.0` range will not match a `-buksu` release.\n\n| Import | Contents |\n|---|---|\n| `@buksu-devs/fingerprintjs` | The library: `load`, `hashComponents`, `hashStableComponents`, … |\n| `@buksu-devs/fingerprintjs/device-agent` | `getDeviceIdentity`, `getAgentDeviceId` |\n\n## Installation\n\nPublished to **npmjs.com** as a public package. Nothing to configure — no registry line, no\ntoken, no `.npmrc`, no CI secret:\n\n```bash\nnpm install @buksu-devs/fingerprintjs@5.2.2-buksu.1\n```\n\nPin the version exactly. `-buksu.N` is a semver prerelease, so a caret range — even `>=5.2.0` —\nnever matches it.\n\nThe **source repository stays private**; only the compiled build is published. See\n[`docs/installing.md`](docs/installing.md), including how to migrate off the retired\nGitHub Packages releases.\n\n## Usage\n\n```js\nimport * as FingerprintJS from '@buksu-devs/fingerprintjs'\n\nconst fp = await FingerprintJS.load()\nconst { visitorId, components, confidence } = await fp.get()\n\n// Upstream identifier — rotates when the display, zoom or a preference changes\nconsole.log(visitorId)\n\n// Fork addition — survives those changes\nconsole.log(FingerprintJS.hashStableComponents(components))\n```\n\nRead the caveats in [`docs/fork.md`](docs/fork.md) before adopting `hashStableComponents()`. It\ntrades entropy for stability and can be **worse** than the stock identifier on a fleet of\nidentically imaged machines.\n\n### What `get()` returns\n\n```ts\n{\n  visitorId:  string,            // 32 hex chars — per BROWSER, not per device\n  confidence: { score: number, comment?: string },\n  components: { [source: string]: { value, duration } | { error, duration } },\n  version:    string             // the agent version, e.g. \"5.2.0\"\n}\n```\n\n`confidence.score` is a coarse platform heuristic, not a measure of the components gathered —\n`src/confidence.ts` branches on platform alone (macOS 0.5, Windows 0.6, Android 0.4, other 0.7).\n\n## Getting a device ID\n\n`visitorId` identifies a **browser installation**, not a machine. Chrome, Firefox and Safari on\none computer produce three unrelated values. For an identifier that is the same in every browser\nyou need [`tools/device-agent`](tools/device-agent) running on the machine.\n\n```js\nimport * as FingerprintJS from '@buksu-devs/fingerprintjs'\nimport { getDeviceIdentity } from '@buksu-devs/fingerprintjs/device-agent'\n\nconst identity = await getDeviceIdentity({ fingerprintjs: FingerprintJS })\n\nif (identity.cross_browser) {\n  // identity.device_id is the same in every browser on this machine\n} else {\n  // No agent reachable. identity.browser_id holds across your systems, VPN and\n  // incognito — but NOT across browsers.\n}\n```\n\n### What `getDeviceIdentity()` returns\n\n```ts\n{\n  id:            string,          // device_id when the agent answered, else browser_id\n  source:        'agent' | 'fingerprint',\n  cross_browser: boolean,         // ALWAYS check this before treating id as a device\n  device_id:     string | null,   // UUID from the agent, null without it\n  browser_id:    string,          // hashStableComponents() of this browser\n  machine_name?: string,          // agent only\n  confidence:    number,\n  components:    object\n}\n```\n\nThe agent lookup runs concurrently with the fingerprint and times out at 1.2 s, so a missing\nagent costs no meaningful latency.\n\n### What the identity server returns\n\n`POST /identify` on [`tools/identity-server`](tools/identity-server), which stores identities and\nshares them across BukSU systems:\n\n```jsonc\n{\n  \"device_id\":          \"fd87b3ea-da12-41d6-bc96-a23d65ac2551\",\n  \"browser_id\":         \"b0ef4edc2a42ff368cd8c072fb94575c\",\n  \"cross_browser\":      true,\n  \"matched_by\":         \"agent\",      // agent | browser_id | fuzzy | new | ambiguous_new\n  \"confidence\":         1,\n  \"runner_up\":          0,            // similarity of the second-best match\n  \"new_device\":         false,\n  \"risk_score\":         10,           // coarse hint — NOT Fingerprint Pro's suspect_score\n  \"botInformation\":     { \"automated\": false, \"signals\": [], \"reliability\": \"low\" },\n  \"incognito\":          null,         // not detectable, by design — see below\n  \"ip\":                 \"10.0.5.31\",\n  \"firstSeenAt\":        \"2026-09-03T05:15:44.769Z\",\n  \"lastSeenAt\":         \"2026-09-03T08:22:10.114Z\",\n  \"seen_count\":         7,\n  \"systems\":            [\"feedback\", \"portal\", \"library\"],\n  \"browsers_on_device\": 3\n}\n```\n\nThree fields are deliberately honest rather than impressive:\n\n- **`incognito` is always `null`.** Not an oversight. The library is built so every source\n  returns the *same* value in private mode — which is why identity survives incognito at all.\n  There is nothing to detect. Upstream lists incognito detection as a commercial-only feature\n  for the same reason.\n- **`botInformation.reliability` is `\"low\"`.** Every signal is client-reported and trivially\n  spoofed. Useful against casual automation, useless against anyone determined.\n- **`risk_score`, not `suspect_score`.** Named differently so it is not mistaken for\n  Fingerprint's proprietary score, which is fed by server-side signals this has no access to.\n\n**Always read `cross_browser`.** `false` means you hold a per-browser identifier and the same\nmachine in another browser will look like a different device.\n\n## What a fingerprint can and cannot do\n\nMeasured on one Mac with Chrome 152, Firefox 155 and Safari 26.5:\n\n`visitorId` and `device_id` are **not** the same thing. `visitorId` is a hash of browser\nsignals and identifies a browser installation; `device_id` is a UUID the agent stores on the\nmachine. The difference only shows up in one row, but it is the row that matters:\n\n| Case | `visitorId` (no agent) | `device_id` (with agent) |\n|---|---|---|\n| Across BukSU systems (different origins) | ✅ same | ✅ same |\n| Incognito / private window | ✅ same | ✅ same |\n| VPN connected | ✅ same — no IP is read anywhere | ✅ same |\n| Cookies and storage cleared | ✅ same | ✅ same |\n| Monitor changed, zoom, dark mode | ❌ stock · ✅ `hashStableComponents()` | ✅ same |\n| **Different browser, same machine** | ❌ **different — unfixable** | ✅ **same** |\n| Two identically imaged PCs | ⚠️ **same — a false match** | ✅ different (random per machine) |\n\nMeasured across three engines on one machine:\n\n```\nChrome    browser_id b0ef4edc2a42…   device_id fd87b3ea-da12…\nFirefox   browser_id 58c4e8a72ee8…   device_id fd87b3ea-da12…\nSafari    browser_id b60b1296d5ae…   device_id fd87b3ea-da12…\n                     ^^^ three different       ^^^ one identical\n```\n\nCross-engine similarity on one machine — Chrome vs Safari **0.444**, Firefox vs Safari **0.496**,\nChrome vs Firefox **0.528**. Two genuinely different computers score **0.808**. Two browsers on\none machine are *less alike* than two separate machines, so no threshold bridges them.\n[`tools/device-agent`](tools/device-agent) exists for exactly this, and closes it.\n\n## Documentation\n\n| | |\n|---|---|\n| [`docs/fork.md`](docs/fork.md) | **Start here** — what this fork changes, publishing, upstream sync |\n| [`docs/api.md`](docs/api.md) | Upstream API reference |\n| [`docs/version_policy.md`](docs/version_policy.md) | Semver and identifier stability promises |\n| [`docs/browser_support.md`](docs/browser_support.md) | Supported browsers |\n| [`CLAUDE.md`](CLAUDE.md) | Architecture, commands and project constraints |\n| [`contributing.md`](contributing.md) | Upstream's contribution rules — still apply to `src/` |\n\n## Security status\n\nThe published **package** carries only `src/`, which has been audited and is clean.\n\nThe **server tooling in `tools/` has open security issues** and must not be deployed yet — see\n[Issues](https://github.com/Bukidnon-State-University/fingerprintjs-buksu/issues). Most\nsignificantly, the identity server currently accepts an unverified `device_id`, which defeats the\ncross-browser guarantee it exists to provide.\n\nFingerprinting identifiable students across university systems is personal data processing under\nthe Philippine **Data Privacy Act (RA 10173)**. Clear it with the university's data protection\nofficer before deploying, not after.\n\n## Development\n\n```bash\nyarn install\nyarn build                                  # -> dist/\nyarn playground:start                       # dev playground on :8081\nyarn lint\nyarn test:local --browsers ChromeHeadless   # needs yarn build first\n```\n\nCI runs lint, build, `check:dts` and `check:ssr`. It does **not** run browser tests — upstream\nuses BrowserStack, which this fork has no credentials for, and `fonts.test.ts` cannot pass on a\nLinux runner. Run the suite locally before publishing.\n\n## Support\n\nOpen an [issue on this repository](https://github.com/Bukidnon-State-University/fingerprintjs-buksu/issues).\n\nDo **not** raise problems with this fork on the upstream project, its Discord, or its support\nemail. If you can reproduce a bug against unmodified `@fingerprintjs/fingerprintjs`, that one\ndoes belong [upstream](https://github.com/fingerprintjs/fingerprintjs/issues) — and please\ncontribute it there.\n\n## License\n\n[MIT](LICENSE), inherited from FingerprintJS. Copyright (c) Fingerprint, Inc. Modifications by\nBukidnon State University are released under the same license.\n","readmeFilename":"readme.md","_rev":"1-e63b4632f67edfa23391c42e6bb3a0ac"}