petty

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/brand/petty-logo-dark.svg">
  <img src="docs/brand/petty-logo.svg" alt="Petty" width="250">
</picture>

# Petty

**Everything you keep, in its place.** Petty is a private record of what you keep and where: cash
in a tin, tools in the basement, passports in the safe, the drill you lent out. Each drawer sits in a
place, holds items — money, counted things or notes — and is shared only with the people you choose.
Everything is encrypted on your device before it is sent.

**Try it at [petty.kropka.studio](https://petty.kropka.studio)** — nothing to install, it works in your
browser. Or [run your own](#run-your-own).

<p>
  <img src="apps/web/public/landing/home-en-light.webp" alt="Home screen: the total, the places as a picture, and the drawers grouped by place" width="260">
  <img src="apps/web/public/landing/items-en-light.webp" alt="A drawer of things: tools counted by the piece, keys and a torch as single items" width="260">
  <img src="apps/web/public/landing/places-en-light.webp" alt="Places: rooms, shelves and boxes as a tree you can drag" width="260">
</p>

## What it does

- **Money, things and notes.** Cash in any currency, things counted by the piece, and single items
  with a note: a passport, a drill, a spare key. Tag items and filter by tag.
- **Drawers in places.** Home › Bedroom › Wardrobe › Safe. A drawer lives in a place; moving a room
  moves its drawers. Search finds an item by its name, note or tag.
- **Shared, with roles.** A drawer is shared only with the people you pick. Writers add entries;
  readers only look. The server enforces this.
- **Count, check, never erase.** Mark a drawer as checked after a real count. Mistakes are
  reversed, not deleted.
- **Works with AI apps.** Claude Desktop (a one-click add-on), Claude Code, Cursor, VS Code or any
  MCP app can read and update your drawers. It decrypts on your computer; the server still sees only
  ciphertext. A Claude skill teaches it the good habits (one total per currency, ask before it
  writes), and the add-on is listed in the MCP Registry as `io.github.WawRepo/petty`. See
  [docs/agent.md](docs/agent.md).
- **A command line.** `petty` signs in through your browser, like `gh auth login`, then reads and
  writes drawers from a terminal, scripts or AI agents, with `--json` and Tab completion. See
  [docs/cli.md](docs/cli.md).
- **Passkey first, works offline.** Face ID, Touch ID or Windows Hello opens your vault. It
  installs like an app and keeps working without a network.
- **English, Polish, German, Spanish and French** — the app, its emails and the sign-in pages.

## Made for

- **Cash at home** — every tin and envelope in its room, counted and checked. Where Petty started.
- **The workshop** — the zip ties are in Home › Basement › Workshop, in the desk drawer.
- **A trip kitty** — one drawer per trip, one item per person; nobody can quietly change what they paid.
- **Yearly accounts** — a drawer per account, checked once a year, the date kept with it.
- **Lent out** — who has your drill, and since when.
- **The family safe** — where the passports, keys and papers are, shared read-only with the people
  who may one day need it.

## Documentation

| For | Read |
|---|---|
| Users | this README, the in-app privacy page, [docs/agent.md](docs/agent.md) (use Petty from Claude Desktop or another AI app), [docs/cli.md](docs/cli.md) (the `petty` command line) |
| Operators (self-hosting) | [docs/deploy.md](docs/deploy.md) · [docs/monitoring.md](docs/monitoring.md) · [docs/auth-clerk.md](docs/auth-clerk.md) |
| Contributors | [CONTRIBUTING.md](CONTRIBUTING.md) · [docs/decisions.md](docs/decisions.md) · [CLAUDE.md](CLAUDE.md) — the engineering rules; plain text, no AI tool needed to read or follow them |
| Security reviewers | [SECURITY.md](SECURITY.md) · [docs/threat-model.md](docs/threat-model.md) · [docs/security-review-2026-09.md](docs/security-review-2026-09.md) · [docs/README.md](docs/README.md) (how keys and tokens work, with diagrams) |
| History, not maintained | [petty-app-spec.md](docs/history/petty-app-spec.md) (frozen 2026-09-25), [petty-spec-review.md](docs/history/petty-spec-review.md), [SPEC-ISSUES.md](docs/history/SPEC-ISSUES.md) — the original specification, its review and the reasoning behind the first decisions · [petty.html](docs/history/petty.html) — the pre-rewrite prototype |

Ticket IDs such as `PETTY-123` in docs and commit messages refer to the maintainers' internal tracker.
The public trail for changes is this repository's issues, pull requests and [CHANGELOG.md](CHANGELOG.md).

## Security in five lines

1. Drawer content is encrypted in the browser (AES-256-GCM). The server stores that content only as ciphertext — it still sees account
   details (email, display name) and activity metadata (who wrote which entry, when); the in-app
   privacy page lists exactly what.
2. Each drawer has its own key, wrapped for each member with ECDH P-256. Your private keys never
   leave your device unencrypted.
3. Your keys sit in a vault opened by a passkey or a passphrase (Argon2id), with a recovery code.
4. Every ciphertext is bound to its row, drawer, line and author, and entries form a signed hash
   chain, so a server cannot move, re-attribute or silently drop them.
5. Permissions and append-only history are enforced by the server and the database, not by the UI.

The threat model is [docs/threat-model.md](docs/threat-model.md); the settled design decisions are [docs/decisions.md](docs/decisions.md). The latest security review is
`docs/security-review-2026-09.md`. Report problems privately as described in `SECURITY.md`.

## Run your own

```
cp deploy/compose/.env.example deploy/compose/.env    # fill in the values
docker compose -f deploy/compose/docker-compose.yml --env-file deploy/compose/.env up -d
```

Make the database passwords letters and digits only (`openssl rand -hex 32`). Then put an HTTPS
reverse proxy in front of `127.0.0.1:3000`. `docs/deploy.md` has the details,
and `docs/monitoring.md` covers metrics, logs and traces.

## License

Copyright (C) 2026 Petty contributors. Petty is free software under the GNU Affero General Public
License v3.0 (`LICENSE`, and `NOTICE`). If you run a changed version for other people, you must
offer them its source. Contributions are welcome; see `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md`.

---

# Development setup

This part covers running Petty locally. Nothing here needs a cloud account or network access
after `pnpm install`.

## Try it with a seeded household (Docker only)

```
make demo          # pulls the published image (PETTY_TAG=<tag> for another), migrates, seeds two people and six drawers
make demo-local    # same, but builds the image from your working tree (no CI, no registry)
make demo-down     # stop it
make demo-reset    # stop it and drop the data (shares the local dev database volume)
```

Open http://localhost:3300 (mail at http://localhost:8025). Logins are printed by the
seed: `ania@petty.local` / `password-ania` / vault passphrase `vault ania 2026 drawer`;
`bartek@petty.local` / `password-bartek` / `vault bartek 2026 drawer`.

## Settings: one `.env` at the root

Copy `.env.example` to `.env` (gitignored). The API dev server, the tests, Playwright and
`docker compose` all read that one file; the web app needs none (it asks the API). Anything
already in the environment wins over the file. The production image carries no file: a
deployment passes the same names as environment variables or secrets.

## Requirements (clean machine)

- Docker Desktop (or any Docker with Compose v2)
- Node 24 (LTS; `.node-version` says 24 — the image and CI use it too)
- pnpm 11: `corepack enable && corepack prepare pnpm@11.28.2 --activate` (the version in `package.json`)
- GNU make (preinstalled on macOS; `apt install make` on Debian/Ubuntu)

## First run

```
pnpm install
make dev
```

`make dev` starts Postgres 16 and Mailpit in Docker, waits for the database, runs the
migrations, then starts the API on http://127.0.0.1:3000 and the web app on
http://localhost:5173. Stop everything with Ctrl-C and `make stop`.

Then, in a second terminal:

```
make seed        # three test users
curl localhost:3000/health   # {"ok":true,"db":"up"}
```

## Test users

| Email | Login password | Vault passphrase (from Phase 2 on) |
|---|---|---|
| alice@petty.local | password-alice | vault alice 2026 drawer |
| bob@petty.local   | password-bob   | vault bob 2026 drawer |
| carol@petty.local | password-carol | vault carol 2026 drawer |

Mailpit catches every email the app sends (join links, invitations, removals, ownership
offers): http://localhost:8025. Set `SMTP_HOST`/`SMTP_PORT`/`MAIL_FROM`/`APP_URL` for a real provider.

## Commands

| Command | Does |
|---|---|
| `make dev` | db + mailpit + migrate + api + web |
| `make seed` | three users + a shared "Kitchen" drawer with real ciphertext (skips if alice exists; `make reset` first to reseed) |
| `make test` | every vitest suite (API tests need the db) |
| `make lint` | typecheck + eslint |
| `make reset` | drop the database volume, migrate again |
| `pnpm --filter @petty/api migrate:create <name>` | new empty SQL migration |

## Offline

The web app is an installable PWA. The service worker caches the app shell only;
API responses are never HTTP-cached. Ciphertext (vault blob, bootstrap) and
non-extractable key handles live in IndexedDB, so unlock and reading work offline.
Entries and document edits made offline wait in an encrypted outbox and are sent
on reconnect (idempotent by client id); the home screen then reports what changed
while you were away and which queued changes were refused.

`pnpm e2e` runs two Playwright projects: `dev` (Vite dev server) and `prod`
(the API serving the production build on :3100 under the strict security headers;
fails on any CSP violation; service worker active). A third, `clerk-prod`, runs the Clerk sign-in
against a Clerk development i