VaultPGP

FastAPI app for OpenPGP encrypt, decrypt, sign, and verify, with an integrated web UI (tabbed workspace) and a JSON API (/docs).

Configure keys in .env:

Never commit .env. Copy .env.example and fill in real values. Export your public key once, e.g. gpg --armor --export YOUR_KEY_ID, and paste it into OPENPGP_PUBLIC_KEY.

• Python 3.11+
• GnuPG (gpg) on your PATH

Create the environment once from the project root:

cd /path/to/VaultPGP
python3 -m venv .venv

Activate it every time you open a new terminal before running pip or uvicorn:

To leave the environment: deactivate

With the venv activated:

pip install -e ".[dev]"
cp .env.example .env

Edit .env (use double quotes around multiline key blocks). Start the server:

uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

Open http://127.0.0.1:8000.

Install without dev dependencies: pip install -e .

The home page is a single workspace with:

• Tabs — Encrypt, Decrypt, Sign, Verify (one action visible at a time).
• Status chips — whether GnuPG is available and whether secret/public keys were loaded from .env.
• After each form submit — the tab that handled the request stays selected so you see results immediately.
• URL hash — switching tabs updates the address (e.g. #verify). You can bookmark or share http://127.0.0.1:8000#decrypt.
• Copy — buttons on outputs use the clipboard when the browser allows it.
• Verify — large field for a full clearsigned block; optional signer's public key when the signature is from someone else (otherwise GnuPG returns “no public key”). Detached verify is under an expandable section.
• Sign — default output is signed + encrypted to OPENPGP_PUBLIC_KEY (armored BEGIN PGP MESSAGE) so you can paste it into Decrypt. Clearsigned and detached-only modes are available as radio options.

A short footer links to OpenAPI at /docs.

Four POST endpoints. Use JSON (Content-Type: application/json) with the same field names as the forms, or call from scripts.

• If you POST JSON and do not send Accept: application/json (typical curl default is Accept: */*), encrypt, decrypt, and sign return raw armored text (text/plain) with real line breaks — safe to redirect to a file or pipe to gpg.
• To get a JSON object, send Accept: application/json. That response includes human-readable fields plus ciphertext_b64, plaintext_b64, signature_b64 (UTF-8 armored content, base64-encoded) for one-line copy; decode with base64 -d.
• ?format=plain or Accept: text/plain also forces a plain armored body.

Python requests: requests.post(..., json=...) often omits Accept: application/json, so you receive plain armored text, not JSON. Use headers={"Accept": "application/json"} if you call .json() on the response.

Interactive docs: http://127.0.0.1:8000/docs

Encrypt to yourself (plain armored response with default curl):

curl -s -H "Content-Type: application/json" \
  -d '{"plaintext":"note to self","recipient_mode":"self"}' \
  http://127.0.0.1:8000/encrypt > message.asc

Encrypt to someone else:

curl -s -H "Content-Type: application/json" \
  -d '{"plaintext":"hello","recipient_mode":"other","recipient_public_key":"'"$(cat their-pubkey.asc)"'"}' \
  http://127.0.0.1:8000/encrypt

JSON envelope (for jq or apps):

curl -s -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"plaintext":"secret","recipient_mode":"self"}' \
  http://127.0.0.1:8000/encrypt | jq -r .ciphertext

JSON string values escape newlines as \n. Do not paste raw JSON into GnuPG — you may see “illegal base64 data at input byte 0” or similar.

1. Prefer plain curl output (no Accept: application/json) and save to .asc, or use jq -r .ciphertext, or ciphertext_b64 + base64 -d.
2. Decrypting inside VaultPGP normalizes common paste issues before calling GnuPG.

GET /health — reports whether gpg is available.

• .env holds key material in plaintext on disk; restrict permissions and keep it out of version control.
• Bind to 127.0.0.1 for local use only. Do not expose the app on a network without authentication and TLS.