# mdflow-crypt

<!-- Keep in sync with the page at app/mdflow-crypt/page.tsx and the package README at packages/mdflow-crypt/README.md. -->

> mdflow-crypt is a standalone, zero-dependency command-line tool that encrypts
> and decrypts MDflow (https://mdflow.cz) documents **locally**, on your own
> machine. This is the plain-markdown twin of https://mdflow.cz/mdflow-crypt.
> Published on npm as `mdflow-crypt`. Last updated July 2026.

## What it is

MDflow encrypts a document's body in your browser; the server only ever stores
ciphertext (`mdflow-enc:v1:…`). Encrypted documents are deliberately excluded
from search and are opaque to AI agents. `mdflow-crypt` does the same crypto on
your own machine, so you can take an encrypted document out of MDflow and read
or write it offline.

- **Local by design.** Your plaintext and your password never leave your
  computer — they never go to a server or an AI model. Do not pipe it through a
  remote runner or let an AI agent run it on your behalf; that would defeat the
  purpose.
- **Zero dependencies.** A single `.mjs` file, no dependencies, runs on Node 18+.
- **Byte-identical to the browser.** The format is `PBKDF2-HMAC-SHA256` (600,000
  iterations) → `AES-256-GCM`, a verbatim match of MDflow's in-browser
  encryption. What the app encrypts, the CLI decrypts, and vice versa.
- MIT licensed.

## Install

You need Node.js 18 or newer (`node -v`).

Run it with npx, no install required:

```bash
# decrypt: mdflow-enc:v1 file  →  <name>_decrypted.md
npx mdflow-crypt decrypt notes.md

# encrypt: markdown file  →  <name>_encrypted.md  (paste the result into MDflow)
npx mdflow-crypt encrypt notes.md
```

Or install it as a permanent command:

```bash
npm install -g mdflow-crypt
mdflow-crypt encrypt notes.md
```

For a security tool, prefer pinning a version you trust rather than always
pulling the latest:

```bash
npx mdflow-crypt@1.0.2 decrypt notes.md
```

## Usage

Two commands: `encrypt` and `decrypt`. The output file is written next to the
input with the original extension dropped:

| Command | `report.md` → |
| --- | --- |
| `encrypt` | `report_encrypted.md` |
| `decrypt` | `report_decrypted.md` |

Typical round-trip:

1. In MDflow, copy the encrypted document body (the `mdflow-enc:v1:…` text) into
   a local file, e.g. `notes.md`.
2. `npx mdflow-crypt decrypt notes.md` — you're prompted for the password
   (hidden), and the plaintext is written to `notes_decrypted.md`.
3. Edit the file, run `npx mdflow-crypt encrypt notes.md`, and paste the fresh
   `mdflow-enc:v1:…` blob back into the document body in MDflow.

### Password

Resolved in this order (first match wins):

1. `--password <pw>` — an inline flag.
2. `--password-file <path>` — read from a file (the first line; a trailing
   newline is ignored, spaces preserved). Keep it `chmod 600`.
3. the `[password]` positional argument.
4. otherwise you are **prompted** (hidden; `encrypt` asks twice to confirm).

`--password` and the positional argument are visible to other processes and land
in your shell history — for anything sensitive prefer the hidden prompt or a
`chmod 600` `--password-file`.

### Behavior

- **decrypt** requires an `mdflow-enc:` file; a wrong password or corrupted data
  exits non-zero and writes nothing.
- **encrypt** refuses a file that is already encrypted, and asks for the password
  twice. There is **no password recovery** — a forgotten password means the
  document is unrecoverable, so store it in a password manager.
- Exit codes: `0` ok · `1` usage / unreadable / wrong-shape input · `2` no or
  mismatched password · `3` decrypt failed.

## Security notes

- This is a **local** tool. Decrypting never exposes your content to a server or
  a model — so run it on your own machine, not through a remote runner or an AI
  agent.
- For a security tool, **pin a version** you trust (`npx mdflow-crypt@1.0.2 …`)
  rather than always pulling the latest.
- There is no password recovery and no backdoor. The crypto matches MDflow's
  in-browser encryption exactly.

## Links

- npm package: https://www.npmjs.com/package/mdflow-crypt
- Source: https://github.com/vaclavmartin/mdflow/tree/main/packages/mdflow-crypt
- Background on how MDflow encrypts notes:
  https://mdflow.cz/blog/client-side-encryption-for-online-notes