rcmd/keeporg
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e999e353f7686029061ba9e30fd2c00c0c8b6cc8
keeporg/docs/PROTOCOL.md
T
ReactorcoremeltdownandClaude Opus 5.5 4ffc434b1b Keep server data in an encrypted database, and harden every part 
Storage. The server keeps its data in SQLite (a file in the data
directory, the default) or PostgreSQL (database, KEEPORG_DATABASE_URL or
-database). Every row, the KDBX versions included, is sealed with
AES-256-GCM under a key derived from the master key and named by an HMAC.
The master key is required to start and a different one is refused. A data
directory from 0.10 or earlier is imported on first start. Several servers
may share one PostgreSQL database. Go goes to 1.26 for the pure-Go
drivers (modernc.org/sqlite, jackc/pgx).

Hardening, after an audit of the server, both clients and the deployment:
- Single sign-on approves a device only after an explicit Approve in the
  browser that started it, bound by a cookie and PKCE; identities are never
  linked by username, by verified email only when allowed, never to admins.
- Sign-in attempts are limited per address and per account, passwords are
  checked outside the store lock with uniform timing, one-time codes work
  once, and starting two-factor needs the password.
- Merge vaults bound KDF parameters, payload size and XML shape, check
  pushes before storing them, and run at most two merges at once. A version
  is written in the same transaction as its metadata.
- Tokens in URLs only on the event stream, which ends on revocation; CSP,
  frame-ancestors, no-store and HSTS; sign-in CSRF; 404 for databases
  without access; new trusted_proxies.
- Clients open only the server's approval page, keep case-variant and
  retired file names apart, never overwrite a save made during a pull,
  require https except locally, send the stream token in a header, bound
  their reads and escape notifications and terminal output.
- The .deb creates the master key, systemd is sandboxed further, nginx sets
  modern TLS and HSTS, and CI deploys from main only.

Server 0.12.0, desktop 0.6.0, Android 0.4.0 (versionCode 4).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 15:38:32 +01:00

179 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# KeepOrg HTTP API
Every `/api/` endpoint takes and returns JSON and needs
`Authorization: Bearer <token>`, except the login, device and invite
endpoints. Errors carry `{"code": "...", "error": "..."}`; `code` is stable
and meant to be matched on, `error` is for humans.
HTML is served at `/web` (sign in, list vaults, create one, change your
password) and at `/device`, `/invite/{token}`, `/oidc/login` and
`/oidc/callback`. `/oidc/login` with no parameters signs a browser in and
ends in a session cookie; with `?code=<user code>` it approves a waiting
client instead and ends in a token that client polls for. The web pages use the same session
tokens in a cookie that is `HttpOnly`, `SameSite=Strict` and `Secure` behind
https, and every form carries a per-session CSRF token.
## Authentication
| Method | Path | Body | Answer |
| --- | --- | --- | --- |
| POST | `/api/v1/auth/login` | `{username, password, totp, label}` | `{token, expires_at, user}`; `401 totp_required` when a second factor is enrolled and missing, `401 totp_invalid`, `401 bad_credentials` |
| POST | `/api/v1/auth/logout` | – | revokes the calling token |
| GET | `/api/v1/auth/whoami` | – | the account and its group memberships |
| POST | `/api/v1/auth/password` | `{current_password, new_password, totp}` | changes the account password; the current one is required, and the second factor when enrolled. Every other session of that account is revoked |
| POST | `/api/v1/auth/totp/enroll` | `{password, totp}`; `totp` only when a factor is already on | `{secret, uri}`; not active until confirmed. Without the password, `403 reauth_required`; replacing an active factor needs its current code too |
| POST | `/api/v1/auth/totp/confirm` | `{code}` | `{totp_enabled: true}` |
| DELETE | `/api/v1/auth/totp` | `{password, totp}` | `{totp_enabled: false}`; `403 reauth_required`, `403 bad_credentials`, `403 totp_invalid` |
| GET | `/api/v1/auth/sessions` | – | `{sessions: [{id, label, browser, current, created_at, last_seen_at, expires_at}]}`, the caller's own |
| DELETE | `/api/v1/auth/sessions/{id}` | – | signs that session out; `404` when it is not the caller's |
| DELETE | `/api/v1/auth/sessions` | – | `{revoked: n}`: every session of the caller but this one |
| POST | `/api/v1/auth/device/start` | `{label, return_url}` | `{device_code, user_code, verification_url, interval, expires_in}`; `400` when `return_url` is not a `keeporg:` URL |
| POST | `/api/v1/auth/device/poll` | `{device_code}` | `202 {status: "pending"}`, then `200 {token, ...}` once; `410 expired` |
A device code is single use: the first successful poll consumes it.
Sign-in attempts are limited per client address and per account. Over the
limit, `/auth/login`, `/auth/device/start` and the re-authenticating
endpoints answer `429 throttled` with `Retry-After`. A one-time code is
accepted once; a second use is `totp_invalid`. Device labels are trimmed to
64 characters.
Endpoints about a database answer `404 not_found` both for one that does not
exist and for one the caller has no access to. A push to a merge vault whose
KDBX header is malformed or demands more key derivation work than the server
opens (`internal/kdbx/limits.go`) is `400 invalid_kdbx`. A merge that cannot
get a turn within 30 seconds is `503 busy`.
A session `id` is a one-way digest of its token, never the token itself, so
a list of sessions cannot be used to sign in as any of them. Failed
re-authentication answers `403`, not `401`, so a client that drops its
token on `401` does not sign itself out over a mistyped password.
`last_seen_at` is refreshed at most every five minutes.
`return_url` is optional (server 0.9 and later). When it is given, the page
that ends the approval, after a password or single sign-on, carries a
"Return to KeepOrg" link to it. Only the `keeporg:` scheme is accepted, so
the page cannot be made to send anybody elsewhere. It is for a client whose
browser is a separate application, which is to say a phone; the client still
learns of the approval by polling, and the link only brings the person back.
Servers before 0.9 reject the unknown field with `400`, so a client should
retry without it.
## Synchronization
| Method | Path | Notes |
| --- | --- | --- |
| GET | `/api/v1/databases` | `{databases: [{id, name, perm, merge_strategy, version, sha256, size, updated_at, updated_by}]}` |
| GET | `/api/v1/databases/{id}/blob` | bytes; `ETag: "<version>"`, `X-KeepOrg-SHA256`; `204` when the database has no content yet; `?version=<n>` reads a stored older version |
| PUT | `/api/v1/databases/{id}/blob` | body is the KDBX file. `If-Match` is required |
| GET | `/api/v1/events` | SSE, with the `Authorization` header like everything else. `?access_token=` is still accepted here, and only here, for clients before 0.12; it puts the token in proxy logs. The stream ends once the session is revoked or the account disabled |
### PUT semantics
`If-Match` carries the version the edit was based on, or `*` to force.
| Condition | Status | Body |
| --- | --- | --- |
| `If-Match` missing | `428 precondition_required` | – |
| version matches, bytes differ | `200` | `{version, sha256, unchanged: false}` |
| version matches, bytes identical | `200` | `{version, sha256, unchanged: true}` |
| version stale, strategy is `merge` | `200` | `{version, sha256, merged: true, merge_summary, based_on}` — the two copies were folded together and the result stored as a new version |
| version stale, strategy is `merge`, but merging failed | `409 merge_failed` | `{error, current_version, merge_strategy}`; the stored vault is untouched |
| version stale, any other strategy | `409 conflict` | `{current_version, merge_strategy}`, plus `ETag` and `X-KeepOrg-Strategy` |
| `If-Match: *`, strategy is `client-wins` | `200` | the server copy is replaced |
| `If-Match: *`, any other strategy | `409 force_not_allowed` | – |
| read-only access | `403 forbidden` | – |
| no access | `404 not_found` | a database you cannot read does not exist to you |
| larger than `max_db_size_mb` | `413 too_large` | – |
`X-KeepOrg-SHA256` on a `PUT` is optional; when present it must match the
body or the request is rejected with `400 checksum_mismatch`.
After any accepted push, compare the `sha256` in the answer with what you
sent. If they differ the server stored something else — a merge — and the
local copy must be replaced by a fresh `GET`.
### Events
```
event: db-updated
data: {"type":"db-updated","database_id":"...","name":"Team","version":7,"sha256":"...","by":"alice"}
event: db-list-changed
data: {"type":"db-list-changed","database_id":"..."}
```
`db-updated` follows an accepted push; `db-list-changed` follows a grant,
rename, strategy change or deletion. A comment line (`: keepalive`) arrives
every 25 seconds. Reconnect on any error and reconcile fully; events are
notifications, never state.
## Vaults
A vault is a database the server created and can open. Creating one is the
only way the server comes to hold a KDBX key, and the only strategy that
needs one is `merge`.
| Method | Path | Body | Needs |
| --- | --- | --- | --- |
| POST | `/api/v1/vaults` | `{name, owner_group_id, merge_strategy, password}` | group admin of the owner |
| POST | `/api/v1/databases/{id}/key` | `{password}` or `{forget: true}` | database admin |
`POST /api/v1/vaults` builds an empty KDBX 4 database, encrypts it with
`password`, stores it as version 1 and answers with the database view. The
password must be at least 12 characters. For `merge_strategy: "merge"`
(the default here) the password is kept, encrypted under the server's master
key; for every other strategy it is used once and forgotten. A server with no
master key refuses with `400`.
`POST /api/v1/databases/{id}/key` stores the password of a database that
already has content, after checking that it opens the stored version, which
is how an uploaded database becomes mergeable. `{"forget": true}` removes it;
that is refused while the strategy is still `merge`.
The wrapped key is never returned by any endpoint.
## Administration
Permission needed is in the last column. "Group admin" means administering
the group named or any group above it.
| Method | Path | Body / query | Needs |
| --- | --- | --- | --- |
| GET | `/api/v1/groups` | – | any account; lists what you can see |
| POST | `/api/v1/groups` | `{name, parent_id}` | group admin of the parent; server admin for a root group |
| DELETE | `/api/v1/groups/{id}` | – | group admin; refuses while it has children, members or databases |
| POST | `/api/v1/groups/{id}/members` | `{username or user_id, role}` | group admin |
| DELETE | `/api/v1/groups/{id}/members/{user}` | – | group admin |
| POST | `/api/v1/databases` | `{name, owner_group_id, merge_strategy}` | group admin of the owner |
| PATCH | `/api/v1/databases/{id}` | `{name?, merge_strategy?}` | database admin |
| DELETE | `/api/v1/databases/{id}` | `{password, totp?}` | database admin, re-proving their own password; deletes every stored version |
| POST | `/api/v1/grants` | `{group_id, database_id, perm}` | database admin |
| DELETE | `/api/v1/grants` | `?group_id=&database_id=` | database admin |
| POST | `/api/v1/invites` | `{group_id, role, ttl_hours, max_uses}` | group admin |
| GET | `/api/v1/invites` | – | your own invites, and those of groups you administer |
| DELETE | `/api/v1/invites/{token}` | – | whoever may see it: its creator, an admin of its group, a server admin |
| GET | `/api/v1/users` | – | yourself, plus members of groups you administer |
| PATCH | `/api/v1/users/{id}` | `{action}` | server admin |
| GET | `/healthz` | – | unauthenticated liveness |
`merge_strategy` is one of `merge`, `server-wins`, `client-wins`, `manual`.
Switching to `merge` requires a stored key and is otherwise refused with
`400`. `perm` is one of `read`, `write`, `admin`. `role` is `member` or
`admin`.
Deleting a database is the one call that asks for credentials again. A
session token is enough to read and write a vault and not enough to destroy
every version of it, so the body carries the caller's own account password,
and `totp` as well when that account has a second factor enrolled — the
server answers `401 totp_required` when it is missing. An account that signs
in only through an identity provider has no password to send and passes
`{"confirm_name": "<the database's exact name>"}` instead.
An account `action` is one of `disable`, `enable`, `promote`, `demote`,
`clear-totp` or `delete`. `disable` and `delete` also revoke every session
that account holds. The three that would lock the caller out — `disable`,
`demote`, `delete` — are refused on the caller's own account, because a
server with no reachable administrator can only be repaired with
`keeporgd -reset-admin` on the host.
Reference in New Issue View Git Blame Copy Permalink