From 81101c6d6593414843f0e63e85a6e51ccbdc91a1 Mon Sep 17 00:00:00 2001 From: Stefan Schmidt-Egermann Date: Sat, 25 Apr 2026 12:03:58 +0200 Subject: [PATCH] docs: cross-links updated to 3-level structure --- CONTRIBUTING.md | 39 +++++++++++++ README.md | 143 +++++++++++++++++++++++++++++++++++++++++++++++- SECURITY.md | 33 +++++++++++ 3 files changed, 213 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 2c81f31..b03527d 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,142 @@ -# capture-python +# hightrusted CAPTURE — Python SDK -Python SDK für die hightrusted CAPTURE API \ No newline at end of file +> **Status:** v0.1 Preview — API stabil, SDK in aktiver Entwicklung + +Offizielles Python-SDK für die [hightrusted CAPTURE API](https://capture.hightrusted.net) — +forensische Web-Captures mit qualifiziertem Zeitstempel nach RFC 3161 / eIDAS Art. 41. + +**Made in Germany.** Server in Deutschland. DSGVO-nativ. Kein US-Cloud-Anbieter +in der Verarbeitungskette. Quelloffen unter MIT-Lizenz. + +## Was die CAPTURE API tut + +Sie nimmt eine URL entgegen, rendert die Seite vollständig (inkl. JavaScript), +liefert sie als PDF/A zurück und versieht das Ergebnis mit einem qualifizierten +Zeitstempel. Das Ergebnis ist gerichtsverwertbar und Jahre später noch +verifizierbar — auch nachdem die Original-Seite längst offline ist. + +Anwendungsfälle: Markenrechtsverletzungen dokumentieren, Auftragsbedingungen +zum Buchungszeitpunkt sichern, Compliance-Nachweise für Behörden, Beweissicherung +durch Anwälte und Sachverständige. + +## Installation + +```bash +pip install hightrusted-capture +``` + +## Quickstart + +```python +from hightrusted_capture import Client + +client = Client(api_key="ht_live_...") + +# Synchron — wartet bis zu 30 s auf das fertige PDF +capture = client.capture(url="https://example.com") + +print(capture.id) +print(capture.verify_url) +print(capture.timestamp.issued_at) + +# PDF herunterladen +capture.download("./beweis.pdf") +``` + +## Authentifizierung + +Bearer-Token mit API-Key. Key-Erzeugung im Dashboard: +https://capture.hightrusted.net/dashboard/api-keys + +```python +client = Client(api_key="ht_live_...") +# alternativ via Umgebungsvariable HIGHTRUSTED_API_KEY +``` + +## Asynchrone Captures + Webhooks + +```python +job = client.capture_async( + url="https://example.com", + webhook_url="https://your-app.tld/webhooks/capture", +) +# job.status == "queued" + +# später, sobald der Webhook capture.ready geliefert hat: +capture = client.get(job.id) +capture.download("./beweis.pdf") +``` + +## Verify + +```python +result = client.verify(capture_id="cap_...") +print(result.valid) # True +print(result.timestamp) # 2026-04-25T11:29:40Z +``` + +## Rate Limits + +Limits werden pro API-Key gemessen. Bei Überschreitung: HTTP 429 mit +`Retry-After`-Header. Das SDK respektiert den Header automatisch und retried. + +| Plan | req/min | Calls/Monat | +|-----------|---------|-------------| +| Developer | 5 | 100 | +| Starter | 30 | 300 | +| Growth | 120 | 2.000 | +| Scale | 600 | 10.000 | + +## Voraussetzungen + +- Python 3.9 oder höher +- `requests` (wird automatisch installiert) + +## Entwicklung + +```bash +git clone ssh://git@git.hightrusted.net:2222/hightrusted-capture/python.git +cd python +python -m venv .venv && source .venv/bin/activate +pip install -e ".[dev]" +pytest +``` + +## Roadmap + +- [ ] v0.1 — Basis-Client (sync + async), Verify, Download +- [ ] v0.2 — Retry-Logik, Webhook-Verifikation, Type-Hints vollständig +- [ ] v0.3 — Async/Await-Variante (`httpx`) +- [ ] v1.0 — Stabile API, semantische Versionierung + +## Verwandte Repositorys + +**Im selben Produkt** ([`hightrusted-capture`](https://git.hightrusted.net/hightrusted-capture)): + +- [`openapi`](https://git.hightrusted.net/hightrusted-capture/openapi) — OpenAPI 3.1 Spec (Single Source of Truth) +- [`postman`](https://git.hightrusted.net/hightrusted-capture/postman) — Postman Collection +- [`examples`](https://git.hightrusted.net/hightrusted-capture/examples) — Beispiel-Anwendungen +- [`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`.