Menu ▾ ▴

FAQ

RedoSan

Frequently Asked Questions

General

What is RedoSan Authenticity?

A 100% client-side suite for proving the authenticity and provenance of digital media. It combines image watermarking (9 algorithms), audio watermarking (8 algorithms), document watermarking (5 techniques), fingerprinting (21 hash algorithms), pixel injection (23 algorithms), C2PA Content Credentials, OpenTimestamps, forensic analysis, Decentralized Identity (DID), Digital Passport certificates, file conversion, ID generation, metadata analysis, and on-device face/iris/voice biometrics — all running locally in your browser or via a Node.js CLI. No data is ever uploaded to a server (except OpenTimestamps, which contacts Bitcoin timestamp servers, and CDN/Hugging Face fetches for model and library files).

Who is this for?

Journalists verifying photo authenticity, artists proving ownership of digital artwork, photographers establishing provenance, musicians protecting audio content, forensic analysts examining image integrity, content creators documenting their workflow, developers integrating authenticity checks, legal professionals needing evidentiary documentation, and anyone who needs to demonstrate that a digital file has not been tampered with since a known point in time.

Is it free?

Yes, it is open-source under the GPL-2.0-or-later license (package.json). You can use it, modify it, and distribute it freely, provided you comply with the license terms.

Is it production-ready?

The project is stable. All 6,200+ tests pass across 107 unit test files + 59 E2E suites (Node 22 + 24), 77 CI/CD workflows enforce code quality, 30+ historical CodeQL alerts are resolved, and all core algorithms are functionally complete. The tool is actively maintained (v2.0.0 released 2026-10-07).

Does it work offline?

The browser version requires an internet connection for the initial page load (CDN libraries: jsPDF, docx, QRious, JSZip, LameJS, FFmpeg.wasm, and for the biometric tools the ONNX runtimes / model files). Local vendor/ copies load first, with CDN as fallback. After that, all processing is local. The CLI version works fully offline once dependencies are installed.

How do I install the CLI?

From a clone of the repository:

git clone https://github.com/Redo-San/RedoSan-Authenticity.git
cd RedoSan-Authenticity
npm install
npm link        # makes the `redosan` command available globally
redosan --help

Without npm link, run it directly with node cli/index.js <command>. Requirements: Node.js >= 22.14.0. See [Installation] for the full setup guide (tests, dev server, troubleshooting).

Is the CLI published on npm?

Not yet. The package is prepared as redosan-authenticity-cli (v2.0.0, bin wiring and staged-publish workflow in place) but npm view redosan-authenticity-cli returns 404 — publication is staged behind OIDC/trusted-publishing approval. Install from source as described above until it is published.

What's new in v2.0.0?

  • npm-ready CLI — package fully prepared for publication (bin wiring, staged-publish workflow with tag/version verification)
  • Security hardening — CLI tool names no longer pass through a shell (command-injection fix), perceptual hashes wired into the fingerprint CLI, patched katex/smol-toml/MCP SDK overrides, two-tier npm-audit policy
  • Contribution readiness — full GPL-2.0 text, Code of Conduct, issue templates, 12 curated good first issue tasks
  • Quality — 107 unit test files + 59 E2E suites (6,200+ tests), 77 CI workflows, knip/depcheck policy alignment, two-phase release workflow with changelog + SBOM

Earlier: v1.9 added Voice Biometric, v1.8 added Iris Biometric i18n and quality gates, v1.7.1 hardened Face Biometric (WebAuthn PRF vault, liveness, ArcFace ONNX). See [Changelog] for the complete release history.

Technical

What file formats are supported?

Format Fingerprint Watermark Pixel Inject C2PA Read C2PA Write Audio WM Doc WM Metadata Timestamp
JPEG Yes Yes Yes Yes Yes No No Yes Yes
PNG Yes Yes Yes Yes Yes No No Yes Yes
BMP Yes Yes Yes No No No No Yes Yes
TIFF Yes No No No No No No Yes Yes
WebP Yes No No No No No No Yes Yes
WAV No No No No No Yes No No Yes
DOCX No No No No No No Yes No Yes
PDF No No No No No No Yes No Yes
TXT Yes No No No No No Yes No Yes

How many algorithms does each tool offer?

Tool Algorithms
Image Watermark 9 (Spatial LSB, Frequency DCT, Neural SS, Latent DCT, Zero-bit, Multi-bit, Forensic, Fragile, Imatag-style) + auto-detect
Audio Watermark 8 (LSB, Phase Coding, Echo Hiding, DSSS, QIM, DWT Haar, Patchwork, DCT)
Document Watermark 5 (Whitespace, Zero-Width Characters, Synonym, Line-Shift, Word-Shift)
Pixel Injection 23 across 4 categories (Spatial 4, Frequency 4, Deep Learning 5, Professional 5) + 5 analysis modes (statistical detection, ML detection, blind decoding, robustness testing, quality metrics); Auto Detect tries them all
Fingerprint 21 (17 cryptographic + 4 perceptual: pHash, aHash, dHash, wHash)
ID Forge 5 (UUID v4, UUID v7, ULID, NanoID, SWHID)
DID 3 key types (Ed25519, P-256, RSA-2048/RSA-4096)
Certificate 3 output formats (PDF, DOCX, EPUB)
Face / Iris / Voice On-device detection, matching, liveness + anti-spoof, template protection

How do the image watermark algorithms differ?

  • Spatial algorithms (Spatial LSB, Neural SS, Multi-bit, Fragile): Modify pixel values directly. High capacity, low robustness.
  • Frequency algorithms (Frequency DCT, Latent DCT, Zero-bit, Forensic, Imatag-style): Transform the image, modify coefficients, inverse-transform. Lower capacity, higher robustness.

Which watermark algorithm should I use?

  • For maximum capacity: Spatial LSB (3 bits/pixel) or Imatag-style (DCT dual-channel)
  • For best robustness against cropping: Latent DCT or Imatag-style (both DCT-based with redundancy)
  • For best overall balance: Frequency DCT
  • For tamper detection: Fragile (SHA-256 based, tamper-evident)
  • For presence-only marking: Zero-bit (fixed RedoSanZeroBit signature)
  • For JPEG workflows: DCT-based algorithms survive JPEG compression better, but none are 100% robust

Why doesn't DCT survive JPEG compression perfectly?

DCT-based watermarking modifies frequency coefficients. JPEG compression reapplies its own DCT with quantization, which alters or destroys the watermarked coefficients. Even at JPEG quality 100, some quantization occurs. This is a fundamental limitation of transform-domain watermarking combined with lossy compression.

Can watermarking and pixel injection be used together?

Spatial algorithms share the same bit positions, so they can interfere if used on the same image. Frequency-domain algorithms operate on different transform coefficients and can generally coexist, though capacity is reduced. The Simplified Mode pipeline handles this automatically by using different algorithm families for watermarking vs. pixel injection.

What is C2PA and why must it be last?

C2PA (Coalition for Content Provenance and Authenticity) is an industry standard for embedding provenance metadata in media files. The manifest contains claims about who created the content, when, and with what tools. C2PA must be the last pixel operation because canvas operations (toBlob(), toDataURL(), loadImage()) strip C2PA chunks from image data. If you watermark after C2PA signing, the C2PA manifest is lost.

What is DID and how is it used?

DID (Decentralized Identifier) provides a way to create self-sovereign digital identities. RedoSan Authenticity supports the DID:key method with Ed25519, P-256, and RSA key types. DIDs can be used to sign file fingerprints, creating a cryptographic link between the file and the identity. The signature can be verified independently.

How does the domain origin self-check work?

All browser JavaScript files start with an IIFE that checks window.location.href against a regex allowing only redo-san.github.io, localhost, and 127.0.0.1 (file: URLs are exempt). On untrusted domains the script throws RedoSan Authenticity: This script is protected by GPL license. — so a cloned deployment fails loudly instead of looking functional.

How does the MPA architecture work?

Each tool has its own standalone HTML page at Style/pages/{name}/index.html. The MPA router (mpa-router.js) intercepts internal link clicks, fetches the target page via AJAX, swaps only the content area, and updates the URL via pushState. This preserves the audio player, sidebar state, and all JS state across navigations. The SPA entry point (index.html) remains fully functional with hash-based routing. Removal-tools links are the exception: they always perform a full-page redirect. See [Architecture] for the full design.

Security

Is my data safe?

Yes. The entire tool runs client-side in your browser or locally on your machine. No images, metadata, or personal information is uploaded to any server. The only network calls are:

  1. CDN library loading (initial page load and lazily-loaded modules)
  2. ONNX model / Hugging Face fetches for the biometric tools
  3. OpenTimestamps calendar (for timestamp creation)
  4. Bitcoin block explorers (for timestamp verification)

How are passwords handled?

Passwords are used to seed a pseudo-random number generator for algorithms that require randomized pixel selection. The CLI additionally uses crypto.pbkdf2Sync with 100,000 iterations for key derivation. Passwords are never sent over the network.

Is my biometric data uploaded anywhere?

No. Face, iris, and voice templates are stored on-device (local registry / IndexedDB, encrypted — face uses a WebAuthn PRF vault) and matching runs in the browser. Only model files are downloaded from CDNs / Hugging Face. Consent is session-scoped and withdrawable, and all three pipelines include liveness / anti-spoof checks.

What do the biometric tools do?

All three run in the browser only (no CLI equivalent):

  • Face — register and verify faces with ArcFace ONNX embeddings, WebAuthn PRF vault storage, anti-spoof and liveness checks ([Face Biometric])
  • Iris — in-browser iris capture with quality assessment (ISO/IEC 29794-6), liveness/anti-spoof, and encrypted templates ([Iris Biometric])
  • Voice — 3-minute recorder with voice-activity detection, ECAPA/WavLM embeddings, anti-spoof, encrypted template protection, and C2PA audio provenance ([Voice Biometric])

What happens if someone steals the C2PA key?

The embedded C2PA key is a well-known test key from the C2PA specification. It is not intended for production use. In a production deployment, you would replace it with your own key pair. Anyone with the test key can create valid C2PA manifests, which is why the tool is designed for transparency (the key is public) rather than cryptographic trust.

How does the Service Worker protect against malicious files?

The SW intercepts all fetch requests and enforces:

  1. 61 dangerous extensions blocked (exe, sh, py, elf, jar, dll, zip, apk, etc.)
  2. 128-entry JavaScript whitelist (126 unique) — any unlisted .js file gets 403
  3. 50 CSS files whitelisted
  4. 27 HTML pages whitelisted (SPA, 404, template, 23 MPA pages)
  5. 64 YML/YAML files whitelisted (workflow files)
  6. 18 JSON config files whitelisted
  7. 5 Markdown + 1 XML whitelist entries
  8. 23 version-pinned external CDN URLs whitelisted
  9. Embedded URL detection at 3 encoding levels (plain, single-encoded, double-encoded)
  10. Logo hotlink protection — direct navigation to logo files returns 403

What protection exists against automated bots?

The browser UI includes checkAutomation() which detects headless Chrome, Puppeteer, Playwright, Selenium, and other automation frameworks. When detected, a warning overlay is displayed. Detection methods include checking navigator.webdriver, navigator.plugins.length, and several other automation-specific properties.

Can the security layers be bypassed?

The CLI validation can be bypassed with --allow-dangerous. The Service Worker's whitelists are enforced at the SW level and cannot be bypassed by client-side JavaScript (though a motivated user could disable the SW in DevTools). The domain origin self-check is trivially patched by removing the IIFE — it is a deterrent, not a cryptographic safeguard. The full threat model and defense layers are documented on [Security].

What CodeQL alerts were fixed?

30+ CodeQL alerts were resolved across the project's history: incomplete URL sanitization, missing null checks, prototype pollution, XSS via innerHTML, regex denial of service, insecure random number generation, unsigned integer handling, and an iris_ui.js XSS fix shipped in v1.7.1. Intentional patterns (such as the tag-whitelist approach in sanitizeHtml) are documented with suppression comments.

Are there any known vulnerabilities?

The project tracks zero open alerts across CodeQL, Dependabot, and Secret Scanning, and runs a two-tier npm audit: a blocking npm audit --omit=dev --audit-level=high in the unit-test CI job, a non-blocking full-scope audit in E2E, plus a weekly security-audit.yml run. 22 dependencies are overridden to patched versions (tar 7.5.22, js-yaml 4.3.2, markdown-it 14.3.2, smol-toml 1.9.0, qs 6.16.0, katex 0.18.2, serialize-javascript 7.0.6, uuid 14.0.0, glob 13.0.6, got 11.8.5, tmp 0.2.7, and others — see package.json).

Browser

Why is the page blank when I open it locally?

The domain origin self-check in all JS files blocks execution on any domain other than redo-san.github.io, localhost, or 127.0.0.1. Make sure you are accessing via http://localhost:PORT or http://127.0.0.1:PORT (for example the bundled node dev-server.js).

How do I switch between Simplified and Professional modes?

Use the mode toggle buttons in the header. Simplified mode provides a guided 10-step pipeline. Professional mode provides per-algorithm control in individual sections. The mode is persisted in history.state for back/forward navigation.

How do I change the language?

Click the language toggle button in the top-right corner to switch between 8 languages: Arabic, German, English, Spanish, French, Japanese, Korean, and Chinese. The setting is applied immediately and all UI text is re-translated. RTL/LTR direction is updated automatically.

Can I access individual tools directly?

Yes! Each tool has its own standalone MPA page:

  • https://redo-san.github.io/RedoSan-Authenticity/Style/pages/watermark/
  • https://redo-san.github.io/RedoSan-Authenticity/Style/pages/audio-watermark/
  • https://redo-san.github.io/RedoSan-Authenticity/Style/pages/fingerprint/
  • https://redo-san.github.io/RedoSan-Authenticity/Style/pages/pixel-injection/
  • https://redo-san.github.io/RedoSan-Authenticity/Style/pages/c2pa/
  • https://redo-san.github.io/RedoSan-Authenticity/Style/pages/did/
  • https://redo-san.github.io/RedoSan-Authenticity/Style/pages/certificate/
  • https://redo-san.github.io/RedoSan-Authenticity/Style/pages/forensic/
  • https://redo-san.github.io/RedoSan-Authenticity/Style/pages/converter/
  • https://redo-san.github.io/RedoSan-Authenticity/Style/pages/id_forge/
  • https://redo-san.github.io/RedoSan-Authenticity/Style/pages/document-watermark/
  • https://redo-san.github.io/RedoSan-Authenticity/Style/pages/face-biometric/
  • https://redo-san.github.io/RedoSan-Authenticity/Style/pages/iris-biometric/
  • https://redo-san.github.io/RedoSan-Authenticity/Style/pages/voice-biometric/
  • https://redo-san.github.io/RedoSan-Authenticity/Style/pages/removal-tools/ (local builds only — see below)
  • and more: metadata, timestamp, about, contact, privacy, social, search, home

Why don't I see the Removal Tools on the live site?

Removal_Tools/ and Style/pages/removal-tools/ are gitignored and local-only (commit 6f2b8ee removed them from GitHub Pages). On redo-san.github.io, sanitizeRemovalTools() strips the links from the navigation, the MPA router forces a full-page redirect, and window.RedoSanLoadRemovalTools no-ops. The page shell exists in the whitelist, but the engine script only loads on self-hosted copies where Removal_Tools/removal_tools.js is present.

Why does the Digital Passport PDF look different from what I see on screen?

The PDF is generated client-side using jsPDF, which has limitations in layout rendering compared to HTML/CSS. The PDF prioritizes data completeness over visual fidelity. All hash values, timestamps, user info, C2PA claims, and watermark data are included.

Development

How do I add a new watermark algorithm?

  1. Add the embed/extract functions in Watermark/watermark_core.js
  2. Add the algorithm entry in Watermark/watermark.js (algorithm list + switch case)
  3. Add the algorithm to the CLI handler in cli/commands/watermark.js
  4. Add tests in cli/tests/watermark_core_test.js

How do I add a new language translation?

  1. Copy Style/lang/i18n-data-en.js to Style/lang/i18n-data-{code}.js
  2. Translate all values (keep keys unchanged)
  3. Add the language to Style/i18n.js language list
  4. Add the language file path to the JS_WHITELIST in sw.js (and mirror in 404.html)

How do I add a new file to the JS whitelist?

Add the path to the JS_WHITELIST array in both sw.js and 404.html. Note the two files can drift: as of v2.0.0, sw.js additionally lists vendor/docx.umd.min.js and Removal_Tools/removal_tools.js, while 404.html still lists Voice_Biometric/voice_liveness.js (which sw.js does not) and lacks the face-biometric CSS pair and the EXT_WHITELIST. Reconcile both files when editing.

How do I add a new MPA page?

  1. Create Style/pages/{name}/index.html using _page_template.html
  2. Add the page content section (extracted from index.html)
  3. Add the path to sw.js HTML whitelist (and 404.html)
  4. Add the page's css/style.css and css/responsive.css to the CSS whitelist
  5. Update Style/navigation.js for standalone mode detection

How do I run the interactive menu?

There is no redosan menu subcommand. Use the standalone menu script instead:

node cli/menu.js      # or double-click start.bat / start.sh

Similarly, ID generation is not a redosan id-forge subcommand — call the library directly:

node cli/lib/id_forge.js uuidv4 5
node cli/lib/id_forge.js all 3 --json

Why does the CLI use vm.runInContext() instead of require()?

The browser JS files use top-level function and var declarations. In Node.js, require() wraps the module in a function scope, making these declarations private. vm.runInContext() executes in the global scope of a new V8 context, making all declarations available to subsequent modules.

How do I run a single test file?

node --test cli/tests/did_test.js
node --test cli/tests/fingerprint_test.js
node --test cli/tests/audio_watermark_core_test.js
node --test cli/tests/document_watermark_test.js

How do I run end-to-end tests?

npm run test:e2e-all    # all Playwright E2E tests
npm run test:e2e-mpa    # MPA standalone page tests

How do I check code quality before committing?

npm run check         # lint + stylelint + biome + test
npm run check:quick   # quick auto-fix + core tests
npm run check:full    # full audit (lint, biome, stylelint, markdownlint, cspell, madge, depcheck, tests)
npm run check:fix     # auto-fix all lint/format/style issues
npm run lint:ox       # oxlint fast gate (errors only)

What pre-commit hooks are configured?

Husky runs several gates before lint-staged:

  1. git diff --check --cached (whitespace / conflict markers)
  2. node scripts/guard-large-files.mjs (warn 5-10 MiB, block >= 10 MiB)
  3. scripts/secret-scan-precommit.ps1 (gitleaks probe)
  4. lint-staged: JS → oxlint (errors only) then eslint --fix then prettier; CSS → stylelint --fix then prettier; HTML → prettier; JSON → biome then prettier; YAML/MD → biome
  5. commit-msg strips non-noreply Co-authored-by: trailers; pre-push runs commitlint and (for workflow changes) actionlint

How do I test the Service Worker locally?

  1. Open DevTools → Application → Service Workers
  2. Check "Update on reload" to force SW update
  3. Use the SW pane to inspect cached requests, blocked URLs, and registered routes
  4. The SW only activates on localhost, 127.0.0.1, or redo-san.github.io

Related

Wiki: API Reference
Wiki: Architecture
Wiki: Changelog
Wiki: Face Biometric
Wiki: Home
Wiki: Installation
Wiki: Iris Biometric
Wiki: Security
Wiki: Usage Guide
Wiki: Voice Biometric
Wiki: _Sidebar

auth0 logo