|
| 1 | +# AI Assistant Working Instructions for Broprint.js |
| 2 | + |
| 3 | +These instructions teach AI coding agents how to contribute effectively to this repository. Keep answers concise and pragmatic. |
| 4 | + |
| 5 | +## Project Essence |
| 6 | +- Purpose: Generate a stable (not guaranteed globally unique) browser fingerprint combining an AudioContext timing trace + a rendered Canvas data URI hashed with `cyrb53` (custom 53‑bit hash). |
| 7 | +- Public API surface (exported): `getCurrentBrowserFingerPrint(): Promise<string>` from `src/index.ts`. |
| 8 | +- Build: TypeScript -> JS via `npm run build:npm` (tsc). Published package exposes compiled code in `lib/` with `main` + `types` pointing to `./lib/index.*`. |
| 9 | + |
| 10 | +## Key Files / Flow |
| 11 | +1. `src/index.ts` orchestrates fingerprint creation: |
| 12 | + - Calls `generateTheAudioFingerPrint.run(cb)` (offline audio render) -> partial numeric string. |
| 13 | + - Calls `getCanvasFingerprint()` -> data URI of deterministic canvas drawing (or static fallback if unsupported). |
| 14 | + - Concatenates (currently same logic for Brave) then base64 encodes audio part and appends canvas value, then hashes with `cyrb53` (seed 0) -> final number, coerced to string. |
| 15 | +2. `src/code/generateTheAudioPrints.ts`: Offline AudioContext rendering 500 frames (indices 4500-4999) summed to produce a floating sum -> stringed. |
| 16 | +3. `src/code/GenerateCanvasFingerprint.ts`: Draws layered text & shapes on canvas for entropy; returns `canvas.toDataURL()`. |
| 17 | +4. `src/code/EncryptDecrypt.ts`: Contains hash utilities used (murmurhash3_32_gc, javaHashCode, cyrb53). Only `cyrb53` currently used by public API. |
| 18 | + |
| 19 | +## Conventions & Patterns |
| 20 | +- No external runtime dependencies (despite README mention of crypto-js in older versions). Keep bundle tiny; avoid adding deps unless essential. |
| 21 | +- Hash / fingerprint logic purposely simple & deterministic; avoid introducing time, locale, or network variability unless behind an opt-in flag. |
| 22 | +- Use synchronous operations except for audio (asynchronous OfflineAudioContext). Promise composition kept minimal. |
| 23 | +- Fallback behavior: If audio fingerprinting fails, fall back to canvas-only hash inside catch. |
| 24 | +- Brave browser branch present but currently identical; if modifying, keep Brave privacy differences in mind (possible reduced entropy). |
| 25 | +- No test suite yet; if adding tests, prefer lightweight Jest or vitest with jsdom for canvas + mock Web Audio. |
| 26 | +- Formatting is minimal; preserve existing style (no semicolons at ends except retained by file, loose var usage inside legacy code—refactors should be incremental, not sweeping). |
| 27 | + |
| 28 | +## Build / Publish Workflow |
| 29 | +- Build command: `npm run build:npm` (invokes `tsc`). Ensure `lib/` artifacts updated. |
| 30 | +- CI: `.github/workflows/ci.yml` builds on PRs (develop/master) and pushes to develop. |
| 31 | +- Publish: Push to `master` triggers `.github/workflows/publish.yml` which publishes if the version in `package.json` is not already on npm. Version bumps are manual. |
| 32 | +- Files published: restricted via `package.json#files` (lib, LICENSE, README.MD). Ensure any new public types land in `lib/`. |
| 33 | + |
| 34 | +## When Editing Public API |
| 35 | +- Update both TypeScript source (`src/`) and ensure build outputs land in `lib/` (run build locally before committing if repo tracks build output; if not, rely on publish workflow to regenerate—currently repository already contains `lib/`). |
| 36 | +- Keep signature of `getCurrentBrowserFingerPrint` stable; if adding options, prefer an optional parameter object with defaults (e.g., `{ includeAudio?: boolean; includeCanvas?: boolean; seed?: number }`). |
| 37 | +- Document new options in README and bump minor version. |
| 38 | + |
| 39 | +## Error Handling |
| 40 | +- Current API rejects only on total failure (both audio + canvas). Preserve this contract; do not throw synchronous errors—return a rejected Promise. |
| 41 | +- If adding new failure modes, ensure they’re caught and degrade gracefully to reduced-entropy fingerprint. |
| 42 | + |
| 43 | +## Performance / Size Considerations |
| 44 | +- Avoid heavy libs (crypto, uuid) — custom hashing already present. |
| 45 | +- Audio & canvas operations should remain < a few ms; do not add layout thrash or large DOM manipulations. |
| 46 | + |
| 47 | +## Example Usage (keep working) |
| 48 | +```ts |
| 49 | +import { getCurrentBrowserFingerPrint } from '@rajesh896/broprint.js'; |
| 50 | +const id = await getCurrentBrowserFingerPrint(); |
| 51 | +``` |
| 52 | + |
| 53 | +## Common Pitfalls for Agents |
| 54 | +- Don’t introduce Node-only APIs into browser path (fs, path, etc.). This library is browser-focused. |
| 55 | +- Avoid using Date.now randomness in the fingerprint (breaks determinism) unless put behind a clearly documented opt-in. |
| 56 | +- Maintain ESM compatibility; entry point currently works via bare import. |
| 57 | +- Preserve tree-shake friendliness: avoid side-effectful top-level code. |
| 58 | + |
| 59 | +## Safe Extension Ideas (If Asked) |
| 60 | +- Optional config parameter to disable audio or canvas. |
| 61 | +- Expose raw (unhashed) components for analytics (`getRawFingerPrintParts()` returning { audio, canvas }). |
| 62 | +- Add lightweight tests for deterministic hashing given mocked inputs. |
| 63 | + |
| 64 | +## Security / Privacy Notes |
| 65 | +- Fingerprint NOT cryptographically secure or collision-proof; it’s a heuristic identifier. Be explicit if asked. |
| 66 | +- Respect user privacy—avoid adding invasive signals (plugins, fonts) without discussion. |
| 67 | + |
| 68 | +## Maintainer Metadata |
| 69 | +- CODEOWNERS: @Rajesh-Royal owns all paths. |
| 70 | +- Direct questions to issues or discussions; security concerns follow SECURITY.md process. |
| 71 | + |
| 72 | +Respond with changes only; keep explanations short. |
0 commit comments