k0nsult.cloud / ai-truth / ipIII / api-produkcyjne

API — rekomendacje produkcyjne

Docelowa architektura bezpieczeństwa warstwy API portalu ipIII, sformułowana jako odpowiedź na zalecenie audytowe §4.4. To plan wzmocnienia, nie opis stanu bieżącego. Cała warstwa opisana niżej ma status ROADMAP — nie jest jeszcze wdrożona na produkcji.

← ipIII hub Evidence-first Model danych API (stan obecny) API produkcyjne Role i priorytety

Specyfikacja referencyjna. Nie stanowi certyfikacji ani opinii prawnej; implementacja produkcyjna ma status ROADMAP. Dokument opisuje stan docelowy warstwy API, do którego zmierza portal — nie potwierdza, że mechanizmy (żywe OIDC, mTLS, RBAC w bazie) działają dziś na produkcji. Punkty oznaczone GAP nie są zaimplementowane.

Claim ≤ Proof. Nie deklarujemy zabezpieczenia, którego nie ma.

Obecne API chroni prosty nagłówek współdzielonego sekretu x-konsult-secret. To wystarcza dla środowiska referencyjnego / demo, ale jest niewystarczające do produkcji obsługującej realne dane incydentów bankowych. Poniżej — mapa obszar → zalecenie, zgodna z zaleceniem §4.4.

STAN: x-konsult-secret DEPRECATED do prod→OIDC + mTLS + RBAC/ABAC ROADMAP→audytowalne API produkcyjne

Stan bieżący vs. docelowy

Dziś stan obecny

Jeden współdzielony sekret x-konsult-secret w nagłówku HTTP. Brak tożsamości użytkownika, brak ról, brak rotacji, brak śladu „kto".

GAP względem wymagań produkcyjnych podmiotu kluczowego (NIS2/KSC).

Cel ROADMAP

Federacyjna tożsamość (OIDC), wzajemne uwierzytelnienie usług (mTLS), autoryzacja RBAC+ABAC, pełny audyt każdej mutacji, podpisy webhooków, HITL dla akcji wrażliwych.

ROADMAP — wdrożenie po ACK i decyzji o środowisku produkcyjnym.

Mapa obszar → zalecenie (§4.4)

Każdy wiersz to zalecenie docelowe. Kolumna „Status" jest jawna: nic z poniższych nie działa dziś na produkcji.

Obszar	Zalecenie produkcyjne	Uzasadnienie / uwaga	Status
Uwierzytelnianie (Auth)	OIDC / OAuth2 przez centralny IdP (np. Keycloak). Tokeny JWT o krótkim TTL, refresh z rotacją.	Tożsamość użytkownika zamiast współdzielonego sekretu. Wsparcie MFA po stronie IdP.	ROADMAP
Service-to-service	mTLS między usługami + rotowane tokeny usługowe (short-lived, wystawiane przez IdP / secret manager).	Uwierzytelnienie dwustronne. Brak stałych sekretów w kodzie/env.	ROADMAP
Klucze API	Klucz per integracja (nie globalny), z jawnym `scope` i `expiry`. Odwoływalne, wersjonowane.	Ograniczenie promienia rażenia przy wycieku. Możliwość unieważnienia jednej integracji.	ROADMAP
Autoryzacja	RBAC + ABAC: role (analityk, SOC, compliance, admin) + atrybuty (tenant, sektor, klasa danych, poziom incydentu).	Zasada najmniejszych uprawnień. Dostęp warunkowany kontekstem, nie tylko rolą.	ROADMAP
Audyt	Każda mutacja zapisana z: `user`, `session`, `IP`, `request_id`, timestamp, diff przed/po. Log niemodyfikowalny (append-only).	Ślad audytowy dla KNF / CSIRT. Fundament evidence-first na poziomie infrastruktury.	ROADMAP
Rate limiting	Limit per token / per tenant (nie tylko per IP). Progi P0-krytyczne wyłączone spod agresywnego throttlingu.	Ochrona przed nadużyciem i wyczerpaniem zasobów; izolacja najemców.	ROADMAP
Podpisywanie webhooków	HMAC (np. SHA-256) na payloadzie + timestamp + ochrona przed replay. Sekret per odbiorca.	Odbiorca weryfikuje autentyczność i integralność zdarzenia wychodzącego.	ROADMAP
Akcje wrażliwe	HITL (human-in-the-loop) + step-up auth (ponowne, silniejsze uwierzytelnienie) dla zamknięć P0/P1, eskalacji prawnych, eksportu do organu.	Nieodwracalne / regulacyjne akcje wymagają świadomej decyzji człowieka.	ROADMAP
Eksport raportów	Watermark (znak wodny: odbiorca, czas, request_id) + zdarzenie audytowe na każdy eksport.	Śledzenie wycieku dokumentu i pełen zapis „kto wyeksportował co i kiedy".	ROADMAP
Dostęp do dowodów	Signed URL z krótkim TTL, związany z rolą (role-bound). Brak trwałych, publicznych linków do materiału dowodowego.	Chain of custody: dostęp czasowy, kontekstowy, rozliczalny.	ROADMAP

DEPRECATED do produkcji: `x-konsult-secret`

Jasne stanowisko. Nagłówek x-konsult-secret jest współdzielonym sekretem statycznym. W środowisku referencyjnym / demo pełni rolę prostej bramki. Do produkcji obsługującej realne dane incydentów jest uznany za DEPRECATED i musi zostać zastąpiony warstwą OIDC/mTLS/RBAC opisaną powyżej. Nie należy go traktować jako zabezpieczenia klasy produkcyjnej.

Brak tożsamości — sekret nie mówi „kto"; niemożliwy audyt na poziomie użytkownika.
Brak rotacji i zakresu — jeden sekret dla wszystkiego; wyciek = pełny dostęp.
Brak least-privilege — nie da się ograniczyć do roli/tenanta/klasy danych.
Brak step-up / HITL — akcje wrażliwe nieodróżnialne od zwykłych.

Docelowy przepływ żądania ROADMAP

1 · Tożsamość. Klient uzyskuje token OIDC/OAuth2 z IdP (Keycloak). Usługa-usługa: mTLS + rotowany token usługowy.

2 · Brama API. Walidacja tokenu (podpis, TTL, audience), rate-limit per token/tenant, nadanie request_id.

3 · Autoryzacja. RBAC (rola) + ABAC (tenant, sektor, klasa danych, poziom incydentu). Odmowa domyślna.

4 · Akcja wrażliwa? Jeśli tak — HITL + step-up auth przed wykonaniem (zamknięcie P0/P1, eksport do organu, eskalacja prawna).

5 · Mutacja + audyt. Zapis zmiany z user/session/IP/request_id + diff do logu append-only.

6 · Zdarzenia wychodzące. Webhooki podpisane HMAC; eksporty z watermarkiem; dostęp do dowodów przez signed URL o krótkim TTL.

Kontrakt maszynowy

Pełna, maszynowo czytelna definicja endpointów, schematów i wymagań bezpieczeństwa jest publikowana jako kontrakt OpenAPI:

OpenAPI 3.x DANE

Kontrakt maszynowy warstwy API portalu ipIII.

/ai-truth/ipIII/openapi.json

Schematy securitySchemes (OIDC, mTLS, apiKey) w kontrakcie opisują stan docelowy. Zgodność implementacji z kontraktem = ROADMAP.

Uczciwie o statusie. Ta strona to plan docelowy, nie stan obecny. Żaden z mechanizmów (OIDC, mTLS, RBAC/ABAC, audyt mutacji, HMAC, HITL, signed URL) nie jest deklarowany jako działający na produkcji. Wdrożenie wymaga decyzji o środowisku produkcyjnym, ACK oraz osobnej weryfikacji. Do tego czasu portal pozostaje referencją / dokumentacją, a bramką jest x-konsult-secret (tylko demo).

Zasada nadrzędna. Warstwa API dziedziczy walutę zaufania portalu: dowód. Deklaracja zabezpieczenia bez działającej implementacji to hipoteza (status GAP / ROADMAP), nie fakt. Nie udajemy produkcji tam, gdzie mamy referencję.