feat: external session API + magic login (merge from open-refboard 02750ba)
Publish container image / build-and-push (push) Canceled after 0s

- POST /api/external/session: bridge auth via X-API-Key, JIT user provisioning
- GET /api/external/health: capability report
- /magic frontend route: consumes ?token= JWT, redirects
- docs/EXTERNAL-API.md: bridge contract spec
This commit is contained in:
Hermes committed 2026-10-14 10:13:54 +00:00
1 parent 4cda9c8c0a
commit 0504df49b0
7 files changed
+428 -43

No files matched your search

+99
View File
@@ -0,0 +1,99 @@
# Open RefBoard — External Integration API (v1)
Generische Schnittstelle für Bridges: externe Systeme (AYON, Nextcloud, Skripte, …)
authentifizieren sich per API-Key und melden Nutzer zu RefBoard-Sessions an.
RefBoard ist dabei bridge-agnostisch — jede Bridge ist ein dünner Client dieser Spec.
## Voraussetzung
`REFBOARD_API_KEY` muss in der RefBoard-`.env` gesetzt sein (Header `X-API-Key`).
Ohne Key antwortet die API mit `503 API key not configured on server`.
## Endpoints
### `GET /api/external/health`
Liveness + Capability-Report. Kein Auth nötig? Doch: API-Key (Konsistenz).
```json
{ "status": "ok", "service": "refboard", "open_refboard": true, "api_version": 1, "users": 12 }
```
### `POST /api/external/session`
Stellt sicher, dass der Nutzer existiert (Auto-Provisionierung), und stellt ein
Login-JWT aus.
**Request:**
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
| `user_name` | string | ✅ | Identität aus dem Quellsystem. Wird zu Username sanitisiert (`a-z0-9_-`), auch Display-Name. **Pflicht.** |
| `user_email` | string | – | Externe E-Mail. Default: `<username>@bridges.local` (konfigurierbar via `EXTERNAL_BRIDGE_EMAIL_DOMAIN`). |
| `board_id` | string | – | Direkt auf dieses Board landen. |
| `collection_name` | string | – | Collection per Name suchen; wird bei Bedarf **erzeugt** (User wird Owner). |
| `collection_id` | string | – | Collection per ID (keine Auto-Erzeugung; 404 wenn fehlend). |
| `board_name` | string | – | Board-Name innerhalb der Collection (Default `"Main"`; wird bei Bedarf erzeugt). |
| `role` | `"member"` \| `"admin"` | – | Rolle **nur für neu angelegte** Nutzer (Default `member`). |
**Antwort 200:**
```json
{
"user": { "id": "…", "username": "niklas", "display_name": "Niklas", "email": "…", "role": "member" },
"token": "<JWT>",
"token_type": "Bearer",
"expires_in": 604800,
"board": { "id": "…", "name": "Main", "collection_id": "…", "url": "https://…/board/<id>" }
}
```
**Fehler:** `400` (user_name fehlt), `401` (API-Key), `403` (User deaktiviert),
`404` (board_id/collection_id unbekannt), `409` (E-Mail-Konflikt bei Provisionierung),
`503` (API-Key nicht konfiguriert).
### Magic-Login (Browser)
Bridge schickt den Nutzer an:
```
https://<refboard>/magic?token=<JWT>&redirect=/board/<boardId>
```
- `/magic` validiert den Token via `/api/auth/me`, speichert ihn und leitet weiter.
- `redirect` optional (Default `/`).
- Token läuft nach `JWT_EXPIRES_IN` ab (Default 7d).
## Provisionierungs-Regeln
- Neuer `user_name` → Konto wird automatisch angelegt (Zufalls-Passwort, damit kein
direkter Passwort-Login möglich ist; Reset nur via Admin).
- Wiedererkennung anhand **Username** (sanitisierter `user_name`).
- E-Mail-Kollision (`user_email` existiert, aber anderer Username) → `409`, keine
stillen Zusammenführungen.
- Existierende Nutzer: keine Rollen-Änderung durch Bridges (mindestens `role`
nur bei Neuanlage).
## Bridge-Minimalbeispiel
```bash
curl -X POST https://<refboard>/api/external/session \
-H "X-API-Key: $REFBOARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"user_name": "niklas", "collection_name": "amberflash", "board_name": "Refs"}'
# → { token, board.url } → Browser öffnen: board.url + "?token=" … eigentlich: /magic?token=…
```
Login-URL bauen:
```javascript
const loginUrl = `${session.board.url.replace(/\/board\/(.+)$/, '/magic')}?token=${session.token}&redirect=/board/${session.board.id}`;
```
## Konventionen für Bridges
1. Bridge kennt nur: RefBoard-URL + `REFBOARD_API_KEY`. Kein User-Passwort-Handling.
2. Bridge mappt ihre Identität auf `user_name` (stabil & eindeutig pro Quelle,
z.B. AYON-Username bzw. Nextcloud-UserId).
3. Board-Auswahl: `collection_name` pro Quellprojekt (AYON: Projektname,
Nextcloud: Ordnername) — RefBoard erzeugt sie on-demand.