root
7eed722ff5
Why: two questions about operating this turned up two gaps. "Where do I get the admin password" had no answer once the line scrolled out of the log, and "how do I set up OIDC" ran straight into a sign-in link that could not work. What: - /oidc/login with no parameters now signs a browser in and ends in a session cookie. It previously required the user code of a waiting client, so the link on the web sign-in page always failed. With a code it still approves a device, and the two paths no longer overlap: an empty user code matches no pending device. - POST /api/v1/auth/password, `keeporg passwd`, and a form on /web/vaults. Changing a password requires the current one, and the one-time code when a second factor is enrolled, and revokes that account's other sessions. Until now nothing could change a password, which made the advice printed at first start impossible to follow. - keeporgd -reset-admin, for when that first password was not kept: a new one printed once, any second factor cleared, sessions revoked. It writes the state document directly and says to stop the server first. - The client read stdin through a new buffered reader per prompt, so the first prompt swallowed the rest and anything asking twice could not be scripted. One shared reader now. A prompt for a password being set no longer reads $KEEPORG_PASSWORD either; that variable holds the password you sign in with, and taking it here would have set the new password to the old one. - HANDOVER gains a first-sign-in section and an OIDC setup section covering the redirect URI, the config block, both entry points and how an identity becomes an account. Proved: OIDC now has tests, against a stub provider that serves discovery, authorization, token and userinfo. They cover the web sign-in that was broken, device approval, linking an existing account by username, the refusal when auto_create is off, and a forged callback state. Eight more cover the password change. Checked by hand with the real binaries: the first-start password logs once and works, -reset-admin replaces it while the old one stops working, and `keeporg passwd` changes it from a pipe. Server 0.5.0, desktop clients 0.3.0.
131 lines
7.1 KiB
Markdown
131 lines
7.1 KiB
Markdown
# 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` | – | `{secret, uri}`; not active until confirmed |
|
||
| POST | `/api/v1/auth/totp/confirm` | `{code}` | `{totp_enabled: true}` |
|
||
| POST | `/api/v1/auth/device/start` | `{label}` | `{device_code, user_code, verification_url, interval, expires_in}` |
|
||
| 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.
|
||
|
||
## 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. Accepts `?access_token=` because an event stream cannot always set headers |
|
||
|
||
### 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}` | – | database admin; 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 |
|
||
| GET | `/api/v1/users` | – | yourself, plus members of groups you administer |
|
||
| 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`.
|