INDICIUM

Image Native Digital Integrity & Color Integrity Unit Monitor

A forensic tool for detecting color manipulation in images through statistical color analysis.

Overview

INDICIUM allows photographers and content creators to:

• Register original images exported from Lightroom/Photoshop (with Adobe Content Credentials already embedded).
• Calculate a "color signature" based on color statistics (mean, variance, histograms) in AdobeRGB and simulated sRGB.
• Detect subsequent color manipulations (filters, aggressive LUTs) by comparing images found on the web with registered signatures.
• Visualize detailed forensic metrics (global score, per-channel histograms, sector alteration heatmap).

Key Features

• No database poisoning: Only signatures (metadata) are stored, never full images.
• Privacy-first: Signature calculation is performed locally via CLI; images are never uploaded to the backend.
• Modular architecture: Backend (NestJS), CLI (Node/TS), Web UI (SvelteKit) are independent.
• Open source: MIT licensed, code available on GitHub.
• Forensic-grade: Multiple metrics, detailed visualization, interpretable score (0–100).

Architecture

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│   CLI (Node/TS) │─────▶│  Backend (NestJS)│◀────│ Web UI (SvelteKit)│
│  - Calculation  │      │  - API REST     │      │  - Dashboard    │
│  - Verification │      │  - MariaDB      │      │  - Visualization│
│  - Batch        │      │  - Auth (keys)  │      │  - Management   │
└─────────────────┘      └─────────────────┘      └─────────────────┘

Tech Stack

Component	Technology	Notes
Backend	NestJS 11.x	REST API, TypeORM, Swagger
Database	MariaDB 11.x	Signature storage
CLI	Node.js 22.x	TypeScript, sharp, imagehash
Web UI	SvelteKit 2.x	TypeScript, Chart.js, Tailwind
Image Processing	sharp (libvips) 0.34.x	ICC conversion, histograms
Containerization	Docker 27.x	Backend + DB + Frontend
License	MIT	Open source

Quick Start

Prerequisites

• Node.js 22+
• Docker & Docker Compose
• MariaDB (or use Docker Compose)

1. Clone the Repository

git clone https://github.com/AlexM2Media/indicium.git
cd indicium

2. Start with Docker Compose

# Copy environment example
cp .env.example .env

# Edit .env with your credentials
nano .env

# Start all services
docker-compose up -d

Services will be available at:

• Backend API: http://localhost:3000
• Web UI: http://localhost:3001
• MariaDB: localhost:3306

3. Install CLI

cd cli
npm install
npm link  # Makes `indicium` available globally

4. Configure CLI

indicium config set api-url http://localhost:3000
indicium config set api-key your-api-key-here

5. Register an Image

indicium register --image IMG_1234_AdobeRGB.jpg --name "IMG_1234"

6. Verify an Image

indicium verify --image downloaded.jpg --id uuid-of-image

Usage

CLI Commands

# Register a single image
indicium register --image path/to/image.jpg --name "Image Name"

# Verify an image
indicium verify --image path/to/image.jpg --id uuid-of-image

# Batch register
indicium batch --dir ./exports --pattern "IMG_*_AdobeRGB.jpg"

# Configure
indicium config set api-url http://localhost:3000
indicium config set api-key your-api-key

API Endpoints

• POST /api/images/register - Register a new image with color signatures
• GET /api/images/:id - Get image metadata and signatures
• GET /api/images/hash/:sha256 - Find image by SHA-256 hash
• POST /api/verify - Submit verification result (optional logging)
• GET /api/verify/:imageId - Get verification history for an image

See full API documentation at http://localhost:3000/api (Swagger).

Web UI Routes

Access the dashboard at http://localhost:3001:

• / - Landing page
• /register - Register images (upload signatures calculated by CLI)
• /verify - Verify images (upload or URL)
• /image/[id] - Forensic dashboard with score, histograms, sector heatmap
• /dashboard - List of registered images (requires authentication)

How It Works

1. Registration

1. Export image from Lightroom/Photoshop with Adobe Content Credentials.
2. CLI calculates:
   • SHA-256 hash of the file.
   • Color statistics in AdobeRGB (global mean, variance, 32-bin histograms).
   • Same statistics for 4ק grid sectors (24 sectors total).
   • Convert to sRGB (ICC profile) and recalculate statistics.
3. Send signatures to backend via API.
4. Backend stores in MariaDB.

2. Verification

1. Download suspected image from the web.
2. CLI calculates same statistics (assumes sRGB).
3. Fetch original signature from backend.
4. Compare:
   • Mean deviation (global and per sector).
   • Variance deviation.
   • Histogram distance (Chi-square).
5. Calculate score 0–100.
6. Display results (score, per-channel breakdown, altered sectors).

3. Score Interpretation

• 0–30: Authentic (within expected variation from platform conversion/compression).
• 30–60: Possible manipulation (moderate color changes).
• 60–100: Manipulated (aggressive filters, LUTs).

Development

Backend

cd backend
npm install
npm run start:dev

CLI

cd cli
npm install
npm run dev

Web UI

cd web
npm install
npm run dev

Documentation

See docs/ folder for detailed technical documentation:

• architecture.md - System architecture
• api.md - API reference
• cli.md - CLI usage
• deployment.md - Deployment guide

Full specification: INDICIUM-specification.md

License

MIT License - see LICENSE file.

Contributing

Contributions are welcome! Please read our Contributing Guide first.

Acknowledgments

• Built with NestJS, SvelteKit, and sharp.
• Inspired by forensic image analysis research and C2PA standards.

---

Repository Activity

---

Author: Alejandro Mateo - @AlexM2Media
Repo: INDICIUM
Web/Portfolio: alexm2.media