first

README.md

@@ -1,8 +1,90 @@
 # csob
 
-.NET API služba vytvořená přes CSBot Services Portal.
+Multi-tenant REST integrace na **ČSOB PSD2 (Open Banking) API** podle Czech Open Banking Standard (COBS).
+.NET 8 služba běžící v AppFactory za reverse proxy `/apps/csob`.
+
+Pokrývá **AISP** (informace o účtech), **PISP** (iniciace plateb, trvalých příkazů a inkas vč. sign/SCA flow),
+**consents** a **OAuth2** helper (Authorization Code flow).
+
+## Architektura
+
+Služba je **bezstavový proxy** – neukládá žádné credentials. Volající klientská služba předává veškeré
+citlivé údaje (eIDAS certifikát, OAuth client id/secret, access token, APIKEY, TPP name) **per-request
+v HTTP hlavičkách** (jen přes TLS). mTLS se na základě certifikátu z hlavičky staví per-request a klienti
+se cachují podle thumbprintu certifikátu. Nic se neloguje ani neukládá na disk.
+
+Strukturně zrcadlí sesterskou službu `idoklad` (Configuration → env, Credentials → hlavičky, Client factory
++ Accessor, Services, Controllers, Infrastructure middleware + Swagger operation filter, `/docs`).
 
 ## Endpointy
 
-- GET /
-- GET /health
+Veřejně dostupné přes `https://services.csbot.cz/apps/csob/...`.
+
+### Meta (bez credentials)
+- `GET /health` – liveness
+- `GET /version` – název/verze + API info
+- `GET /status` – ne-secret konfigurace (base/oauth URL, timeout)
+- `GET /docs` – Swagger UI
+- `GET /docs/v1/swagger.json` – OpenAPI dokument
+
+### OAuth2
+- `GET /oauth/authorization-url` – sestaví authorize URL pro přesměrování PSU
+- `POST /oauth/token` – výměna `code` → access/refresh token (mTLS)
+- `POST /oauth/refresh` – obnova access tokenu (mTLS)
+
+### AISP – účty
+- `GET /accounts`
+- `GET /accounts/{id}/balance`
+- `GET /accounts/{id}/transactions`
+- `GET /accounts/{id}/transactions/awaiting`
+- `GET /accounts/{id}/standing-orders`
+- `GET /accounts/{id}/standing-orders/{standingOrderId}`
+- `GET /accounts/{id}/direct-debits`
+
+### PISP – platby / trvalé příkazy / inkasa
+Pro každou agendu: `POST` (iniciace), `GET /{id}` (detail), `GET /{id}/status`, `DELETE /{id}` (zrušení),
+a sign/SCA flow `POST|GET|PUT /{id}/sign/{signId}`.
+- `/payments`
+- `/standing-orders`
+- `/direct-debits`
+
+### Consents
+- `POST /consents`, `GET /consents/{id}`, `DELETE /consents/{id}`
+
+## Credential hlavičky (per-request, jen přes TLS)
+
+| Hlavička | Význam | Předáno do ČSOB jako |
+|---|---|---|
+| `X-CSOB-Certificate` | eIDAS klientský certifikát (QWAC), **Base64 PFX/PKCS#12** vč. privátního klíče a chainu | mutual TLS |
+| `X-CSOB-Certificate-Password` | heslo k PFX (volitelné) | – |
+| `X-Access-Token` | OAuth2 Bearer access token PSU (AISP/PISP/consents) | `Authorization: Bearer` |
+| `X-API-Key` | ČSOB application API key | `APIKEY` |
+| `X-TPP-Name` | název TPP organizace | `TPP-Name` |
+| `X-CSOB-Client-Id` / `X-CSOB-Client-Secret` | OAuth2 app credentials (jen `/oauth/*`) | OAuth form |
+| `X-User-Involved`, `X-User-IP-Address` | volitelný PSU kontext | `User-Involved`, `User-IP-Address` |
+
+Hlavičky `X-Request-ID` a `Date` generuje služba automaticky.
+
+## Konfigurace (environment variables – pouze ne-secret)
+
+| Proměnná | Default |
+|---|---|
+| `APP_NAME` | `ČSOB PSD2 Service` |
+| `APP_VERSION` | `1.0.0` |
+| `ROOT_PATH` | (prázdné; AppFactory nastaví `/apps/csob`) |
+| `CSOB_API_BASE_URL` | `https://api.csob.cz/api/csob/psd2/v1` |
+| `CSOB_OAUTH_AUTHORIZE_URL` | `https://identita.csob.cz/mep/fs/fl/oauth2/auth` |
+| `CSOB_OAUTH_TOKEN_URL` | `https://api.csob.cz/api/csob/oauth2/v1/token` |
+| `CSOB_REQUEST_TIMEOUT_SECONDS` | `100` |
+
+> **Žádné secrets v env.** Certifikát, client id/secret, access token a APIKEY jdou výhradně per-request hlavičkami.
+
+## Lokální spuštění
+
+```bash
+dotnet run --project Csob.csproj
+# nebo
+ROOT_PATH=/apps/csob ASPNETCORE_URLS=http://0.0.0.0:8080 dotnet run
+```
+
+Podrobnosti k OAuth/SCA flow a kompletní seznam endpointů viz [documentation/](documentation/).