agnes-the-ai-analyst/dev_docs/draft/services-integration-codex.md

# Pilot: PO Integrace pro Interního Analysta (bez lokálního ukládání klíčů)

## Shrnutí
Cíl je dodat produkční pilot pro **Purchase Order System** s tímto chováním:
1. Uživatel v dashboardu udělá jen `Connect` (1 klik + Google consent).
2. Server bezpečně uloží per-user credential (šifrovaně, ne v lokálním počítači).
3. Na klientovi se token načte **on-demand přes SSH** pouze pro jeden příkaz (ENV jen v child procesu).
4. Do `.claude/rules` se synchronizuje znalost, že PO operace mají používat PO wrapper/skill.
5. Dodáme zároveň **full skill beta** (vedle produkční varianty rules+wrapper).

## Scope a hranice
- In-scope:
  - Obecný service registry model (rozšiřitelný), implementace provideru jen pro `po`.
  - Connect/Disconnect/Test flow v dashboard katalogu.
  - Server-side per-user encrypted credential store.
  - Runtime wrapper přes SSH s krátkodobým tokenem.
  - Audit + revoke + 30denní rotace.
  - Sync rules + skill beta distribuce.
- Out-of-scope:
  - CRM/Revolut implementace (jen připravený framework).
  - Plná proxy architektura pro API calls (volání půjde přímo klient -> PO API).
  - Migrace na externí secret manager v pilotu.

## Návrh řešení (decision-complete)

### 1) Service registry a datový model
- Přidat nový server-side registry JSON: `/data/integrations/registry.json`.
- Schema položky služby:
  - `service_id` (`po`)
  - `display_name`
  - `connect_type` (`oauth_bootstrap_link`)
  - `scopes`
  - `api_base_url`
  - `enabled`
  - `skill_slug` (`po-system`)
  - `rule_template_id`
- Per-user credential metadata:
  - `/data/integrations/state/<service>/<username>.json`
  - Obsah: `status`, `connected_at`, `last_rotated_at`, `expires_at`, `token_ref`, `audit_last_use_at`
- Per-user encrypted secret:
  - `/data/integrations/secrets/<service>/<username>.enc`
  - Šifrování AES-GCM, key z `/etc/internal-analyst/integrations.key` (root:root, 600).

### 2) Dashboard UX (katalog zdrojů)
- Do `webapp/templates/catalog.html` přidat novou kartu “Purchase Order System”.
- Akce:
  - `Connect` -> redirect na bootstrap URL PO.
  - `Disconnect` -> revoke + smazání secretu.
  - `Test connection` -> ověření issuance short-lived tokenu.
- UI stav:
  - `Not connected`, `Connected`, `Error`, `Reauthorization required`.

### 3) Webapp API rozhraní
- Přidat nové endpointy (Flask):
  - `GET /api/integrations/catalog`
  - `POST /api/integrations/<service>/connect`
  - `GET /api/integrations/<service>/callback`
  - `POST /api/integrations/<service>/disconnect`
  - `POST /api/integrations/<service>/test`
- Interní service layer:
  - nový `webapp/integration_service.py`
  - provider interface:
    - `build_connect_url(user, state)`
    - `exchange_callback(code, state)`
    - `rotate(user)`
    - `issue_runtime_token(user, ttl_seconds)`
    - `revoke(user)`
- `po` provider implementace jako první konkrétní provider.

### 4) PO bootstrap link + token lifecycle
- Connect flow:
  1. Uživatel klikne Connect v dashboardu.
  2. Redirect na PO auth/bootstrap endpoint (Google auth + consent).
  3. Callback zpět na webapp.
  4. Webapp uloží refresh credential šifrovaně.
- Rotace:
  - server job (cron/systemd) denně kontroluje `last_rotated_at`.
  - rotuje každých 30 dní.
- Revoke:
  - Disconnect okamžitě revokuje token v PO a maže server secret.

### 5) Runtime token injection přes SSH (bez lokální persistence)
- Přidat server helper:
  - `/usr/local/bin/integration-runtime-env`
  - Vstup: `--service po --ttl 300 --format env`
  - Výstup: shell-safe `export` lines pro child proces.
- Přístup:
  - přes sudoers povolit pouze self-service issuance (uživatel jen pro svůj účet).
  - helper tvrdě validuje volajícího uživatele a service allowlist.
- Lokální wrapper skript v syncovaných skriptech:
  - `server/scripts/po-run`
  - Spuštění:
    - `ssh data-analyst "/usr/local/bin/integration-runtime-env --service po --ttl 300 --format env"`
    - spustí cílový příkaz v subshell s ENV
    - po skončení ENV zahodí (bez zápisu do souboru)
- Přímá API volání:
  - klientský skript/skill volá PO API přímo s runtime ENV tokenem.

### 6) Rules + skill beta distribuce
- Produkčně:
  - generovat service rule soubor na serveru: `/home/<user>/.claude_rules/svc_po.md`
  - `scripts/sync_data.sh` už pravidla stahuje do `.claude/rules/`; upravit jen reporting, aby počítal i `svc_*.md`.
- Skill beta:
  - přidat sync složku `server/skills/po-system/` (SKILL.md + scripts + references).
  - přidat skript `server/scripts/install_skills.sh`:
    - instaluje do uživatelova Codex skill home.
  - `sync_data.sh` po syncu volá `install_skills.sh` (best-effort, neblokuje datový sync).

### 7) Audit, observability, bezpečnost
- Audit log soubor:
  - `/data/integrations/audit.log` (append-only)
  - eventy: `connect`, `callback_ok`, `runtime_issue`, `rotate`, `revoke`, `error`
- Bezpečnostní guardrails:
  - token nikdy nelogovat
  - helper vrací jen krátkodobý access token
  - TTL runtime tokenu default 5 min
  - strict input validation service/usernames
- Monitoring:
  - dashboard health check pro integrations service
  - metriky: connect success rate, runtime issuance latency, rotate failures.

## Důležité změny veřejných API/rozhraní/typů
- Nové REST endpointy pod `/api/integrations/*`.
- Nový datový kontrakt `registry.json` pro katalog služeb.
- Nový provider interface v `webapp/integration_service.py`.
- Nový CLI kontrakt helperu `integration-runtime-env`.
- Nový lokální wrapper command `po-run`.

## Testy a validační scénáře

### Unit testy
- `webapp/integration_service.py`:
  - validace state/nonce
  - encrypt/decrypt secretu
  - rotace pravidla 30 dní
- provider `po`:
  - connect URL tvorba
  - callback exchange error handling
- helper `integration-runtime-env`:
  - self-user enforcement
  - invalid service rejection
  - TTL bounds

### Integration testy
- E2E Connect flow:
  - dashboard -> PO consent -> callback -> connected status.
- E2E runtime:
  - `po-run "curl ..."` získá token přes SSH a provede volání.
- E2E Disconnect:
  - revoke v PO + odstranění state/secrets + UI přepnutí na not connected.
- E2E rotation:
  - forced rotation scenario + audit log verification.

### Security testy
- Pokus o issuance tokenu pro jiného uživatele (musí failnout).
- Pokus o command injection přes service parameter (musí failnout).
- Ověření, že token není v logu ani na disku klienta po dokončení příkazu.

### Acceptance kritéria
- Uživatel připojí PO službu 1 klikem + consent.
- Žádný persistentní API klíč na klientově disku.
- `po-run` funguje bez ručního exportu tokenu.
- Disconnect do 1 min deaktivuje další runtime issuance.
- Rotace probíhá automaticky po 30 dnech.

## Rollout plán
1. Backend + helper + audit nasadit behind feature flag `INTEGRATIONS_PO_ENABLED=false`.
2. Zapnout interně pro 1–2 test uživatele.
3. Ověřit E2E + security checklist.
4. Zapnout pro všechny analytiky.
5. Po stabilizaci přidat další provider (CRM) přes stejný interface.

## Assumptions a zvolené defaulty
- PO systém je plně pod kontrolou týmu a lze doplnit endpointy pro issuance/rotate/revoke.
- Identita uživatele je mapovatelná mezi dashboardem a server účtem.
- Runtime přenos credentialů má být pouze přes SSH mechanismus (ne lokální secret file).
- Default runtime token TTL: 300 sekund.
- Default rotace: 30 dní.
- Pilot storage není `.env`; používá per-user encrypted store.
- Produkční path v pilotu je rules+wrapper, full skill je beta paralelně.