Claude Fable 5
0c85293830
Some checks failed
CI / Lint, typecheck, test (push) Failing after 1m39s
CI / Auth e2e pack (push) Has been skipped
CI / Import/export fidelity gate (push) Has been skipped
CI / Build container images (push) Has been skipped
CD / Build and push images (push) Successful in 3m51s
CD / Deploy to Test (push) Successful in 9s
CD / Smoke tests against Test (push) Successful in 1m10s
CD / Promote to Int (push) Successful in 11s
Token-authenticated machine access at /api/public/v1 — the foundation for the built-in MCP endpoint (#105). Personal access tokens: - api_tokens table (SHA-256 hash, scope read|write, optional pond restriction, expiry, revocation, throttled last-used) + migration; secrets are dt_pat_<random>, shown exactly once - lifecycle endpoints under /users/me/api-tokens (session-only — a leaked token can never mint more tokens) with audit entries api.token_created/api.token_revoked - settings UI section (create with scope/expiry/pond restriction, one-time reveal with copy, list with status + revoke), de+en Activation (404 semantics per #60 on both levels): - instance setting api.enabled (default off, admin settings switch) - pond setting apiEnabled (default off, pond settings toggle; the PondsService settings-merge learned the key — the #92 lesson) Surface (/api/public/v1, excluded from the SPA's global prefix): - me, ponds, pages (list/read as Markdown+HTML, create from Markdown via the shared pipeline, PATCH title/content, DELETE to trash), search (permission-filtered + narrowed to exposed ponds, highlights as **…**), markdown ZIP export, labels (tree, create/rename/recolour/move/delete, assign/unassign), comments (threads, create, resolve/reopen) - content replacement travels the collab-owned document path: the new state lands as a MANUAL version "API update", then the established restore NOTIFY applies it — open editors converge, history stays append-only, no second lineage (VersionsService.replaceContent) - hand-maintained OpenAPI 3.1 document at /openapi.json, pinned to the controller by a route-coverage test in both directions Enforcement: - PublicApiGuard: instance switch → bearer PAT auth (request.user is the token's user) → per-token rate limit (429 + Retry-After) → scope (403 scope_required) → pond opt-in + token restriction - the shared PermissionGuard then applies the unchanged permission model; PageParamSource gained pondSlugParam for the slug+slug routes - no cookies anywhere → no CSRF surface (pinned by a hostile-Origin test) - every write audit-logged as api.write with the token attributed Tests/verification: - 12-test e2e pack: lifecycle, switches, permission matrix (reader/editor/outsider × scopes), restriction, page roundtrip incl. restore-NOTIFY assertion, labels, comments incl. policy, search narrowing, ZIP export, rate limit; full api suite 60/60 green (quota fixture via per-user override — never the instance default) - new collab-pack test proves an open editor converges onto an API content replacement (green against a local seeded stack) - UI smoke against the built SPA: token create/reveal/revoke, pond opt-in persists, admin switch persists (10/10) - docs/self-hosting/public-api.md + README link Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EwZ4jR4KFAPvpjWevfUGX1
64 lines
3.5 KiB
Markdown
64 lines
3.5 KiB
Markdown
# Public REST API (issue #104)
|
|
|
|
Dorfteich instances can expose a token-authenticated REST API at
|
|
`/api/public/v1` for scripts and integrations. It is **off by default**,
|
|
twice: a Site Admin enables the instance switch (_Admin → Settings →
|
|
Public API_), and every pond that should be reachable opts in separately
|
|
(_Pond settings → Public API_). Anything not enabled answers 404 —
|
|
indistinguishable from an instance without the feature.
|
|
|
|
## Personal access tokens
|
|
|
|
Every user manages their tokens under _Settings → API tokens_: a name, a
|
|
scope (`read` or `read+write`), an optional expiry, and an optional
|
|
restriction to selected ponds. The secret (`dt_pat_…`) is shown exactly
|
|
once and stored hashed; tokens are revocable and show their last use.
|
|
|
|
A token acts **as its user**: the normal permission model — grants, label
|
|
scopes, the 404-vs-403 policy — applies unchanged. Scope and pond
|
|
restriction only narrow it further; they never grant anything the user
|
|
could not do in the app.
|
|
|
|
## Using the API
|
|
|
|
```sh
|
|
curl -H "Authorization: Bearer dt_pat_..." \
|
|
https://your-instance.example/api/public/v1/me
|
|
```
|
|
|
|
- The machine-readable description lives at
|
|
`/api/public/v1/openapi.json` (reachable without a token while the
|
|
instance switch is on).
|
|
- Requests are rate-limited per token (HTTP 429 + `Retry-After`).
|
|
- Errors carry the api's uniform body: `{ code, message, details? }`.
|
|
- Page content is Markdown in, Markdown + rendered HTML out. A content
|
|
update (`PATCH …/pages/{slug}` with `markdown`) **replaces** the whole
|
|
page; it is applied through the collaborative document, so open editors
|
|
converge live, and the previous state stays in the version history
|
|
(the change itself appears as a manual version named "API update").
|
|
|
|
### Endpoint overview
|
|
|
|
| Area | Endpoints |
|
|
| -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
|
|
| Identity | `GET /me` |
|
|
| Ponds | `GET /ponds`, `GET /ponds/{slug}` |
|
|
| Pages | `GET/POST /ponds/{slug}/pages`, `GET/PATCH/DELETE /ponds/{slug}/pages/{pageSlug}` |
|
|
| Search | `GET /search?q=&pond=&label=` |
|
|
| Export | `GET /ponds/{slug}/export/markdown` (ZIP) |
|
|
| Labels | `GET/POST /ponds/{slug}/labels`, `PATCH/DELETE /ponds/{slug}/labels/{id}`, `PUT/DELETE /ponds/{slug}/pages/{pageSlug}/labels/{id}` |
|
|
| Comments | `GET/POST /ponds/{slug}/pages/{pageSlug}/comments`, `POST/DELETE …/comments/{id}/resolve` |
|
|
|
|
Deliberately not in v1 (stage 2): attachment upload, version endpoints,
|
|
webhooks.
|
|
|
|
## Security notes
|
|
|
|
- Bearer tokens only — no cookies are involved, so there is no CSRF
|
|
surface; browser sessions cannot call the public API and tokens cannot
|
|
manage tokens.
|
|
- Token creation and revocation are audit-logged, as is every write
|
|
through the API (action `api.write`, with the token attributed).
|
|
- Treat a token like a password. Revoke it under _Settings → API tokens_
|
|
the moment it may have leaked.
|