# Maat Journal decryption tool

Decrypt a Maat Journal export with your 12-word recovery phrase, without the app.
Full instructions with screenshots: https://maatjournal.com/decryption-tool.html

## What you need

- Python 3.9 or newer
- Your 12-word recovery phrase (you type it when the tool asks, it is never saved)
- The `backup.json` from your Maat export (the export is a zip, unzip it first)

## Install

Put `maat_decrypt.py` and the installer for your system in one folder.

macOS and Linux:

    chmod +x install.sh
    ./install.sh

Windows (PowerShell):

    powershell -ExecutionPolicy Bypass -File .\install.ps1

The installer creates a `venv` folder next to the script and installs `mnemonic` and `pycryptodome` into it. Nothing else on your computer changes.

## Decrypt

macOS and Linux:

    ./venv/bin/python maat_decrypt.py --input backup.json --format text

Windows:

    .\venv\Scripts\python.exe maat_decrypt.py --input backup.json --format text

The tool asks for your recovery phrase and hides it while you type. Leave out `--format text` for JSON output, add `--output name.txt` to pick the file name.

For automation only: set the `MAAT_RECOVERY_PHRASE` environment variable for a single command. Keep the phrase out of files.

## How it works

1. The 12 words become a seed (BIP39, empty passphrase).
2. HKDF-SHA256 with salt `maat-journal-v1` and info `master-encryption-key` derives the 256-bit master key.
3. Every entry is AES-256-GCM, stored as Base64(IV + ciphertext + tag), and is decrypted one by one.
4. The result is written as JSON or plain text. Entries that fail are listed under `failed_entries`.

A wrong phrase decrypts nothing and the tool says so.

## Security

Your recovery phrase is the only key to your journal. Type it into the tool's prompt and nowhere else. The decrypted file holds your private entries: store it where only you can read it and delete it when you are done.