From 2db26ced18ca01fd1f1342f20b08b3b9c18dfe14 Mon Sep 17 00:00:00 2001 From: Stefan Schmidt-Egermann Date: Sat, 25 Apr 2026 12:04:02 +0200 Subject: [PATCH] docs: cross-links updated to 3-level structure --- CONTRIBUTING.md | 39 +++++++++++++++++ README.md | 114 +++++++++++++++++++++++++++++++++++++++++++++++- SECURITY.md | 33 ++++++++++++++ 3 files changed, 184 insertions(+), 2 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b85282c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,39 @@ +# Contributing + +Vielen Dank für dein Interesse an der hightrusted CAPTURE API. + +## Wer kann beitragen + +Diese Repositorys werden primär von hightrusted GmbH gepflegt. Wir freuen uns +über Bug-Reports, Verbesserungsvorschläge und Pull-Requests aus der Community. + +## Issues + +- **Bug-Report:** beschreibe das erwartete vs. tatsächliche Verhalten und liefere + einen reproduzierbaren Code-Schnipsel mit. Bitte keine API-Keys mit posten. +- **Feature-Request:** beschreibe den Use-Case — wir entscheiden, ob das Feature + in das SDK gehört oder besser direkt gegen die API umgesetzt wird. + +## Pull Requests + +1. Fork und Branch (`feat/...`, `fix/...`, `docs/...`). +2. Tests anpassen oder ergänzen. +3. Lokale Build-Pipeline grün bekommen (siehe README). +4. **Commits signieren** — sowohl GPG als auch X.509 werden akzeptiert. Unsignierte + Commits werden nicht gemerged. +5. PR öffnen mit klarer Beschreibung: Was ändert sich, warum, Breaking Change ja/nein. + +## Code-Stil + +Jede Sprache hat ihre eigene Konvention — siehe README des jeweiligen Repos. +Tendenziell: Pflegt euch an den Standards, die wir bereits im Code verwenden. + +## Lizenz + +Beiträge gehen unter der MIT-Lizenz ein (siehe `LICENSE`). Mit dem Öffnen eines +PRs bestätigst du, dass du das Recht hast, deinen Beitrag unter diese Lizenz zu +stellen. + +## Kontakt + +`developers@hightrusted.net` diff --git a/README.md b/README.md index b1ff4c1..05925f0 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,113 @@ -# capture-openapi +# hightrusted CAPTURE — OpenAPI Specification -OpenAPI 3.1 Spezifikation der hightrusted CAPTURE API \ No newline at end of file +> **Status:** v0.1 Preview — API stabil, Spec ist Single Source of Truth für alle SDKs + +OpenAPI 3.1 Spezifikation der [hightrusted CAPTURE API](https://capture.hightrusted.net) — +forensische Web-Captures mit qualifiziertem Zeitstempel nach RFC 3161 / eIDAS Art. 41. + +Diese Spec ist die **maschinenlesbare Referenz**, aus der wir alle anderen Artefakte +ableiten: SDKs, Client-Bibliotheken, Postman-Collection, gerenderte Doku. + +**Made in Germany.** Server in Deutschland. DSGVO-nativ. Kein US-Cloud-Anbieter +in der Verarbeitungskette. + +## Inhalt + +- `openapi.yaml` — die OpenAPI 3.1 Spec +- `examples/` — Beispiel-Requests und -Responses für jeden Endpoint +- `CHANGELOG.md` — Versions-History der Spec + +## Validierung + +```bash +# Mit redocly cli +npx @redocly/cli lint openapi.yaml + +# Oder mit spectral +npx @stoplight/spectral-cli lint openapi.yaml +``` + +## Doku rendern + +```bash +# HTML-Doku mit Redoc bauen +npx @redocly/cli build-docs openapi.yaml -o ./docs/index.html +``` + +Ergebnis: statische HTML-Datei mit kompletter API-Doku, die du auf jedem Webserver +ablegen kannst. + +## Client-Generierung + +Aus dieser Spec lassen sich automatisch Clients für 50+ Sprachen erzeugen +(siehe https://openapi-generator.tech). Wir pflegen offizielle Clients für +Python, Node.js und PHP — siehe [Verwandte Repositorys](#verwandte-repositorys). + +```bash +# Beispiel: Go-Client erzeugen +openapi-generator-cli generate \ + -i openapi.yaml \ + -g go \ + -o ./clients/go +``` + +## Versionierung + +API-Versionen sind im Pfad: `/api/v1/...` + +- **Breaking Changes** → neue Major-Version (`/api/v2`), alte Major bleibt 24 Monate erreichbar +- **Non-Breaking Changes** (neue Felder, neue Endpoints) → ohne Versionssprung + +Diese OpenAPI-Spec verfolgt die API 1:1. Änderungen sind in `CHANGELOG.md` +nachvollziehbar. + +## Endpoints (Übersicht) + +| Endpoint | Beschreibung | Auth | +|--------------------------------|---------------------------------------|--------| +| `POST /captures` | Capture erstellen (sync/async/webhook)| Bearer | +| `GET /captures/{id}` | Status & Metadaten abrufen | Bearer | +| `GET /captures/{id}/pdf` | PDF herunterladen | Bearer | +| `GET /captures/{id}/verify` | Capture verifizieren | — | +| `GET /usage` | eigenen Verbrauch abrufen | Bearer | + +## Webhook-Events + +| Event | Wann | +|-------------------|-----------------------------------------| +| `capture.ready` | PDF und Zeitstempel fertig | +| `capture.failed` | Fehler beim Rendern oder TSA | + +Webhook-Retry: 3 Versuche mit exponentiellem Backoff (1 min, 5 min, 30 min). + +## Verwandte Repositorys + +**Im selben Produkt** ([`hightrusted-capture`](https://git.hightrusted.net/hightrusted-capture)): + +- [`postman`](https://git.hightrusted.net/hightrusted-capture/postman) — Postman Collection +- [`examples`](https://git.hightrusted.net/hightrusted-capture/examples) — Beispiel-Anwendungen +- [`python`](https://git.hightrusted.net/hightrusted-capture/python) — Python-SDK +- [`node`](https://git.hightrusted.net/hightrusted-capture/node) — Node.js-SDK +- [`php`](https://git.hightrusted.net/hightrusted-capture/php) — PHP-SDK + +**Plattform-übergreifend** ([`hightrusted`](https://git.hightrusted.net/hightrusted)): + +- [`platform`](https://git.hightrusted.net/hightrusted/platform) — Plattform-Übersicht, Architektur, Produkt-Liste +- [`developer-portal`](https://git.hightrusted.net/hightrusted/developer-portal) — gemeinsame Konventionen, Auth, Errors, Rate-Limits +- [`compliance`](https://git.hightrusted.net/hightrusted/compliance) — DSGVO, AGB-Templates, Whitepaper + +## Support + +- **Doku:** https://capture.hightrusted.net/api/docs +- **Status-Page:** https://status.hightrusted.net +- **Developer Support:** developers@hightrusted.net +- **Sicherheitslücken:** siehe [SECURITY.md](./SECURITY.md) + +## Lizenz + +MIT — siehe [LICENSE](./LICENSE). + +--- + +**hightrusted GmbH** — *The European Trust Infrastructure.* +Made in Germany. DSGVO-nativ. eIDAS-konform. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..9ed887a --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,33 @@ +# Security Policy + +## Sicherheitslücken melden + +Wenn du eine Sicherheitslücke in diesem SDK oder in der hightrusted CAPTURE API +findest, **öffne kein öffentliches Issue**. Stattdessen: + +- **E-Mail:** `security@hightrusted.net` +- **PGP-Key:** veröffentlicht auf https://hightrusted.net/.well-known/security.txt + +Bitte gib in der Meldung an: + +- Betroffenes Repository / SDK-Version +- Beschreibung der Schwachstelle und potenzielle Auswirkung +- Schritte zur Reproduktion +- Falls vorhanden: Proof-of-Concept-Code + +Wir bestätigen den Eingang innerhalb von 48 Stunden und arbeiten an einer +zeitnahen Behebung. Verantwortliche Offenlegung wird honoriert — wir nennen +Reporter (auf Wunsch) in den Release-Notes. + +## Unterstützte Versionen + +Während der `v0.x`-Phase werden nur die jeweils aktuellste Minor-Version und +deren letzte zwei Patch-Versionen aktiv mit Sicherheits-Updates versorgt. + +Ab `v1.0` gilt: aktuelle Major + vorherige Major (12 Monate Übergangsfrist). + +## Out of Scope + +Diese Policy gilt für die SDKs in diesem Repository und die zugehörige +hightrusted CAPTURE API. Für Schwachstellen in anderen hightrusted-Produkten +(SIGN, ID, MEET, PAY, …) gilt jeweils die dortige `SECURITY.md`.