diff --git a/LICENSE b/LICENSE index c7ebe92..ed12564 100644 --- a/LICENSE +++ b/LICENSE @@ -1,9 +1,21 @@ MIT License -Copyright (c) 2026 hightrusted +Copyright (c) 2026 hightrusted GmbH -Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: -The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 817504c..9062ff2 100644 --- a/README.md +++ b/README.md @@ -1,89 +1,78 @@ # hightrusted CAPTURE — Postman Collection -> **Status:** v0.1 Preview — API stabil, Collection wird mit jedem API-Release aktualisiert +> **Status:** v1.0.0 — synchron mit OpenAPI Spec Postman-Collection 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. +**Made in Germany.** Server in Deutschland. DSGVO-nativ. ## Inhalt -- `hightrusted-capture.postman_collection.json` — alle Endpoints mit Beispielen -- `hightrusted-capture.postman_environment.json` — Environment-Template (`api_key`, `base_url`) +- `hightrusted-capture.postman_collection.json` — alle Endpoints mit Tests +- `hightrusted-capture.postman_environment.json` — Environment mit `api_key`, `base_url` ## Endpoints in der Collection -- `POST /captures` — Capture erstellen (sync / async / webhook) -- `GET /captures/{id}` — Status abfragen -- `GET /captures/{id}/pdf` — PDF herunterladen -- `GET /captures/{id}/verify` — Capture verifizieren (kostenlos, ohne API-Key) -- `GET /usage` — eigenen Verbrauch abrufen +**Captures:** +- Capture erstellen — synchron / asynchron / webhook +- Capture-Status abrufen +- Captures auflisten +- PDF herunterladen + +**Verify:** +- Verifikation per Capture-ID +- Verifikation per Verify-URL +- Verifikation per PDF-Upload + +**Account:** +- Eigenen Verbrauch abrufen ## Nutzung -### Variante 1 — Direkt-Import in Postman +### Variante 1 — Direkt-Import -1. Postman öffnen → **Import** → diese beiden Files auswählen -2. Im Environment `hightrusted-capture` den Wert `api_key` setzen +1. Postman → **Import** → beide JSON-Dateien auswählen +2. Im Environment `hightrusted CAPTURE — Production` den Wert `api_key` setzen (Dashboard: https://capture.hightrusted.net/dashboard/api-keys) 3. Environment auswählen → Requests senden -### Variante 2 — Öffentlicher Workspace +### Variante 2 — Newman CI -Direkter Fork aus dem öffentlichen Postman-Workspace: -https://www.postman.com/hightrusted/workspace/capture-api - -## Authentifizierung - -Bearer-Token. In der Collection bereits voreingestellt — du musst nur die -Variable `{{api_key}}` im Environment befüllen. +```bash +npm install -g newman +newman run hightrusted-capture.postman_collection.json \ + -e hightrusted-capture.postman_environment.json \ + --env-var "api_key=$HIGHTRUSTED_API_KEY" +``` ## Tests in der Collection -Jede Request hat einfache Response-Tests: - +Jede Request hat Response-Tests: - HTTP-Status korrekt -- `request_id`-Header gesetzt -- Bei `POST /captures` (sync): `id`, `status`, `verify_url` vorhanden -- Bei `GET /captures/{id}/verify`: `valid` ist Boolean +- Schema-Felder vorhanden (`id`, `status`, `verify_url`, etc.) +- Beim Capture-Erstellen wird die `id` als Collection-Variable `last_capture_id` + gesetzt — die nachfolgenden Requests (Status, PDF, Verify) nutzen sie automatisch. -Damit kannst du die Collection auch im Newman-CI nutzen: - -```bash -newman run hightrusted-capture.postman_collection.json \ - -e hightrusted-capture.postman_environment.json -``` +So kannst du mit drei Klicks einen kompletten Lifecycle durchlaufen: +**Capture erstellen → Status prüfen → PDF herunterladen → Verifizieren**. ## Versionierung -Diese Collection folgt der API-Version (`/api/v1/...`). Breaking Changes der API -führen zu einer neuen Major-Version der Collection. Non-Breaking Changes -(neue Endpoints, neue Felder) werden ohne Versionssprung eingepflegt. +Diese Collection folgt der API-Version (`/api/v1/...`). Sie wird mit jedem +API-Release aktualisiert. Breaking Changes der API führen zu einer neuen +Major-Version der Collection. ## 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) +- [`openapi`](https://git.hightrusted.net/hightrusted-capture/openapi) — OpenAPI 3.1 Spec - [`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 +- [`python`](https://git.hightrusted.net/hightrusted-capture/python) / [`node`](https://git.hightrusted.net/hightrusted-capture/node) / [`php`](https://git.hightrusted.net/hightrusted-capture/php) — SDKs ## 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 @@ -92,4 +81,3 @@ 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 index 9ed887a..63ed5b2 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -25,9 +25,3 @@ 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`. diff --git a/hightrusted-capture.postman_collection.json b/hightrusted-capture.postman_collection.json new file mode 100644 index 0000000..cdd1c3c --- /dev/null +++ b/hightrusted-capture.postman_collection.json @@ -0,0 +1,265 @@ +{ + "info": { + "name": "hightrusted CAPTURE API", + "description": "Forensische Web-Captures mit qualifiziertem Zeitstempel nach RFC 3161 / eIDAS Art. 41.\n\n**Authentifizierung:** Bearer-Token. Setze die Variable `api_key` im Environment.\n\n**API-Key holen:** https://capture.hightrusted.net/dashboard/api-keys\n\n**Doku:** https://capture.hightrusted.net/api/docs", + "version": "1.0.0", + "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" + }, + "auth": { + "type": "bearer", + "bearer": [ + { "key": "token", "value": "{{api_key}}", "type": "string" } + ] + }, + "variable": [ + { + "key": "base_url", + "value": "https://capture.hightrusted.net/api/v1", + "type": "string" + } + ], + "item": [ + { + "name": "Captures", + "item": [ + { + "name": "Capture erstellen — synchron", + "event": [ + { + "listen": "test", + "script": { + "type": "text/javascript", + "exec": [ + "pm.test('Status 200', () => pm.response.to.have.status(200));", + "const json = pm.response.json();", + "pm.test('Hat id und status', () => {", + " pm.expect(json.id).to.be.a('string');", + " pm.expect(json.status).to.equal('ready');", + "});", + "pm.test('Hat verify_url', () => {", + " pm.expect(json.verify_url).to.match(/^https:\\/\\/verify\\.hightrusted\\.net/);", + "});", + "pm.collectionVariables.set('last_capture_id', json.id);" + ] + } + } + ], + "request": { + "method": "POST", + "header": [ + { "key": "Content-Type", "value": "application/json" } + ], + "body": { + "mode": "raw", + "raw": "{\n \"url\": \"https://example.com\"\n}" + }, + "url": { + "raw": "{{base_url}}/captures", + "host": ["{{base_url}}"], + "path": ["captures"] + }, + "description": "Erstellt eine Capture und wartet bis zu 30 s auf das fertige PDF." + } + }, + { + "name": "Capture erstellen — asynchron", + "event": [ + { + "listen": "test", + "script": { + "type": "text/javascript", + "exec": [ + "pm.test('Status 202', () => pm.response.to.have.status(202));", + "const json = pm.response.json();", + "pm.test('Status ist queued', () => pm.expect(json.status).to.equal('queued'));", + "pm.collectionVariables.set('async_capture_id', json.id);" + ] + } + } + ], + "request": { + "method": "POST", + "header": [{ "key": "Content-Type", "value": "application/json" }], + "body": { + "mode": "raw", + "raw": "{\n \"url\": \"https://example.com\",\n \"mode\": \"async\",\n \"reference\": \"case-2026-001\"\n}" + }, + "url": { + "raw": "{{base_url}}/captures", + "host": ["{{base_url}}"], + "path": ["captures"] + } + } + }, + { + "name": "Capture erstellen — webhook", + "request": { + "method": "POST", + "header": [{ "key": "Content-Type", "value": "application/json" }], + "body": { + "mode": "raw", + "raw": "{\n \"url\": \"https://example.com\",\n \"mode\": \"webhook\",\n \"webhook_url\": \"https://your-domain.tld/webhooks/capture\",\n \"reference\": \"case-2026-001\",\n \"viewport\": { \"width\": 1920, \"height\": 1080 }\n}" + }, + "url": { + "raw": "{{base_url}}/captures", + "host": ["{{base_url}}"], + "path": ["captures"] + }, + "description": "Capture starten, Server liefert das fertige Ergebnis per HTTP-POST aus." + } + }, + { + "name": "Capture-Status abrufen", + "event": [ + { + "listen": "test", + "script": { + "type": "text/javascript", + "exec": [ + "pm.test('Status 200', () => pm.response.to.have.status(200));", + "const json = pm.response.json();", + "pm.test('Hat id', () => pm.expect(json.id).to.be.a('string'));" + ] + } + } + ], + "request": { + "method": "GET", + "url": { + "raw": "{{base_url}}/captures/{{last_capture_id}}", + "host": ["{{base_url}}"], + "path": ["captures", "{{last_capture_id}}"] + } + } + }, + { + "name": "Captures auflisten", + "request": { + "method": "GET", + "url": { + "raw": "{{base_url}}/captures?limit=25&status=ready", + "host": ["{{base_url}}"], + "path": ["captures"], + "query": [ + { "key": "limit", "value": "25" }, + { "key": "status", "value": "ready" } + ] + } + } + }, + { + "name": "PDF herunterladen", + "request": { + "method": "GET", + "url": { + "raw": "{{base_url}}/captures/{{last_capture_id}}/pdf", + "host": ["{{base_url}}"], + "path": ["captures", "{{last_capture_id}}", "pdf"] + }, + "description": "Liefert PDF/A-3 mit eingebettetem RFC-3161-Zeitstempel.\n\nIn Postman: \"Send and Download\" verwenden, um das PDF zu speichern." + } + } + ] + }, + { + "name": "Verify", + "item": [ + { + "name": "Verifikation per Capture-ID", + "event": [ + { + "listen": "test", + "script": { + "type": "text/javascript", + "exec": [ + "pm.test('Status 200', () => pm.response.to.have.status(200));", + "const json = pm.response.json();", + "pm.test('valid ist Boolean', () => pm.expect(json.valid).to.be.a('boolean'));", + "pm.test('Hat audit_log', () => pm.expect(json.audit_log).to.be.an('object'));" + ] + } + } + ], + "request": { + "method": "POST", + "header": [{ "key": "Content-Type", "value": "application/json" }], + "body": { + "mode": "raw", + "raw": "{\n \"source\": \"{{last_capture_id}}\"\n}" + }, + "url": { + "raw": "{{base_url}}/verify", + "host": ["{{base_url}}"], + "path": ["verify"] + }, + "description": "Verifikation ist KOSTENLOS — keine Quota-Belastung." + } + }, + { + "name": "Verifikation per Verify-URL", + "request": { + "method": "POST", + "header": [{ "key": "Content-Type", "value": "application/json" }], + "body": { + "mode": "raw", + "raw": "{\n \"source\": \"https://verify.hightrusted.net/c/REPLACE_ME\"\n}" + }, + "url": { + "raw": "{{base_url}}/verify", + "host": ["{{base_url}}"], + "path": ["verify"] + } + } + }, + { + "name": "Verifikation per PDF-Upload", + "request": { + "method": "POST", + "body": { + "mode": "formdata", + "formdata": [ + { "key": "pdf", "type": "file", "src": [] } + ] + }, + "url": { + "raw": "{{base_url}}/verify", + "host": ["{{base_url}}"], + "path": ["verify"] + }, + "description": "Lädt eine lokale PDF hoch und verifiziert sie. Funktioniert auch ohne API-Key (Verify ist öffentlich)." + } + } + ] + }, + { + "name": "Account", + "item": [ + { + "name": "Eigenen Verbrauch abrufen", + "event": [ + { + "listen": "test", + "script": { + "type": "text/javascript", + "exec": [ + "pm.test('Status 200', () => pm.response.to.have.status(200));", + "const json = pm.response.json();", + "pm.test('Hat plan', () => pm.expect(json.plan).to.be.a('string'));", + "pm.test('Hat used_calls', () => pm.expect(json.used_calls).to.be.a('number'));" + ] + } + } + ], + "request": { + "method": "GET", + "url": { + "raw": "{{base_url}}/usage", + "host": ["{{base_url}}"], + "path": ["usage"] + } + } + } + ] + } + ] +} diff --git a/hightrusted-capture.postman_environment.json b/hightrusted-capture.postman_environment.json new file mode 100644 index 0000000..383eae4 --- /dev/null +++ b/hightrusted-capture.postman_environment.json @@ -0,0 +1,19 @@ +{ + "id": "hightrusted-capture-prod", + "name": "hightrusted CAPTURE — Production", + "values": [ + { + "key": "api_key", + "value": "ht_live_REPLACE_ME", + "type": "secret", + "enabled": true + }, + { + "key": "base_url", + "value": "https://capture.hightrusted.net/api/v1", + "type": "default", + "enabled": true + } + ], + "_postman_variable_scope": "environment" +}