Immutable Archive

Overview

The Invocore archive is an append-only store for every tax-relevant document. On upload, the file is SHA-256 hashed, appended to the per-organisation hash chain, and written to the filesystem with chmod 0444 + chattr +i. No one — administrators included — can change archived content after the fact.

• ✓SHA-256 hash per document, anchored in a per-organisation hash chain
• ✓PostgreSQL triggers block UPDATE / DELETE / TRUNCATE on the journal table
• ✓10-year default retention (§ 147 AO), with a service-side floor that rejects shorter overrides
• ✓Hourly anchoring in a Merkle tree with RFC 3161 TSA timestamp
• ✓Self-contained ZIP verification package — external auditors verify without backend access

Legal background

The German principles for properly maintained electronic books (GoBD) require three properties for every tax-relevant document:

Per-organisation hash chain

Every organisation starts with a deterministic genesis block (block_number = 0, prev_hash = 64×"0"). Every subsequent upload appends a block whose prev_hash points at the previous block's entry_hash. If anyone tampers with a document or a block, the chain deterministically breaks at a known index — the verify endpoint reports the broken block loudly.

How a block is built

1. 1. Hashing

   The file is read into memory and SHA-256 hashed. If a block with the same hash already exists in your org, the endpoint returns 409 Conflict (idempotency by hash).

2. 2. Storage

   The bytes are written to primary storage (local filesystem with immutability flags). Off-host secondary replication (Hetzner Storage Box) is wired but disabled by default — toggle ARCHIVE_SECONDARY_ENABLED to enable.

3. 3. Block append

   In the same DB transaction, a row is appended to journal_entries. A PG trigger (journal_entry_chain_trg) reads the prior block's entry_hash, sets it as prev_hash, and deterministically computes entry_hash = SHA-256(block_number ‖ prev_hash ‖ doc_hash ‖ operation).

4. 4. Audit log

   In parallel, an audit_logs row (action = archive_upload) is written with user_id, IP, user-agent, SHA-256, and block number. Transaction rollback drops the block and the audit log consistently.

API reference

All endpoints require JWT (Bearer) authentication and are tenant-scoped via the X-Tenant-Id header.

{
  "document_id": "31c2c1f0-502a-47f3-bb85-01f81362a7b7",
  "sha256": "13ebe841cbed79bb6eec0031c3af5019…",
  "block_number": 1,
  "entry_hash": "61212e86d03e3165a15f958bf2975…",
  "storage_primary_path": "42426bf6-1428-…/2026/05/31c2c1…",
  "replication_status": "none",
  "immutable_locked": true,
  "retention_until": "2036-05-16T21:14:00Z"
}

{
  "items": [
    {
      "document_id": "…",
      "original_filename": "rechnung_2026_001.pdf",
      "sha256": "…",
      "size_bytes": 4242
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 50,
  "pages": 1
}

{
  "ok": true,
  "entries": 42,
  "genesis": true,
  "reason": null,
  "broken_at": null
}

{
  "format_version": "1.0",
  "document": {
    "sha256": "…"
  },
  "chain": {
    "entries": 42
  }
}

Retention (§ 147 AO)

Retention is set at upload time as retention_until (default: 10 years for invoice, contract, form). A retention_years override below 10 raises ValueError("archive.retention_too_short") — that is the compliance floor. The nightly retention sweep marks expired documents as is_retention_deleted = true, removes the bytes from primary + secondary storage, and appends an immutable archive_retention_delete block to the hash chain as proof of deletion.

TSA timestamping (RFC 3161)

Every hour the anchor worker batches new blocks per organisation into a Merkle tree, computes the root, and fetches an RFC 3161 timestamp from a Time Stamping Authority. Development uses FreeTSA; production targets a qualified TSA (D-Trust, A-Trust). The TSA response is stored as a blob in the anchors table and shipped with the verification package. If TSA acquisition fails, the anchor retries with exponential backoff — the chain itself remains intact without the timestamp.

External verification

Every document can be verified fully offline. The ZIP verification package contains everything an external auditor needs — no backend access required:

• →manifest.json with block_number, sha256, prev_hash, entry_hash, and path to the original file
• →document/<filename> — the unmodified original bytes
• →verify.py — standalone Python script (stdlib + cryptography only) that checks the SHA-256, recomputes the chain, and verifies the TSA token against the Merkle root
• →tsa_token.bin — RFC 3161 DER-encoded TSA response with qualified certificate
• →README.txt — auditor instructions

In the customer account

The archive lives under Archive in the main menu. Each tenant sees only their own hash chain and their own documents.

Frequently asked questions