HushShot Wiki

01Overview

A privacy shield for the screenshots and documents you share every day.

People paste screenshots into chat apps, AI assistants, bug trackers and social media constantly. Those images often contain a card number, a home address, a face, an API key or a QR code that logs someone in, and the file itself can carry hidden GPS coordinates and camera serial numbers. Drawing black boxes by hand is slow, easy to get wrong, and leaves the metadata untouched.

HushShot finds that information for you, hides it, and writes a clean copy of the file with no hidden metadata. It has no backend: the text recognition, face detection and barcode scanning all run in your browser tab.

Who it's for

• Job seekers sharing pay stubs, offer letters or ID scans.
• Remote workers and support staff sharing screens, logs and error screenshots.
• Developers posting terminal output that might contain tokens or keys.
• Creators posting photos where bystanders' faces or location data should not be public.
• Students and professionals uploading forms to AI tools.

02Quick start

Use the hosted app, run it locally, or wrap it as a desktop app.

Use it online

Open syasj.github.io/hushshot. There's nothing to install and no sign-up. Drop a file, or click one of the eight built-in example documents to see it work. Once the page has loaded, it keeps working with no internet connection.

Run it locally

Requires Node.js 18+ and a modern browser (Chrome/Edge 119+, Firefox 121+, Safari 17.4+).

$ git clone https://github.com/SYasJ/hushshot
$ cd hushshot
$ npm install        # also copies OCR / face / PDF assets into public/vendor
$ npm run dev        # → http://localhost:5173

Production build: plain static files you can host anywhere (GitHub Pages, Netlify, S3, a USB stick):

$ npm run build      # → dist/
$ npm run preview    # serve dist/ at http://localhost:4173

Desktop app (experimental)

A small Electron shell serves the built app from a loopback-only server and blocks every request that isn't to that server, so it's offline by design.

$ npm run desktop        # build + launch
$ npm run desktop:pack   # installers (dmg / nsis / AppImage) → release/

03User guide

From dropping a file to sharing a clean copy, usually in under a minute.

1. DropDrag an image or PDF onto the page, click to browse, or paste a screenshot with Ctrl/⌘+V.
2. ScanText recognition, barcode and face detection run in sequence. Detected items are hidden as soon as each step finishes.
3. ReviewClick a box to un-hide or re-hide it, switch whole categories off, or drag to hide anything that was missed.
4. SaveDownload the sanitized file, or copy it to the clipboard. The output is re-opened and checked for metadata.

Opening files

HushShot handles one document at a time. If several files are dropped, the first one is opened.

Reviewing detections

• Solid cyan box: the item is hidden. Hover to see its category and a masked hint (e.g. j••••••••).
• Dashed amber box: the item is not hidden. Click it to hide it again.
• Categories panel: each category has a count and a switch. Turning a category off reveals all of its items at once, which is useful if, say, you want phone numbers visible but everything else hidden.
• Draw your own box: press and drag on any empty part of the image. Manual boxes appear under Drawn by you and have a red × to remove them.
• Hold to compare: press and hold 👁 Hold to compare to see the original. Release to return to the redacted view.
• Multi-page PDFs: use the ‹ › buttons or the arrow keys. Every page is scanned; counts include all pages.

Styles & strength

The Strength slider makes the mosaic coarser. All three styles destroy the underlying detail. See Irreversible redaction.

Saving & copying

Saved files are named <original>-redacted.<ext>. After saving, a note confirms how many regions were hidden, how many metadata fields were removed, and that the re-check found 0 metadata fields in the output.

Keyboard shortcuts

04Examples

Real output from the production build. All people, numbers and addresses are fictional; portraits are AI-generated.

Every example can be opened with one click from the app's landing page. Each sheet shows the original followed by Blur, Pixelate and Blackout.

05What gets detected

Text rules run on OCR output; faces and barcodes use dedicated detectors.

Text patterns

Each OCR line is matched against the rules in src/detect/patterns.js. Matches are mapped back to pixel boxes, trimmed to just the sensitive part (e.g. only the address in Email:jane@x.com), and extended across line breaks for phones, addresses and cards.

Faces

Faces are found with the SSD-MobileNet v1 model via TensorFlow.js (WebGL when available, CPU otherwise). Two details make it work on real-world images:

• Letterboxing: each scan window is padded to a square so wide or tall images don't distort faces.
• Tiling: images larger than 640 px are also scanned in overlapping 2×2 tiles (3×3 above 2,200 px) so small faces in group photos are found. Duplicates are merged with non-maximum suppression.

Faces are covered with an ellipse and extra margin. Minimum confidence is 0.55.

Barcodes & QR codes

HushShot uses the browser's native BarcodeDetector when present (Chrome on macOS, Android and ChromeOS). Elsewhere it falls back to ZXing in pure JavaScript, trying several scales (100%, 50%, 70%, 35%, 150%) because soft screenshot codes often decode only at a different size.

Supported: QR, Data Matrix, Aztec, PDF417, Code 128, Code 39, EAN-13/8, UPC-A/E, ITF, Codabar. For 1D codes, ZXing only reports a scan line, so the full bar height is estimated from the image. A structure check rejects text that was mistaken for bars.

06Metadata stripping

What is hiding in your file, shown before it's removed.

When a file opens, the Hidden metadata card lists what was found, colour-coded by risk:

How removal works

• Nothing is copied from the source file. The export is re-encoded from raw canvas pixels, so EXIF, XMP, IPTC, embedded thumbnails, ICC profiles and PDF info dictionaries have no way to come along.
• PDFs are written with metadata auto-stamping off: no Producer, no creation or modification dates.
• Verification: after writing, the app re-opens its own output and checks it for metadata. If anything is found, the save note turns amber and asks you to report the bug.

07Security & privacy model

Bad redaction is worse than none, so the design assumes someone will try to undo it.

Local-only processing

• No backend exists. OCR (Tesseract.js), face detection (TensorFlow.js), barcode decoding (ZXing) and PDF rendering (PDF.js) all run in your tab.
• All models, WebAssembly and fonts are bundled with the app. There are no CDN calls at runtime.
• Content-Security-Policy in production builds: connect-src 'self', form-action 'none', object-src 'none', base-uri 'none'. Even a bug in the app couldn't send your file to another server.
• Tested: the end-to-end suite fails if the page makes a single request to another origin or logs any CSP violation.
• No analytics, cookies, accounts or telemetry.

Irreversible redaction

1. Average first, smooth second. Blur and Pixelate first replace each block of pixels with its average colour, and only then smooth the result. The fine detail is discarded, not just obscured.
2. Coarse cells over text. A line of text gets only about 1–2.4 cells across its height, larger than a glyph. Fine mosaics of a known font can be brute-forced back into text (the technique behind tools like Depix), and coarse cells defeat that.
3. Random noise per block. Each block's colour is jittered, so an attacker can't pixelate candidate text and look for an exact colour match.
4. Nothing is layered. The output is a fresh set of pixels. There is no original hidden underneath, unlike PDF highlight annotations, which can simply be deleted.
5. PDFs are flattened. Each page is rasterised, redacted and re-embedded as an image, so the text under a redaction no longer exists in the file.
6. Verified by OCR. The end-to-end test runs OCR on the exported file and asserts that none of the sample's secrets can be read, while normal text still can.

Threat model

Found a way to recover redacted content or leak data? Please report it privately. See SECURITY.md, and only ever share fictional documents.

08Limitations

HushShot is a safety net, not a guarantee.

• Names aren't detected. They depend on context and would cause many false positives with pattern matching alone. Use the drag-to-hide tool.
• OCR isn't perfect. Tiny fonts, low contrast, handwriting, and rotated or curved text can be missed.
• English-first. Address rules are US/Canada/UK oriented; OCR uses the English model.
• Faces: heavily rotated, covered or tiny faces can be missed, and non-faces occasionally trigger.
• Barcodes: without the native detector, damaged or very small 1D codes can be missed.
• Not detected by design: license plates, signatures, logos, company names, free-form medical text.
• PDFs are limited to 60 pages and become image-only.
• Performance: the first scan loads about 15 MB of models. Face detection on CPU (no GPU acceleration) can be slow on large images.

09Architecture

A static single-page app: vanilla JavaScript, built with Vite, no framework.

Modules

Heavy modules (OCR, faces, barcodes, PDF, export) are loaded on demand with dynamic import(), so the landing page stays small. The OCR worker is reused across files and shut down when you click New file.

10Development

Scripts, extending detection, and the test suite.

npm scripts

Adding a detection rule

A rule is one object in the RULES array in src/detect/patterns.js:

{
  // Example: an employee ID like "EMP-004521"
  type: 'account',                          // category id (see CATEGORIES)
  re: /\bEmployee\s*ID\s*[:#]?\s*(EMP-\d{6})\b/gi, // must use the g flag
  group: 1,                                  // optional: hide only this capture group
  confidence: 0.9,                           // or validate(match) → 0..1 (0 = reject)
}

1. Add the rule object. Use validate() for checks a regex can't do, like a checksum.
2. For a new category, add it to CATEGORIES and TEXT_TYPES in patterns.js, and to TAGS and CAT_ORDER in src/main.js.
3. Add positive and negative cases to tests/patterns.test.js. False positives that hide harmless text are bugs too.

test('employee id', () => {
  assert.equal(found('Employee ID: EMP-004521', ['account'])[0].s, 'EMP-004521');
  assert.deepEqual(found('EMP-004521 was mentioned', ['account']), []);  // no label → no match
});

Testing

$ npm test                                  # unit tests
$ npm run build && npm run preview &
$ npm run e2e -- http://localhost:4173/     # end-to-end

The end-to-end test drives the real UI against the production build, so the CSP is enforced. It asserts:

• every category is detected on the sample pay stub;
• OCR of the exported PNG can't read any secret, while normal text stays readable;
• a JPEG with GPS and camera data comes out with no EXIF segment;
• a 2-page PDF with a text layer and author metadata comes out with no selectable secrets and an empty info dictionary;
• zero external requests, and zero console errors or CSP violations.

CI (.github/workflows/ci.yml) runs unit tests, the build and the end-to-end test on every push and pull request.

Debugging

Open the app with ?debug (e.g. http://localhost:5173/?debug) to expose window.__hushshot in the console. It contains the live state (pages, OCR lines, regions) plus detectFaces() and detectBarcodes() for trying detectors on any canvas. Detector failures are logged with a [hushshot] prefix.

11Configuration

Build-time variables and tuning constants.

12Deployment

It's a folder of static files. Host it anywhere.

GitHub Pages (built in)

1. Fork the repository.
2. Go to Settings → Pages and set Source to GitHub Actions.
3. Set VITE_SITE_URL in .env to your Pages URL, and update public/robots.txt and public/sitemap.xml.
4. Push to main. .github/workflows/pages.yml builds and publishes automatically.

Any static host

$ npm ci && npm run build   # upload the dist/ folder

For hosts that let you set HTTP headers (Netlify, Cloudflare Pages, nginx), consider adding the same CSP as a real header plus frame-ancestors 'none', which can't be set from a <meta> tag. Serve .wasm as application/wasm.

Desktop installers

npm run desktop:pack produces a DMG (macOS), an NSIS installer (Windows) or an AppImage (Linux) in release/, using desktop/electron-builder.yml.

13Troubleshooting

14FAQ

15Roadmap

16Contributing & license

Contributions are welcome: new detection rules, locale support, UI polish, and above all bug reports with fictional reproductions. Ground rules:

• No network calls. Ever. Bundle assets instead of loading them from a CDN.
• Never keep original pixels or metadata in the output. Exports must be re-encoded from a canvas.
• Only fictional data in tests and samples.
• Run npm test and the end-to-end test before opening a pull request.

Credits

Built on Tesseract.js, @vladmandic/face-api + TensorFlow.js, ZXing, PDF.js, pdf-lib, exifr and Vite.

License

MIT © HushShot contributors.