Evidence Pack Generation

Relevant source files

The following files were used as context for generating this wiki page:

• truelens-backend/app/services/evidence_pack.py
• truelens-app/src/lib/types.ts
• truelens-backend/app/services/document_analysis.py
• truelens-backend/app/tasks/ml_pipeline.py
• truelens-app/src/app/developers/page.tsx
• truelens-app/src/app/documents/page.tsx

The Evidence Pack Generation system is a specialized service within TrueLens designed to create verifiable proof of authenticity for documents that have passed through the Document Analysis pipeline. Its primary purpose is to provide users with a tamper-evident package that bundles analysis findings, cryptographic signatures, and a verification mechanism into a portable format.

The system acts as the final stage of the verification workflow, transforming raw analysis signals into a structured "Security Ledger" manifest. This pack ensures that document integrity can be verified externally without requiring direct access to the internal TrueLens database, using a combination of SHA-256 hashing and digital signatures.
Sources: truelens-backend/app/services/evidence_pack.py:1-12, truelens-app/src/app/documents/page.tsx:210-218

System Architecture

The generation process is triggered after a document has been analyzed and assigned a status of verified. The architecture relies on three primary components: the Manifest Creator, the QR Generator, and the Cryptographic Signer.

Evidence Pack Components

• JSON Manifest: A structured data object containing the document's identity, cryptographic hash, and analysis summary.
• Cryptographic Signature: A signature issued by the "TrueLens Security Ledger" to prevent tampering of the manifest.
• QR Code: A visual representation of the verification URL, allowing third parties to scan and verify the document's status on the TrueLens portal.

The diagram shows the parallel generation of the JSON metadata and the visual QR verification component.
Sources: truelens-backend/app/services/evidence_pack.py:23-64, truelens-app/src/lib/types.ts:40-62

Data Structures

The evidence pack is defined by the interaction between the backend service and the frontend type definitions. The core data structure is the manifest, which is included in the final dictionary returned to the client.

Manifest Schema

Field	Type	Description
document_id	String	Unique identifier of the document in the TrueLens system.
filename	String	Original name of the uploaded file.
hash_sha256	String	The unique SHA-256 hash representing the document content.
trust_score	Integer	Calculated score (0-100) based on multi-signal analysis.
verified_at	ISO8601	Timestamp of the successful verification.
signature	String	Cryptographic signature of the document hash.
findings	Array	List of findings from the Document Analysis Service.
issuer	String	Hardcoded as "TrueLens Security Ledger".

Sources: truelens-backend/app/services/evidence_pack.py:27-37, truelens-app/src/lib/types.ts:54-61

Generation Workflow

The generation workflow follows a specific sequence once a document analysis task is completed by the ML pipeline.

1. Data Retrieval: The service extracts the document's properties, including the hash (SHA-256) and findings generated during analysis.
2. Manifest Assembly: Data is compiled into the standard manifest format.
3. URL Construction: A verification URL is generated pointing to the TrueLens portal (e.g., http://localhost:3000/verify?hash={doc.hash}).
4. QR Code Rendering: The qrcode library is used to generate a high-correction (ERROR_CORRECT_H) PNG image.
5. Encoding: The QR image is converted to a Base64 string for easy transmission via JSON APIs.

This sequence illustrates the transformation of a verified document object into a complete evidence pack.
Sources: truelens-backend/app/services/evidence_pack.py:23-57, truelens-backend/app/tasks/ml_pipeline.py:186-210

Implementation Details

QR Code Configuration

The QR code is generated with specific parameters to ensure it remains scannable even with significant damage or low-quality prints:

• Version: 1
• Error Correction: ERROR_CORRECT_H (High - approx 30% of data can be restored).
• Box Size: 10
• Border: 4
  Sources: truelens-backend/app/services/evidence_pack.py:43-52

Integration with Analysis Findings

The findings included in the pack are derived from the analyze_document function, which detects issues such as:

• Font Consistency: Multiple font families suggesting copy-paste forgery.
• Arithmetic Inconsistency: Mismatched totals in invoices.
• Metadata Tampering: Discrepancies between creation and modification dates.
  Sources: truelens-backend/app/services/document_analysis.py:133-160, truelens-backend/app/services/document_analysis.py:255-275

Verification API

Developers can interact with these generated packs via the verification endpoint:

• Endpoint: POST /api/v1/verify
• Body: {"hash": "a3f2b8c9..."}
• Purpose: Validates the document against the "Security Ledger" using the hash provided in the evidence pack's manifest.
  Sources: truelens-app/src/app/developers/page.tsx:32-37

Summary

The Evidence Pack Generation service bridges the gap between internal ML analysis and external trust. By packaging findings into a signed manifest and providing a QR-based verification path, it enables the "TrueLens Security Ledger" to act as a source of truth for document authenticity in the age of AI-generated and manipulated content.