.. include:: /Includes.rst.txt

.. _integrity:

=================
Integrity & trust
=================

.. toctree::
   :maxdepth: 2
   :titlesonly:

   VerifyCli
   OpenTimestampsManual

.. _integrity-overview:

Overview
========

When a backup finishes, T3Vault seals it with ``BackupIntegrityService``:

1. Hash artefacts (``*.zip`` incl. :file:`database.zip`, legacy :file:`database.sql.gz` / :file:`database.sql`,
   :file:`MANIFEST.json`) with SHA-256.
2. Write :file:`integrity.json` (algorithm, ``createdAt``, file digests).
3. Optionally write :file:`integrity.json.hmac` (HMAC-SHA256 bound to the site
   ``secret``).
4. Submit the digest of :file:`integrity.json` to OpenTimestamps calendars and
   store the proof as :file:`integrity.json.ots`.
5. Write :file:`integrity-meta.json` (stamp outcome metadata — **not** a trust
   anchor).

Trust model:

* Changing backup files without a new seal breaks the hash check.
* Forging a new seal requires a new OpenTimestamps proof.
* Final time-stamp time comes from the Bitcoin blockchain, not this server.
* A large gap between ``createdAt`` and that blockchain time is treated as
  suspicious (T3Vault allows up to 72 hours for calendar → chain confirmation).
* Until the proof is fully attested, status stays ``pending``.
* HMAC is only checked when the site secret is available; on foreign hosts it is
  skipped so cross-system restore still works.

.. _integrity-how-to-verify:

How to verify a backup (recommended)
====================================

The goal is to detect whether the backup was **modified after sealing**.

**Recommended:** re-hash artefacts against :file:`integrity.json` with the
bundled verifier (no Bitcoin node required):

.. code-block:: bash

   php t3vault-verify.phar /path/to/backup_YYYYMMDD_HHMMSS_<id>

Exit code ``0`` / state ``ok`` (or ``pending`` with matching hashes) means the
listed files still match the seal. State ``tampered`` means do **not** restore.

**Optional:** confirm the seal via :ref:`opentimestamps-manual` — either in the
browser on `opentimestamps.org <https://opentimestamps.org/>`_ or with the
``ots`` CLI. The hash check above already answers the “was it changed?”
question for the archive files.

You can also verify from the T3Vault UI (**Integrity** / verify action).

Always keep :file:`integrity.json` and :file:`integrity.json.ots` together in
the backup directory.

.. _integrity-states:

Verification states
===================

================  ================================================================
State             Meaning
================  ================================================================
``ok``            Hashes match and OTS proof is attested within the time window
``pending``       Hashes OK; calendar proof not yet upgraded to Bitcoin
``missing``       Integrity files incomplete
``stamp_failed``  Stamping failed earlier; hashes may still be OK
``tampered``      Hash or OTS digest mismatch / attestation skew
``checking``      Transient UI state while a check runs
================  ================================================================