v0.1.0

Reference

Install the CLI

With Git and Rust with Cargo installed:

git clone https://github.com/Gohlub/kompromat.git
cd kompromat
cargo install --locked --path .

This installs kompromat and kompromat-api. To use the public endpoint, you only need to run the CLI. Choose an API →

Offline proofs

kompromat prove canary.json > proof.json
kompromat verify proof.json --manifest manifest.json

Verify against a matching manifest you obtained independently. A valid proof prints {"valid":true}. To submit the saved proof to the public API, register its manifest there first, then run:

kompromat submit proof.json --api https://kompromat.sh

A proof establishes possession when it was created. It has no timestamp or expiry, and does not identify the finder or where they found the file.

CLI commands

Run kompromat <command> --help for full usage. Paths below refer to local JSON files.

generate --out KEY: Create a secret key file and print its public manifest to stdout. Optional: --metadata JSON (a JSON object, default {}) and --api URL. Refuses to overwrite an existing key.
register MANIFEST: Register a public manifest. Optional: --api URL.
prove KEY: Create a proof offline and print JSON to stdout. Optional: --message TEXT to include an encrypted note.
report KEY: Create and submit a proof. Optional: --message TEXT and --api URL.
verify PROOF --manifest MANIFEST: Verify a proof locally against a public manifest. Prints {"valid":true} on success; exits with an error on failure.
submit PROOF: Submit a saved proof. Optional: --api URL.
attach KEY --message TEXT: Encrypt, sign, and send a note. Optional: --api URL.
unlock KEY: Fetch, verify, and decrypt all notes. Prints JSON. Optional: --api URL.

generate, register, and submit default to http://127.0.0.1:3000. report, attach, and unlock use the address saved in the key unless you pass --api.

--reply is an alias for --message on prove and report.

HTTP API

Send JSON with the Content-Type: application/json header. Register a manifest before submitting proofs or notes.

POST /dossiers: Body: manifest JSON. Returns the manifest with 201 when created, or 200 if already registered with the same metadata. Different metadata for the same key returns 409.
GET /dossiers/{public_key}: Returns the registered public manifest.
POST /proofs: Body: proof JSON from prove. Verifies the proof and stores its optional encrypted note. Returns the proof with 201, or 200 for a repeated signature.
GET /dossiers/{public_key}/proofs: Returns an array of proofs in insertion order.
POST /messages: Body: a signed, encrypted message. Returns the message with 201, or 200 for a repeat. Reusing a nonce with different ciphertext returns 409. Use attach to create and send one.
GET /dossiers/{public_key}/messages: Returns an array of encrypted messages in insertion order. Use unlock to decrypt them locally.

Submit a proof over HTTP

curl https://kompromat.sh/proofs \
  -H 'Content-Type: application/json' \
  --data-binary @proof.json

This uses the file from the offline proof example. Change the URL to the API where you registered the manifest.

Errors and limits

400: Invalid key encoding, signature, or proof.
404: No manifest registered for this key.
409: Conflicting metadata or reused message nonce.
413: Request body exceeds 64 KiB.
422: JSON fields do not match the expected schema.
500: Database or internal server error.

Read endpoints are public. Metadata, proofs, and encrypted messages are retrievable without the key; only key holders can decrypt notes. For registered keys, empty proof and message lists return [].

API source ↗ JSON types ↗

Run the API

The server is a single process backed by SQLite.

kompromat-api \
  --listen 127.0.0.1:3000 \
  --database ./kompromat.sqlite3

--listen ADDRESS: Bind address and port. Default: 127.0.0.1:3000.
--database PATH: SQLite database file. Default: kompromat.sqlite3 in the working directory.
--release-base-url URL: HTTPS directory of prebuilt release archives and their .sha256 files, used by the GET /cli installer. Default: https://kompromat.sh/releases/latest/download.

For remote use, put the HTTP service behind an HTTPS reverse proxy and use its public URL when generating and registering keys. The API has no account login or rate limiting. Proofs and message writes require valid signatures.

Troubleshooting

The key file already exists: Choose a new --out path and a new manifest filename. Shell redirection can truncate an existing manifest before generation fails, so don’t rerun the example over files you need.
Connection refused or request timed out: Check that the API is running and the URL is reachable. 127.0.0.1 refers to the machine running the command. Use --api URL to override the saved address. Requests time out after 15 seconds; redirects are not followed.
The API returns 404: Register the matching manifest on the same API you are submitting to.
Registration returns 409: This key is already registered with different metadata. Resend the original manifest or generate a new key. Registration does not update metadata.
A proof does not verify: Check that the proof and trusted manifest refer to the same public key. Modifying signed fields invalidates the proof.
A note exceeds 16 KiB: Shorten the message. The limit is measured in bytes, not characters.
The key is lost: The API cannot recover the secret or decrypt notes for you. Keep a copy if you need to read or reply later.

Back to top ↑