stephan/kiddo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: align versions and update update-service docs

Browse Source
This commit is contained in:
Stephan Wilkens
2026-01-15 08:40:54 +01:00
parent 589f9595f4
commit c41482a7b3
89 changed files with 266 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/admin-token-operations.md
View File

@ -1,4 +1,5 @@
ID: DOC_000006 | Version: 0.1.0 | Status: Draft
ID: DOC_000006 | Version: 0.2.1 | Status: Draft
By: Codex (GPT-5)
# Admin Token Operations

2
docs/architecture/openapi.yaml
View File

@ -1,7 +1,7 @@
openapi: 3.0.3
info:
title: Update Webservice API
version: 0.1.0
version: 0.2.1
servers:
- url: https://update.wlkns.org
- url: https://staging.update.wlkns.org

2
docs/client-quickstart.md
View File

@ -1,4 +1,4 @@
ID: DOC_000008 | Version: 0.1.0 | Status: Draft
ID: DOC_000008 | Version: 0.2.1 | Status: Draft
# Client Quickstart

2
docs/oidc-validation.md
View File

@ -1,4 +1,4 @@
ID: DOC_000003 | Version: 0.1.0 | Status: Draft
ID: DOC_000003 | Version: 0.2.1 | Status: Draft
By: Codex (GPT-5)
# OIDC End-to-End Validation (Kiddo)

5
docs/third-party-api.md
View File

@ -1,4 +1,5 @@
ID: DOC_000005 | Version: 0.1.0 | Status: Draft
ID: DOC_000005 | Version: 0.2.1 | Status: Draft
By: Codex (GPT-5)
# Third-Party API Guide
@ -117,7 +118,7 @@ Common error codes:
`payload_too_large`, `status_invalid`
## Rate Limits
Limits are tiered by scope. See `docs/architecture/ARCHITECTURE.md` for current values.
Limits are tiered by scope. See `docs/architecture/openapi/paths/limits.yaml` for current values.
## Examples
Fetch manifest:

27
docs/update-api.md
View File

@ -1,4 +1,4 @@
ID: DOC_000006 | Version: 0.1.0 | Status: Draft
ID: DOC_000006 | Version: 0.2.1 | Status: Draft
By: Codex (GPT-5)
# Update API (Kiddo Backend)
@ -8,6 +8,16 @@ Definiert interne API-Endpunkte fuer Update-Status, Check, Apply, Rollback und L
## Endpoints
### POST /update/enroll
Body (optional):
```json
{ "enroll_token": "<one-time-token>" }
```
Antwort:
```json
{ "enrolled": true, "message": "Enrollment successful" }
```
### GET /update/status
Antwort:
```json
@ -15,7 +25,8 @@ Antwort:
"current_version": "0.1.2",
"last_status": "success|failed|unknown",
"last_error": "<optional>",
"last_timestamp": "2025-12-28T12:34:56Z"
"last_timestamp": "2025-12-28T12:34:56Z",
"enrolled": true
}
```
@ -51,10 +62,18 @@ Antwort:
Antwort:
```json
[
{"timestamp":"2025-12-28T12:34:56Z","status":"success","message":"updated to 0.1.2"}
{
"timestamp": "2025-12-28T12:34:56Z",
"status": "success",
"message": "updated to 0.1.2",
"version": "0.1.2",
"device_id": "kiddo-001",
"error": null
}
]
```
## Notes
- Alle Endpunkte erfordern Auth (Session/Bearer).
- Alle Endpunkte erfordern Auth (Session-Cookie oder `Authorization: Bearer <token>`).
- Apply/Rollback starten async; UI pollt /update/status.
- `/update/enroll` speichert das Update-Token lokal (siehe `SKD_UPDATE_TOKEN_FILE`).

10
docs/update-client.md
View File

@ -1,4 +1,4 @@
ID: DOC_000004 | Version: 0.1.0 | Status: Draft
ID: DOC_000004 | Version: 0.2.1 | Status: Draft
By: Codex (GPT-5)
# Client Update Flow (Kiddo)
@ -18,7 +18,8 @@ Beispiel:
```
## Flow (High Level)
1. Manifest abrufen (auth optional via Bearer Token).
0. Falls kein Token vorhanden ist: Enrollment durchfuehren (Pre-Shared Token -> Langzeit-Token).
1. Manifest abrufen (auth via Bearer Token).
2. `artifact_url` herunterladen.
3. SHA256 pruefen (Signatur optional).
4. In Staging-Verzeichnis entpacken.
@ -37,13 +38,14 @@ Beispiel:
## Security Notes
- Artefakte muessen checksum-verifiziert sein.
- Token-Handling ueber `SKD_UPDATE_TOKEN`.
- Token-Handling ueber `SKD_UPDATE_TOKEN` oder `SKD_UPDATE_TOKEN_FILE`.
- Enrollment nutzt einen Pre-Shared Token und speichert das Langzeit-Token lokal.
## Constraints
- Update-Service ist extern (update.wlkns.org).
- Service muss als root stoppen/starten koennen.
## Status Reporting
- Status wird per HTTP POST an `https://update.wlkns.org/status` gemeldet.
- Status wird per HTTP POST an `${SKD_UPDATE_SERVICE_URL}/v1/projects/${SKD_UPDATE_PROJECT_ID}/status` gemeldet.
- Schema siehe `docs/update-status.md`.
- Lokaler Status/Logs liegen unter `/var/lib/skd` (konfigurierbar via ENV).

20
docs/update-status.md
View File

@ -1,4 +1,4 @@
ID: DOC_000005 | Version: 0.1.0 | Status: Draft
ID: DOC_000005 | Version: 0.2.1 | Status: Draft
By: Codex (GPT-5)
# Update Status Reporting
@ -9,17 +9,21 @@ Definiert das Status-Schema fuer Update-Resultate und den Uebertragungsweg.
## Status Schema (JSON)
```json
{
"device_id": "<hostname>",
"version": "0.1.2",
"status": "success|failed",
"error": "<optional message>",
"timestamp": "2025-12-28T12:34:56Z"
"project_id": "safe-kiddo-control",
"client_id": "<hostname>",
"version": "0.2.1",
"status": "success|failed|in_progress",
"timestamp": "2025-12-28T12:34:56Z",
"duration_ms": 1234,
"error_code": "<optional>",
"reason": "<optional>"
}
```
## Transport
- HTTP POST an `https://update.wlkns.org/status`
- Auth: Bearer Token (`SKD_UPDATE_TOKEN`)
- HTTP POST an `${SKD_UPDATE_SERVICE_URL}/v1/projects/${SKD_UPDATE_PROJECT_ID}/status`
- Auth: Bearer Token (`SKD_UPDATE_TOKEN` oder `SKD_UPDATE_TOKEN_FILE`)
## Notes
- Statusmeldungen sind best-effort; Fehler beim Senden blockieren kein Update.
- Reporting wird nur gesendet, wenn ein Update-Token vorhanden ist.