Maat
Get the app

Decryption tool

Open your export on any computer.

A small Python script, published with its source in plain view, that turns a Maat export back into readable text using your 12-word recovery phrase. It runs on your own machine. It needs no account, no server and no Maat.

Download maat_decrypt.py Installation steps

Python 3.9 or newer · macOS, Windows, Linux · Readme

Why this tool exists

Your journal is encrypted with a key that only you hold. That promise is only worth something if you can read your entries without us. This tool is that guarantee, in about 400 lines you can inspect.

What it needs

Python 3.9 or newer, the backup.json from your export, and your 12-word recovery phrase. You type the phrase when the tool asks. It is hidden while you type and never saved.

What it does

Turns your phrase into the master key (BIP39, then HKDF-SHA256), decrypts every entry (AES-256-GCM) and writes a text or JSON file. Entries it cannot open are listed, and a wrong phrase is reported as such.

What it changes on your computer

One folder. The installer creates a private Python environment next to the script and installs two libraries into it (mnemonic, pycryptodome). Delete the folder and everything is gone.

Step 1

Get your export from the app

  1. Open Backup & Import

    In Maat Journal, tap the gear icon, then Backup.

  2. Export

    Leave Encrypt exports switched on and tap Export. Save the file to Files or iCloud Drive, AirDrop it, or send it to yourself.

  3. Unzip

    The export is a zip with backup.json and your audio files inside. Unzip it on your computer. The tool reads backup.json.

Step 2

Install the tool

Download maat_decrypt.py and the installer for your system into one folder, for example Downloads/maat-decrypt.

macOS

Download install.sh into the same folder. Open Terminal (Spotlight, type Terminal), go to the folder and run the installer.

cd ~/Downloads/maat-decrypt
chmod +x install.sh
./install.sh

Python 3 comes with the Xcode command line tools. If the installer says Python is missing, install it from python.org or with Homebrew: brew install python.

Windows

Install Python 3 from python.org and tick Add python.exe to PATH. Download install.ps1 into the same folder. Open PowerShell (Start menu, type PowerShell), go to the folder and run the installer.

cd $HOME\Downloads\maat-decrypt
powershell -ExecutionPolicy Bypass -File .\install.ps1

The ExecutionPolicy Bypass part only applies to this one command. It lets PowerShell run a downloaded script.

Linux

Install Python and the venv module once, then run the same installer as on macOS.

sudo apt install python3 python3-venv
cd ~/Downloads/maat-decrypt
chmod +x install.sh
./install.sh

The apt line is for Debian and Ubuntu. Other distributions ship Python with venv included.

Step 3

Decrypt

Run the tool with your export. It asks for your 12-word recovery phrase and hides it while you type. The phrase stays in memory for that one run. The only file the tool writes is the decrypted output you asked for.

macOS and Linux

./venv/bin/python maat_decrypt.py --input backup.json --format text
Recovery phrase: ************

Windows

.\venv\Scripts\python.exe maat_decrypt.py --input backup.json --format text
Recovery phrase: ************
Output options

Leave out --format text to get JSON with all metadata, useful for importing elsewhere. Add --output myjournal.txt to choose the file name. The text format lists date, mood and content per entry.

Automation

For scripts you can hand the phrase to a single command through the MAAT_RECOVERY_PHRASE environment variable instead of typing it. Keep the phrase out of files and shell history.

Keep the result private

The decrypted file contains your entries in plain text. Store it where only you can read it and delete it when you are done.

Technical details

Recovery phrase
12-word BIP39 mnemonic
Seed
BIP39 standard, 512 bits, empty passphrase
Key derivation
HKDF-SHA256, salt maat-journal-v1, info master-encryption-key
Encryption
AES-256-GCM per journal entry
Ciphertext
Base64(IV + ciphertext + tag), 16-byte IV and tag
Export format
Version 1.0, with detection and migration for later versions

Troubleshooting

When something does not work

"None of the entries could be decrypted"

Almost always a wrong recovery phrase. Check all 12 words, their order and spelling. Similar words (for example able and above) are the usual culprit. Upper and lower case do not matter.

The installer says Python is missing

Install Python 3.9 or newer from python.org. On Windows, tick "Add python.exe to PATH" during setup, then open a new PowerShell window. On Debian or Ubuntu run sudo apt install python3 python3-venv.

"Missing required dependencies"

The tool was started with the system Python instead of the one in the venv folder. Use the exact command from step 3, which points at venv/bin/python (macOS, Linux) or venv\Scripts\python.exe (Windows).

Some entries fail, most work

Those entries were created under a different recovery phrase, for example before a phrase reset. They are listed under failed_entries in the JSON output. Run the tool again with the phrase that was active when they were written.

Windows refuses to run install.ps1

Use the full command from step 2 including -ExecutionPolicy Bypass. It permits this one script for this one run and changes nothing else.

Your data is yours

Read how the whole chain works.

Data ownership at Maat Privacy policy