Menu ▾ ▴

Installation

RedoSan

Installation

This guide covers setting up RedoSan Authenticity for CLI usage, browser development, and GitHub Pages deployment.

npm status (v2.0.0): the package redosan-authenticity-cli is fully prepared for npm (bin wiring, staged-publish workflow with OIDC + 2FA approval) but is not yet published. Until the first publish, install from source as described below.

Prerequisites

Dependency Version Required For
Node.js >= 22.14.0 (22 or 24 recommended; CI runs both) CLI execution, testing
npm 10+ Package management
Git Any Cloning the repository
Cairo/Pango/GIF/LibRSVG System libraries canvas native addon (Linux/macOS)

Quick Start (CLI)

1. Clone the Repository

git clone https://github.com/Redo-San/RedoSan-Authenticity.git
cd RedoSan-Authenticity

2. Install System Dependencies (Linux)

The canvas npm package requires native libraries. On Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y libcairo2-dev libjpeg-turbo8-dev libpango1.0-dev libgif-dev librsvg2-dev build-essential

Windows: Install Visual Studio Build Tools with "Desktop development with C++" workload, or use npm install --ignore-scripts and use the browser version only.

macOS: Xcode Command Line Tools (xcode-select --install) and Homebrew packages (brew install cairo pango giflib librsvg jpeg).

3. Install npm Dependencies

npm install

This installs all dependencies including canvas (^3.2.3), commander (^14.0.3), docx (^9.7.2), pdfkit, qrcode, jszip, and acorn.

npm link

This makes the redosan command available anywhere in your terminal. Without linking, run commands directly with node cli/index.js <command>.

5. Verify Installation

redosan --help

You should see the help menu with 14 subcommands:

Commands:
  fingerprint [options] <file>               Generate cryptographic fingerprints (hashes) for a file
  watermark                                  Embed or extract invisible watermarks in images
  metadata [options] <file>                  Read metadata (EXIF, dimensions, format) from an image
  timestamp [options] <action> <file>        Create or verify OpenTimestamps (.ots) proofs
  c2pa [options] <action> <file>             Sign, read, or verify C2PA provenance metadata
  pixel-injection [options] <action>         Advanced spatial/frequency/DL watermark algorithms (23 algorithms)
  audio-watermark [options] <action> <file>  Embed or extract watermarks in WAV audio files
  forensic [options] <file>                  Analyze image tamper signals (ELA, noise inconsistency, JPEG structure, copy-move)
  did [options] <action> [file]              Generate DID keypair or sign a file fingerprint
  certificate [options] <file>               Generate a Digital Passport certificate from an image and identity data
  document-watermark [options] <action>      Embed or extract invisible watermarks in text documents
  converter [options] <file>                 Convert image/audio files between formats
  upgrade [options] <file>                   Upgrade an incomplete .ots timestamp proof via calendar aggregator
  tools                                      Check availability of external tools (exiftool, sox, ImageMagick, etc.)
  help [command]                             display help for command

Two helpers are not subcommands:

  • Interactive menu: node cli/menu.js (numbered menu wrapping the CLI)
  • ID Forge: node cli/lib/id_forge.js <uuidv4|uuidv7|ulid|swhid|nanoid|all> [count|file] [--json|--csv]

Running the Browser Version

No installation is required for the browser version. The tool runs entirely in the browser:

Option A: GitHub Pages (Official)

Visit https://redo-san.github.io/RedoSan-Authenticity/

Individual MPA pages are also accessible directly (23 pages in total):

  • .../Style/pages/home/ · about/ · contact/ · privacy/ · search/ · social/
  • .../Style/pages/fingerprint/ · watermark/ · pixel-injection/ · audio-watermark/ · document-watermark/
  • .../Style/pages/metadata/ · timestamp/ · c2pa/ · forensic/ · did/ · certificate/
  • .../Style/pages/converter/ · id_forge/ · removal-tools/
  • .../Style/pages/face-biometric/ · iris-biometric/ · voice-biometric/

Option B: Local Development Server

# Using Node.js built-in http server
npx http-server . -p 8080 -c-1

# Or using Python
python -m http.server 8080

Then open http://localhost:8080 in your browser. The Service Worker will register on page load and enforce security policies.

Running Tests

The project uses Node.js built-in node:test (zero external test dependencies) plus Playwright for E2E. The full suite includes 107 unit test files + 59 E2E suites with 6,200+ tests:

# Run all tests (sequential, 2-minute timeout per test suite)
npm test

# Run core tests only (includes face biometric suite)
npm run test:core

# Run with coverage (c8)
npm run coverage

# Biometric suites
npm run test:face
npm run test:voice

# Individual test files
node --test cli/tests/did_test.js
node --test cli/tests/fingerprint_test.js

Test output uses TAP format. CI runs tests on Node.js 22 and 24 (required checks: unit (22), unit (24)).

Test scripts (from package.json):

Script Scope
npm test Full chain: core, pixel, advwm, c2pa, audio, docw, conv, ts, meta, cert, txtxt, cli, e2e-all
npm run test:core did, fingerprint, id_forge, watermark_core, forensic + face suite
npm run test:cli CLI command + export suites
npm run test:face / test:voice Biometric suites (engine, crypto, liveness, anti-spoof, UI, …)
npm run test:e2e-all All Playwright/node E2E suites (600s timeout)
npm run test:e2e-mpa MPA standalone page suites
npm run test:e2e-voice-biometric Voice biometric MPA suite
npm run coverage c8 coverage report

CI/CD Pipeline

The repository includes 77 GitHub Actions workflows covering CI, security, quality, maintenance, and community management:

Category Workflows (selected)
Core ci.yml (tests on Node 22/24, coverage), lint.yml, deploy-pages.yml
Security security.yml (Semgrep + TruffleHog + npm audit), codeql.yml, zizmor.yml, scorecards.yml, dependency-review.yml, secret-scanner.yml, permissions-sheriff.yml
Quality a11y.yml (Pa11y + axe-core), performance.yml (Lighthouse CI), css-lint.yml, prettier-check.yml, html-hint.yml, cross-ref-check.yml
Maintenance broken-links.yml, todo-issues.yml, stale.yml, translate.yml, spell-check.yml, cspell-check.yml, markdownlint.yml, depcheck.yml, size-limit.yml, madge-check.yml
PR Management pr-title-lint.yml, auto-assign.yml, pr-size-label.yml, labeler.yml, branch-name-lint.yml, pr-body-check.yml, issue-labeler.yml
AI Review code-review-openrouter.yml, gemini-analysis.yml, codebase-audit.yml, ollama-analysis.yml, semgrep.yml
Release / npm release.yml (draft + git-cliff changelog + SBOM), staged.yml (OIDC staged npm publish), milestone.yml
Community welcome.yml, a11y-fix.yml, console-log-detector.yml

Dependabot is configured for weekly npm and GitHub Actions dependency updates.

Browser Security Restrictions

When running locally, the Service Worker requires either localhost, 127.0.0.1, or redo-san.github.io as the hostname. All browser JS files include a domain origin self-check that prevents execution on untrusted domains.

The Service Worker maintains whitelists for:

  • 120+ JS files in the JavaScript whitelist
  • 50 CSS files in the CSS whitelist
  • 60+ YML/YAML files in the workflow/config whitelist
  • 27 HTML pages in the HTML whitelist
  • 18 JSON files in the JSON whitelist
  • 20+ external CDN URLs in the external whitelist

and blocks 60+ dangerous extensions (.exe, .sh, .py, .elf, etc.). See [Security] for the full threat model.

If you see a blank page or console errors when running from a different IP or custom domain, check that:

  1. You are accessing via localhost or 127.0.0.1
  2. The Service Worker is registered (check Application → Service Workers in DevTools)
  3. All JS files are in the expected paths

Troubleshooting

canvas Installation Fails

# Try installing with system libraries path
npm install canvas --build-from-source

# Or skip native module entirely (browser-only usage)
npm install --ignore-scripts

redosan Command Not Found

# Check the global link
npm link

# Or run directly
node cli/index.js <command>

Tests Fail with Timeout

# Increase timeout (default is 120000ms = 2 minutes)
node --test --test-concurrency=1 --test-timeout=600000

Port Already in Use

# Kill the process using the port (e.g., 8080)
npx kill-port 8080

Related

Wiki: API Reference
Wiki: Architecture
Wiki: FAQ
Wiki: Home
Wiki: Security
Wiki: Usage Guide
Wiki: _Sidebar

auth0 logo