David/veylant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

First commit

Browse Source
This commit is contained in:
David 2026-02-23 13:35:04 +01:00
commit 6b1ba49922
260 changed files with 37316 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

265
.github/workflows/ci.yml vendored Normal file
View File

@ -0,0 +1,265 @@
name: CI
on:
push:
branches: [main, develop]
pull_request:
branches: [main]
concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true
jobs:
# ─────────────────────────────────────────────
# Go: build, lint, test
# ─────────────────────────────────────────────
go:
name: Go
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: "1.24"
cache: true
- name: Build
run: go build ./cmd/proxy/
- name: Vet
run: go vet ./...
- name: Lint
uses: golangci/golangci-lint-action@v6
with:
version: latest
args: --timeout=5m
- name: Test
run: go test -race -coverprofile=coverage.out ./...
- name: Check coverage threshold (>= 80% on internal packages)
run: |
go test -race -coverprofile=coverage_internal.out -coverpkg=./internal/... ./internal/...
COVERAGE=$(go tool cover -func=coverage_internal.out | grep total | awk '{print $3}' | tr -d '%')
echo "Internal package coverage: ${COVERAGE}%"
awk -v cov="$COVERAGE" 'BEGIN { if (cov+0 < 80) { print "Coverage " cov "% is below 80% threshold"; exit 1 } }'
- name: Upload coverage
uses: actions/upload-artifact@v4
if: always()
with:
name: go-coverage
path: coverage.out
# ─────────────────────────────────────────────
# Python: format check, lint, test
# ─────────────────────────────────────────────
python:
name: Python
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
cache: pip
cache-dependency-path: services/pii/requirements.txt
- name: Install dependencies
run: pip install -r services/pii/requirements.txt
- name: Format check (black)
run: black --check services/pii/
- name: Lint (ruff)
run: ruff check services/pii/
- name: Test with coverage
run: |
pytest services/pii/ -v --tb=short \
--cov=services/pii \
--cov-report=term-missing \
--ignore=services/pii/tests/test_ner.py \
--cov-fail-under=75
# NER tests excluded in CI: fr_core_news_lg (~600MB) is not downloaded in the CI Python job.
# The model is downloaded during Docker build (see Dockerfile) and tested in the security job.
# ─────────────────────────────────────────────
# Security: secret scanning + container vulnerability scan
# ─────────────────────────────────────────────
security:
name: Security
runs-on: ubuntu-latest
permissions:
contents: read
security-events: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # Full history required by gitleaks
- name: gitleaks — secret scanning
uses: gitleaks/gitleaks-action@v2
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Semgrep — SAST (E10-04 + E11-11 custom rules)
uses: returntocorp/semgrep-action@v1
with:
config: >-
p/golang
p/python
p/react
p/secrets
.semgrep.yml
env:
SEMGREP_APP_TOKEN: ${{ secrets.SEMGREP_APP_TOKEN }}
# Non-blocking when SEMGREP_APP_TOKEN is not configured (e.g., forks).
continue-on-error: ${{ secrets.SEMGREP_APP_TOKEN == '' }}
- name: Build Docker image
run: |
docker build \
--cache-from type=registry,ref=ghcr.io/${{ github.repository }}/proxy:cache \
-t proxy:${{ github.sha }} \
.
- name: Trivy — container vulnerability scan
uses: aquasecurity/trivy-action@master
with:
image-ref: proxy:${{ github.sha }}
format: sarif
output: trivy-results.sarif
exit-code: "1"
severity: CRITICAL,HIGH
ignore-unfixed: true
- name: Upload Trivy results to GitHub Security
uses: github/codeql-action/upload-sarif@v3
if: always()
with:
sarif_file: trivy-results.sarif
# ─────────────────────────────────────────────
# OWASP ZAP DAST — only on push to main (E10-06)
# Starts the proxy in dev mode and runs a ZAP baseline scan.
# Results are uploaded as a CI artifact (non-blocking).
# ─────────────────────────────────────────────
zap-dast:
name: OWASP ZAP DAST
runs-on: ubuntu-latest
needs: [go, python, security]
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: "1.24"
cache: true
- name: Start proxy (dev mode)
run: |
VEYLANT_SERVER_ENV=development \
VEYLANT_SERVER_PORT=8090 \
go run ./cmd/proxy/ &
env:
VEYLANT_SERVER_ENV: development
VEYLANT_SERVER_PORT: "8090"
- name: Wait for proxy to start
run: |
for i in $(seq 1 15); do
curl -sf http://localhost:8090/healthz && exit 0
sleep 1
done
echo "Proxy did not start in time" && exit 1
- name: ZAP Baseline Scan
uses: zaproxy/action-baseline@v0.12.0
with:
target: 'http://localhost:8090'
fail_action: false
artifact_name: zap-baseline-report
# ─────────────────────────────────────────────
# k6 smoke test — run on every push to main
# Validates proxy is up and responsive before any deploy.
# ─────────────────────────────────────────────
load-test:
name: k6 Smoke Test
runs-on: ubuntu-latest
needs: [go]
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: "1.24"
cache: true
- name: Install k6
run: |
curl -fsSL https://dl.k6.io/key.gpg | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/k6.gpg
echo "deb https://dl.k6.io/deb stable main" | sudo tee /etc/apt/sources.list.d/k6.list
sudo apt-get update && sudo apt-get install -y k6
- name: Start proxy (dev mode)
run: go run ./cmd/proxy/ &
env:
VEYLANT_SERVER_ENV: development
VEYLANT_SERVER_PORT: "8090"
- name: Wait for proxy
run: |
for i in $(seq 1 20); do
curl -sf http://localhost:8090/healthz && break
sleep 1
done
- name: k6 smoke scenario
run: |
k6 run \
--env VEYLANT_URL=http://localhost:8090 \
--env VEYLANT_TOKEN=dev-token \
--env SCENARIO=smoke \
test/k6/k6-load-test.js
# ─────────────────────────────────────────────
# Deploy to staging — only on push to main
# Uses blue/green deployment for zero-downtime and instant rollback (< 30s).
# Manual rollback: make deploy-rollback NAMESPACE=veylant ACTIVE_SLOT=blue
# ─────────────────────────────────────────────
deploy-staging:
name: Deploy (staging — blue/green)
runs-on: ubuntu-latest
needs: [go, python, security, load-test]
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
environment: staging
steps:
- uses: actions/checkout@v4
- name: Set up Helm
uses: azure/setup-helm@v4
with:
version: v3.16.0
- name: Configure kubectl
run: |
mkdir -p ~/.kube
echo "${{ secrets.KUBECONFIG }}" > ~/.kube/config
chmod 600 ~/.kube/config
- name: Blue/green deploy
run: |
chmod +x deploy/scripts/blue-green.sh
./deploy/scripts/blue-green.sh
env:
IMAGE_TAG: ${{ github.sha }}
NAMESPACE: veylant
VEYLANT_URL: ${{ secrets.STAGING_VEYLANT_URL }}

148
.github/workflows/release.yml vendored Normal file
View File

@ -0,0 +1,148 @@
name: Release
on:
push:
tags:
- "v*"
permissions:
contents: write # Create GitHub Release
packages: write # Push to ghcr.io
id-token: write # OIDC for provenance attestation
jobs:
# ─────────────────────────────────────────────
# Build & push Docker image to GHCR
# ─────────────────────────────────────────────
docker:
name: Build & Push Docker Image
runs-on: ubuntu-latest
outputs:
image-digest: ${{ steps.push.outputs.digest }}
steps:
- uses: actions/checkout@v4
- name: Extract version from tag
id: version
run: echo "VERSION=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Log in to GitHub Container Registry
uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Build and push
id: push
uses: docker/build-push-action@v5
with:
context: .
push: true
platforms: linux/amd64,linux/arm64
tags: |
ghcr.io/${{ github.repository }}:${{ github.ref_name }}
ghcr.io/${{ github.repository }}:${{ steps.version.outputs.VERSION }}
ghcr.io/${{ github.repository }}:latest
cache-from: type=registry,ref=ghcr.io/${{ github.repository }}:cache
cache-to: type=registry,ref=ghcr.io/${{ github.repository }}:cache,mode=max
labels: |
org.opencontainers.image.title=Veylant IA Gateway
org.opencontainers.image.description=AI Governance Proxy for Enterprise
org.opencontainers.image.version=${{ steps.version.outputs.VERSION }}
org.opencontainers.image.revision=${{ github.sha }}
org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}
- name: Trivy — container scan (must pass for release)
uses: aquasecurity/trivy-action@master
with:
image-ref: ghcr.io/${{ github.repository }}:${{ github.ref_name }}
format: sarif
output: trivy-release.sarif
exit-code: "1"
severity: CRITICAL,HIGH
ignore-unfixed: true
- name: Upload Trivy results
uses: github/codeql-action/upload-sarif@v3
if: always()
with:
sarif_file: trivy-release.sarif
# ─────────────────────────────────────────────
# Package Helm chart
# ─────────────────────────────────────────────
helm:
name: Package & Push Helm Chart
runs-on: ubuntu-latest
needs: [docker]
steps:
- uses: actions/checkout@v4
- name: Set up Helm
uses: azure/setup-helm@v4
with:
version: v3.16.0
- name: Log in to GHCR OCI registry (Helm)
run: |
echo "${{ secrets.GITHUB_TOKEN }}" | helm registry login ghcr.io \
--username ${{ github.actor }} \
--password-stdin
- name: Package Helm chart
run: |
helm package deploy/helm/veylant-proxy \
--version "${{ github.ref_name }}" \
--app-version "${{ github.ref_name }}"
- name: Push Helm chart to GHCR OCI
run: |
helm push veylant-proxy-*.tgz \
oci://ghcr.io/${{ github.repository_owner }}/charts
# ─────────────────────────────────────────────
# Create GitHub Release with CHANGELOG notes
# ─────────────────────────────────────────────
release:
name: Create GitHub Release
runs-on: ubuntu-latest
needs: [docker, helm]
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Extract release notes from CHANGELOG.md
id: changelog
run: |
# Extract section for this version from CHANGELOG.md
VERSION="${{ github.ref_name }}"
VERSION_NO_V="${VERSION#v}"
# Extract content between this version header and the next one
NOTES=$(awk "/^## \[${VERSION_NO_V}\]/{found=1; next} found && /^## \[/{exit} found{print}" CHANGELOG.md)
if [ -z "$NOTES" ]; then
NOTES="See [CHANGELOG.md](./CHANGELOG.md) for full release notes."
fi
# Write to file to handle multiline content
echo "$NOTES" > release_notes.md
echo "Release notes extracted ($(wc -l < release_notes.md) lines)"
- name: Create GitHub Release
uses: softprops/action-gh-release@v2
with:
name: "Veylant IA ${{ github.ref_name }}"
body_path: release_notes.md
draft: false
prerelease: ${{ contains(github.ref_name, '-rc') || contains(github.ref_name, '-beta') }}
generate_release_notes: false
files: |
CHANGELOG.md
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

79
.gitignore vendored Normal file
View File

@ -0,0 +1,79 @@
# Go
bin/
*.exe
*.exe~
*.dll
*.so
*.dylib
*.test
*.out
coverage.out
coverage.html
# Vendor
vendor/
# Go workspace
go.work
go.work.sum
# Python
__pycache__/
*.py[cod]
*$py.class
*.pyc
.venv/
venv/
env/
dist/
*.egg-info/
.pytest_cache/
.mypy_cache/
htmlcov/
# Node / Frontend
node_modules/
.next/
out/
dist/
*.local
# Environment & secrets
.env
.env.*
!.env.example
*.pem
*.key
*.p12
*.pfx
secrets/
vault-tokens/
# Docker
.docker/
# Terraform
.terraform/
*.tfstate
*.tfstate.*
*.tfplan
.terraform.lock.hcl
# IDE
.idea/
.vscode/
*.swp
*.swo
*~
.DS_Store
# Generated proto stubs
gen/
services/pii/gen/
# Logs
*.log
logs/
# Coverage reports
coverage/

44
.golangci.yml Normal file
View File

@ -0,0 +1,44 @@
version: "2"
linters:
enable:
- errcheck # Check all error return values
- govet # Suspicious Go constructs
- staticcheck # Large set of static analysis checks
- ineffassign # Detect ineffectual assignments
- unused # Find unused code
- gofmt # Formatting
- goimports # Import ordering
- gocritic # Common Go mistakes
- noctx # HTTP requests should use context
- bodyclose # HTTP response body must be closed
- exhaustive # Exhaustive enum switch
- godot # Comments should end with a period
- misspell # Spelling errors in comments/strings
- whitespace # Unnecessary blank lines
settings:
errcheck:
check-type-assertions: true
govet:
enable-all: true
staticcheck:
checks: ["all"]
godot:
scope: declarations
linters-settings:
goimports:
local-prefixes: github.com/veylant/ia-gateway
issues:
exclude-rules:
# Allow _ in test files for assertion patterns
- path: _test\.go
linters: [errcheck]
# Generated proto files are not our code
- path: gen/
linters: ["all"]
run:
timeout: 5m

113
.semgrep.yml Normal file
View File

@ -0,0 +1,113 @@
rules:
# ── Go: HTTP handler context hygiene ────────────────────────────────────────
- id: veylant-context-background-in-handler
languages: [go]
severity: WARNING
message: >
HTTP handler uses context.Background() instead of r.Context().
This bypasses request cancellation, tracing, and tenant context propagation.
Use r.Context() to inherit the request lifetime.
patterns:
- pattern: |
func $HANDLER($W http.ResponseWriter, $R *http.Request) {
...
context.Background()
...
}
paths:
include:
- "internal/**/*.go"
- "cmd/**/*.go"
# ── Go: SQL injection risk ──────────────────────────────────────────────────
- id: veylant-sql-string-concatenation
languages: [go]
severity: ERROR
message: >
SQL query built using string concatenation or fmt.Sprintf.
This is a potential SQL injection vulnerability.
Use parameterised queries ($1, $2, ...) or named placeholders instead.
patterns:
- pattern: db.QueryContext($CTX, $QUERY + $VAR, ...)
- pattern: db.QueryRowContext($CTX, $QUERY + $VAR, ...)
- pattern: db.ExecContext($CTX, $QUERY + $VAR, ...)
- pattern: db.QueryContext($CTX, fmt.Sprintf(...), ...)
- pattern: db.QueryRowContext($CTX, fmt.Sprintf(...), ...)
- pattern: db.ExecContext($CTX, fmt.Sprintf(...), ...)
paths:
include:
- "internal/**/*.go"
# ── Go: Sensitive data in structured logs ───────────────────────────────────
- id: veylant-sensitive-field-in-log
languages: [go]
severity: WARNING
message: >
Potentially sensitive field name logged. Ensure this does not contain PII,
API keys, passwords, or tokens. Use redaction helpers for sensitive values.
patterns:
- pattern: zap.String("password", ...)
- pattern: zap.String("api_key", ...)
- pattern: zap.String("token", ...)
- pattern: zap.String("secret", ...)
- pattern: zap.String("Authorization", ...)
- pattern: zap.String("email", ...)
- pattern: zap.String("prompt", ...)
paths:
include:
- "internal/**/*.go"
- "cmd/**/*.go"
# ── Go: Hardcoded credentials ───────────────────────────────────────────────
- id: veylant-hardcoded-api-key
languages: [go]
severity: ERROR
message: >
Hardcoded string that looks like an API key or secret.
API keys must be loaded from environment variables or Vault — never hardcoded.
patterns:
- pattern: |
$KEY = "sk-..."
- pattern: |
APIKey: "sk-..."
paths:
include:
- "internal/**/*.go"
- "cmd/**/*.go"
# ── Go: Missing request size limit ─────────────────────────────────────────
- id: veylant-missing-max-bytes-reader
languages: [go]
severity: WARNING
message: >
HTTP request body decoded without http.MaxBytesReader().
A client can send an unbounded body, causing memory exhaustion.
Wrap r.Body with http.MaxBytesReader(w, r.Body, maxBytes) before decoding.
patterns:
- pattern: json.NewDecoder($R.Body).Decode(...)
paths:
include:
- "internal/**/*.go"
fix: |
r.Body = http.MaxBytesReader(w, r.Body, 1<<20) // 1 MiB
json.NewDecoder(r.Body).Decode(...)
# ── Python: Eval/exec of user input ─────────────────────────────────────────
- id: veylant-python-eval-user-input
languages: [python]
severity: ERROR
message: >
eval() or exec() called with a variable — potential code injection.
Never evaluate user-supplied data.
patterns:
- pattern: eval($X)
- pattern: exec($X)
paths:
include:
- "services/**/*.py"

112
CHANGELOG.md Normal file
View File

@ -0,0 +1,112 @@
# Changelog
All notable changes to Veylant IA are documented in this file.
Format: [Conventional Commits](https://www.conventionalcommits.org/) — `feat`, `fix`, `chore`, `docs`, `perf`, `security`.
---
## [1.0.0] — 2026-06-21 — Production Launch
### Milestone 6 — Beta, Polish & Launch (Sprint 13)
#### feat: Production K8s cluster on AWS eu-west-3 (E1-10)
- Terraform EKS module: 3-AZ managed node groups (eu-west-3a/b/c), t3.medium, cluster v1.31
- HPA `autoscaling/v2` template: CPU 70% + memory 80% targets, scale 3→15 replicas
- `values-production.yaml`: replicaCount=3, autoscaling enabled, fail_open=false for PII
- Daily PostgreSQL backup CronJob: pg_dump | gzip → S3, 7-day retention via S3 lifecycle
- S3 backup bucket with AES-256 encryption, public access blocked, IRSA for pod-level IAM
- PodDisruptionBudget: minAvailable=1 (Sprint 12)
- Topology spread constraints across AZs
#### feat: Production monitoring stack (E1-11)
- Alertmanager: PagerDuty (critical) + Slack (warning + critical channels), inhibit rules
- 4 new Prometheus alert rules: VeylantProxyDown, VeylantCertExpiringSoon, VeylantDBConnectionsHigh, VeylantPIIVolumeAnomaly
- Production SLO dashboard: uptime 99.5% gauge, error budget remaining, PII by type, DB connections, provider breakdown, Redis memory
- Extended proxy-overview dashboard: +3 panels (PII rate by type, DB connections, provider pie chart)
- Prometheus alertmanager integration + rule_files config
- Blackbox exporter config for TLS certificate expiry probing
#### feat: Pilot client migration runbook (E11-13)
- 5-phase migration runbook: pre-migration backup → PG data migration → Keycloak reconfiguration → validation → SSO cutover
- Rollback plan at each phase
- CORS update procedure for client domains
#### feat: 5 operational runbooks (E1-12)
- `provider-down.md`: circuit breaker recovery, fallback activation, escalation matrix
- `database-full.md`: connection pool exhaustion, VACUUM, PVC expansion via AWS EBS
- `certificate-expired.md`: cert-manager forced renewal, emergency self-signed rollback
- `traffic-spike.md`: HPA manual override, tenant rate limiting, maintenance mode
- `pii-breach.md`: GDPR Art. 33 notification procedure, CNIL 72h deadline, evidence collection
#### docs: Pentest remediation report (E11-12)
- CVSS heatmap: 0 Critical, 0 High, 0 Medium open
- 5 findings documented with remediation evidence
- Go/No-Go checklist for Sprint 13 production decision
#### docs: Commercial materials (E11-14)
- One-pager: Shadow AI problem → Veylant solution → differentiators → pricing → CTA
- Pitch deck (10 slides): problem, solution, PII demo, governance, compliance, business model, roadmap, team, CTA
- Battle card: RSSI / DSI / DPO personas — pain points, qualification questions, objection handling, MEDDIC grid, competitive positioning
---
## [0.2.0] — 2026-05-30 — Sprint 12 (Security & Polish)
### Security & UX hardening (E11-09 / E11-10)
- **fix(security): CORS middleware** — `Access-Control-Allow-Origin` allowlist per environment; OPTIONS preflight 204
- **fix(security): CSP segmented** — strict CSP for `/v1/*`, relaxed for `/docs` and `/playground` (unpkg.com allowed)
- **fix(security): COOP header** — `Cross-Origin-Opener-Policy: same-origin` added
- **fix(ratelimit): Retry-After header on 429** — RFC 6585 compliant; `RetryAfterSec: 1` default
- **fix(ux): 403 message with allowed models** — error now lists allowed models for the user's role
- **feat(ux): X-Request-Id in error responses** — `WriteErrorWithRequestID()` injects request ID in all error responses
### Observability (E2-12)
- **feat(observability): k6 load test suite** — 4 scenarios (smoke/load/stress/soak), `SCENARIO` env var selection, p99 < 500ms threshold
- **feat(observability): Prometheus recording rules** — p99, p95, request rate, error rate pre-computed
- **feat(observability): 3 alert rules** — VeylantHighLatencyP99, VeylantHighErrorRate, VeylantCircuitBreakerOpen
### Blue/Green Deployment (E1-09)
- **feat(deploy): Istio VirtualService + DestinationRule** — blue/green subsets, atomic traffic switch
- **feat(deploy): blue-green.sh** — 7-step orchestration: detect active slot → deploy inactive → smoke test → patch VS → verify → scale down old slot
- **feat(deploy): PodDisruptionBudget** — minAvailable=1
- **feat(ci): k6 smoke job in CI** — runs before deploy-staging; blocks deployment on SLA breach
### Public Playground (E8-15)
- **feat(product): GET /playground** — self-contained HTML demo page with PII visualization and color-coded entity badges
- **feat(product): POST /playground/analyze** — IP rate-limited (20 req/min, 5-min eviction), graceful PII fallback
- **feat(security): Semgrep custom rules** — 6 rules: context.Background() in handlers, SQL injection, sensitive logging, hardcoded keys, missing MaxBytesReader, Python eval()
### Documentation (E11-08 / E11-11)
- **docs: feedback-backlog.md** — Sprint 12 MoSCoW from 2 pilot sessions (TechVision ESN + RH Conseil)
- **docs: pentest-scope.md** — grey box pentest scope, attack surfaces, rules of engagement
---
## [0.1.0] — 2026-04-30 — Sprint 11 (Feature Flags, E2E Tests, OpenAPI, Guides)
- **feat: Feature flags** — PostgreSQL-backed with in-memory fallback (E11-07)
- **feat: E2E tests** — Playwright for dashboard UI, testcontainers for integration (E11-01a/b)
- **feat: OpenAPI 3.1 spec** — swaggo annotations, Swagger UI at /docs (E11-02)
- **docs: Integration guide** — OpenAI SDK compatibility, environment setup (E11-03)
- **docs: Admin guide** — routing rules, RBAC, CORS configuration (E11-04)
- **docs: Onboarding guide** — first-time setup, Keycloak federation (E11-05/06)
---
## [0.0.1] — 2026-02-15 — Sprints 1–10 (MVP Core)
- Go proxy: chi router, zap logger, viper config, graceful shutdown
- PII sidecar: FastAPI + gRPC, regex + Presidio + spaCy (fr_core_news_lg), 3-layer detection
- Intelligent routing engine: PostgreSQL JSONB, in-memory cache, priority ASC, first-match-wins
- RBAC: Keycloak OIDC, 4 roles (admin/manager/user/auditor), per-model restrictions
- Audit logs: ClickHouse append-only, async batch writer, TTL retention
- GDPR Article 30 registry + AI Act risk classification + PDF export
- Multi-tenant isolation: PostgreSQL RLS, `veylant_app` role, per-session `app.tenant_id`
- AES-256-GCM encryption for prompt storage, Redis pseudonymization mappings
- Provider adapters: OpenAI, Anthropic, Azure, Mistral, Ollama
- Circuit breaker: threshold=5, open_ttl=60s
- Token-bucket rate limiter: per-tenant + per-user, DB overrides
- Prometheus metrics middleware + Grafana dashboards
- React 18 dashboard: shadcn/ui, recharts, OIDC auth flow
- Helm chart v0.1.0, Docker multi-stage build, docker-compose dev stack
- CI/CD: golangci-lint, black, ruff, Semgrep SAST, Trivy image scan, gitleaks, OWASP ZAP DAST

192
CLAUDE.md Normal file
View File

@ -0,0 +1,192 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
**Veylant IA** — A B2B SaaS platform acting as an intelligent proxy/gateway for enterprise AI consumption. Core value proposition: prevent Shadow AI, enforce PII anonymization, ensure GDPR/EU AI Act compliance, and control costs across all LLM usage in an organization.
Full product requirements are in `docs/AI_Governance_Hub_PRD.md` and the 6-month execution plan (13 sprints, 164 tasks) is in `docs/AI_Governance_Hub_Plan_Realisation.md`.
## Architecture
**Go module**: `github.com/veylant/ia-gateway` · **Go version**: 1.24
**Modular monolith** (not microservices), with two distinct runtimes:
```
API Gateway (Traefik)
│
Go Proxy [cmd/proxy] — chi router, zap logger, viper config
├── internal/middleware/ Auth (OIDC/Keycloak), RateLimit, RequestID, SecurityHeaders
├── internal/router/ RBAC enforcement + provider dispatch + fallback chain
├── internal/routing/ Rules engine (PostgreSQL JSONB, in-memory cache, priority ASC)
├── internal/pii/ gRPC client to PII sidecar + /v1/pii/analyze HTTP handler
├── internal/auditlog/ ClickHouse append-only logger (async batch writer)
├── internal/compliance/ GDPR Art.30 registry + AI Act classification + PDF reports
├── internal/admin/ Admin REST API (/v1/admin/*) — routing rules, users, providers
├── internal/billing/ Token cost tracking (per provider pricing)
├── internal/circuitbreaker/ Failure-count breaker (threshold=5, open_ttl=60s)
├── internal/ratelimit/ Token-bucket limiter (per-tenant + per-user, DB overrides)
├── internal/flags/ Feature flags (PostgreSQL + in-memory fallback)
├── internal/crypto/ AES-256-GCM encryptor for prompt storage
├── internal/metrics/ Prometheus middleware + metrics registration
├── internal/provider/ Adapter interface + OpenAI/Anthropic/Azure/Mistral/Ollama impls
├── internal/proxy/ Core request handler (PII → upstream → audit → response)
├── internal/apierror/ OpenAI-format error helpers (WriteError, WriteErrorWithRequestID)
├── internal/health/ /healthz, /docs, /playground, /playground/analyze handlers
└── internal/config/ Viper-based config loader (VEYLANT_* env var overrides)
│ gRPC (<2ms) to localhost:50051
PII Detection Service [services/pii] — FastAPI + grpc.aio
├── HTTP health: :8091/healthz
├── Layer 1: Regex (IBAN, email, phone, SSN, credit cards)
├── Layer 2: Presidio + spaCy NER (names, addresses, orgs)
└── Layer 3: LLM validation (V1.1, ambiguous cases)
│
LLM Provider Adapters (OpenAI, Anthropic, Azure, Mistral, Ollama)
```
**Data layer:**
- PostgreSQL 16 — config, users, policies, processing registry (Row-Level Security for multi-tenancy; app role: `veylant_app`)
- ClickHouse — analytics and immutable audit logs
- Redis 7 — sessions, rate limiting, PII pseudonymization mappings (AES-256-GCM + TTL)
- Keycloak — IAM, SSO, SAML 2.0/OIDC federation (dev console: http://localhost:8080, admin/admin; test users: admin@veylant.dev/admin123, user@veylant.dev/user123)
- Prometheus — metrics scraper on :9090; Grafana — dashboards on :3001 (admin/admin)
- HashiCorp Vault — secrets and API key rotation (90-day cycle)
**Frontend:** React 18 + TypeScript + Vite, shadcn/ui, recharts. Routes protected via OIDC (Keycloak); `web/src/auth/` manages the auth flow. API clients live in `web/src/api/`.
## Repository Structure
```
cmd/proxy/ # Go main entry point — wires all modules, starts HTTP server
internal/ # All Go modules (see Architecture above for full list)
gen/ # Generated Go gRPC stubs (buf generate → never edit manually)
services/pii/ # Python FastAPI + gRPC PII detection service
gen/pii/v1/ # Generated Python proto stubs (run `make proto` first)
proto/pii/v1/ # gRPC .proto definitions
migrations/ # golang-migrate SQL files (up/down pairs)
clickhouse/ # ClickHouse DDL applied at startup via ApplyDDL()
web/ # React frontend (Vite, src/pages, src/components, src/api)
deploy/ # Helm charts for Kubernetes
config.yaml # Local dev config (overridden by VEYLANT_* env vars)
```
## Build & Development Commands
Use `make` as the primary interface. The proxy runs on **:8090**, PII HTTP on **:8091**, PII gRPC on **:50051**.
```bash
make dev # Start full stack (proxy + PostgreSQL + ClickHouse + Redis + Keycloak + PII)
make dev-down # Stop and remove all containers and volumes
make dev-logs # Tail logs from all services
make build # go build → bin/proxy
make test # go test -race ./...
make test-cover # Tests with HTML coverage report (coverage.html)
make test-integration # Integration tests with testcontainers (requires Docker)
make lint # golangci-lint + black --check + ruff check
make fmt # gofmt + black
make proto # buf generate — regenerates gen/ and services/pii/gen/
make proto-lint # buf lint
make migrate-up # Apply pending DB migrations
make migrate-down # Roll back last migration
make migrate-status # Show current migration version
make check # Full pre-commit: build + vet + lint + test
make health # curl localhost:8090/healthz
make docs # Open http://localhost:8090/docs in browser (proxy must be running)
make helm-dry-run # Render Helm templates without deploying
make helm-deploy # Deploy to staging (requires IMAGE_TAG + KUBECONFIG env vars)
make load-test # k6 load test (SCENARIO=smoke|load|stress|soak, default: smoke)
make deploy-blue # Blue/green: deploy IMAGE_TAG to blue slot (requires kubectl + Istio)
make deploy-green # Blue/green: deploy IMAGE_TAG to green slot
make deploy-rollback # Roll back traffic to ACTIVE_SLOT (e.g. make deploy-rollback ACTIVE_SLOT=blue)
```
**Frontend dev server** (Vite, runs on :3000):
```bash
cd web && npm install && npm run dev
```
**Run a single Go test:**
```bash
go test -run TestName ./internal/module/
```
**Run a single Python test:**
```bash
pytest services/pii/test_file.py::test_function
```
**Proto prerequisite:** Run `make proto` before starting the PII service if `gen/` or `services/pii/gen/` is missing — the service will start but reject all gRPC requests otherwise.
**Config override:** Any config key can be overridden via env var with the `VEYLANT_` prefix and `.` → `_` replacement. Example: `VEYLANT_SERVER_PORT=9090` overrides `server.port`.
**Tools required:** `buf` (`brew install buf`), `golang-migrate` (`brew install golang-migrate`), `golangci-lint`, Python 3.12, `black`, `ruff`.
## Development Mode Graceful Degradation
When `server.env=development`, the proxy degrades gracefully instead of crashing:
- **Keycloak unreachable** → falls back to `MockVerifier` (JWT auth bypassed; dev user injected as `admin` role)
- **PostgreSQL unreachable** → routing engine and feature flags disabled; flag store uses in-memory fallback
- **ClickHouse unreachable** → audit logging disabled
- **PII service unreachable** → PII disabled if `pii.fail_open=true` (default)
In production (`server.env=production`), any of the above causes a fatal startup error.
## Key Technical Constraints
**Latency budget**: The entire PII pipeline (regex + NER + pseudonymization) must complete in **<50ms**. The PII gRPC call has a configurable timeout (`pii.timeout_ms`, default 100ms).
**Streaming (SSE)**: The proxy must flush SSE chunks without buffering. PII anonymization applies to the **request** before it's sent upstream — not to the streamed response. This is the most technically complex piece of the MVP.
**Multi-tenancy**: Logical isolation via PostgreSQL Row-Level Security. The app connects as role `veylant_app` and sets `app.tenant_id` per session. Superuser bypasses RLS (dev only).
**Immutable audit logs**: ClickHouse is append-only — no DELETE operations. Retention via TTL policies only. ClickHouse DDL is applied idempotently at startup from `migrations/clickhouse/`.
**Routing rule evaluation**: Rules are sorted ascending by `priority` (lower = evaluated first). All conditions within a rule are AND-joined. An empty `Conditions` slice is a catch-all. First match wins. Supported condition fields: `user.role`, `user.department`, `request.sensitivity`, `request.model`, `request.use_case`, `request.token_estimate`. Operators: `eq`, `neq`, `in`, `nin`, `gte`, `lte`, `contains`, `matches`.
## Conventions
**Go import ordering** (`goimports` with `local-prefixes: github.com/veylant/ia-gateway`): three groups — stdlib · external · `github.com/veylant/ia-gateway/internal/...`. `gen/` is excluded from all linters (generated code).
**Commits**: Conventional Commits (`feat:`, `fix:`, `chore:`) — used for automated changelog generation.
**API versioning**: `/v1/` prefix, OpenAI-compatible format (`/v1/chat/completions`) so existing OpenAI SDK clients work without modification.
**LLM Provider Adapters**: Each provider implements `provider.Adapter` (`Send()`, `Stream()`, `Validate()`, `HealthCheck()`). Add new providers by implementing this interface in `internal/provider/<name>/`.
**Error handling**: Go modules use typed errors with `errors.Wrap`. The proxy always returns errors in OpenAI JSON format (`type`, `message`, `code`).
**Feature flags**: PostgreSQL table (`feature_flags`) + in-memory fallback when DB is unavailable. No external service.
**OpenAPI docs**: Generated from swaggo annotations — never write API docs by hand.
**Testing split**: 70% unit (`testing` + `testify` / `pytest`) · 20% integration (`testcontainers` for PG/ClickHouse/Redis) · 10% E2E (Playwright for UI). Tests are written in parallel with each module, not deferred.
**CI coverage thresholds**: Go internal packages must maintain ≥80% coverage; Python PII service ≥75%. NER tests (`test_ner.py`) are excluded from CI because `fr_core_news_lg` (~600MB) is only available in the Docker build.
## Custom Semgrep Rules (`.semgrep.yml`)
These are enforced in CI and represent project-specific guardrails:
- **`context.Background()` in HTTP handlers** → use `r.Context()` to propagate tenant context and cancellation.
- **SQL string concatenation** (`db.QueryContext(ctx, query+var)` or `fmt.Sprintf`) → use parameterized queries (`$1, $2, ...`).
- **Sensitive fields in logs** (`zap.String("password"|"api_key"|"token"|"secret"|"Authorization"|"email"|"prompt", ...)`) → use redaction helpers.
- **Hardcoded API keys** (string literals starting with `sk-`) → load from env or Vault.
- **`json.NewDecoder(r.Body).Decode()`** without `http.MaxBytesReader` → wrap body first.
- **Python `eval()`/`exec()`** on variables → never evaluate user-supplied data.
## Security Patterns
- Zero Trust network, mTLS between services, TLS 1.3 externally
- All sensitive fields encrypted at application level (AES-256-GCM)
- API keys stored as SHA-256 hashes only; prefix kept for display (e.g. `sk-vyl_ab12cd34`)
- RBAC roles: `admin`, `manager`, `user`, `auditor` — per-model and per-department permissions. `admin`/`manager` have unrestricted model access; `user` is limited to `rbac.user_allowed_models`; `auditor` cannot call `/v1/chat/completions` by default.
- Audit-of-the-audit: all accesses to audit logs are themselves logged
- CI pipeline: Semgrep (SAST), Trivy (image scanning, CRITICAL/HIGH blocking), gitleaks (secret detection), OWASP ZAP DAST (non-blocking, main branch only)
- Release pipeline (`v*` tag push): multi-arch Docker image (amd64/arm64) → GHCR, Helm chart → GHCR OCI, GitHub Release with notes extracted from CHANGELOG.md
## MVP Scope (V1)
In scope: AI proxy, PII anonymization + pseudonymization, intelligent routing engine, audit logs, RBAC, React dashboard, GDPR Article 30 registry, AI Act risk classification, provider configuration wizard, integrated playground (prompt test with PII visualization).
Out of scope (V2+): ML anomaly detection, Shadow AI discovery, physical multi-tenant isolation, native SDKs, SIEM integrations.

39
Dockerfile Normal file
View File

@ -0,0 +1,39 @@
# ─────────────────────────────────────────────
# Stage 1: Build
# ─────────────────────────────────────────────
# SHA256 pinned for reproducible builds (E10-05).
# To refresh: docker pull --platform linux/amd64 golang:1.24-alpine && docker inspect ... | jq -r '.[0].RepoDigests[0]'
FROM golang:1.24-alpine@sha256:8bee1901f1e530bfb4a7850aa7a479d17ae3a18beb6e09064ed54cfd245b7191 AS builder
RUN apk add --no-cache git ca-certificates
WORKDIR /app
# Download dependencies first (cache layer)
COPY go.mod go.sum ./
RUN go mod download
# Copy source and build
COPY . .
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
go build -ldflags="-s -w -extldflags '-static'" \
-o /app/bin/proxy ./cmd/proxy/
# ─────────────────────────────────────────────
# Stage 2: Runtime (distroless — no shell, minimal attack surface)
# ─────────────────────────────────────────────
# SHA256 pinned for reproducible builds (E10-05).
FROM gcr.io/distroless/static-debian12@sha256:20bc6c0bc4d625a22a8fde3e55f6515709b32055ef8fb9cfbddaa06d1760f838
WORKDIR /app
# Copy binary and default config
COPY --from=builder /app/bin/proxy .
COPY --from=builder /app/config.yaml .
# Non-root user (distroless default uid 65532)
USER 65532:65532
EXPOSE 8090
ENTRYPOINT ["/app/proxy"]

161
Makefile Normal file
View File

@ -0,0 +1,161 @@
.PHONY: dev dev-down build test test-cover lint fmt proto migrate-up migrate-down health check docs load-test deploy-blue deploy-green deploy-rollback
# ─────────────────────────────────────────────
# Local development
# ─────────────────────────────────────────────
## dev: Start the full local stack (proxy + PostgreSQL + ClickHouse + Redis + Keycloak + PII)
dev:
docker compose up --build
## dev-down: Stop and remove all containers and volumes
dev-down:
docker compose down -v
## dev-logs: Tail logs from all services
dev-logs:
docker compose logs -f
# ─────────────────────────────────────────────
# Go
# ─────────────────────────────────────────────
## build: Compile the Go proxy binary to bin/proxy
build:
@mkdir -p bin
go build -o bin/proxy ./cmd/proxy/
## test: Run all Go tests with race detector
test:
go test -race ./...
## test-cover: Run tests with HTML coverage report
test-cover:
go test -race -coverprofile=coverage.out ./...
go tool cover -html=coverage.out -o coverage.html
@echo "Coverage report: coverage.html"
## lint: Run golangci-lint (Go) and black --check (Python)
lint:
golangci-lint run
black --check services/pii/
ruff check services/pii/
## fmt: Auto-format Go and Python code
fmt:
gofmt -w .
black services/pii/
# ─────────────────────────────────────────────
# Proto (requires: brew install buf)
# ─────────────────────────────────────────────
## proto: Generate gRPC stubs for Go (gen/) and Python (services/pii/gen/)
proto:
buf generate
## proto-lint: Lint the proto definitions
proto-lint:
buf lint
# ─────────────────────────────────────────────
# Database migrations (requires: brew install golang-migrate)
# ─────────────────────────────────────────────
DB_URL ?= postgres://veylant:veylant_dev@localhost:5432/veylant?sslmode=disable
## migrate-up: Apply all pending migrations
migrate-up:
migrate -path migrations -database "$(DB_URL)" up
## migrate-down: Roll back the last migration
migrate-down:
migrate -path migrations -database "$(DB_URL)" down 1
## migrate-status: Show migration status
migrate-status:
migrate -path migrations -database "$(DB_URL)" version
# ─────────────────────────────────────────────
# Checks & utilities
# ─────────────────────────────────────────────
## docs: Open the API documentation in the browser (proxy must be running)
docs:
@echo "API docs available at http://localhost:8090/docs"
@echo "OpenAPI spec: http://localhost:8090/docs/openapi.yaml"
@open http://localhost:8090/docs 2>/dev/null || xdg-open http://localhost:8090/docs 2>/dev/null || true
## health: Check the proxy health endpoint
health:
@curl -sf http://localhost:8090/healthz | python3 -m json.tool
## check: Run build + vet + lint + test (full pre-commit check)
check: build
go vet ./...
golangci-lint run
go test -race ./...
## test-integration: Run integration tests (requires Docker)
test-integration:
go test -tags integration -v -timeout 10m ./test/integration/...
# ─────────────────────────────────────────────
# Helm (requires: helm)
# ─────────────────────────────────────────────
## helm-dry-run: Render Helm templates without deploying
helm-dry-run:
helm template veylant-proxy deploy/helm/veylant-proxy
## helm-deploy: Deploy to staging (requires KUBECONFIG and IMAGE_TAG env vars)
helm-deploy:
helm upgrade --install veylant-proxy deploy/helm/veylant-proxy \
--namespace veylant \
--create-namespace \
--set image.tag=$(IMAGE_TAG) \
--wait --timeout 5m
# ─────────────────────────────────────────────
# Load tests (requires: brew install k6)
# ─────────────────────────────────────────────
SCENARIO ?= smoke
VEYLANT_URL ?= http://localhost:8090
VEYLANT_TOKEN ?= dev-token
## load-test: Run k6 load tests (SCENARIO=smoke|load|stress|soak, default: smoke)
load-test:
k6 run \
--env VEYLANT_URL=$(VEYLANT_URL) \
--env VEYLANT_TOKEN=$(VEYLANT_TOKEN) \
--env SCENARIO=$(SCENARIO) \
test/k6/k6-load-test.js
# ─────────────────────────────────────────────
# Blue/Green deployment (requires: kubectl + helm + Istio)
# ─────────────────────────────────────────────
NAMESPACE ?= veylant
ACTIVE_SLOT ?= blue
## deploy-blue: Deploy IMAGE_TAG to the blue slot
deploy-blue:
IMAGE_TAG=$(IMAGE_TAG) NAMESPACE=$(NAMESPACE) ACTIVE_SLOT=green \
./deploy/scripts/blue-green.sh
## deploy-green: Deploy IMAGE_TAG to the green slot
deploy-green:
IMAGE_TAG=$(IMAGE_TAG) NAMESPACE=$(NAMESPACE) ACTIVE_SLOT=blue \
./deploy/scripts/blue-green.sh
## deploy-rollback: Roll back to the previous active slot
deploy-rollback:
@echo "Rolling back: switching traffic back to $(ACTIVE_SLOT)..."
kubectl patch virtualservice veylant-proxy -n $(NAMESPACE) --type merge \
-p '{"spec":{"http":[{"route":[{"destination":{"host":"veylant-proxy","subset":"$(ACTIVE_SLOT)"},"weight":100}]}]}}'
@echo "Rollback complete. Active slot: $(ACTIVE_SLOT)"
## help: Show this help message
help:
@grep -E '^## ' Makefile | sed 's/## / /'

66
README.md Normal file
View File

@ -0,0 +1,66 @@
# Veylant IA — AI Governance Hub
B2B SaaS platform acting as an intelligent proxy/gateway for enterprise AI consumption.
Prevents Shadow AI, enforces PII anonymization, ensures GDPR/EU AI Act compliance, and controls costs across all LLM usage.
## Quick start
```bash
# Start the full local stack (proxy + PostgreSQL + ClickHouse + Redis + Keycloak)
make dev
# Health check
make health
# → {"status":"ok","timestamp":"..."}
# Stop and clean
make dev-down
```
## Test credentials (development only)
| User | Password | Role |
|------|----------|------|
| admin@veylant.dev | admin123 | Admin |
| user@veylant.dev | user123 | User |
Keycloak admin console: http://localhost:8080 (admin / admin)
## Architecture
See `docs/AI_Governance_Hub_PRD.md` for the full technical architecture.
```
API Gateway (Traefik)
│
Go Proxy [cmd/proxy] ← chi router, JWT auth, routing rules
├── Module Auth ← Keycloak/OIDC/SAML
├── Module Router ← rules engine
├── Module Logger ← ClickHouse append-only
├── Module PII ← gRPC → Python sidecar
├── Module Billing ← cost tracking
└── Module RBAC ← row-level per tenant
│ gRPC
PII Service [services/pii] ← FastAPI + Presidio + spaCy
│
LLM Adapters ← OpenAI, Anthropic, Azure, Mistral, Ollama
```
## Commands
```bash
make build # go build ./cmd/proxy/
make test # go test -race ./...
make lint # golangci-lint + black --check
make fmt # gofmt + black
make proto # buf generate (requires: brew install buf)
make migrate-up # apply DB migrations
make health # curl /healthz
```
## Documentation
- `docs/AI_Governance_Hub_PRD.md` — Full product requirements
- `docs/AI_Governance_Hub_Plan_Realisation.md` — 26-week execution plan (164 tasks)
- `docs/Veylant_IA_Plan_Agile_Scrum.md` — Agile/Scrum plan (13 sprints)
- `docs/adr/` — Architecture Decision Records

21
buf.gen.yaml Normal file
View File

@ -0,0 +1,21 @@
version: v2
plugins:
# Go stubs → gen/pii/v1/
- remote: buf.build/protocolbuffers/go
out: gen
opt:
- paths=source_relative
# Go gRPC stubs → gen/pii/v1/
- remote: buf.build/grpc/go
out: gen
opt:
- paths=source_relative
# Python stubs → services/pii/gen/
- remote: buf.build/protocolbuffers/python
out: services/pii/gen
# Python gRPC stubs → services/pii/gen/
- remote: buf.build/grpc/python
out: services/pii/gen

11
buf.yaml Normal file
View File

@ -0,0 +1,11 @@
version: v2
modules:
- path: proto
lint:
use:
- STANDARD
except:
- PACKAGE_VERSION_SUFFIX # pii.v1 already has version in package name
breaking:
use:
- FILE

433
cmd/proxy/main.go Normal file
View File

@ -0,0 +1,433 @@
package main
import (
"context"
"database/sql"
"errors"
"fmt"
"net/http"
"os"
"os/signal"
"syscall"
"time"
"github.com/go-chi/chi/v5"
chimiddleware "github.com/go-chi/chi/v5/middleware"
"github.com/prometheus/client_golang/prometheus/promhttp"
"go.uber.org/zap"
"go.uber.org/zap/zapcore"
_ "github.com/jackc/pgx/v5/stdlib" // register pgx driver
"github.com/veylant/ia-gateway/internal/admin"
"github.com/veylant/ia-gateway/internal/auditlog"
"github.com/veylant/ia-gateway/internal/circuitbreaker"
"github.com/veylant/ia-gateway/internal/compliance"
"github.com/veylant/ia-gateway/internal/config"
"github.com/veylant/ia-gateway/internal/crypto"
"github.com/veylant/ia-gateway/internal/flags"
"github.com/veylant/ia-gateway/internal/health"
"github.com/veylant/ia-gateway/internal/metrics"
"github.com/veylant/ia-gateway/internal/middleware"
"github.com/veylant/ia-gateway/internal/pii"
"github.com/veylant/ia-gateway/internal/provider"
"github.com/veylant/ia-gateway/internal/provider/anthropic"
"github.com/veylant/ia-gateway/internal/provider/azure"
"github.com/veylant/ia-gateway/internal/provider/mistral"
"github.com/veylant/ia-gateway/internal/provider/ollama"
"github.com/veylant/ia-gateway/internal/provider/openai"
"github.com/veylant/ia-gateway/internal/proxy"
"github.com/veylant/ia-gateway/internal/ratelimit"
"github.com/veylant/ia-gateway/internal/router"
"github.com/veylant/ia-gateway/internal/routing"
)
func main() {
cfg, err := config.Load()
if err != nil {
fmt.Fprintf(os.Stderr, "failed to load config: %v\n", err)
os.Exit(1)
}
logger := buildLogger(cfg.Log.Level, cfg.Log.Format)
defer logger.Sync() //nolint:errcheck
// ── JWT / OIDC verifier ───────────────────────────────────────────────────
issuerURL := fmt.Sprintf("%s/realms/%s", cfg.Keycloak.BaseURL, cfg.Keycloak.Realm)
logger.Info("initialising OIDC verifier", zap.String("issuer", issuerURL))
ctx := context.Background()
oidcVerifier, err := middleware.NewOIDCVerifier(ctx, issuerURL, cfg.Keycloak.ClientID)
if err != nil {
if cfg.Server.Env == "development" {
logger.Warn("OIDC verifier unavailable — JWT auth will reject all requests",
zap.Error(err))
oidcVerifier = nil
} else {
logger.Fatal("failed to initialise OIDC verifier", zap.Error(err))
}
}
// ── LLM provider adapters ─────────────────────────────────────────────────
adapters := map[string]provider.Adapter{}
adapters["openai"] = openai.New(openai.Config{
APIKey: cfg.Providers.OpenAI.APIKey,
BaseURL: cfg.Providers.OpenAI.BaseURL,
TimeoutSeconds: cfg.Providers.OpenAI.TimeoutSeconds,
MaxConns: cfg.Providers.OpenAI.MaxConns,
})
if cfg.Providers.Anthropic.APIKey != "" {
adapters["anthropic"] = anthropic.New(anthropic.Config{
APIKey: cfg.Providers.Anthropic.APIKey,
BaseURL: cfg.Providers.Anthropic.BaseURL,
Version: cfg.Providers.Anthropic.Version,
TimeoutSeconds: cfg.Providers.Anthropic.TimeoutSeconds,
MaxConns: cfg.Providers.Anthropic.MaxConns,
})
logger.Info("Anthropic adapter enabled")
}
if cfg.Providers.Azure.ResourceName != "" && cfg.Providers.Azure.APIKey != "" {
adapters["azure"] = azure.New(azure.Config{
APIKey: cfg.Providers.Azure.APIKey,
ResourceName: cfg.Providers.Azure.ResourceName,
DeploymentID: cfg.Providers.Azure.DeploymentID,
APIVersion: cfg.Providers.Azure.APIVersion,
TimeoutSeconds: cfg.Providers.Azure.TimeoutSeconds,
MaxConns: cfg.Providers.Azure.MaxConns,
})
logger.Info("Azure OpenAI adapter enabled",
zap.String("resource", cfg.Providers.Azure.ResourceName),
zap.String("deployment", cfg.Providers.Azure.DeploymentID),
)
}
if cfg.Providers.Mistral.APIKey != "" {
adapters["mistral"] = mistral.New(mistral.Config{
APIKey: cfg.Providers.Mistral.APIKey,
BaseURL: cfg.Providers.Mistral.BaseURL,
TimeoutSeconds: cfg.Providers.Mistral.TimeoutSeconds,
MaxConns: cfg.Providers.Mistral.MaxConns,
})
logger.Info("Mistral adapter enabled")
}
adapters["ollama"] = ollama.New(ollama.Config{
BaseURL: cfg.Providers.Ollama.BaseURL,
TimeoutSeconds: cfg.Providers.Ollama.TimeoutSeconds,
MaxConns: cfg.Providers.Ollama.MaxConns,
})
logger.Info("Ollama adapter enabled", zap.String("base_url", cfg.Providers.Ollama.BaseURL))
// ── Database (PostgreSQL via pgx) ─────────────────────────────────────────
var db *sql.DB
if cfg.Database.URL != "" {
var dbErr error
db, dbErr = sql.Open("pgx", cfg.Database.URL)
if dbErr != nil {
logger.Fatal("failed to open database", zap.Error(dbErr))
}
db.SetMaxOpenConns(cfg.Database.MaxOpenConns)
db.SetMaxIdleConns(cfg.Database.MaxIdleConns)
if pingErr := db.PingContext(ctx); pingErr != nil {
if cfg.Server.Env == "development" {
logger.Warn("database unavailable — routing engine disabled", zap.Error(pingErr))
db = nil
} else {
logger.Fatal("database ping failed", zap.Error(pingErr))
}
} else {
logger.Info("database connected", zap.String("url", cfg.Database.URL))
}
}
// ── Routing engine ────────────────────────────────────────────────────────
var routingEngine *routing.Engine
if db != nil {
ttl := time.Duration(cfg.Routing.CacheTTLSeconds) * time.Second
if ttl <= 0 {
ttl = 30 * time.Second
}
pgStore := routing.NewPgStore(db, logger)
routingEngine = routing.New(pgStore, ttl, logger)
routingEngine.Start()
logger.Info("routing engine started", zap.Duration("cache_ttl", ttl))
}
// ── Circuit breaker (E2-09) ───────────────────────────────────────────────
cb := circuitbreaker.New(5, 60*time.Second)
logger.Info("circuit breaker initialised", zap.Int("threshold", 5), zap.Duration("open_ttl", 60*time.Second))
// ── Provider router (RBAC + model dispatch + optional engine) ─────────────
providerRouter := router.NewWithEngineAndBreaker(adapters, &cfg.RBAC, routingEngine, cb, logger)
logger.Info("provider router initialised",
zap.Int("adapter_count", len(adapters)),
zap.Strings("user_allowed_models", cfg.RBAC.UserAllowedModels),
zap.Bool("routing_engine", routingEngine != nil),
)
// ── PII client (optional) ─────────────────────────────────────────────────
var piiClient *pii.Client
if cfg.PII.Enabled {
pc, piiErr := pii.New(pii.Config{
Address: cfg.PII.ServiceAddr,
Timeout: time.Duration(cfg.PII.TimeoutMs) * time.Millisecond,
FailOpen: cfg.PII.FailOpen,
}, logger)
if piiErr != nil {
logger.Warn("PII client init failed — PII disabled", zap.Error(piiErr))
} else {
piiClient = pc
defer pc.Close() //nolint:errcheck
logger.Info("PII client connected", zap.String("addr", cfg.PII.ServiceAddr))
}
}
// ── AES-256-GCM encryptor (optional) ─────────────────────────────────────
var encryptor *crypto.Encryptor
if cfg.Crypto.AESKeyBase64 != "" {
enc, encErr := crypto.NewEncryptor(cfg.Crypto.AESKeyBase64)
if encErr != nil {
logger.Warn("crypto encryptor init failed — prompt encryption disabled", zap.Error(encErr))
} else {
encryptor = enc
logger.Info("AES-256-GCM encryptor enabled")
}
} else {
logger.Warn("VEYLANT_CRYPTO_AES_KEY_BASE64 not set — prompt encryption disabled")
}
// ── ClickHouse audit logger (optional) ────────────────────────────────────
var auditLogger auditlog.Logger
if cfg.ClickHouse.DSN != "" {
chLogger, chErr := auditlog.NewClickHouseLogger(
cfg.ClickHouse.DSN,
cfg.ClickHouse.MaxConns,
cfg.ClickHouse.DialTimeoutSec,
logger,
)
if chErr != nil {
if cfg.Server.Env == "development" {
logger.Warn("ClickHouse unavailable — audit logging disabled", zap.Error(chErr))
} else {
logger.Fatal("ClickHouse init failed", zap.Error(chErr))
}
} else {
// Apply DDL idempotently.
ddlPath := "migrations/clickhouse/000001_audit_logs.sql"
if ddlErr := chLogger.ApplyDDL(ddlPath); ddlErr != nil {
logger.Warn("ClickHouse DDL apply failed — audit logging disabled", zap.Error(ddlErr))
} else {
chLogger.Start()
defer chLogger.Stop()
auditLogger = chLogger
logger.Info("ClickHouse audit logger started", zap.String("dsn", cfg.ClickHouse.DSN))
}
}
} else {
logger.Warn("clickhouse.dsn not set — audit logging disabled")
}
// ── Feature flag store (E4-12 zero-retention + future flags + E11-07) ──────
var flagStore flags.FlagStore
if db != nil {
flagStore = flags.NewPgFlagStore(db, logger)
logger.Info("feature flag store: PostgreSQL")
} else {
flagStore = flags.NewMemFlagStore()
logger.Warn("feature flag store: in-memory (no database)")
}
// Wire flag store into the provider router so it can check routing_enabled (E11-07).
providerRouter.WithFlagStore(flagStore)
// ── Proxy handler ─────────────────────────────────────────────────────────
proxyHandler := proxy.NewWithAudit(providerRouter, logger, piiClient, auditLogger, encryptor).
WithFlagStore(flagStore)
// ── Rate limiter (E10-09) ─────────────────────────────────────────────────
rateLimiter := ratelimit.New(ratelimit.RateLimitConfig{
RequestsPerMin: cfg.RateLimit.DefaultTenantRPM,
BurstSize: cfg.RateLimit.DefaultTenantBurst,
UserRPM: cfg.RateLimit.DefaultUserRPM,
UserBurst: cfg.RateLimit.DefaultUserBurst,
IsEnabled: true,
}, logger)
// Load per-tenant overrides from DB (best-effort; missing DB is graceful).
if db != nil {
rlStore := ratelimit.NewStore(db, logger)
if overrides, err := rlStore.List(ctx); err == nil {
for _, cfg := range overrides {
rateLimiter.SetConfig(cfg)
}
logger.Info("rate limit overrides loaded", zap.Int("count", len(overrides)))
} else {
logger.Warn("failed to load rate limit overrides", zap.Error(err))
}
}
logger.Info("rate limiter initialised",
zap.Int("default_tenant_rpm", cfg.RateLimit.DefaultTenantRPM),
zap.Int("default_user_rpm", cfg.RateLimit.DefaultUserRPM),
)
// ── HTTP router ───────────────────────────────────────────────────────────
r := chi.NewRouter()
r.Use(middleware.SecurityHeaders(cfg.Server.Env))
r.Use(middleware.RequestID)
r.Use(chimiddleware.RealIP)
r.Use(chimiddleware.Recoverer)
if cfg.Metrics.Enabled {
r.Use(metrics.Middleware("openai"))
}
r.Get("/healthz", health.Handler)
// OpenAPI documentation (E11-02).
r.Get("/docs", health.DocsHTMLHandler)
r.Get("/docs/openapi.yaml", health.DocsYAMLHandler)
// Public PII playground — no JWT required (E8-15).
r.Get("/playground", health.PlaygroundHandler)
r.Post("/playground/analyze", health.PlaygroundAnalyzeHandler(piiClient, logger))
if cfg.Metrics.Enabled {
r.Get(cfg.Metrics.Path, promhttp.Handler().ServeHTTP)
}
r.Route("/v1", func(r chi.Router) {
r.Use(middleware.CORS(cfg.Server.AllowedOrigins))
var authMW func(http.Handler) http.Handler
if oidcVerifier != nil {
authMW = middleware.Auth(oidcVerifier)
} else {
authMW = middleware.Auth(&middleware.MockVerifier{
Claims: &middleware.UserClaims{
UserID: "dev-user",
TenantID: "00000000-0000-0000-0000-000000000001",
Email: "dev@veylant.local",
Roles: []string{"admin"},
},
})
logger.Warn("running in DEV mode — JWT validation is DISABLED")
}
r.Use(authMW)
r.Use(middleware.RateLimit(rateLimiter))
r.Post("/chat/completions", proxyHandler.ServeHTTP)
// PII analyze endpoint for Playground (E8-11, Sprint 8).
piiAnalyzeHandler := pii.NewAnalyzeHandler(piiClient, logger)
r.Post("/pii/analyze", piiAnalyzeHandler.ServeHTTP)
// Admin API — routing policies + audit logs (Sprint 5 + Sprint 6)
// + user management + provider status (Sprint 8).
if routingEngine != nil {
var adminHandler *admin.Handler
if auditLogger != nil {
adminHandler = admin.NewWithAudit(
routing.NewPgStore(db, logger),
routingEngine.Cache(),
auditLogger,
logger,
)
} else {
adminHandler = admin.New(
routing.NewPgStore(db, logger),
routingEngine.Cache(),
logger,
)
}
// Wire db, router, rate limiter, and feature flags (Sprint 8 + Sprint 10 + Sprint 11).
adminHandler.WithDB(db).WithRouter(providerRouter).WithRateLimiter(rateLimiter).WithFlagStore(flagStore)
r.Route("/admin", adminHandler.Routes)
}
// Compliance module — GDPR Art. 30 registry + AI Act classification + PDF reports (Sprint 9).
if db != nil {
compStore := compliance.NewPgStore(db, logger)
compHandler := compliance.New(compStore, logger).
WithAudit(auditLogger).
WithDB(db).
WithTenantName(cfg.Server.TenantName)
r.Route("/admin/compliance", compHandler.Routes)
logger.Info("compliance module started")
}
})
// ── HTTP server ───────────────────────────────────────────────────────────
addr := fmt.Sprintf(":%d", cfg.Server.Port)
srv := &http.Server{
Addr: addr,
Handler: r,
ReadTimeout: 30 * time.Second,
WriteTimeout: 30 * time.Second,
IdleTimeout: 120 * time.Second,
}
quit := make(chan os.Signal, 1)
signal.Notify(quit, syscall.SIGTERM, syscall.SIGINT)
go func() {
logger.Info("Veylant IA proxy started",
zap.String("addr", addr),
zap.String("env", cfg.Server.Env),
zap.Bool("metrics", cfg.Metrics.Enabled),
zap.String("oidc_issuer", issuerURL),
zap.Bool("audit_logging", auditLogger != nil),
zap.Bool("encryption", encryptor != nil),
)
if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
logger.Fatal("server error", zap.Error(err))
}
}()
<-quit
logger.Info("shutdown signal received, draining connections...")
if routingEngine != nil {
routingEngine.Stop()
}
timeout := time.Duration(cfg.Server.ShutdownTimeout) * time.Second
shutdownCtx, cancel := context.WithTimeout(context.Background(), timeout)
defer cancel()
if err := srv.Shutdown(shutdownCtx); err != nil {
logger.Error("graceful shutdown failed", zap.Error(err))
os.Exit(1)
}
logger.Info("server stopped cleanly")
}
func buildLogger(level, format string) *zap.Logger {
lvl := zap.InfoLevel
if err := lvl.UnmarshalText([]byte(level)); err != nil {
lvl = zap.InfoLevel
}
encoderCfg := zap.NewProductionEncoderConfig()
encoderCfg.TimeKey = "timestamp"
encoderCfg.EncodeTime = zapcore.ISO8601TimeEncoder
encoding := "json"
if format == "console" {
encoding = "console"
}
zapCfg := zap.Config{
Level: zap.NewAtomicLevelAt(lvl),
Development: false,
Encoding: encoding,
EncoderConfig: encoderCfg,
OutputPaths: []string{"stdout"},
ErrorOutputPaths: []string{"stderr"},
}
logger, err := zapCfg.Build()
if err != nil {
panic(fmt.Sprintf("failed to build logger: %v", err))
}
return logger
}

115
config.yaml Normal file
View File

@ -0,0 +1,115 @@
server:
port: 8090
shutdown_timeout_seconds: 30
env: development
tenant_name: "Mon Organisation"
# CORS: origins allowed to call the proxy from a browser (React dashboard).
# Override in production: VEYLANT_SERVER_ALLOWED_ORIGINS=https://dashboard.veylant.ai
allowed_origins:
- "http://localhost:3000"
database:
url: "postgres://veylant:veylant_dev@localhost:5432/veylant?sslmode=disable"
max_open_conns: 25
max_idle_conns: 5
migrations_path: "migrations"
redis:
url: "redis://localhost:6379"
keycloak:
base_url: "http://localhost:8080"
realm: "veylant"
client_id: "veylant-proxy"
pii:
enabled: true
service_addr: "localhost:50051"
timeout_ms: 100
fail_open: true
log:
level: "info"
format: "json"
# LLM provider adapters.
# Sensitive values (API keys) must be injected via env vars — never hardcode them.
# Example: VEYLANT_PROVIDERS_OPENAI_API_KEY=sk-...
providers:
openai:
base_url: "https://api.openai.com/v1"
timeout_seconds: 30
max_conns: 100
anthropic:
base_url: "https://api.anthropic.com/v1"
version: "2023-06-01"
timeout_seconds: 30
max_conns: 100
# api_key: set via VEYLANT_PROVIDERS_ANTHROPIC_API_KEY
azure:
api_version: "2024-02-01"
timeout_seconds: 30
max_conns: 100
# api_key: set via VEYLANT_PROVIDERS_AZURE_API_KEY
# resource_name: set via VEYLANT_PROVIDERS_AZURE_RESOURCE_NAME (e.g. "my-azure-resource")
# deployment_id: set via VEYLANT_PROVIDERS_AZURE_DEPLOYMENT_ID (e.g. "gpt-4o")
mistral:
base_url: "https://api.mistral.ai/v1"
timeout_seconds: 30
max_conns: 100
# api_key: set via VEYLANT_PROVIDERS_MISTRAL_API_KEY
ollama:
base_url: "http://localhost:11434/v1"
timeout_seconds: 120
max_conns: 10
# Role-based access control for the provider router.
# Controls which models each role can access.
rbac:
# Models accessible to the "user" role (exact match or prefix, e.g. "gpt-4o-mini" matches "gpt-4o-mini-2024-07-18").
# admin and manager roles always have unrestricted access.
user_allowed_models:
- "gpt-4o-mini"
- "gpt-3.5-turbo"
- "mistral-small"
# If false (default), auditors receive 403 on /v1/chat/completions.
auditor_can_complete: false
metrics:
enabled: true
path: "/metrics"
# Intelligent routing engine.
# Rules are stored in the routing_rules table and cached per tenant.
routing:
# How long routing rules are cached in memory before a background refresh.
# Admin mutations call Invalidate() immediately regardless of this TTL.
cache_ttl_seconds: 30
# ClickHouse audit log (Sprint 6).
# DSN: clickhouse://user:pass@host:9000/database
# Set via env var: VEYLANT_CLICKHOUSE_DSN
clickhouse:
dsn: "clickhouse://veylant:veylant_dev@localhost:9000/veylant_logs"
max_conns: 10
dial_timeout_seconds: 5
# Cryptography settings.
# AES-256-GCM key for encrypting prompt_anonymized in the audit log.
# MUST be set via env var in production: VEYLANT_CRYPTO_AES_KEY_BASE64
# Generate: openssl rand -base64 32
crypto:
# Development placeholder — override in production via env var.
aes_key_base64: ""
# Rate limiting defaults. Per-tenant overrides are stored in rate_limit_configs table.
# Override via env: VEYLANT_RATE_LIMIT_DEFAULT_TENANT_RPM, VEYLANT_RATE_LIMIT_DEFAULT_USER_RPM, etc.
rate_limit:
default_tenant_rpm: 1000
default_tenant_burst: 200
default_user_rpm: 100
default_user_burst: 20

132
deploy/alertmanager/alertmanager.yml Normal file
View File

@ -0,0 +1,132 @@
global:
# Default timeout for receivers.
resolve_timeout: 5m
# Slack default settings (overridden per receiver if needed).
slack_api_url: "https://hooks.slack.com/services/PLACEHOLDER"
# Templates for Slack message formatting.
templates:
- "/etc/alertmanager/templates/*.tmpl"
# ──────────────────────────────────────────────────────────────────────────────
# Routing tree
# ──────────────────────────────────────────────────────────────────────────────
route:
# Default receiver: all alerts go to Slack unless matched by a child route.
receiver: slack-default
# Group alerts by alert name and provider to avoid alert spam.
group_by: [alertname, provider]
# Wait 30s before sending the first notification (allows grouping).
group_wait: 30s
# Wait 5m before sending a notification about new alerts in an existing group.
group_interval: 5m
# Resend a notification every 4h if the alert is still firing.
repeat_interval: 4h
routes:
# Critical alerts → PagerDuty (on-call escalation).
- match:
severity: critical
receiver: pagerduty
# Critical alerts bypass grouping delays — notify immediately.
group_wait: 10s
repeat_interval: 1h
continue: false
# Warning alerts → dedicated Slack channel.
- match:
severity: warning
receiver: slack-warnings
continue: false
# ──────────────────────────────────────────────────────────────────────────────
# Inhibition rules
# ──────────────────────────────────────────────────────────────────────────────
inhibit_rules:
# If a critical alert fires for a provider, suppress warnings for the same provider.
# Avoids noise when a provider is fully down (circuit breaker + latency fire together).
- source_match:
severity: critical
target_match:
severity: warning
equal: [provider]
# If ProxyDown fires, suppress all other alerts (proxy is the root cause).
- source_match:
alertname: VeylantProxyDown
target_match_re:
alertname: ".+"
equal: []
# ──────────────────────────────────────────────────────────────────────────────
# Receivers
# ──────────────────────────────────────────────────────────────────────────────
receivers:
# Default Slack channel — catch-all for uncategorised alerts.
- name: slack-default
slack_configs:
- channel: "#veylant-alerts"
send_resolved: true
username: "Veylant Alertmanager"
icon_emoji: ":warning:"
title: >-
{{ if eq .Status "firing" }}🔴{{ else }}✅{{ end }}
[{{ .Status | toUpper }}] {{ .CommonLabels.alertname }}
text: >-
{{ range .Alerts }}
*Alert:* {{ .Annotations.summary }}
*Description:* {{ .Annotations.description }}
*Provider:* {{ .Labels.provider | default "N/A" }}
*Severity:* {{ .Labels.severity }}
*Runbook:* {{ .Annotations.runbook | default "N/A" }}
{{ end }}
# Warning channel — operational warnings, lower urgency.
- name: slack-warnings
slack_configs:
- channel: "#veylant-warnings"
send_resolved: true
username: "Veylant Alertmanager"
icon_emoji: ":yellow_circle:"
title: >-
{{ if eq .Status "firing" }}🟡{{ else }}✅{{ end }}
[{{ .Status | toUpper }}] {{ .CommonLabels.alertname }}
text: >-
{{ range .Alerts }}
*Alert:* {{ .Annotations.summary }}
*Description:* {{ .Annotations.description }}
*Runbook:* {{ .Annotations.runbook | default "N/A" }}
{{ end }}
# PagerDuty — critical on-call escalation.
- name: pagerduty
pagerduty_configs:
- routing_key: "${PAGERDUTY_INTEGRATION_KEY}"
severity: >-
{{ if eq .CommonLabels.severity "critical" }}critical{{ else }}warning{{ end }}
description: "{{ .CommonAnnotations.summary }}"
details:
alertname: "{{ .CommonLabels.alertname }}"
provider: "{{ .CommonLabels.provider }}"
description: "{{ .CommonAnnotations.description }}"
runbook: "{{ .CommonAnnotations.runbook }}"
# Also notify Slack for visibility.
slack_configs:
- channel: "#veylant-critical"
send_resolved: true
username: "Veylant Alertmanager"
icon_emoji: ":red_circle:"
title: >-
{{ if eq .Status "firing" }}🚨 CRITICAL{{ else }}✅ RESOLVED{{ end }}:
{{ .CommonLabels.alertname }}
text: >-
*PagerDuty escalated.*
{{ range .Alerts }}
*Summary:* {{ .Annotations.summary }}
*Description:* {{ .Annotations.description }}
*Runbook:* {{ .Annotations.runbook | default "N/A" }}
{{ end }}

256
deploy/grafana/dashboards/production-slo.json Normal file
View File

@ -0,0 +1,256 @@
{
"title": "Veylant — Production SLO & Error Budget",
"uid": "veylant-production-slo",
"schemaVersion": 38,
"version": 1,
"refresh": "1m",
"time": { "from": "now-30d", "to": "now" },
"tags": ["slo", "production", "veylant"],
"panels": [
{
"id": 1,
"title": "Uptime SLO — 30-day rolling (target: 99.5%)",
"type": "gauge",
"gridPos": { "h": 8, "w": 6, "x": 0, "y": 0 },
"options": {
"reduceOptions": { "calcs": ["lastNotNull"] },
"orientation": "auto",
"showThresholdLabels": true,
"showThresholdMarkers": true
},
"fieldConfig": {
"defaults": {
"unit": "percentunit",
"min": 0.99,
"max": 1,
"thresholds": {
"mode": "absolute",
"steps": [
{ "color": "red", "value": null },
{ "color": "yellow", "value": 0.995 },
{ "color": "green", "value": 0.999 }
]
}
}
},
"targets": [
{
"expr": "1 - (sum(increase(veylant_request_errors_total[30d])) / sum(increase(veylant_requests_total[30d])))",
"legendFormat": "Uptime SLO"
}
]
},
{
"id": 2,
"title": "Error Budget Remaining (minutes)",
"description": "SLO target: 99.5% uptime over 30 days = 216 min allowed downtime",
"type": "stat",
"gridPos": { "h": 8, "w": 6, "x": 6, "y": 0 },
"options": {
"reduceOptions": { "calcs": ["lastNotNull"] },
"colorMode": "background"
},
"fieldConfig": {
"defaults": {
"unit": "m",
"thresholds": {
"mode": "absolute",
"steps": [
{ "color": "red", "value": null },
{ "color": "yellow", "value": 43 },
{ "color": "green", "value": 108 }
]
}
}
},
"targets": [
{
"expr": "(0.005 * 30 * 24 * 60) - (sum(increase(veylant_request_errors_total[30d])) / sum(increase(veylant_requests_total[30d])) * 30 * 24 * 60)",
"legendFormat": "Budget remaining (min)"
}
]
},
{
"id": 3,
"title": "p99 Latency SLO (target: < 500ms)",
"type": "gauge",
"gridPos": { "h": 8, "w": 6, "x": 12, "y": 0 },
"options": {
"reduceOptions": { "calcs": ["lastNotNull"] },
"orientation": "auto",
"showThresholdMarkers": true
},
"fieldConfig": {
"defaults": {
"unit": "s",
"thresholds": {
"mode": "absolute",
"steps": [
{ "color": "green", "value": null },
{ "color": "yellow", "value": 0.3 },
{ "color": "red", "value": 0.5 }
]
}
}
},
"targets": [
{
"expr": "histogram_quantile(0.99, sum by (le) (rate(veylant_request_duration_seconds_bucket[5m])))",
"legendFormat": "p99 latency"
}
]
},
{
"id": 4,
"title": "Active Alerts",
"type": "stat",
"gridPos": { "h": 8, "w": 6, "x": 18, "y": 0 },
"options": {
"reduceOptions": { "calcs": ["lastNotNull"] },
"colorMode": "background"
},
"fieldConfig": {
"defaults": {
"thresholds": {
"mode": "absolute",
"steps": [
{ "color": "green", "value": null },
{ "color": "yellow", "value": 1 },
{ "color": "red", "value": 3 }
]
}
}
},
"targets": [
{
"expr": "sum(ALERTS{alertstate=\"firing\",job=~\"veylant.*\"})",
"legendFormat": "Firing alerts"
}
]
},
{
"id": 5,
"title": "PII Entities Detected — Rate by Type (per min)",
"type": "timeseries",
"gridPos": { "h": 8, "w": 12, "x": 0, "y": 8 },
"targets": [
{
"expr": "sum by (entity_type) (rate(veylant_pii_entities_detected_total[1m])) * 60",
"legendFormat": "{{ entity_type }}"
}
],
"fieldConfig": {
"defaults": {
"unit": "short",
"custom": { "lineWidth": 2 }
}
}
},
{
"id": 6,
"title": "PostgreSQL Active Connections",
"type": "timeseries",
"gridPos": { "h": 8, "w": 12, "x": 12, "y": 8 },
"targets": [
{
"expr": "veylant_db_connections_active",
"legendFormat": "Active connections"
},
{
"expr": "veylant_db_connections_idle",
"legendFormat": "Idle connections"
}
],
"fieldConfig": {
"defaults": {
"unit": "short",
"thresholds": {
"mode": "absolute",
"steps": [
{ "color": "green", "value": null },
{ "color": "yellow", "value": 15 },
{ "color": "red", "value": 20 }
]
}
}
}
},
{
"id": 7,
"title": "Provider RPS Breakdown",
"type": "piechart",
"gridPos": { "h": 8, "w": 8, "x": 0, "y": 16 },
"options": {
"pieType": "donut",
"displayLabels": ["name", "percent"]
},
"targets": [
{
"expr": "sum by (provider) (rate(veylant_requests_total[5m]))",
"legendFormat": "{{ provider }}"
}
]
},
{
"id": 8,
"title": "Provider RPS — Time Series",
"type": "timeseries",
"gridPos": { "h": 8, "w": 16, "x": 8, "y": 16 },
"targets": [
{
"expr": "sum by (provider) (rate(veylant_requests_total[1m]))",
"legendFormat": "{{ provider }}"
}
],
"fieldConfig": {
"defaults": {
"unit": "reqps",
"custom": { "lineWidth": 2 }
}
}
},
{
"id": 9,
"title": "Redis Memory Usage %",
"type": "timeseries",
"gridPos": { "h": 8, "w": 12, "x": 0, "y": 24 },
"targets": [
{
"expr": "redis_memory_used_bytes / redis_memory_max_bytes * 100",
"legendFormat": "Redis memory %"
}
],
"fieldConfig": {
"defaults": {
"unit": "percent",
"thresholds": {
"mode": "absolute",
"steps": [
{ "color": "green", "value": null },
{ "color": "yellow", "value": 70 },
{ "color": "red", "value": 90 }
]
}
}
}
},
{
"id": 10,
"title": "Error Rate by Provider (5m avg)",
"type": "timeseries",
"gridPos": { "h": 8, "w": 12, "x": 12, "y": 24 },
"targets": [
{
"expr": "veylant:error_rate:5m * 100",
"legendFormat": "{{ provider }} error %"
}
],
"fieldConfig": {
"defaults": {
"unit": "percent",
"custom": { "lineWidth": 2 }
}
}
}
]
}

134
deploy/grafana/dashboards/proxy-overview.json Normal file
View File

@ -0,0 +1,134 @@
{
"title": "Veylant Proxy — Overview",
"uid": "veylant-proxy-overview",
"schemaVersion": 38,
"version": 1,
"refresh": "15s",
"panels": [
{
"id": 1,
"title": "Requests per second",
"type": "timeseries",
"gridPos": { "h": 8, "w": 12, "x": 0, "y": 0 },
"targets": [
{
"expr": "rate(veylant_requests_total[1m])",
"legendFormat": "{{method}} {{path}} {{status}}"
}
]
},
{
"id": 2,
"title": "Request duration p50/p95/p99 (seconds)",
"type": "timeseries",
"gridPos": { "h": 8, "w": 12, "x": 12, "y": 0 },
"targets": [
{
"expr": "histogram_quantile(0.50, rate(veylant_request_duration_seconds_bucket[1m]))",
"legendFormat": "p50"
},
{
"expr": "histogram_quantile(0.95, rate(veylant_request_duration_seconds_bucket[1m]))",
"legendFormat": "p95"
},
{
"expr": "histogram_quantile(0.99, rate(veylant_request_duration_seconds_bucket[1m]))",
"legendFormat": "p99"
}
]
},
{
"id": 3,
"title": "Error rate",
"type": "timeseries",
"gridPos": { "h": 8, "w": 12, "x": 0, "y": 8 },
"targets": [
{
"expr": "rate(veylant_request_errors_total[1m])",
"legendFormat": "{{error_type}}"
}
]
},
{
"id": 4,
"title": "Total requests (24h)",
"type": "stat",
"gridPos": { "h": 4, "w": 6, "x": 12, "y": 8 },
"targets": [
{
"expr": "sum(increase(veylant_requests_total[24h]))",
"legendFormat": "Total"
}
]
},
{
"id": 5,
"title": "Error rate % (24h)",
"type": "stat",
"gridPos": { "h": 4, "w": 6, "x": 18, "y": 8 },
"targets": [
{
"expr": "100 * sum(increase(veylant_request_errors_total[24h])) / sum(increase(veylant_requests_total[24h]))",
"legendFormat": "Error %"
}
]
},
{
"id": 6,
"title": "PII Entities Detected — Rate by Type",
"type": "timeseries",
"gridPos": { "h": 8, "w": 12, "x": 0, "y": 16 },
"targets": [
{
"expr": "sum by (entity_type) (rate(veylant_pii_entities_detected_total[1m]))",
"legendFormat": "{{ entity_type }}"
}
],
"fieldConfig": {
"defaults": {
"unit": "short",
"custom": { "lineWidth": 2 }
}
}
},
{
"id": 7,
"title": "PostgreSQL Active Connections",
"type": "timeseries",
"gridPos": { "h": 8, "w": 12, "x": 12, "y": 16 },
"targets": [
{
"expr": "veylant_db_connections_active",
"legendFormat": "Active"
},
{
"expr": "veylant_db_connections_idle",
"legendFormat": "Idle"
}
],
"fieldConfig": {
"defaults": {
"unit": "short"
}
}
},
{
"id": 8,
"title": "Provider Breakdown (RPS)",
"type": "piechart",
"gridPos": { "h": 8, "w": 8, "x": 0, "y": 24 },
"options": {
"pieType": "donut",
"displayLabels": ["name", "percent"]
},
"targets": [
{
"expr": "sum by (provider) (rate(veylant_requests_total[5m]))",
"legendFormat": "{{ provider }}"
}
]
}
],
"schemaVersion": 38,
"version": 2
}

11
deploy/grafana/provisioning/dashboards/dashboards.yml Normal file
View File

@ -0,0 +1,11 @@
apiVersion: 1
providers:
- name: "Veylant"
orgId: 1
folder: "Veylant IA"
type: file
disableDeletion: false
updateIntervalSeconds: 30
options:
path: /var/lib/grafana/dashboards

9
deploy/grafana/provisioning/datasources/prometheus.yml Normal file
View File

@ -0,0 +1,9 @@
apiVersion: 1
datasources:
- name: Prometheus
type: prometheus
access: proxy
url: http://prometheus:9090
isDefault: true
editable: false

13
deploy/helm/veylant-proxy/Chart.yaml Normal file
View File

@ -0,0 +1,13 @@
apiVersion: v2
name: veylant-proxy
description: Veylant IA — AI Governance Proxy
type: application
version: 1.0.0
appVersion: "1.0.0"
keywords:
- ai
- proxy
- governance
- pii
maintainers:
- name: Veylant Engineering

60
deploy/helm/veylant-proxy/templates/_helpers.tpl Normal file
View File

@ -0,0 +1,60 @@
{{/*
Expand the name of the chart.
*/}}
{{- define "veylant-proxy.name" -}}
{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
{{- end }}
{{/*
Create a default fully qualified app name.
*/}}
{{- define "veylant-proxy.fullname" -}}
{{- if .Values.fullnameOverride }}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- $name := default .Chart.Name .Values.nameOverride }}
{{- if contains $name .Release.Name }}
{{- .Release.Name | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
{{- end }}
{{- end }}
{{- end }}
{{/*
Common labels.
*/}}
{{- define "veylant-proxy.labels" -}}
helm.sh/chart: {{ include "veylant-proxy.chart" . }}
{{ include "veylant-proxy.selectorLabels" . }}
{{- if .Chart.AppVersion }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
{{- end }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}
{{/*
Selector labels.
*/}}
{{- define "veylant-proxy.selectorLabels" -}}
app.kubernetes.io/name: {{ include "veylant-proxy.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}
{{/*
Chart label.
*/}}
{{- define "veylant-proxy.chart" -}}
{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
{{- end }}
{{/*
Service account name.
*/}}
{{- define "veylant-proxy.serviceAccountName" -}}
{{- if .Values.serviceAccount.create }}
{{- default (include "veylant-proxy.fullname" .) .Values.serviceAccount.name }}
{{- else }}
{{- default "default" .Values.serviceAccount.name }}
{{- end }}
{{- end }}

18
deploy/helm/veylant-proxy/templates/configmap.yaml Normal file
View File

@ -0,0 +1,18 @@
apiVersion: v1
kind: ConfigMap
metadata:
name: {{ include "veylant-proxy.fullname" . }}-config
labels:
{{- include "veylant-proxy.labels" . | nindent 4 }}
data:
config.yaml: |
server:
port: {{ .Values.config.server.port }}
shutdown_timeout_seconds: {{ .Values.config.server.shutdown_timeout_seconds | default 30 }}
env: {{ .Values.config.server.env }}
log:
level: {{ .Values.config.log.level }}
format: {{ .Values.config.log.format }}
metrics:
enabled: {{ .Values.config.metrics.enabled }}
path: {{ .Values.config.metrics.path }}

64
deploy/helm/veylant-proxy/templates/deployment.yaml Normal file
View File

@ -0,0 +1,64 @@
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ include "veylant-proxy.fullname" . }}
labels:
{{- include "veylant-proxy.labels" . | nindent 4 }}
spec:
replicas: {{ .Values.replicaCount }}
selector:
matchLabels:
{{- include "veylant-proxy.selectorLabels" . | nindent 6 }}
template:
metadata:
labels:
{{- include "veylant-proxy.selectorLabels" . | nindent 8 }}
app.kubernetes.io/slot: {{ .Values.slot | default "blue" }}
spec:
serviceAccountName: {{ include "veylant-proxy.serviceAccountName" . }}
containers:
- name: proxy
image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
imagePullPolicy: {{ .Values.image.pullPolicy }}
ports:
- name: http
containerPort: {{ .Values.service.port }}
protocol: TCP
env:
- name: VEYLANT_SERVER_PORT
value: "{{ .Values.service.port }}"
- name: VEYLANT_PROVIDERS_OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: {{ .Values.secrets.openaiApiKeySecretName }}
key: {{ .Values.secrets.openaiApiKeySecretKey }}
- name: VEYLANT_DATABASE_URL
valueFrom:
secretKeyRef:
name: {{ .Values.secrets.databaseUrlSecretName }}
key: {{ .Values.secrets.databaseUrlSecretKey }}
volumeMounts:
- name: config
mountPath: /config.yaml
subPath: config.yaml
readOnly: true
livenessProbe:
httpGet:
path: /healthz
port: http
initialDelaySeconds: 5
periodSeconds: 10
failureThreshold: 3
readinessProbe:
httpGet:
path: /healthz
port: http
initialDelaySeconds: 3
periodSeconds: 5
failureThreshold: 3
resources:
{{- toYaml .Values.resources | nindent 12 }}
volumes:
- name: config
configMap:
name: {{ include "veylant-proxy.fullname" . }}-config

43
deploy/helm/veylant-proxy/templates/hpa.yaml Normal file
View File

@ -0,0 +1,43 @@
{{- if .Values.autoscaling.enabled }}
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
name: {{ include "veylant-proxy.fullname" . }}
labels:
{{- include "veylant-proxy.labels" . | nindent 4 }}
spec:
scaleTargetRef:
apiVersion: apps/v1
kind: Deployment
name: {{ include "veylant-proxy.fullname" . }}
minReplicas: {{ .Values.autoscaling.minReplicas }}
maxReplicas: {{ .Values.autoscaling.maxReplicas }}
metrics:
- type: Resource
resource:
name: cpu
target:
type: Utilization
averageUtilization: {{ .Values.autoscaling.targetCPUUtilizationPercentage | default 70 }}
- type: Resource
resource:
name: memory
target:
type: Utilization
averageUtilization: {{ .Values.autoscaling.targetMemoryUtilizationPercentage | default 80 }}
behavior:
scaleUp:
# React quickly to traffic spikes — allow doubling replicas every 60s.
stabilizationWindowSeconds: 30
policies:
- type: Percent
value: 100
periodSeconds: 60
scaleDown:
# Scale down conservatively to avoid oscillation.
stabilizationWindowSeconds: 300
policies:
- type: Percent
value: 25
periodSeconds: 60
{{- end }}

16
deploy/helm/veylant-proxy/templates/poddisruptionbudget.yaml Normal file
View File

@ -0,0 +1,16 @@
{{- if gt (int .Values.replicaCount) 1 }}
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
name: {{ include "veylant-proxy.fullname" . }}
labels:
{{- include "veylant-proxy.labels" . | nindent 4 }}
spec:
# Ensure at least 1 pod remains available during voluntary disruptions
# (node drains, rolling updates). This guarantees zero-downtime for the
# active slot during a blue/green switch.
minAvailable: 1
selector:
matchLabels:
{{- include "veylant-proxy.selectorLabels" . | nindent 6 }}
{{- end }}

15
deploy/helm/veylant-proxy/templates/service.yaml Normal file
View File

@ -0,0 +1,15 @@
apiVersion: v1
kind: Service
metadata:
name: {{ include "veylant-proxy.fullname" . }}
labels:
{{- include "veylant-proxy.labels" . | nindent 4 }}
spec:
type: {{ .Values.service.type }}
ports:
- port: {{ .Values.service.port }}
targetPort: http
protocol: TCP
name: http
selector:
{{- include "veylant-proxy.selectorLabels" . | nindent 4 }}

8
deploy/helm/veylant-proxy/values-blue.yaml Normal file
View File

@ -0,0 +1,8 @@
# values-blue.yaml — overrides for the blue deployment slot.
# Usage:
# helm upgrade --install veylant-proxy-blue deploy/helm/veylant-proxy \
# -f deploy/helm/veylant-proxy/values-blue.yaml \
# --set image.tag=<sha> --namespace veylant
slot: blue
replicaCount: 2

8
deploy/helm/veylant-proxy/values-green.yaml Normal file
View File

@ -0,0 +1,8 @@
# values-green.yaml — overrides for the green deployment slot.
# Usage:
# helm upgrade --install veylant-proxy-green deploy/helm/veylant-proxy \
# -f deploy/helm/veylant-proxy/values-green.yaml \
# --set image.tag=<sha> --namespace veylant
slot: green
replicaCount: 2

94
deploy/helm/veylant-proxy/values-production.yaml Normal file
View File

@ -0,0 +1,94 @@
# Production overrides for veylant-proxy Helm chart.
# Apply with: helm upgrade veylant-proxy-blue deploy/helm/veylant-proxy \
# -f deploy/helm/veylant-proxy/values-production.yaml \
# -f deploy/helm/veylant-proxy/values-blue.yaml \
# --set image.tag=$IMAGE_TAG
# 3 replicas — 1 per Availability Zone (eu-west-3a/3b/3c).
replicaCount: 3
# Deployment slot (overridden at deploy time by values-blue.yaml / values-green.yaml).
slot: blue
image:
repository: ghcr.io/veylant/ia-gateway
pullPolicy: IfNotPresent
tag: "" # Set via --set image.tag=$GITHUB_SHA
serviceAccount:
create: true
name: ""
service:
type: ClusterIP
port: 8090
# Production resource profile — tuned for t3.medium nodes.
resources:
requests:
cpu: 250m
memory: 256Mi
limits:
cpu: 1000m
memory: 512Mi
# HPA enabled for production — scales between 3 and 15 replicas.
autoscaling:
enabled: true
minReplicas: 3
maxReplicas: 15
targetCPUUtilizationPercentage: 70
targetMemoryUtilizationPercentage: 80
# Application configuration — production settings.
config:
server:
port: 8090
shutdown_timeout_seconds: 30
env: production
allowed_origins:
- "https://dashboard.veylant.ai"
log:
level: warn # Reduced verbosity in production; errors + warnings only
format: json
pii:
enabled: true
fail_open: false # PII failure blocks request in production
timeout_ms: 100
metrics:
enabled: true
path: /metrics
# Secret references — created via Vault Agent Injector annotations.
secrets:
openaiApiKeySecretName: veylant-proxy-secrets
openaiApiKeySecretKey: openai-api-key
databaseUrlSecretName: veylant-proxy-secrets
databaseUrlSecretKey: database-url
# Enable Prometheus ServiceMonitor for production scraping.
metrics:
serviceMonitor:
enabled: true
interval: 15s
path: /metrics
# Pod topology spread — ensure pods spread across AZs.
topologySpreadConstraints:
- maxSkew: 1
topologyKey: topology.kubernetes.io/zone
whenUnsatisfiable: DoNotSchedule
labelSelector:
matchLabels:
app.kubernetes.io/name: veylant-proxy
# Pod anti-affinity — avoid co-location on same node.
affinity:
podAntiAffinity:
preferredDuringSchedulingIgnoredDuringExecution:
- weight: 100
podAffinityTerm:
labelSelector:
matchLabels:
app.kubernetes.io/name: veylant-proxy
topologyKey: kubernetes.io/hostname

67
deploy/helm/veylant-proxy/values.yaml Normal file
View File

@ -0,0 +1,67 @@
# Default values for veylant-proxy.
# Override in staging/production via --set or a values-<env>.yaml file.
# For blue/green deployments use values-blue.yaml / values-green.yaml.
replicaCount: 2
# Deployment slot for blue/green strategy. Used as an Istio DestinationRule subset
# label. Must be "blue" or "green". Override via values-blue.yaml / values-green.yaml.
slot: blue
image:
repository: ghcr.io/veylant/ia-gateway
pullPolicy: IfNotPresent
tag: "" # Defaults to Chart.appVersion if empty
serviceAccount:
create: true
name: ""
service:
type: ClusterIP
port: 8090
resources:
limits:
cpu: 500m
memory: 256Mi
requests:
cpu: 100m
memory: 128Mi
autoscaling:
enabled: false
minReplicas: 2
maxReplicas: 10
targetCPUUtilizationPercentage: 70
targetMemoryUtilizationPercentage: 80
# Application configuration (mounted as config.yaml via ConfigMap).
# Sensitive values (API keys, DB passwords) must be provided via Kubernetes
# Secrets and referenced via env vars (e.g. VEYLANT_PROVIDERS_OPENAI_API_KEY).
config:
server:
port: 8090
shutdown_timeout_seconds: 30
env: staging
log:
level: info
format: json
metrics:
enabled: true
path: /metrics
# References to Kubernetes Secret keys for sensitive environment variables.
# These secrets must be created separately (e.g. via Vault Agent Injector).
secrets:
openaiApiKeySecretName: veylant-proxy-secrets
openaiApiKeySecretKey: openai-api-key
databaseUrlSecretName: veylant-proxy-secrets
databaseUrlSecretKey: database-url
# Prometheus ServiceMonitor (requires prometheus-operator CRDs).
metrics:
serviceMonitor:
enabled: false
interval: 15s
path: /metrics

81
deploy/k8s/istio/peer-auth.yaml Normal file
View File

@ -0,0 +1,81 @@
# Istio mTLS configuration for the veylant namespace (E10-01).
# Enforces STRICT mutual TLS for all service-to-service communication.
# Prerequisites: Istio installed with sidecar injection enabled on the namespace.
# kubectl label namespace veylant istio-injection=enabled
# Apply: kubectl apply -f deploy/k8s/istio/peer-auth.yaml
---
# STRICT PeerAuthentication: all inbound connections must use mTLS.
# Pods without a valid certificate will be rejected.
apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
name: default
namespace: veylant
spec:
mtls:
mode: STRICT
---
# DestinationRule: require mTLS for traffic to the proxy.
apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
name: veylant-proxy-mtls
namespace: veylant
spec:
host: veylant-proxy.veylant.svc.cluster.local
trafficPolicy:
tls:
mode: ISTIO_MUTUAL
---
# DestinationRule: require mTLS for traffic to the PII service.
apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
name: pii-service-mtls
namespace: veylant
spec:
host: pii-service.veylant.svc.cluster.local
trafficPolicy:
tls:
mode: ISTIO_MUTUAL
---
# DestinationRule: require mTLS for traffic to PostgreSQL.
apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
name: postgres-mtls
namespace: veylant
spec:
host: postgres.veylant.svc.cluster.local
trafficPolicy:
tls:
mode: ISTIO_MUTUAL
---
# DestinationRule: require mTLS for traffic to Redis.
apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
name: redis-mtls
namespace: veylant
spec:
host: redis.veylant.svc.cluster.local
trafficPolicy:
tls:
mode: ISTIO_MUTUAL
---
# DestinationRule: require mTLS for traffic to ClickHouse.
apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
name: clickhouse-mtls
namespace: veylant
spec:
host: clickhouse.veylant.svc.cluster.local
trafficPolicy:
tls:
mode: ISTIO_MUTUAL

71
deploy/k8s/istio/virtual-service.yaml Normal file
View File

@ -0,0 +1,71 @@
# Istio VirtualService + DestinationRule for blue/green traffic switching.
#
# Traffic flow:
# Client → Istio Ingress Gateway → VirtualService → DestinationRule subset → Pod
#
# Two releases coexist at all times:
# veylant-proxy-blue (helm release, slot=blue label)
# veylant-proxy-green (helm release, slot=green label)
#
# Switch traffic atomically (rollback < 5s):
# # Switch to green:
# kubectl patch vs veylant-proxy -n veylant --type merge \
# -p '{"spec":{"http":[{"route":[{"destination":{"host":"veylant-proxy","subset":"green"},"weight":100}]}]}}'
# # Roll back to blue:
# kubectl patch vs veylant-proxy -n veylant --type merge \
# -p '{"spec":{"http":[{"route":[{"destination":{"host":"veylant-proxy","subset":"blue"},"weight":100}]}]}}'
#
# Managed automatically by deploy/scripts/blue-green.sh.
---
apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
name: veylant-proxy
namespace: veylant
spec:
hosts:
- veylant-proxy
- api.veylant.ai # external hostname (TLS terminated at Gateway)
gateways:
- veylant-gateway
- mesh # also applies to in-cluster traffic
http:
- match:
- uri:
prefix: /
route:
# Default: 100% to blue slot.
# blue-green.sh patches this to switch slots atomically.
- destination:
host: veylant-proxy
subset: blue
weight: 100
timeout: 35s # slightly > proxy WriteTimeout (30s)
retries:
attempts: 2
perTryTimeout: 15s
retryOn: gateway-error,connect-failure,retriable-4xx
---
apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
name: veylant-proxy
namespace: veylant
spec:
host: veylant-proxy
trafficPolicy:
connectionPool:
http:
h2UpgradePolicy: UPGRADE
idleTimeout: 90s
outlierDetection:
consecutiveGatewayErrors: 5
interval: 10s
baseEjectionTime: 30s
subsets:
- name: blue
labels:
app.kubernetes.io/slot: blue
- name: green
labels:
app.kubernetes.io/slot: green

147
deploy/k8s/network-policies.yaml Normal file
View File

@ -0,0 +1,147 @@
# Network policies for the veylant namespace (E10-02).
# Strategy: default-deny-all, then explicit whitelist per service.
# Apply: kubectl apply -f deploy/k8s/network-policies.yaml -n veylant
---
# Default deny all ingress and egress within the namespace.
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: default-deny-all
namespace: veylant
spec:
podSelector: {}
policyTypes:
- Ingress
- Egress
---
# Allow inbound HTTP traffic to the proxy from the ingress controller only.
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: allow-proxy-ingress
namespace: veylant
spec:
podSelector:
matchLabels:
app: veylant-proxy
policyTypes:
- Ingress
ingress:
- from:
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: ingress-nginx
ports:
- protocol: TCP
port: 8090
---
# Allow the proxy to call the PII sidecar gRPC service.
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: allow-proxy-to-pii
namespace: veylant
spec:
podSelector:
matchLabels:
app: veylant-proxy
policyTypes:
- Egress
egress:
- to:
- podSelector:
matchLabels:
app: pii-service
ports:
- protocol: TCP
port: 50051
---
# Allow the proxy to connect to PostgreSQL.
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: allow-proxy-to-postgres
namespace: veylant
spec:
podSelector:
matchLabels:
app: veylant-proxy
policyTypes:
- Egress
egress:
- to:
- podSelector:
matchLabels:
app: postgres
ports:
- protocol: TCP
port: 5432
---
# Allow the proxy to connect to ClickHouse for audit logging.
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: allow-proxy-to-clickhouse
namespace: veylant
spec:
podSelector:
matchLabels:
app: veylant-proxy
policyTypes:
- Egress
egress:
- to:
- podSelector:
matchLabels:
app: clickhouse
ports:
- protocol: TCP
port: 9000
---
# Allow the proxy to connect to Redis (rate limiting + PII pseudonym cache).
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: allow-proxy-to-redis
namespace: veylant
spec:
podSelector:
matchLabels:
app: veylant-proxy
policyTypes:
- Egress
egress:
- to:
- podSelector:
matchLabels:
app: redis
ports:
- protocol: TCP
port: 6379
---
# Allow DNS resolution (CoreDNS) for all pods.
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: allow-dns-egress
namespace: veylant
spec:
podSelector: {}
policyTypes:
- Egress
egress:
- to:
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: kube-system
ports:
- protocol: UDP
port: 53
- protocol: TCP
port: 53

119
deploy/k8s/production/postgres-backup.yaml Normal file
View File

@ -0,0 +1,119 @@
apiVersion: batch/v1
kind: CronJob
metadata:
name: veylant-postgres-backup
namespace: veylant
labels:
app.kubernetes.io/name: veylant-postgres-backup
app.kubernetes.io/component: backup
spec:
# Run daily at 02:00 UTC — off-peak for EU West.
schedule: "0 2 * * *"
concurrencyPolicy: Forbid
successfulJobsHistoryLimit: 7
failedJobsHistoryLimit: 3
jobTemplate:
spec:
# Retry once on failure before marking as failed.
backoffLimit: 1
template:
metadata:
labels:
app.kubernetes.io/name: veylant-postgres-backup
annotations:
# Vault Agent Injector — inject secrets from Vault.
vault.hashicorp.com/agent-inject: "true"
vault.hashicorp.com/role: "veylant-backup"
vault.hashicorp.com/agent-inject-secret-db: "secret/veylant/production/db"
vault.hashicorp.com/agent-inject-template-db: |
{{- with secret "secret/veylant/production/db" -}}
export PGPASSWORD="{{ .Data.data.password }}"
export PGUSER="{{ .Data.data.username }}"
export PGHOST="{{ .Data.data.host }}"
export PGDATABASE="{{ .Data.data.dbname }}"
{{- end }}
vault.hashicorp.com/agent-inject-secret-aws: "secret/veylant/production/aws"
vault.hashicorp.com/agent-inject-template-aws: |
{{- with secret "secret/veylant/production/aws" -}}
export AWS_ACCESS_KEY_ID="{{ .Data.data.access_key_id }}"
export AWS_SECRET_ACCESS_KEY="{{ .Data.data.secret_access_key }}"
export AWS_DEFAULT_REGION="{{ .Data.data.region }}"
{{- end }}
spec:
restartPolicy: OnFailure
serviceAccountName: veylant-backup
securityContext:
runAsNonRoot: true
runAsUser: 999
fsGroup: 999
containers:
- name: pg-backup
image: postgres:16-alpine
imagePullPolicy: IfNotPresent
resources:
requests:
cpu: 100m
memory: 128Mi
limits:
cpu: 500m
memory: 256Mi
env:
- name: S3_BUCKET
value: "veylant-backups-production"
- name: BACKUP_PREFIX
value: "postgres"
command:
- /bin/sh
- -c
- |
set -euo pipefail
# Load secrets injected by Vault Agent.
source /vault/secrets/db
source /vault/secrets/aws
# Install AWS CLI (not in postgres:16-alpine by default).
apk add --no-cache aws-cli 2>/dev/null || true
TIMESTAMP=$(date -u +"%Y%m%d_%H%M%S")
FILENAME="${BACKUP_PREFIX}_${TIMESTAMP}.sql.gz"
S3_PATH="s3://${S3_BUCKET}/${BACKUP_PREFIX}/${FILENAME}"
echo "[$(date -u)] Starting backup: ${FILENAME}"
# Dump and compress — pipe directly to S3 without storing locally.
pg_dump \
--host="${PGHOST}" \
--username="${PGUSER}" \
--dbname="${PGDATABASE}" \
--format=plain \
--no-password \
--verbose \
| gzip -9 \
| aws s3 cp - "${S3_PATH}" \
--storage-class STANDARD_IA \
--metadata "created-by=veylant-backup,db=${PGDATABASE}"
echo "[$(date -u)] Backup completed: ${S3_PATH}"
# Verify the upload is readable.
aws s3 ls "${S3_PATH}" || { echo "Upload verification failed"; exit 1; }
echo "[$(date -u)] Backup verified successfully."
---
# S3 Lifecycle policy is managed in Terraform (deploy/terraform/main.tf).
# Retention: 7 daily backups kept automatically via S3 lifecycle rules.
# Manual restore: aws s3 cp s3://veylant-backups-production/postgres/<file> - | gunzip | psql
---
apiVersion: v1
kind: ServiceAccount
metadata:
name: veylant-backup
namespace: veylant
labels:
app.kubernetes.io/name: veylant-backup
annotations:
# AWS IRSA — IAM role for S3 write access (created in Terraform).
eks.amazonaws.com/role-arn: "arn:aws:iam::ACCOUNT_ID:role/veylant-backup-role"

50
deploy/k8s/vault/secret-provider.yaml Normal file
View File

@ -0,0 +1,50 @@
# SecretProviderClass — mounts Vault secrets as files via the CSI driver (E10-03).
# Prerequisites: secrets-store-csi-driver + vault-provider installed in the cluster.
# helm install csi secrets-store-csi-driver/secrets-store-csi-driver -n kube-system
# helm install vault-csi hashicorp/vault --set "csi.enabled=true"
# Apply: kubectl apply -f deploy/k8s/vault/secret-provider.yaml -n veylant
---
apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
name: veylant-secrets
namespace: veylant
spec:
provider: vault
parameters:
# Vault server address.
vaultAddress: "https://vault.vault.svc.cluster.local:8200"
# Vault role bound to the proxy ServiceAccount.
roleName: "veylant-proxy"
# Secrets to mount as files under /mnt/secrets-store/.
objects: |
- objectName: "openai-api-key"
secretPath: "secret/data/veylant/llm-keys"
secretKey: "openai_api_key"
- objectName: "anthropic-api-key"
secretPath: "secret/data/veylant/llm-keys"
secretKey: "anthropic_api_key"
- objectName: "mistral-api-key"
secretPath: "secret/data/veylant/llm-keys"
secretKey: "mistral_api_key"
- objectName: "aes-key-base64"
secretPath: "secret/data/veylant/crypto"
secretKey: "aes_key_base64"
- objectName: "db-url"
secretPath: "secret/data/veylant/database"
secretKey: "url"
# Sync secrets to Kubernetes Secret for env-var injection.
secretObjects:
- secretName: veylant-llm-keys
type: Opaque
data:
- objectName: openai-api-key
key: VEYLANT_PROVIDERS_OPENAI_API_KEY
- objectName: anthropic-api-key
key: VEYLANT_PROVIDERS_ANTHROPIC_API_KEY
- objectName: mistral-api-key
key: VEYLANT_PROVIDERS_MISTRAL_API_KEY
- objectName: aes-key-base64
key: VEYLANT_CRYPTO_AES_KEY_BASE64
- objectName: db-url
key: VEYLANT_DATABASE_URL

22
deploy/k8s/vault/serviceaccount.yaml Normal file
View File

@ -0,0 +1,22 @@
# Kubernetes ServiceAccount for the Veylant proxy pod (E10-03).
# Vault authenticates the proxy using this SA's JWT token (Kubernetes auth method).
# Apply: kubectl apply -f deploy/k8s/vault/serviceaccount.yaml -n veylant
---
apiVersion: v1
kind: ServiceAccount
metadata:
name: veylant-proxy
namespace: veylant
annotations:
# Enable Vault Agent sidecar injection for automatic secret management.
vault.hashicorp.com/agent-inject: "true"
vault.hashicorp.com/role: "veylant-proxy"
# Inject LLM provider API keys as environment variables.
vault.hashicorp.com/agent-inject-secret-llm-keys: "secret/data/veylant/llm-keys"
vault.hashicorp.com/agent-inject-template-llm-keys: |
{{- with secret "secret/data/veylant/llm-keys" -}}
export VEYLANT_PROVIDERS_OPENAI_API_KEY="{{ .Data.data.openai_api_key }}"
export VEYLANT_PROVIDERS_ANTHROPIC_API_KEY="{{ .Data.data.anthropic_api_key }}"
export VEYLANT_PROVIDERS_MISTRAL_API_KEY="{{ .Data.data.mistral_api_key }}"
export VEYLANT_CRYPTO_AES_KEY_BASE64="{{ .Data.data.aes_key_base64 }}"
{{- end }}

39
deploy/k8s/vault/vault-auth.yaml Normal file
View File

@ -0,0 +1,39 @@
# Vault Kubernetes authentication configuration (E10-03).
# Binds the veylant-proxy ServiceAccount to the Vault role defined in vault-policy.hcl.
# Prerequisites: Vault Kubernetes auth method enabled.
# vault auth enable kubernetes
# vault write auth/kubernetes/config kubernetes_host="https://$K8S_HOST:443"
# Apply: kubectl apply -f deploy/k8s/vault/vault-auth.yaml -n veylant
---
# VaultAuth resource (requires the Vault Secrets Operator or Agent Injector).
# Using Vault Agent Injector annotations (defined in serviceaccount.yaml).
# This ConfigMap holds the Vault connection parameters for reference.
apiVersion: v1
kind: ConfigMap
metadata:
name: vault-config
namespace: veylant
data:
# Vault server address — override with VAULT_ADDR env var or Helm values.
VAULT_ADDR: "https://vault.vault.svc.cluster.local:8200"
# Vault namespace (Enterprise only; leave empty for open-source Vault).
VAULT_NAMESPACE: ""
# Kubernetes auth mount path.
VAULT_AUTH_PATH: "auth/kubernetes"
# Vault role bound to the veylant-proxy ServiceAccount.
VAULT_ROLE: "veylant-proxy"
---
# ClusterRoleBinding allowing Vault to verify ServiceAccount tokens.
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: vault-token-reviewer
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: system:auth-delegator
subjects:
- kind: ServiceAccount
name: vault
namespace: vault

37
deploy/k8s/vault/vault-policy.hcl Normal file
View File

@ -0,0 +1,37 @@
# Vault policy for the veylant-proxy role (E10-03).
# Grants read-only access to all secrets under the veylant/ path.
#
# Apply to Vault:
# vault policy write veylant-proxy deploy/k8s/vault/vault-policy.hcl
#
# Then create the Kubernetes auth role:
# vault write auth/kubernetes/role/veylant-proxy \
# bound_service_account_names=veylant-proxy \
# bound_service_account_namespaces=veylant \
# policies=veylant-proxy \
# ttl=1h
# LLM provider API keys — read only.
path "secret/data/veylant/llm-keys" {
capabilities = ["read"]
}
# Cryptographic secrets (AES key for prompt encryption) — read only.
path "secret/data/veylant/crypto" {
capabilities = ["read"]
}
# Database connection URL — read only.
path "secret/data/veylant/database" {
capabilities = ["read"]
}
# Allow metadata reads (needed for dynamic lease renewal).
path "secret/metadata/veylant/*" {
capabilities = ["read", "list"]
}
# Deny all other paths explicitly (defense-in-depth).
path "*" {
capabilities = ["deny"]
}

170
deploy/keycloak/realm-export.json Normal file
View File

@ -0,0 +1,170 @@
{
"realm": "veylant",
"displayName": "Veylant IA",
"enabled": true,
"sslRequired": "none",
"registrationAllowed": false,
"loginWithEmailAllowed": true,
"duplicateEmailsAllowed": false,
"resetPasswordAllowed": true,
"editUsernameAllowed": false,
"bruteForceProtected": true,
"accessTokenLifespan": 3600,
"refreshTokenMaxReuse": 0,
"roles": {
"realm": [
{
"name": "admin",
"description": "Full access to all resources and settings"
},
{
"name": "manager",
"description": "Manage users and policies within their department"
},
{
"name": "user",
"description": "Standard AI proxy access — restricted to allowed models"
},
{
"name": "auditor",
"description": "Read-only access to audit logs and compliance reports"
}
]
},
"clients": [
{
"clientId": "veylant-proxy",
"name": "Veylant IA Proxy",
"enabled": true,
"protocol": "openid-connect",
"publicClient": false,
"serviceAccountsEnabled": true,
"directAccessGrantsEnabled": true,
"standardFlowEnabled": true,
"secret": "dev-secret-change-in-production",
"redirectUris": [
"http://localhost:3000/*",
"http://localhost:8090/*"
],
"webOrigins": [
"http://localhost:3000",
"http://localhost:8090"
],
"defaultClientScopes": [
"openid",
"profile",
"email",
"roles"
],
"protocolMappers": [
{
"name": "tenant-id-mapper",
"protocol": "openid-connect",
"protocolMapper": "oidc-usermodel-attribute-mapper",
"consentRequired": false,
"config": {
"userinfo.token.claim": "true",
"user.attribute": "tenant_id",
"id.token.claim": "true",
"access.token.claim": "true",
"claim.name": "tenant_id",
"jsonType.label": "String"
}
}
]
},
{
"clientId": "veylant-dashboard",
"name": "Veylant IA Dashboard",
"enabled": true,
"protocol": "openid-connect",
"publicClient": true,
"directAccessGrantsEnabled": false,
"standardFlowEnabled": true,
"redirectUris": [
"http://localhost:3000/*"
],
"webOrigins": [
"http://localhost:3000"
]
}
],
"users": [
{
"username": "admin@veylant.dev",
"email": "admin@veylant.dev",
"firstName": "Admin",
"lastName": "Veylant",
"enabled": true,
"emailVerified": true,
"credentials": [
{
"type": "password",
"value": "admin123",
"temporary": false
}
],
"realmRoles": ["admin"],
"attributes": {
"tenant_id": ["00000000-0000-0000-0000-000000000001"]
}
},
{
"username": "manager@veylant.dev",
"email": "manager@veylant.dev",
"firstName": "Manager",
"lastName": "Finance",
"enabled": true,
"emailVerified": true,
"credentials": [
{
"type": "password",
"value": "manager123",
"temporary": false
}
],
"realmRoles": ["manager"],
"attributes": {
"tenant_id": ["00000000-0000-0000-0000-000000000001"]
}
},
{
"username": "user@veylant.dev",
"email": "user@veylant.dev",
"firstName": "User",
"lastName": "Test",
"enabled": true,
"emailVerified": true,
"credentials": [
{
"type": "password",
"value": "user123",
"temporary": false
}
],
"realmRoles": ["user"],
"attributes": {
"tenant_id": ["00000000-0000-0000-0000-000000000001"]
}
},
{
"username": "auditor@veylant.dev",
"email": "auditor@veylant.dev",
"firstName": "Auditor",
"lastName": "Compliance",
"enabled": true,
"emailVerified": true,
"credentials": [
{
"type": "password",
"value": "auditor123",
"temporary": false
}
],
"realmRoles": ["auditor"],
"attributes": {
"tenant_id": ["00000000-0000-0000-0000-000000000001"]
}
}
]
}

98
deploy/onboarding/README.md Normal file
View File

@ -0,0 +1,98 @@
# Veylant IA — Pilot Client Onboarding
Operational in **under one working day**.
## Prerequisites
| Tool | Version | Notes |
|---|---|---|
| `curl` | any | Standard on macOS/Linux |
| `python3` | 3.8+ | JSON parsing in scripts |
| Veylant IA proxy | running | `make dev` or production URL |
| Admin JWT | valid | Issued by Keycloak for the platform admin |
## Scripts
### `onboard-tenant.sh` — Full tenant provisioning
Provisions a new client tenant end-to-end:
1. Checks proxy health
2. Creates the tenant admin user
3. Seeds 4 routing policy templates (HR, Finance, Engineering, Catchall)
4. Configures rate limits
5. Prints a verification summary
```bash
# Make executable (once)
chmod +x onboard-tenant.sh import-users.sh
# Set required variables
export VEYLANT_URL=https://api.veylant.ai
export VEYLANT_ADMIN_TOKEN=<platform-admin-jwt>
export TENANT_ADMIN_EMAIL=admin@client.example
# Optional overrides
export TENANT_ADMIN_FIRST=Marie
export TENANT_ADMIN_LAST=Dupont
export RPM=2000
export BURST=400
./onboard-tenant.sh
```
### `import-users.sh` — Bulk user import from CSV
Imports a list of users from a CSV file. Idempotent — already-existing users (HTTP 409) are skipped without error.
```bash
export VEYLANT_URL=https://api.veylant.ai
export VEYLANT_ADMIN_TOKEN=<admin-jwt>
./import-users.sh sample-users.csv
```
### `sample-users.csv` — Example CSV format
```
email,first_name,last_name,department,role
alice.martin@corp.example,Alice,Martin,HR,user
bob.dupont@corp.example,Bob,Dupont,Finance,user
```
**Roles**: `admin`, `manager`, `user`, `auditor`
## Day-1 Checklist
- [ ] Run `onboard-tenant.sh` to provision the tenant
- [ ] Customize the CSV with real user data
- [ ] Run `import-users.sh` to bulk-import users
- [ ] Issue Keycloak JWTs for each user (via your IdP admin console)
- [ ] Share the [integration guide](../../docs/integration-guide.md) with developers
- [ ] Verify a test request: `curl -X POST $VEYLANT_URL/v1/chat/completions ...`
- [ ] Confirm audit logs appear: `GET /v1/admin/logs`
## Rate Limit Defaults
| Setting | Default | Override via |
|---|---|---|
| Requests/min | 1 000 | `RPM` env var |
| Burst | 200 | `BURST` env var |
| Per-user RPM | 200 | RPM ÷ 5 |
| Per-user burst | 40 | BURST ÷ 5 |
Limits can be adjusted at any time without restart via:
```bash
curl -X PUT $VEYLANT_URL/v1/admin/rate-limits/<tenant_id> \
-H "Authorization: Bearer $TOKEN" \
-d '{"requests_per_min": 3000, "burst_size": 600, "is_enabled": true}'
```
## Troubleshooting
| Symptom | Check |
|---|---|
| `VEYLANT_URL` not set | Export the variable and retry |
| HTTP 401 on API calls | JWT may have expired — refresh via Keycloak |
| HTTP 403 | Token role is not `admin` — use the platform admin token |
| User creation fails (HTTP 500) | Check PostgreSQL is running: `make health` |
| PII not working | Ensure PII sidecar is up: `curl http://localhost:8091/healthz` |

76
deploy/onboarding/import-users.sh Normal file
View File

@ -0,0 +1,76 @@
#!/usr/bin/env bash
# deploy/onboarding/import-users.sh
#
# Bulk-imports users from a CSV file into Veylant IA.
#
# CSV format (with header):
# email,first_name,last_name,department,role
#
# Usage:
# export VEYLANT_URL=http://localhost:8090
# export VEYLANT_ADMIN_TOKEN=<admin-jwt>
# ./import-users.sh deploy/onboarding/sample-users.csv
#
# Required env vars:
# VEYLANT_URL - base URL of the proxy (no trailing slash)
# VEYLANT_ADMIN_TOKEN - JWT with admin role
set -euo pipefail
VEYLANT_URL="${VEYLANT_URL:?VEYLANT_URL is required}"
VEYLANT_ADMIN_TOKEN="${VEYLANT_ADMIN_TOKEN:?VEYLANT_ADMIN_TOKEN is required}"
CSV_FILE="${1:?Usage: $0 <csv-file>}"
[[ -f "$CSV_FILE" ]] || { echo "ERROR: file not found: $CSV_FILE" >&2; exit 1; }
API="${VEYLANT_URL}/v1/admin"
AUTH="Authorization: Bearer ${VEYLANT_ADMIN_TOKEN}"
log() { echo "[import-users] $*"; }
success=0
failed=0
skip=0
# Skip header line, process each row
while IFS=',' read -r email first_name last_name department role; do
# Skip empty lines and header
[[ -z "$email" || "$email" == "email" ]] && { ((skip++)) || true; continue; }
log "Importing ${email} (${role}, ${department})…"
http_code=$(curl -s -o /dev/null -w "%{http_code}" \
-X POST "${API}/users" \
-H "${AUTH}" \
-H "Content-Type: application/json" \
-d "{
\"email\": \"${email}\",
\"first_name\": \"${first_name}\",
\"last_name\": \"${last_name}\",
\"department\": \"${department}\",
\"role\": \"${role}\"
}")
if [[ "$http_code" == "201" ]]; then
log " → created (201)"
((success++)) || true
elif [[ "$http_code" == "409" ]]; then
log " → already exists, skipped (409)"
((skip++)) || true
else
log " → ERROR: HTTP ${http_code}"
((failed++)) || true
fi
done < "$CSV_FILE"
log ""
log "Import summary:"
log " Created : ${success}"
log " Skipped : ${skip}"
log " Errors : ${failed}"
if [[ "$failed" -gt 0 ]]; then
log "WARNING: ${failed} user(s) failed to import. Check logs above."
exit 1
fi

135
deploy/onboarding/onboard-tenant.sh Normal file
View File

@ -0,0 +1,135 @@
#!/usr/bin/env bash
# deploy/onboarding/onboard-tenant.sh
#
# Provisions a new pilot tenant in Veylant IA:
# 1. Creates the tenant admin user
# 2. Seeds default routing policies (hr, finance, engineering)
# 3. Configures default rate limits
# 4. Verifies the setup
#
# Usage:
# export VEYLANT_URL=http://localhost:8090
# export VEYLANT_ADMIN_TOKEN=<super-admin-jwt>
# export TENANT_NAME="Acme Corp"
# export TENANT_ADMIN_EMAIL=admin@acme.example
# ./onboard-tenant.sh
#
# Required env vars:
# VEYLANT_URL - base URL of the proxy (no trailing slash)
# VEYLANT_ADMIN_TOKEN - JWT with admin role for the platform tenant
# TENANT_ADMIN_EMAIL - email of the new tenant's first admin
#
# Optional env vars:
# TENANT_ADMIN_FIRST - first name (default: Admin)
# TENANT_ADMIN_LAST - last name (default: User)
# RPM - requests per minute (default: 1000)
# BURST - burst size (default: 200)
set -euo pipefail
# ── Config ────────────────────────────────────────────────────────────────────
VEYLANT_URL="${VEYLANT_URL:?VEYLANT_URL is required}"
VEYLANT_ADMIN_TOKEN="${VEYLANT_ADMIN_TOKEN:?VEYLANT_ADMIN_TOKEN is required}"
TENANT_ADMIN_EMAIL="${TENANT_ADMIN_EMAIL:?TENANT_ADMIN_EMAIL is required}"
TENANT_ADMIN_FIRST="${TENANT_ADMIN_FIRST:-Admin}"
TENANT_ADMIN_LAST="${TENANT_ADMIN_LAST:-User}"
RPM="${RPM:-1000}"
BURST="${BURST:-200}"
API="${VEYLANT_URL}/v1/admin"
AUTH="Authorization: Bearer ${VEYLANT_ADMIN_TOKEN}"
# ── Helpers ───────────────────────────────────────────────────────────────────
log() { echo "[onboard] $*"; }
die() { echo "[onboard] ERROR: $*" >&2; exit 1; }
api_post() {
local path="$1"
local body="$2"
curl -sf -X POST "${API}${path}" \
-H "${AUTH}" \
-H "Content-Type: application/json" \
-d "${body}"
}
api_put() {
local path="$1"
local body="$2"
curl -sf -X PUT "${API}${path}" \
-H "${AUTH}" \
-H "Content-Type: application/json" \
-d "${body}"
}
api_get() {
local path="$1"
curl -sf -X GET "${API}${path}" \
-H "${AUTH}"
}
# ── Step 1: Health check ──────────────────────────────────────────────────────
log "Checking proxy health…"
status=$(curl -sf "${VEYLANT_URL}/healthz" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('status',''))")
[[ "$status" == "ok" ]] || die "Proxy health check failed (got: $status)"
log "Proxy is healthy."
# ── Step 2: Create tenant admin user ─────────────────────────────────────────
log "Creating tenant admin user: ${TENANT_ADMIN_EMAIL}…"
user_resp=$(api_post "/users" "{
\"email\": \"${TENANT_ADMIN_EMAIL}\",
\"first_name\": \"${TENANT_ADMIN_FIRST}\",
\"last_name\": \"${TENANT_ADMIN_LAST}\",
\"role\": \"admin\"
}")
user_id=$(echo "$user_resp" | python3 -c "import sys,json; print(json.load(sys.stdin).get('id',''))")
[[ -n "$user_id" ]] || die "Failed to create admin user"
log "Admin user created: id=${user_id}"
# ── Step 3: Seed default routing policies ─────────────────────────────────────
for tmpl in hr finance engineering catchall; do
log "Seeding routing template: ${tmpl}…"
api_post "/policies/seed/${tmpl}" "{}" > /dev/null
log " → ${tmpl} policy seeded."
done
# ── Step 4: Configure rate limits ─────────────────────────────────────────────
# Extract tenant_id from the JWT (middle base64 segment).
TENANT_ID=$(echo "$VEYLANT_ADMIN_TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null \
| python3 -c "import sys,json; print(json.load(sys.stdin).get('tenant_id',''))" 2>/dev/null || echo "")
if [[ -n "$TENANT_ID" ]]; then
log "Configuring rate limits for tenant ${TENANT_ID}: ${RPM} RPM, burst ${BURST}…"
api_put "/rate-limits/${TENANT_ID}" "{
\"requests_per_min\": ${RPM},
\"burst_size\": ${BURST},
\"user_rpm\": $((RPM / 5)),
\"user_burst\": $((BURST / 5)),
\"is_enabled\": true
}" > /dev/null
log "Rate limits configured."
else
log "Warning: could not decode tenant_id from JWT — skipping rate-limit setup."
fi
# ── Step 5: Verify ────────────────────────────────────────────────────────────
log "Verifying setup…"
policies=$(api_get "/policies" | python3 -c "import sys,json; d=json.load(sys.stdin); print(len(d.get('data', [])))")
log " → ${policies} routing policies active."
users=$(api_get "/users" | python3 -c "import sys,json; d=json.load(sys.stdin); print(len(d.get('data', [])))")
log " → ${users} user(s) in the tenant."
log ""
log "✓ Tenant onboarding complete."
log " Admin: ${TENANT_ADMIN_EMAIL}"
log " Policies seeded: hr, finance, engineering, catchall"
log " Rate limit: ${RPM} RPM / ${BURST} burst"
log ""
log "Next step: issue a Keycloak JWT for ${TENANT_ADMIN_EMAIL} and share it with the admin."

6
deploy/onboarding/sample-users.csv Normal file
View File

@ -0,0 +1,6 @@
email,first_name,last_name,department,role
alice.martin@corp.example,Alice,Martin,HR,user
bob.dupont@corp.example,Bob,Dupont,Finance,user
carol.smith@corp.example,Carol,Smith,Engineering,manager
david.leroy@corp.example,David,Leroy,Legal,auditor
emma.garcia@corp.example,Emma,Garcia,HR,user
1 email first_name last_name department role
2 alice.martin@corp.example Alice Martin HR user
3 bob.dupont@corp.example Bob Dupont Finance user
4 carol.smith@corp.example Carol Smith Engineering manager
5 david.leroy@corp.example David Leroy Legal auditor
6 emma.garcia@corp.example Emma Garcia HR user

45
deploy/prometheus/prometheus.yml Normal file
View File

@ -0,0 +1,45 @@
global:
scrape_interval: 15s
evaluation_interval: 15s
# Alertmanager integration.
alerting:
alertmanagers:
- static_configs:
- targets: ["alertmanager:9093"]
timeout: 10s
# Load alert and recording rules.
rule_files:
- "/etc/prometheus/rules.yml"
scrape_configs:
- job_name: "veylant-proxy"
static_configs:
- targets: ["proxy:8090"]
metrics_path: "/metrics"
- job_name: "veylant-pii"
static_configs:
- targets: ["pii:8091"]
metrics_path: "/metrics"
- job_name: "alertmanager"
static_configs:
- targets: ["alertmanager:9093"]
# TLS certificate expiry probe (requires blackbox-exporter in production).
- job_name: "veylant-proxy-tls"
metrics_path: /probe
params:
module: [http_2xx]
static_configs:
- targets:
- "https://api.veylant.ai/healthz"
relabel_configs:
- source_labels: [__address__]
target_label: __param_target
- source_labels: [__param_target]
target_label: instance
- target_label: __address__
replacement: blackbox-exporter:9115

147
deploy/prometheus/rules.yml Normal file
View File

@ -0,0 +1,147 @@
groups:
# ── Recording rules — pre-compute expensive percentile queries ─────────────
- name: veylant_recording_rules
interval: 30s
rules:
# p99 request duration over a 5-minute sliding window, per model and provider.
- record: veylant:request_duration:p99
expr: |
histogram_quantile(
0.99,
sum by (le, model, provider) (
rate(veylant_request_duration_seconds_bucket[5m])
)
)
# p95 request duration (for dashboard and alerting).
- record: veylant:request_duration:p95
expr: |
histogram_quantile(
0.95,
sum by (le, model, provider) (
rate(veylant_request_duration_seconds_bucket[5m])
)
)
# Request rate (RPS) per provider.
- record: veylant:request_rate:1m
expr: |
sum by (provider, status_code) (
rate(veylant_request_total[1m])
)
# Error rate (4xx/5xx) as a fraction of total requests.
- record: veylant:error_rate:5m
expr: |
sum by (provider) (
rate(veylant_request_total{status_code=~"[45].."}[5m])
)
/
sum by (provider) (
rate(veylant_request_total[5m])
)
# ── Alert rules ────────────────────────────────────────────────────────────
- name: veylant_alerts
rules:
# Fire when p99 latency exceeds 500ms for more than 5 minutes.
- alert: VeylantHighLatencyP99
expr: veylant:request_duration:p99 > 0.5
for: 5m
labels:
severity: warning
team: platform
annotations:
summary: "Veylant proxy p99 latency is above 500ms"
description: >
p99 latency for model={{ $labels.model }} provider={{ $labels.provider }}
is {{ $value | humanizeDuration }} (threshold: 500ms).
Check upstream provider health and connection pool utilisation.
runbook: "https://docs.veylant.ai/runbooks/high-latency"
# Fire when error rate exceeds 5% for more than 2 minutes.
- alert: VeylantHighErrorRate
expr: veylant:error_rate:5m > 0.05
for: 2m
labels:
severity: critical
team: platform
annotations:
summary: "Veylant proxy error rate is above 5%"
description: >
Error rate for provider={{ $labels.provider }} is
{{ $value | humanizePercentage }} over the last 5 minutes.
runbook: "https://docs.veylant.ai/runbooks/high-error-rate"
# Fire when a circuit breaker opens (provider is failing).
- alert: VeylantCircuitBreakerOpen
expr: veylant_circuit_breaker_state{state="open"} == 1
for: 1m
labels:
severity: critical
team: platform
annotations:
summary: "Circuit breaker open for provider {{ $labels.provider }}"
description: >
The circuit breaker for provider={{ $labels.provider }} has been open
for more than 1 minute. Requests are being rejected.
runbook: "https://docs.veylant.ai/runbooks/provider-down"
# Fire when the proxy is not reachable by Prometheus scrape.
- alert: VeylantProxyDown
expr: up{job="veylant-proxy"} == 0
for: 1m
labels:
severity: critical
team: platform
annotations:
summary: "Veylant proxy is down"
description: >
The Prometheus scrape target for job="veylant-proxy" has been unreachable
for more than 1 minute. The proxy may be crashed or the pod is not running.
runbook: "https://docs.veylant.ai/runbooks/provider-down"
# Fire when a TLS certificate expires in less than 30 days.
- alert: VeylantCertExpiringSoon
expr: |
probe_ssl_earliest_cert_expiry{job="veylant-proxy"} - time() < 30 * 24 * 3600
for: 1h
labels:
severity: warning
team: platform
annotations:
summary: "TLS certificate expiring within 30 days"
description: >
The TLS certificate for the Veylant proxy expires in
{{ $value | humanizeDuration }}. Renew immediately to avoid service disruption.
runbook: "https://docs.veylant.ai/runbooks/certificate-expired"
# Fire when PostgreSQL active connections are high (pool exhaustion risk).
- alert: VeylantDBConnectionsHigh
expr: veylant_db_connections_active > 20
for: 5m
labels:
severity: warning
team: platform
annotations:
summary: "PostgreSQL active connections above threshold"
description: >
PostgreSQL active connections = {{ $value }} (threshold: 20).
Risk of connection pool exhaustion — check for slow queries or connection leaks.
runbook: "https://docs.veylant.ai/runbooks/database-full"
# Fire when PII detection volume is anomalously high (possible data exfiltration attempt).
- alert: VeylantPIIVolumeAnomaly
expr: |
rate(veylant_pii_entities_detected_total[5m])
> 3 * avg_over_time(rate(veylant_pii_entities_detected_total[5m])[1h:5m])
for: 5m
labels:
severity: warning
team: security
annotations:
summary: "PII detection volume anomaly detected"
description: >
PII entity detection rate is {{ $value | humanize }} entities/sec —
more than 3× the 1-hour baseline. Possible data exfiltration or misconfigured client.
runbook: "https://docs.veylant.ai/runbooks/pii-breach"

162
deploy/scripts/blue-green.sh Normal file
View File

@ -0,0 +1,162 @@
#!/usr/bin/env bash
# deploy/scripts/blue-green.sh
#
# Atomic blue/green deployment for Veylant IA proxy.
# Rollback time: < 5s (single kubectl patch on the Istio VirtualService).
#
# Strategy:
# 1. Detect which slot is currently active (blue|green) from the VirtualService.
# 2. Deploy the new image tag to the INACTIVE slot via helm upgrade.
# 3. Wait for the inactive slot's rollout to complete.
# 4. Smoke-test the inactive slot via a temp port-forward.
# 5. Switch 100% traffic to the new slot (patch VirtualService).
# 6. Verify health post-switch; roll back if verification fails.
# 7. Scale down the old slot to 0 replicas to free resources.
#
# Required env vars:
# IMAGE_TAG — Docker image tag to deploy (e.g. sha-abc123)
# NAMESPACE — Kubernetes namespace (default: veylant)
# KUBECONFIG — path to kubeconfig (uses default if not set)
#
# Optional env vars:
# ROLLOUT_TIMEOUT — kubectl rollout wait timeout (default: 5m)
# SMOKE_RETRIES — health check retries after switch (default: 5)
# DRY_RUN — set to "true" to print commands without executing
set -euo pipefail
# ── Config ────────────────────────────────────────────────────────────────────
IMAGE_TAG="${IMAGE_TAG:?IMAGE_TAG is required}"
NAMESPACE="${NAMESPACE:-veylant}"
ROLLOUT_TIMEOUT="${ROLLOUT_TIMEOUT:-5m}"
SMOKE_RETRIES="${SMOKE_RETRIES:-5}"
DRY_RUN="${DRY_RUN:-false}"
CHART_PATH="deploy/helm/veylant-proxy"
# ── Helpers ───────────────────────────────────────────────────────────────────
log() { echo "[blue-green] $*"; }
die() { echo "[blue-green] ERROR: $*" >&2; exit 1; }
run() {
if [[ "$DRY_RUN" == "true" ]]; then
echo "[dry-run] $*"
else
"$@"
fi
}
# ── Step 1: Detect active slot ────────────────────────────────────────────────
log "Detecting active slot from VirtualService..."
ACTIVE_SLOT=$(kubectl get virtualservice veylant-proxy -n "$NAMESPACE" -o jsonpath='{.spec.http[0].route[0].destination.subset}' 2>/dev/null || echo "blue")
if [[ "$ACTIVE_SLOT" == "blue" ]]; then
INACTIVE_SLOT="green"
else
INACTIVE_SLOT="blue"
fi
log "Active slot: ${ACTIVE_SLOT} → deploying to INACTIVE slot: ${INACTIVE_SLOT}"
HELM_RELEASE="veylant-proxy-${INACTIVE_SLOT}"
VALUES_FILE="${CHART_PATH}/values-${INACTIVE_SLOT}.yaml"
# ── Step 2: Deploy to inactive slot ──────────────────────────────────────────
log "Deploying image tag '${IMAGE_TAG}' to slot '${INACTIVE_SLOT}' (release: ${HELM_RELEASE})..."
run helm upgrade --install "$HELM_RELEASE" "$CHART_PATH" \
-f "$VALUES_FILE" \
--namespace "$NAMESPACE" \
--create-namespace \
--set image.tag="$IMAGE_TAG" \
--set slot="$INACTIVE_SLOT" \
--wait \
--timeout "$ROLLOUT_TIMEOUT"
log "Helm deploy complete for slot '${INACTIVE_SLOT}'."
# ── Step 3: Wait for rollout ──────────────────────────────────────────────────
log "Waiting for deployment rollout (timeout: ${ROLLOUT_TIMEOUT})..."
run kubectl rollout status "deployment/${HELM_RELEASE}" \
-n "$NAMESPACE" \
--timeout "$ROLLOUT_TIMEOUT"
log "Rollout complete."
# ── Step 4: Smoke test on inactive slot ──────────────────────────────────────
log "Smoke-testing inactive slot via port-forward..."
PF_PORT=19090
# Start port-forward in background; capture PID for cleanup.
if [[ "$DRY_RUN" != "true" ]]; then
kubectl port-forward \
"deployment/${HELM_RELEASE}" \
"${PF_PORT}:8090" \
-n "$NAMESPACE" &>/tmp/veylant-pf.log &
PF_PID=$!
# Give it 3s to establish.
sleep 3
SMOKE_OK=false
for i in $(seq 1 5); do
HTTP_STATUS=$(curl -sf -o /dev/null -w "%{http_code}" "http://localhost:${PF_PORT}/healthz" 2>/dev/null || echo "000")
if [[ "$HTTP_STATUS" == "200" ]]; then
SMOKE_OK=true
break
fi
log " Smoke attempt ${i}/5: HTTP ${HTTP_STATUS} — retrying..."
sleep 2
done
kill "$PF_PID" 2>/dev/null || true
wait "$PF_PID" 2>/dev/null || true
if [[ "$SMOKE_OK" != "true" ]]; then
die "Smoke test failed on inactive slot '${INACTIVE_SLOT}'. Deployment ABORTED — active slot unchanged."
fi
fi
log "Smoke test passed."
# ── Step 5: Switch traffic to new slot ───────────────────────────────────────
log "Switching 100%% traffic from '${ACTIVE_SLOT}' → '${INACTIVE_SLOT}'..."
run kubectl patch virtualservice veylant-proxy -n "$NAMESPACE" --type merge \
-p "{\"spec\":{\"http\":[{\"route\":[{\"destination\":{\"host\":\"veylant-proxy\",\"subset\":\"${INACTIVE_SLOT}\"},\"weight\":100}]}]}}"
log "Traffic switched."
# ── Step 6: Verify post-switch ────────────────────────────────────────────────
log "Verifying health post-switch (${SMOKE_RETRIES} attempts)..."
VEYLANT_URL="${VEYLANT_URL:-http://localhost:8090}"
POST_SWITCH_OK=false
if [[ "$DRY_RUN" != "true" ]]; then
for i in $(seq 1 "$SMOKE_RETRIES"); do
HTTP_STATUS=$(curl -sf -o /dev/null -w "%{http_code}" "${VEYLANT_URL}/healthz" 2>/dev/null || echo "000")
if [[ "$HTTP_STATUS" == "200" ]]; then
POST_SWITCH_OK=true
break
fi
log " Post-switch check ${i}/${SMOKE_RETRIES}: HTTP ${HTTP_STATUS} — retrying..."
sleep 2
done
else
POST_SWITCH_OK=true
fi
if [[ "$POST_SWITCH_OK" != "true" ]]; then
log "Post-switch verification FAILED. Rolling back to '${ACTIVE_SLOT}'..."
kubectl patch virtualservice veylant-proxy -n "$NAMESPACE" --type merge \
-p "{\"spec\":{\"http\":[{\"route\":[{\"destination\":{\"host\":\"veylant-proxy\",\"subset\":\"${ACTIVE_SLOT}\"},\"weight\":100}]}]}}"
die "Rollback complete. Active slot reverted to '${ACTIVE_SLOT}'."
fi
log "Post-switch verification passed."
# ── Step 7: Scale down old slot ───────────────────────────────────────────────
log "Scaling down old slot '${ACTIVE_SLOT}' to 0 replicas..."
OLD_RELEASE="veylant-proxy-${ACTIVE_SLOT}"
run kubectl scale deployment "$OLD_RELEASE" --replicas=0 -n "$NAMESPACE" 2>/dev/null || \
log " (scale-down skipped — release ${OLD_RELEASE} not found)"
log ""
log "✓ Blue/green deployment complete."
log " Previous slot : ${ACTIVE_SLOT} (scaled to 0)"
log " Active slot : ${INACTIVE_SLOT} (image: ${IMAGE_TAG})"
log " Rollback : make deploy-rollback ACTIVE_SLOT=${ACTIVE_SLOT} NAMESPACE=${NAMESPACE}"

0
deploy/terraform/.gitkeep Normal file
View File

37
deploy/terraform/README.md Normal file
View File

@ -0,0 +1,37 @@
# Infrastructure — Terraform / OpenTofu
> **Sprint 1 note**: Infrastructure provisioning is skipped in Sprint 1 (OpenTofu not yet installed locally).
> See `docs/adr/001-terraform-vs-pulumi.md` for the tooling decision.
## Prerequisites
```bash
brew install opentofu
```
## Structure (to be implemented in Sprint 4+)
```
deploy/terraform/
├── main.tf # Root module, providers, backend (S3 + DynamoDB lock)
├── variables.tf # Input variables
├── outputs.tf # VPC, cluster endpoint, kubeconfig
├── versions.tf # Pinned provider versions
├── vpc/ # VPC, subnets, NAT gateway
├── eks/ # EKS cluster, node groups (terraform-aws-eks v20.x)
└── monitoring/ # CloudWatch, alerts
```
## Before first apply
Create the state backend manually:
```bash
aws s3 mb s3://veylant-terraform-state-eu-west-3 --region eu-west-3
aws dynamodb create-table \
--table-name veylant-terraform-lock \
--attribute-definitions AttributeName=LockID,AttributeType=S \
--key-schema AttributeName=LockID,KeyType=HASH \
--billing-mode PAY_PER_REQUEST \
--region eu-west-3
```

269
deploy/terraform/main.tf Normal file
View File

@ -0,0 +1,269 @@
terraform {
required_version = ">= 1.7"
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 5.0"
}
kubernetes = {
source = "hashicorp/kubernetes"
version = "~> 2.27"
}
}
backend "s3" {
bucket = "veylant-terraform-state"
key = "production/eks/terraform.tfstate"
region = "eu-west-3"
encrypt = true
dynamodb_table = "veylant-terraform-locks"
}
}
provider "aws" {
region = var.aws_region
default_tags {
tags = {
Project = "veylant-ia"
Environment = "production"
ManagedBy = "terraform"
}
}
}
# ──────────────────────────────────────────────
# VPC — 3 public + 3 private subnets across AZs
# ──────────────────────────────────────────────
module "vpc" {
source = "terraform-aws-modules/vpc/aws"
version = "~> 5.5"
name = "veylant-production"
cidr = var.vpc_cidr
azs = ["${var.aws_region}a", "${var.aws_region}b", "${var.aws_region}c"]
private_subnets = var.private_subnet_cidrs
public_subnets = var.public_subnet_cidrs
enable_nat_gateway = true
single_nat_gateway = false # 1 NAT GW per AZ for HA
enable_dns_hostnames = true
enable_dns_support = true
# Required tags for EKS auto-discovery of subnets.
private_subnet_tags = {
"kubernetes.io/role/internal-elb" = "1"
"kubernetes.io/cluster/${var.cluster_name}" = "owned"
}
public_subnet_tags = {
"kubernetes.io/role/elb" = "1"
"kubernetes.io/cluster/${var.cluster_name}" = "owned"
}
}
# ──────────────────────────────────────────────
# EKS Cluster — Kubernetes 1.31, eu-west-3
# ──────────────────────────────────────────────
module "eks" {
source = "terraform-aws-modules/eks/aws"
version = "~> 20.0"
cluster_name = var.cluster_name
cluster_version = "1.31"
vpc_id = module.vpc.vpc_id
subnet_ids = module.vpc.private_subnet_ids
cluster_endpoint_public_access = true # Access via kubectl from CI/CD
# Enable IRSA — required for pod-level IAM roles (backup, Vault).
enable_irsa = true
cluster_addons = {
aws-ebs-csi-driver = {
most_recent = true
service_account_role_arn = module.irsa_ebs_csi.iam_role_arn
}
coredns = {
most_recent = true
}
kube-proxy = {
most_recent = true
}
vpc-cni = {
most_recent = true
before_compute = true
}
}
eks_managed_node_groups = {
# One node group per AZ for topology-aware scheduling.
veylant-az-a = {
name = "veylant-az-a"
subnet_ids = [module.vpc.private_subnets[0]]
instance_types = [var.node_instance_type]
min_size = 1
max_size = 5
desired_size = 2
ami_type = "AL2_x86_64"
disk_size = 50
labels = {
"topology.kubernetes.io/zone" = "${var.aws_region}a"
workload = "veylant"
}
}
veylant-az-b = {
name = "veylant-az-b"
subnet_ids = [module.vpc.private_subnets[1]]
instance_types = [var.node_instance_type]
min_size = 1
max_size = 5
desired_size = 2
ami_type = "AL2_x86_64"
disk_size = 50
labels = {
"topology.kubernetes.io/zone" = "${var.aws_region}b"
workload = "veylant"
}
}
veylant-az-c = {
name = "veylant-az-c"
subnet_ids = [module.vpc.private_subnets[2]]
instance_types = [var.node_instance_type]
min_size = 1
max_size = 5
desired_size = 2
ami_type = "AL2_x86_64"
disk_size = 50
labels = {
"topology.kubernetes.io/zone" = "${var.aws_region}c"
workload = "veylant"
}
}
}
tags = {
Environment = "production"
Cluster = var.cluster_name
}
}
# ──────────────────────────────────────────────
# IRSA — IAM Roles for Service Accounts
# ──────────────────────────────────────────────
# EBS CSI Driver IRSA
module "irsa_ebs_csi" {
source = "terraform-aws-modules/iam/aws//modules/iam-role-for-service-accounts-eks"
version = "~> 5.39"
role_name = "veylant-ebs-csi-driver"
attach_ebs_csi_policy = true
oidc_providers = {
main = {
provider_arn = module.eks.oidc_provider_arn
namespace_service_accounts = ["kube-system:ebs-csi-controller-sa"]
}
}
}
# Backup role IRSA (S3 write for pg_dump)
module "irsa_backup" {
source = "terraform-aws-modules/iam/aws//modules/iam-role-for-service-accounts-eks"
version = "~> 5.39"
role_name = "veylant-backup-role"
role_policy_arns = {
backup = aws_iam_policy.backup_s3.arn
}
oidc_providers = {
main = {
provider_arn = module.eks.oidc_provider_arn
namespace_service_accounts = ["veylant:veylant-backup"]
}
}
}
resource "aws_iam_policy" "backup_s3" {
name = "veylant-backup-s3"
description = "Allow Veylant backup job to write to S3 backup bucket"
policy = jsonencode({
Version = "2012-10-17"
Statement = [
{
Effect = "Allow"
Action = [
"s3:PutObject",
"s3:GetObject",
"s3:ListBucket",
"s3:DeleteObject"
]
Resource = [
"arn:aws:s3:::veylant-backups-production",
"arn:aws:s3:::veylant-backups-production/*"
]
}
]
})
}
# ──────────────────────────────────────────────
# S3 Backup Bucket with 7-day lifecycle
# ──────────────────────────────────────────────
resource "aws_s3_bucket" "backups" {
bucket = "veylant-backups-production"
}
resource "aws_s3_bucket_versioning" "backups" {
bucket = aws_s3_bucket.backups.id
versioning_configuration {
status = "Enabled"
}
}
resource "aws_s3_bucket_server_side_encryption_configuration" "backups" {
bucket = aws_s3_bucket.backups.id
rule {
apply_server_side_encryption_by_default {
sse_algorithm = "AES256"
}
}
}
resource "aws_s3_bucket_lifecycle_configuration" "backups" {
bucket = aws_s3_bucket.backups.id
rule {
id = "expire-old-backups"
status = "Enabled"
filter {
prefix = "postgres/"
}
# Delete backups older than 7 days.
expiration {
days = 7
}
# Clean up incomplete multipart uploads.
abort_incomplete_multipart_upload {
days_after_initiation = 1
}
}
}
resource "aws_s3_bucket_public_access_block" "backups" {
bucket = aws_s3_bucket.backups.id
block_public_acls = true
block_public_policy = true
ignore_public_acls = true
restrict_public_buckets = true
}

54
deploy/terraform/outputs.tf Normal file
View File

@ -0,0 +1,54 @@
output "cluster_endpoint" {
description = "EKS cluster API server endpoint"
value = module.eks.cluster_endpoint
}
output "cluster_certificate_authority_data" {
description = "Base64-encoded certificate authority data for the cluster"
value = module.eks.cluster_certificate_authority_data
sensitive = true
}
output "cluster_name" {
description = "EKS cluster name"
value = module.eks.cluster_name
}
output "cluster_oidc_issuer_url" {
description = "OIDC issuer URL for the EKS cluster (used for IRSA)"
value = module.eks.cluster_oidc_issuer_url
}
output "node_group_arns" {
description = "ARNs of the managed node groups"
value = {
az_a = module.eks.eks_managed_node_groups["veylant-az-a"].node_group_arn
az_b = module.eks.eks_managed_node_groups["veylant-az-b"].node_group_arn
az_c = module.eks.eks_managed_node_groups["veylant-az-c"].node_group_arn
}
}
output "vpc_id" {
description = "VPC ID"
value = module.vpc.vpc_id
}
output "private_subnet_ids" {
description = "Private subnet IDs (one per AZ)"
value = module.vpc.private_subnets
}
output "backup_bucket_name" {
description = "S3 backup bucket name"
value = aws_s3_bucket.backups.id
}
output "backup_role_arn" {
description = "IAM role ARN for the backup service account (IRSA)"
value = module.irsa_backup.iam_role_arn
}
output "kubeconfig_command" {
description = "AWS CLI command to update kubeconfig"
value = "aws eks update-kubeconfig --region ${var.aws_region} --name ${module.eks.cluster_name}"
}

35
deploy/terraform/variables.tf Normal file
View File

@ -0,0 +1,35 @@
variable "aws_region" {
description = "AWS region for the EKS cluster"
type = string
default = "eu-west-3"
}
variable "cluster_name" {
description = "EKS cluster name"
type = string
default = "veylant-production"
}
variable "vpc_cidr" {
description = "CIDR block for the VPC"
type = string
default = "10.0.0.0/16"
}
variable "private_subnet_cidrs" {
description = "CIDR blocks for private subnets (one per AZ)"
type = list(string)
default = ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]
}
variable "public_subnet_cidrs" {
description = "CIDR blocks for public subnets (one per AZ)"
type = list(string)
default = ["10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24"]
}
variable "node_instance_type" {
description = "EC2 instance type for EKS managed node groups"
type = string
default = "t3.medium"
}

235
docker-compose.yml Normal file
View File

@ -0,0 +1,235 @@
services:
# ─────────────────────────────────────────────
# PostgreSQL 16 — primary datastore
# ─────────────────────────────────────────────
postgres:
image: postgres:16-alpine
environment:
POSTGRES_DB: veylant
POSTGRES_USER: veylant
POSTGRES_PASSWORD: veylant_dev
ports:
- "5432:5432"
volumes:
- postgres_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U veylant -d veylant"]
interval: 5s
timeout: 5s
retries: 10
start_period: 10s
# ─────────────────────────────────────────────
# Redis 7 — sessions, rate limiting, PII pseudonymization mappings
# No persistence in dev (AOF/RDB disabled for fast startup)
# ─────────────────────────────────────────────
redis:
image: redis:7-alpine
command: redis-server --save "" --appendonly no
ports:
- "6379:6379"
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 5s
timeout: 3s
retries: 10
# ─────────────────────────────────────────────
# ClickHouse 24.3 LTS — append-only audit logs and analytics
# Pinned to LTS for stability
# ─────────────────────────────────────────────
clickhouse:
image: clickhouse/clickhouse-server:24.3-alpine
environment:
CLICKHOUSE_DB: veylant_logs
CLICKHOUSE_USER: veylant
CLICKHOUSE_PASSWORD: veylant_dev
CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
ports:
- "8123:8123" # HTTP interface (used for health check and dashboard queries)
- "9000:9000" # Native TCP (used by Go driver)
volumes:
- clickhouse_data:/var/lib/clickhouse
healthcheck:
test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:8123/ping || exit 1"]
interval: 5s
timeout: 5s
retries: 20
start_period: 15s
ulimits:
nofile:
soft: 262144
hard: 262144
# ─────────────────────────────────────────────
# Keycloak 24 — IAM, OIDC, SAML 2.0
# start-dev: in-memory DB, no TLS — development only
# Realm is auto-imported from deploy/keycloak/realm-export.json
# ─────────────────────────────────────────────
keycloak:
image: quay.io/keycloak/keycloak:24.0
command: ["start-dev", "--import-realm"]
environment:
KC_BOOTSTRAP_ADMIN_USERNAME: admin
KC_BOOTSTRAP_ADMIN_PASSWORD: admin
KC_DB: dev-mem
KC_HEALTH_ENABLED: "true"
ports:
- "8080:8080"
volumes:
- ./deploy/keycloak:/opt/keycloak/data/import:ro
healthcheck:
test: ["CMD-SHELL", "curl -sf http://localhost:8080/health/ready || exit 1"]
interval: 10s
timeout: 10s
retries: 20
start_period: 30s # Keycloak takes ~20s to start in dev mode
# ─────────────────────────────────────────────
# Veylant proxy — Go application
# ─────────────────────────────────────────────
proxy:
build:
context: .
dockerfile: Dockerfile
ports:
- "8090:8090"
environment:
VEYLANT_SERVER_PORT: "8090"
VEYLANT_SERVER_ENV: "development"
VEYLANT_DATABASE_URL: "postgres://veylant:veylant_dev@postgres:5432/veylant?sslmode=disable"
VEYLANT_REDIS_URL: "redis://redis:6379"
VEYLANT_KEYCLOAK_BASE_URL: "http://keycloak:8080"
VEYLANT_KEYCLOAK_REALM: "veylant"
VEYLANT_KEYCLOAK_CLIENT_ID: "veylant-proxy"
VEYLANT_PII_ENABLED: "true"
VEYLANT_PII_SERVICE_ADDR: "pii:50051"
VEYLANT_PII_TIMEOUT_MS: "100"
VEYLANT_PII_FAIL_OPEN: "true"
VEYLANT_LOG_FORMAT: "console"
VEYLANT_LOG_LEVEL: "debug"
# Provider API keys — set via a .env file or shell environment.
# Only providers with an API key set will be enabled at runtime.
VEYLANT_PROVIDERS_OPENAI_API_KEY: "${OPENAI_API_KEY:-}"
VEYLANT_PROVIDERS_ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY:-}"
VEYLANT_PROVIDERS_MISTRAL_API_KEY: "${MISTRAL_API_KEY:-}"
# Azure OpenAI requires resource name + deployment ID + API key.
VEYLANT_PROVIDERS_AZURE_API_KEY: "${AZURE_OPENAI_API_KEY:-}"
VEYLANT_PROVIDERS_AZURE_RESOURCE_NAME: "${AZURE_OPENAI_RESOURCE_NAME:-}"
VEYLANT_PROVIDERS_AZURE_DEPLOYMENT_ID: "${AZURE_OPENAI_DEPLOYMENT_ID:-}"
# Ollama — defaults to localhost:11434 (use host.docker.internal in Docker Desktop).
VEYLANT_PROVIDERS_OLLAMA_BASE_URL: "${OLLAMA_BASE_URL:-http://host.docker.internal:11434/v1}"
VEYLANT_METRICS_ENABLED: "true"
# ClickHouse audit log (Sprint 6).
VEYLANT_CLICKHOUSE_DSN: "clickhouse://veylant:veylant_dev@clickhouse:9000/veylant_logs"
# AES-256-GCM key for prompt encryption — generate: openssl rand -base64 32
# In production, inject via Vault or secret manager. Leave empty to disable.
VEYLANT_CRYPTO_AES_KEY_BASE64: "${VEYLANT_CRYPTO_AES_KEY_BASE64:-}"
depends_on:
postgres:
condition: service_healthy
redis:
condition: service_healthy
clickhouse:
condition: service_healthy
healthcheck:
test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:8090/healthz || exit 1"]
interval: 5s
timeout: 3s
retries: 10
start_period: 5s
# ─────────────────────────────────────────────
# PII detection service — Python (Sprint 3: full pipeline)
# Layer 1: regex (IBAN/email/phone/SSN/CB)
# Layer 2: Presidio + spaCy NER (PERSON/LOC/ORG)
# Pseudonymization: AES-256-GCM in Redis
# ─────────────────────────────────────────────
pii:
build:
context: ./services/pii
dockerfile: Dockerfile
ports:
- "50051:50051" # gRPC
- "8000:8000" # HTTP health
environment:
PII_GRPC_PORT: "50051"
PII_HTTP_PORT: "8000"
PII_REDIS_URL: "redis://redis:6379"
# PII_ENCRYPTION_KEY must be set to a 32-byte base64-encoded key in production.
# The default dev key is used if unset (NOT safe for production).
PII_ENCRYPTION_KEY: "${PII_ENCRYPTION_KEY:-}"
PII_NER_ENABLED: "true"
PII_NER_CONFIDENCE: "0.85"
PII_TTL_SECONDS: "3600"
depends_on:
redis:
condition: service_healthy
healthcheck:
test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:8000/healthz || exit 1"]
interval: 10s
timeout: 5s
retries: 10
start_period: 60s # spaCy fr_core_news_lg model load takes ~30s on first start
# ─────────────────────────────────────────────
# Prometheus — metrics collection
# Scrapes the proxy /metrics endpoint every 15s
# ─────────────────────────────────────────────
prometheus:
image: prom/prometheus:v2.53.0
ports:
- "9090:9090"
volumes:
- ./deploy/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro
command:
- "--config.file=/etc/prometheus/prometheus.yml"
- "--storage.tsdb.path=/prometheus"
- "--web.console.libraries=/etc/prometheus/console_libraries"
- "--web.console.templates=/etc/prometheus/consoles"
depends_on:
proxy:
condition: service_healthy
# ─────────────────────────────────────────────
# Grafana — metrics visualisation
# Auto-provisioned datasource (Prometheus) + Veylant dashboard
# Default credentials: admin / admin
# ─────────────────────────────────────────────
grafana:
image: grafana/grafana:11.3.0
ports:
- "3001:3000"
environment:
GF_SECURITY_ADMIN_PASSWORD: admin
GF_USERS_ALLOW_SIGN_UP: "false"
volumes:
- ./deploy/grafana/provisioning:/etc/grafana/provisioning:ro
- ./deploy/grafana/dashboards:/var/lib/grafana/dashboards:ro
depends_on:
- prometheus
# ─────────────────────────────────────────────
# Veylant Dashboard — React SPA (Sprint 7)
# Dev server only — production uses dist/ served by nginx
# ─────────────────────────────────────────────
web:
image: node:20-alpine
working_dir: /app
command: sh -c "npm install && npm run dev -- --host"
ports:
- "3000:3000"
volumes:
- ./web:/app
- /app/node_modules
environment:
VITE_AUTH_MODE: "dev"
VITE_KEYCLOAK_URL: "http://localhost:8080/realms/veylant"
depends_on:
proxy:
condition: service_healthy
volumes:
postgres_data:
clickhouse_data:

647
docs/AI_Governance_Hub_PRD.md Normal file
View File

@ -0,0 +1,647 @@
**AI GOVERNANCE HUB**
Product Requirements Document & Technical Architecture
MVP Specification — Version 1.0
**CONFIDENTIEL — Février 2026**
Plateforme de gouvernance centralisée pour les flux IA en entreprise
# 1. Executive Summary
AI Governance Hub est une plateforme SaaS B2B qui agit comme proxy intelligent entre les utilisateurs d’une entreprise et l’ensemble de ses modèles IA (internes et externes). La plateforme répond à un besoin critique et immédiat des DSI, RSSI et responsables conformité : reprendre le contrôle sur les flux IA, éliminer le Shadow AI, et préparer la conformité au Règlement européen sur l’IA (AI Act) dont les premières obligations s’appliquent dès 2025.
## 1.1 Proposition de valeur
**Pour le DSI :** Visibilité complète sur les usages IA, maîtrise des coûts, rationalisation des fournisseurs.
**Pour le RSSI :** Prévention des fuites de données sensibles (PII), journalisation intégrale, détection d’anomalies, contrôle d’accès granulaire.
**Pour le DPO / Compliance :** Registre des traitements automatisé, rapports RGPD générés, classification des risques AI Act, traçabilité bout en bout.
**Pour les utilisateurs métier :** Accès unifié et transparent aux IA autorisées, sans friction ni changement d’habitudes majeur.
## 1.2 Marché et timing
Le marché de la gouvernance IA est estimé à plusieurs milliards d’euros d’ici 2028. L’entrée en vigueur progressive de l’AI Act européen (février 2025 pour les IA interdites, août 2025 pour les obligations générales, août 2026 pour les systèmes à haut risque) crée une urgence réglementaire qui accélère la demande. La fenêtre d’opportunité est ouverte maintenant.
# 2. Définition du MVP
## 2.1 Périmètre fonctionnel MVP (V1)
Le MVP se concentre sur les fonctionnalités strictement nécessaires pour démontrer la valeur auprès d’un premier client pilote et fermer un premier contrat enterprise.
| **Module** | **Fonctionnalité MVP** | **Priorité** |
|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|----------------|
| AI Proxy / Gateway | Reverse proxy interceptant toutes les requêtes vers les LLMs (OpenAI, Anthropic, Azure OpenAI, Mistral). Support streaming SSE. | P0 — Critique |
| Routage intelligent | Règles statiques par département/sensibilité. Fallback automatique. Routing vers modèle on-prem ou cloud selon politique. | P0 — Critique |
| Anonymisation PII | Détection hybride (regex + NER Presidio). Redaction en temps réel dans les prompts. Pseudonymisation réversible avec mapping chiffré. | P0 — Critique |
| Journalisation | Logging structuré de chaque requête/réponse (métadonnées, hash du contenu, user, modèle, tokens, coût). Stockage chiffré AES-256. | P0 — Critique |
| RBAC | Gestion des rôles (Admin, Manager, User, Auditor). Contrôle d’accès par modèle et par département. Intégration SSO SAML 2.0. | P0 — Critique |
| Dashboard sécurité | Vue temps réel : volume de requêtes, PII détectées, coûts par modèle/département, alertes basiques. | P1 — Important |
| Rapports conformité | Export PDF/CSV du registre des traitements IA. Mapping articles RGPD. Classification risque AI Act basique (interdit/haut risque/limité/minimal). | P1 — Important |
| Monitoring tokens/coûts | Comptage tokens par requête, agrégation par utilisateur/département/modèle. Alertes de budget. | P1 — Important |
## 2.2 Hors scope MVP (V2+)
| **Fonctionnalité** | **Raison du report** | **Cible** |
|--------------------------------------------|---------------------------------------------------------------------------------------|------------|
| Détection d’anomalies ML | Trop complexe pour le MVP, nécessite données d’entraînement. | V2 (M7–M9) |
| Classification automatique des données | Requiert un modèle custom de classification de sensibilité. | V2 |
| Multi-tenant complet avec isolation réseau | Le MVP supporte le multi-tenant logique. L’isolation physique (dédiée) viendra en V2. | V2 |
| SDK natifs (Python, JS, Java) | Les intégrations se font via API REST + proxy HTTP au MVP. | V2 |
| Marketplace de politiques | Templates de politiques préconfigurées par industrie. | V3 |
| Agent de découverte Shadow AI | Scanner réseau pour détecter les appels IA non autorisés. | V2 |
| Intégration SIEM (Splunk, Sentinel) | Export syslog basique en MVP, connecteurs natifs en V2. | V2 |
## 2.3 Roadmap V1 → V2 → V3
| **Version** | **Timeline** | **Focus** |
|-------------|--------------|-------------------------------------------------------------------------------------------------|
| V1 (MVP) | M1–M6 | Proxy IA + Anonymisation + RBAC + Logging + Dashboard + Rapports conformité de base |
| V1.1 | M7–M8 | Stabilisation, feedback clients pilotes, amélioration UX, SDK Python |
| V2 | M9–M14 | Détection anomalies ML, Shadow AI discovery, isolation tenant physique, SIEM natif, SDK JS/Java |
| V3 | M15–M20 | Marketplace politiques, AI Act scoring automatisé, Data Lineage, certification ISO 27001 |
# 3. Architecture technique détaillée
## 3.1 Choix architectural : Modular Monolith
Pour le MVP, nous choisissons un monolithe modulaire plutôt que des microservices. Ce choix est délibéré et argumenté :
| **Critère** | **Monolithe modulaire** | **Microservices** |
|--------------------------|---------------------------------------------------------|---------------------------------------------------|
| Vitesse de développement | Rapide — un seul déploiement, debug simplifié | Lent — orchestration, service mesh, observabilité |
| Complexité ops | Faible — 1 conteneur principal + workers | Elevée — 10+ services, Kubernetes day-2 |
| Équipe nécessaire | 3–5 développeurs | 8–12 développeurs + SRE dédié |
| Scalabilité future | Extraction de modules en services possible sans refonte | Natif mais prématuré |
| Latence | Appels en mémoire entre modules | Latence réseau inter-services |
**Arbitrage :** Le monolithe modulaire permet de livrer en 6 mois avec une équipe de 4–5 personnes. Chaque module (proxy, anonymisation, logging, RBAC) est isolé dans son propre package/namespace avec des interfaces claires, ce qui permet une extraction future en microservice si nécessaire sans refonte.
## 3.2 Architecture high-level
L’architecture se décompose en couches fonctionnelles claires :
### Couche 1 — Point d’entrée
- **API Gateway (Kong / Traefik) :** Terminaison TLS, rate limiting, authentification JWT/SAML. Expose un endpoint unique de type OpenAI-compatible (/v1/chat/completions) pour faciliter l’adoption.
- **Load Balancer :** Cloud-native (ALB sur AWS, ou Traefik en on-prem).
### Couche 2 — Core Application (monolithe modulaire)
- **Module Auth :** Validation des tokens JWT, résolution RBAC, extraction du contexte utilisateur (département, rôle, politiques appliquées).
- **Module PII Redaction :** Pipeline de détection et anonymisation en temps réel (détaillé section 4).
- **Module Router :** Moteur de règles déterministe qui choisit le modèle cible selon les politiques (détaillé section 5).
- **Module Logger :** Capture structurée de chaque requête/réponse, écriture asynchrone (détaillé section 6).
- **Module Billing :** Comptage tokens, agrégation coûts, alertes budgétaires.
### Couche 3 — Connecteurs IA
- **Adapter Pattern :** Un adaptateur par fournisseur (OpenAI, Anthropic, Azure, Mistral, Ollama/vLLM pour on-prem). Chaque adaptateur normalise les formats de requête/réponse vers un schema interne unifié.
- **Connection Pool :** Gestion des connexions HTTP persistantes vers chaque fournisseur, avec circuit breaker intégré.
### Couche 4 — Stockage
- **PostgreSQL 16 :** Données relationnelles (utilisateurs, politiques, configuration, registre des traitements). Choix justifié : maturité, JSONB pour la flexibilité, Row-Level Security pour l’isolation multi-tenant, chiffrement natif.
- **ClickHouse :** Logs d’audit et analytics. Choix justifié : compression colonnes (10x), requêtes analytiques ultra-rapides sur des milliards de lignes, parfait pour les dashboards et exports.
- **Redis :** Cache de sessions, rate limiting, mapping PII temporaire, file d’attente légère.
### Couche 5 — Observabilité
- **Prometheus + Grafana :** Métriques techniques (latence proxy, débit, erreurs, santé des connecteurs).
- **OpenTelemetry :** Tracing distribué pour suivre chaque requête de bout en bout.
## 3.3 Multi-tenancy
Le MVP implémente un multi-tenant logique :
- **Isolation des données :** Chaque tenant a un tenant_id propagé dans toutes les tables. PostgreSQL Row-Level Security (RLS) empêche tout accès croisé.
- **Isolation des configurations :** Politiques de routage, seuils PII, et RBAC sont scopeés par tenant.
- **Isolation réseau (V2) :** Pour les clients les plus sensibles, un déploiement dédié (namespace Kubernetes isolé ou instance dédiée) sera proposé.
## 3.4 Compatibilité cloud + on-prem
L’application est conteneurisée (Docker) et déployable via Helm chart sur n’importe quel cluster Kubernetes. Trois modes de déploiement sont prévus :
| **Mode** | **Description** | **Cas d’usage** |
|-----------------|--------------------------------------------------------------------------------------------------------|----------------------------------------------------------|
| SaaS (cloud UE) | Hébergé par nous sur AWS eu-west-3 (Paris) ou OVHcloud. Mise à jour automatique. | PME, ETI, entreprises sans contrainte souveraineté forte |
| Hybrid | Control plane dans notre cloud, data plane chez le client. Les données ne quittent pas l’infra client. | Grandes entreprises avec données sensibles |
| On-prem (V2) | Déploiement intégral chez le client. Licence + support. | Défense, santé, secteur public |
# 4. Module d’anonymisation PII
## 4.1 Approche : Détection hybride multi-couches
L’anonymisation est le différenciateur clé du produit. Nous utilisons une approche hybride à trois couches pour maximiser la précision tout en minimisant la latence :
| **Couche** | **Technique** | **PII ciblées** | **Latence** | **Précision** |
|--------------------------------|--------------------------------------------|---------------------------------------------------|-------------|------------------------------|
| 1 — Regex deterministique | Patterns regex précompilés | IBAN, CB, SS, téléphone, email, numéros ID | \< 1 ms | 99%+ (faux positifs faibles) |
| 2 — NER (Presidio + spaCy) | Modèle NER multilangue (fr_core_news_lg) | Noms, adresses, organisations, dates de naissance | 5–15 ms | 92–96% |
| 3 — LLM local (optionnel V1.1) | Modèle léger (Phi-3 mini) pour cas ambigus | Contextes métiers spécifiques, données médicales | 50–100 ms | 97%+ |
## 4.2 Pipeline de traitement
Le pipeline s’exécute de manière synchrone avant chaque appel au modèle IA :
1. Réception du prompt utilisateur via le proxy.
2. Couche 1 — Regex : Scan rapide des patterns déterministes. Chaque match est remplacé par un token pseudonymisé de type \[PII:TYPE:UUID_COURT\] (ex: \[PII:IBAN:a3f2\]).
3. Couche 2 — NER : Le texte (déjà partiellement redacté) passe dans le modèle Presidio. Les entités détectées avec un score de confiance \> 0.85 sont pseudonymisées.
4. Couche 3 (optionnel) — Vérification LLM : En cas de doute (score entre 0.60 et 0.85), un modèle local valide.
5. Le prompt anonymisé est envoyé au modèle IA cible.
6. La réponse est reçue et les tokens PII sont ré-injectés (dé-pseudonymisation) avant renvoi à l’utilisateur.
## 4.3 Pseudonymisation réversible
**Mapping chiffré temporaire :** Chaque remplacement génère une entrée dans un store Redis chiffré (AES-256-GCM) avec un TTL configurable par le tenant (défaut : durée de la session + 1h, max 24h). Ce mapping permet la dé-pseudonymisation de la réponse.
**Après expiration :** Le mapping est supprimé automatiquement. Les logs d’audit ne conservent que le hash SHA-256 du prompt original et la version anonymisée, jamais les données PII en clair.
**Option « zero-retention » :** Pour les clients les plus exigeants, le mapping peut être purement en mémoire (non persisté même dans Redis), avec destruction à la fin de la requête. Contrepartie : la réponse IA ne sera pas dé-pseudonymisée si elle référence des PII.
## 4.4 Analyse de risque RGPD du module
| **Risque** | **Mitigation** | **Risque résiduel** |
|-----------------------------------------|-------------------------------------------------------------------------------|----------------------------------------------|
| Faux négatif : PII non détectée | Pipeline multi-couches + seuil configurable + monitoring du taux de détection | Modéré (mitigé par la couche LLM en V1.1) |
| Faux positif : donnée légitime redactée | Seuil de confiance ajustable + whitelist par tenant | Faible (impact fonctionnel, pas sécuritaire) |
| Mapping PII compromis | Chiffrement AES-256-GCM + TTL court + isolation par tenant | Faible |
| Données PII dans les logs | Seuls les hashs sont stockés + audit d’accès aux logs | Très faible |
# 5. Module de routage IA
## 5.1 Moteur de règles déterministe
Le routage utilise un moteur de règles évaluées par priorité (type firewall). Chaque règle est une combinaison de conditions → actions :
Conditions disponibles (MVP)
- **user.department :** Département de l’utilisateur (RH, Finance, Engineering, Legal, etc.)
- **user.role :** Rôle RBAC (admin, manager, user, auditor)
- **request.sensitivity :** Niveau de sensibilité déduit par le module PII (none, low, medium, high, critical)
- **request.use_case :** Tag de cas d’usage (code_generation, summarization, translation, analysis, creative)
- **request.token_estimate :** Estimation de la taille de la requête
Actions
- **route_to :** Modèle cible (ex: gpt-4o, claude-sonnet-4-5-20250929, mistral-local, llama-onprem)
- **block :** Requête refusée avec message configurable
- **require_approval :** Mise en attente pour validation manager (V1.1)
- **force_anonymize :** Force l’anonymisation même si le score PII est bas
## 5.2 Exemples de politiques
| **Règle** | **Condition** | **Action** |
|------------------------|---------------------------------------------------------|---------------------------------------------------------|
| R1 — Données critiques | sensitivity = critical | route_to: llama-onprem (IA locale uniquement) |
| R2 — RH | department = RH AND sensitivity \>= medium | route_to: mistral-local + force_anonymize |
| R3 — Engineering | department = Engineering AND use_case = code_generation | route_to: claude-sonnet-4-5-20250929 (performance code) |
| R4 — Budget dépassé | department.monthly_cost \> budget_limit | route_to: gpt-4o-mini (modèle économique) |
| R5 — Default | \* (catch-all) | route_to: gpt-4o |
## 5.3 Fallback automatique
En cas d’indisponibilité du modèle cible, le router applique une chaîne de fallback configurable par tenant :
1. Tentative sur le modèle primaire (timeout configurable, défaut 30s).
2. Si échec ou timeout : bascule vers le modèle secondaire défini dans la politique.
3. Si le secondaire échoue : bascule vers le modèle de fallback global (configuré au niveau tenant).
4. Si tout échoue : retour d’une erreur structurée avec code 503 et suggestion de réessai.
Un circuit breaker (pattern Hystrix) désactive automatiquement un modèle après N erreurs consécutives (configurable, défaut 5), évitant de saturer un provider défaillant.
# 6. Journalisation et audit trail
## 6.1 Structure des logs
Chaque interaction génère un enregistrement structuré immutable dans ClickHouse :
| **Champ** | **Type** | **Description** |
|-------------------|------------------|------------------------------------------------------|
| log_id | UUID v7 | Identifiant unique trié chronologiquement |
| tenant_id | UUID | Isolation multi-tenant |
| user_id | UUID | Identifiant utilisateur (lié au SSO) |
| department | String | Département de l’utilisateur |
| timestamp | DateTime64(3) | Horodatage précis au millisecondes |
| model_requested | String | Modèle demandé par l’utilisateur |
| model_actual | String | Modèle effectivement utilisé (après routage) |
| prompt_hash | SHA-256 | Hash du prompt original (jamais le contenu brut) |
| prompt_anonymized | String (chiffré) | Prompt après anonymisation (optionnel, configurable) |
| response_hash | SHA-256 | Hash de la réponse |
| tokens_input | UInt32 | Nombre de tokens en entrée |
| tokens_output | UInt32 | Nombre de tokens en sortie |
| cost_eur | Decimal(10,6) | Coût calculé de la requête |
| pii_detected | Array(String) | Types de PII détectées (\[IBAN, NOM, EMAIL\]) |
| pii_count | UInt16 | Nombre total de PII redactées |
| sensitivity_level | Enum | none / low / medium / high / critical |
| routing_rule_id | String | Règle de routage appliquée |
| latency_ms | UInt32 | Latence totale (proxy + modèle) |
| status | Enum | success / blocked / error / timeout / fallback |
| ip_address | String (hashé) | Adresse IP hashée de l’appelant |
## 6.2 Chiffrement et sécurité des logs
- **En transit :** TLS 1.3 entre l’application et ClickHouse.
- **At rest :** Chiffrement AES-256 au niveau volume (LUKS) + chiffrement applicatif des champs sensibles (prompt_anonymized).
- **Accès :** Seuls les rôles Admin et Auditor peuvent consulter les logs. Chaque accès aux logs est lui-même loggé (audit de l’audit).
- **Immutabilité :** Les logs sont en append-only. Aucune API de suppression individuelle. La purge respecte la politique de rétention configurée.
## 6.3 Rétention
| **Tier** | **Durée** | **Stockage** |
|--------------------|----------------------|---------------------------------------------------------|
| Hot (accès rapide) | 90 jours | ClickHouse SSD — requêtes \< 1s |
| Warm (archivage) | 1 an | ClickHouse HDD compressé — requêtes \< 10s |
| Cold (conformité) | 5 ans (configurable) | Object Storage (S3/MinIO) chiffré — export à la demande |
## 6.4 Dashboard RSSI
Le dashboard temps réel (React + recharts) présente :
- **Vue globale :** Volume de requêtes (24h, 7j, 30j), répartition par modèle, par département.
- **Sécurité :** Nombre de PII détectées/bloquées, requêtes bloquées par politique, tentatives d’accès non autorisées.
- **Coûts :** Dépense par modèle, par département, projection mensuelle, alertes de dépassement.
- **Alertes :** Pic d’utilisation anormal, tentatives d’exfiltration (volume PII élevé soudain), modèle en état dégradé.
## 6.5 Exports conformité
- **PDF :** Rapport mensuel généré automatiquement : synthèse des traitements IA, PII détectées, incidents, conformité RGPD.
- **CSV :** Export brut des logs (filtrés par date, département, modèle) pour intégration SIEM ou audit externe.
- **Syslog (V1.1) :** Export en temps réel au format CEF pour Splunk, Sentinel, QRadar.
# 7. Conformité RGPD et AI Act
## 7.1 Articles RGPD couverts par la plateforme
| **Article** | **Exigence** | **Couverture par AI Governance Hub** |
|--------------|------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Art. 5(1)(a) | Licéité, loyauté, transparence | Journalisation complète de chaque traitement. Le registre documente la base légale configurée par le DPO pour chaque cas d’usage IA. |
| Art. 5(1)(c) | Minimisation des données | Le module PII anonymise automatiquement les données personnelles avant envoi aux LLMs externes, ne transmettant que le strict nécessaire. |
| Art. 5(1)(e) | Limitation de conservation | Politique de rétention configurable par tenant (hot/warm/cold). Purge automatique à expiration. |
| Art. 5(1)(f) | Intégrité et confidentialité | Chiffrement AES-256 at rest et TLS 1.3 en transit. RBAC strict. Audit d’accès. |
| Art. 13–14 | Information des personnes concernées | Documentation automatique des traitements IA avec finalités, destinataires, durées de conservation. Exportable pour intégration dans la politique de confidentialité du client. |
| Art. 15 | Droit d’accès | API de recherche par user_id permettant d’extraire l’ensemble des logs associés à un individu (version anonymisée). |
| Art. 17 | Droit à l’effacement | Endpoint de purge par user_id supprimant les logs et mappings PII associés, avec confirmation d’effacement loggée. |
| Art. 25 | Protection des données dès la conception | L’anonymisation par défaut (privacy by design) est le principe fondamental de l’architecture. |
| Art. 28 | Sous-traitant | Chaque fournisseur IA est documenté comme sous-traitant avec ses DPA. Le registre maintient la liste à jour. |
| Art. 30 | Registre des traitements | Génération automatique du registre au format Article 30, exportable PDF/CSV. |
| Art. 32 | Sécurité du traitement | Chiffrement, pseudonymisation, contrôle d’accès, audit continu, tests de résilience. |
| Art. 33–34 | Notification de violations | Détection d’incidents (fuite PII, accès non autorisé) avec alertes temps réel pour faciliter la notification dans les 72h. |
| Art. 35 | AIPD / DPIA | Template d’analyse d’impact pré-rempli pour chaque cas d’usage IA, avec évaluation des risques automatisée. |
## 7.2 Préparation AI Act européen
Le Règlement européen sur l’Intelligence Artificielle (Règlement (UE) 2024/1689) impose des obligations progressives. AI Governance Hub positionne ses clients en conformité anticipée :
Classification des risques (Article 6)
La plateforme intègre un moteur de classification assistée qui permet au DPO de qualifier chaque cas d’usage IA selon les quatre niveaux de risque de l’AI Act :
| **Niveau** | **Exemples** | **Obligations** | **Support plateforme** |
|--------------------------|----------------------------------------------------|---------------------------------|----------------------------------------------------------------------------------|
| Interdit (Art. 5) | Scoring social, manipulation subliminale | Usage prohibé | Blocage automatique si le cas d’usage est tagué interdit |
| Haut risque (Annexe III) | Recrutement IA, scoring crédit, diagnostic médical | Conformité complète (Art. 8–15) | Documentation automatisée, journalisation complète, traçabilité, contrôle humain |
| Risque limité (Art. 50) | Chatbots, génération de contenu | Obligations de transparence | Tag automatique des réponses générées par IA |
| Risque minimal | Filtres anti-spam, auto-complétion | Aucune obligation spécifique | Journalisation standard |
Obligations pour les « deployers » (Article 26)
AI Governance Hub aide les entreprises à remplir leurs obligations en tant que « déployeurs » de systèmes IA :
- **Supervision humaine (Art. 14) :** Le workflow d’approbation (V1.1) permet un contrôle humain sur les cas sensibles.
- **Journalisation automatique (Art. 12) :** Chaque utilisation d’un système à haut risque est traçée avec l’ensemble des métadonnées requises.
- **Information des personnes (Art. 13) :** Documentation automatique des finalités et des modèles utilisés.
- **DPIA (Art. 27) :** Analyse d’impact fondamentale prise en charge par la plateforme pour les systèmes à haut risque.
## 7.3 Documentation automatique
La plateforme génère automatiquement :
- **Registre Article 30 RGPD :** Liste complète des traitements IA avec finalités, bases légales, destinataires, durées, mesures de sécurité.
- **Fiche technique AI Act par système :** Description du modèle, classification de risque, mesures de mitigation, tests effectués.
- **Rapport d’incident :** Template pré-rempli en cas de détection d’anomalie PII, avec chronologie et impact estimé.
- **DPIA template :** Analyse d’impact pré-remplie pour chaque cas d’usage IA à haut risque.
# 8. Sécurité
## 8.1 Principes de sécurité
La sécurité est intégrée à chaque couche de l’architecture selon une approche defense-in-depth :
| **Couche** | **Mesure** | **Implémentation** |
|------------------|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Réseau | Zero Trust Network | mTLS entre tous les composants internes. Aucune communication en clair même en réseau privé. Network policies Kubernetes restrictives (deny-all par défaut). |
| Transport | TLS 1.3 obligatoire | Certificats gérés par cert-manager (Let’s Encrypt) ou PKI client en on-prem. |
| Données au repos | AES-256-GCM | Chiffrement volume (LUKS/EBS encryption) + chiffrement applicatif des champs sensibles (clés envelopes via KMS). |
| Application | RBAC + ABAC | Contrôle d’accès par rôle et par attribut. Chaque endpoint est protégé par une politique d’autorisation. |
| Secrets | HashiCorp Vault | Rotation automatique des secrets (API keys LLM, credentials DB). Pas de secrets en variables d’env ou fichiers de config. |
| API | Rate limiting + WAF | Rate limiting par tenant/user (Kong). Protection OWASP Top 10 via ModSecurity/Cloud WAF. |
| Audit | Immutable audit trail | Tous les accès admin, modifications de politique, et consultations de logs sont eux-mêmes audités. |
## 8.2 Gestion des clés et secrets
Les clés API des fournisseurs IA (OpenAI, Anthropic, etc.) sont le secret le plus critique. Elles sont gérées selon les principes suivants :
- **Stockage :** HashiCorp Vault (ou AWS Secrets Manager en mode SaaS). Jamais en base de données ni en variable d’environnement.
- **Accès :** L’application récupère les clés via l’API Vault avec authentification par service account Kubernetes.
- **Rotation :** Rotation automatisée tous les 90 jours. Alerte si une clé n’a pas été tournée.
- **Isolation :** Chaque tenant a son propre path dans Vault. Un tenant ne peut jamais accéder aux secrets d’un autre.
## 8.3 Pentest readiness
La plateforme est conçue pour passer un audit de sécurité externe (type pentest black/grey box) dès le lancement. Mesures préparatoires :
- **SAST :** Analyse statique intégrée à la CI/CD (Semgrep pour le code, Trivy pour les images Docker).
- **DAST :** Scan OWASP ZAP automatisé en staging avant chaque release.
- **Dépendances :** Audit continu des dépendances (npm audit, pip audit, Snyk).
- **Bug bounty :** Programme prévu post-lancement (V1.1) via plateforme YesWeHack.
# 9. Business Model
## 9.1 Modèle de pricing hybride
Le pricing combine un abonnement par utilisateur (prévisibilité pour le client) et un composant volumique (tokens monitorisés) qui aligne la valeur perçue avec l’usage réel :
| | **Starter** | **Business** | **Enterprise** |
|---------------------------|--------------------------|-------------------------------------|---------------------------------------------|
| Cible | Startups, PME innovantes | ETI, départements de grands groupes | CAC 40, banques, assurances, secteur public |
| Utilisateurs inclus | Jusqu’à 50 | Jusqu’à 500 | Illimité |
| Prix / user / mois | 15 € | 25 € | Sur devis (35–55 €) |
| Tokens monitorisés inclus | 5M / mois | 50M / mois | Custom |
| Token supplémentaire | 0.50 € / 1M tokens | 0.30 € / 1M tokens | Négocié |
| Modèles IA connectés | 3 max | 10 max | Illimité |
| Anonymisation PII | Regex uniquement | Regex + NER | Regex + NER + LLM local |
| SSO / SAML | Non | Oui | Oui + custom IdP |
| Rapports conformité | Basique (CSV) | RGPD + AI Act (PDF) | Custom + DPIA + audit trail complet |
| Déploiement | SaaS uniquement | SaaS ou hybrid | SaaS, hybrid ou on-prem |
| Support | Email (48h) | Email + Slack (24h) | Dédié + CSM + SLA 4h |
| SLA | 99.5% | 99.9% | 99.95% + pénalités |
## 9.2 Estimation de revenus
Hypothèse Year 1 (prudente) : 5 clients Starter, 3 Business, 1 Enterprise.
| **Tier** | **Clients** | **Users moyens** | **MRR unitaire** | **MRR total** |
|------------|-------------|------------------|------------------|----------------------|
| Starter | 5 | 30 | 450 € | 2 250 € |
| Business | 3 | 200 | 5 000 € | 15 000 € |
| Enterprise | 1 | 1 000 | 40 000 € | 40 000 € |
| TOTAL | | | | 57 250 € (687k€ ARR) |
## 9.3 Stratégie go-to-market
Persona primaire : RSSI
Le RSSI est le champion interne. Le pitch principal est : « Reprenez le contrôle sur les flux IA avant qu’un incident ne vous y oblige. » L’angle sécurité (Shadow AI, fuite PII) résonne immédiatement.
Persona secondaire : DPO / Compliance
Le DPO est l’allié pour la décision. L’AI Act crée une urgence réglementaire dont la plateforme est la réponse directe.
Acheteur final : DSI
Le DSI signe le budget. Le pitch DSI combine TCO (rationalisation des abonnements IA), risque (conformité, audit) et efficacité (un point d’accès unique pour tous les LLMs).
Canaux
- **Inbound :** Content marketing (blog technique, whitepapers AI Act), webinaires conformité RGPD/IA, référencement sur comparateurs B2B (G2, Capterra).
- **Outbound :** Sales outreach ciblé sur les entreprises +500 employés ayant des usages IA documentés. Partenariats avec cabinets de conseil cyber et RGPD.
- **Communauté :** Open-sourcing du module PII Presidio custom pour construire la crédibilité technique.
# 10. Stack technique recommandée
| **Composant** | **Technologie** | **Justification** | **Alternative** |
|------------------------|---------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| Backend — API | Go 1.22 | Performance native (proxy haute perf), faible empreinte mémoire, typage fort, excellent support concurrence (goroutines pour le streaming SSE). Go est le standard pour les reverse proxies (Traefik, Caddy). | Rust (plus complexe, recrutement difficile) ou Node.js (moins performant pour le proxy) |
| Backend — Workers | Python 3.12 | Ecosystème NLP/NER (spaCy, Presidio). Utilisé pour le pipeline d’anonymisation et les tâches async (génération rapports, purge). | Go (mais perte de l’écosystème NLP) |
| Frontend | React 18 + TypeScript + Vite | Ecosystème mature, composants shadcn/ui pour un design professionnel rapidement, recharts pour les dashboards. | Vue.js (viable mais écosystème composants enterprise moindre) |
| API Gateway | Kong Gateway (OSS) | Gestion des routes, rate limiting, auth plugins (JWT, SAML), logging. Configurable via API déclarative. Déjà éprouvé en production enterprise. | Traefik (plus léger mais moins de plugins enterprise) |
| Base relationnelle | PostgreSQL 16 | Row-Level Security pour multi-tenant, JSONB pour la flexibilité des politiques, maturité, performance, chiffrement natif. | CockroachDB (si distribution géo nécessaire V2) |
| Base analytique / Logs | ClickHouse | Compression 10x, requêtes analytiques ultra-rapides (agrégations, GROUP BY sur milliards de lignes), parfait pour dashboard temps réel et exports. | TimescaleDB (plus simple mais moins performant à l’échelle) |
| Cache / Queue | Redis 7 (Valkey) | Sessions, rate limiting, cache mapping PII, pub/sub pour notifications temps réel. | KeyDB (compatible Redis, multi-threadé) |
| File de messages | Redis Streams (MVP) → NATS (V2) | Redis Streams suffit au MVP pour les tâches async. NATS en V2 pour le découplage si extraction en microservices. | RabbitMQ (plus lourd pour le MVP) |
| IAM / Auth | Keycloak | SSO, SAML 2.0, OIDC, RBAC complet, multi-tenant, federation d’identité. Standard enterprise. Hébergeable en UE. | Auth0 (SaaS US, problème souveraineté) |
| Secrets | HashiCorp Vault | Gestion centralisée des secrets, rotation automatique, audit trail. Intégration native Kubernetes. | AWS Secrets Manager (si 100% AWS) |
| Conteneurs | Docker + Kubernetes (K8s) | Standard de déploiement. Helm charts pour reproductibilité. Compatible cloud et on-prem. | Docker Compose (dév uniquement) |
| CI/CD | GitLab CI | Pipeline intégré : build, test, SAST (Semgrep), scan images (Trivy), deploy. Hébergeable en UE. | GitHub Actions (SaaS US) |
| Monitoring | Prometheus + Grafana | Métriques (latence, débit, erreurs). Alerting via Alertmanager. Stack open-source, pas de lock-in. | Datadog (coût élevé en enterprise) |
| Tracing | OpenTelemetry + Jaeger | Tracing distribué pour suivre chaque requête de bout en bout à travers les modules. | Tempo (alternative Grafana) |
| NER / NLP | Microsoft Presidio + spaCy | Presidio est le standard open-source pour la détection PII. Extensible, multilangue, intégré à spaCy. | AWS Comprehend (coût + données hors UE) |
| Infra cloud | AWS eu-west-3 (Paris) | Certifié HDS, ISO 27001. Région UE. Compatibilité hébergement souverain (OVHcloud/Scaleway en fallback). | OVHcloud (moins de services managés) |
# 11. Plan de développement — 6 mois
**Équipe cible :** 1 CTO/Lead Backend (Go), 1 Backend Senior (Go/Python), 1 Frontend Senior (React), 1 DevOps/SRE, 1 Product Manager (0.5 ETP). Total : 4.5 ETP.
Mois 1 — Fondations et proxy de base
Objectifs
- Infrastructure de base opérationnelle (CI/CD, Kubernetes, monitoring)
- Reverse proxy fonctionnel capable de relayer des requêtes vers OpenAI
- Authentification basique (JWT)
Livrables
| **Tâche** | **Responsable** | **Durée** |
|----------------------------------------------------------------------------------|-----------------|------------|
| Setup GitLab, CI/CD pipeline, registre Docker, cluster K8s staging | DevOps | 1 semaine |
| Scaffolding monolithe Go : structure modulaire, routing HTTP, middleware chain | Lead Backend | 1 semaine |
| Module Proxy : relay transparent vers OpenAI API (non-streaming + streaming SSE) | Lead Backend | 2 semaines |
| Authentification JWT basique + middleware auth | Backend Sr | 1 semaine |
| Setup PostgreSQL + ClickHouse + Redis en Helm | DevOps | 1 semaine |
| Modèle de données initial (users, tenants, policies) + migrations | Backend Sr | 1 semaine |
| Setup Keycloak + intégration OIDC basique | DevOps | 1 semaine |
**Point critique :** Le proxy doit supporter le streaming SSE dès le début. C’est un choix technique structurant qui impacte toute l’architecture.
Mois 2 — Anonymisation PII et multi-modèle
Objectifs
- Pipeline PII fonctionnel (regex + NER Presidio)
- Support multi-modèle (Anthropic, Azure OpenAI, Mistral)
- RBAC fonctionnel
Livrables
| **Tâche** | **Responsable** | **Durée** |
|--------------------------------------------------------------|-----------------|------------|
| Module PII : couche 1 regex (IBAN, email, tél, CB, SS) | Backend Sr | 1 semaine |
| Module PII : intégration Presidio/spaCy (NER multilangue) | Backend Sr | 2 semaines |
| Pseudonymisation réversible + stockage mapping Redis chiffré | Backend Sr | 1 semaine |
| Adaptateurs multi-modèle (Anthropic, Azure, Mistral, Ollama) | Lead Backend | 2 semaines |
| Module RBAC : rôles, permissions, middleware d’autorisation | Lead Backend | 1 semaine |
| Intégration SAML 2.0 dans Keycloak + tests avec Azure AD | DevOps | 1 semaine |
| Setup frontend React : auth flow, layout, navigation | Frontend | 2 semaines |
**Risque technique :** La latence du pipeline PII doit rester \< 50ms pour ne pas dégrader l’expérience. Benchmark dès la semaine 2.
Mois 3 — Routage intelligent et journalisation
Objectifs
- Moteur de règles de routage fonctionnel
- Journalisation complète dans ClickHouse
- Dashboard MVP fonctionnel
Livrables
| **Tâche** | **Responsable** | **Durée** |
|---------------------------------------------------------------------------|-----------------|------------|
| Module Router : moteur de règles, évaluation par priorité, fallback chain | Lead Backend | 2 semaines |
| Module Router : circuit breaker, health check des providers | Lead Backend | 1 semaine |
| Module Logger : écriture async ClickHouse, structure complète des logs | Backend Sr | 2 semaines |
| Module Billing : comptage tokens, agrégation par user/dept/model | Backend Sr | 1 semaine |
| Dashboard frontend : overview (volume, coûts, PII), composants recharts | Frontend | 3 semaines |
| API admin : CRUD politiques de routage, gestion utilisateurs | Lead Backend | 1 semaine |
Mois 4 — Conformité et sécurité
Objectifs
- Rapports conformité RGPD et AI Act opérationnels
- Hardening sécurité complet
- Dashboard RSSI enrichi
Livrables
| **Tâche** | **Responsable** | **Durée** |
|-----------------------------------------------------------------------------|-----------------|------------|
| Module Compliance : registre Art. 30, génération PDF, classification AI Act | Backend Sr | 3 semaines |
| API droits RGPD : accès (Art. 15), effacement (Art. 17), export | Backend Sr | 1 semaine |
| Dashboard RSSI : alertes, détection pics, vue sécurité | Frontend | 2 semaines |
| Hardening : mTLS interne, network policies K8s, Vault intégration | DevOps | 2 semaines |
| SAST/DAST : Semgrep + Trivy + OWASP ZAP intégrés CI/CD | DevOps | 1 semaine |
| Chiffrement at-rest applicatif des champs sensibles | Lead Backend | 1 semaine |
| Tests de charge : benchmark proxy (cible : 1000 req/s, p99 \< 200ms) | DevOps + Lead | 1 semaine |
Mois 5 — Stabilisation et beta privée
Objectifs
- Beta privée avec 2–3 clients pilotes
- Tests end-to-end complets
- Documentation technique et utilisateur
Livrables
| **Tâche** | **Responsable** | **Durée** |
|-----------------------------------------------------------------------------------|-----------------|------------|
| Tests E2E automatisés : parcours complets proxy → PII → routing → log → dashboard | Tous | 2 semaines |
| Onboarding clients pilotes : configuration tenant, import users SSO | PM + DevOps | 2 semaines |
| Bug fixes et ajustements UX d’après feedback pilotes | Tous | 2 semaines |
| Documentation API (OpenAPI 3.1) + guide d’intégration | Lead Backend | 1 semaine |
| Documentation utilisateur + guide admin | PM + Frontend | 1 semaine |
| Optimisation performance d’après données réelles | Lead Backend | 1 semaine |
Mois 6 — Production et lancement
Objectifs
- Mise en production sur infra UE
- Premier contrat signé
- Pentest externe passé
Livrables
| **Tâche** | **Responsable** | **Durée** |
|-------------------------------------------------------------------|------------------|-------------|
| Déploiement production : cluster K8s EU (AWS eu-west-3), DR setup | DevOps | 1 semaine |
| Pentest externe (cabinet spécialisé, grey box) | Externe + DevOps | 2 semaines |
| Remédiation findings pentest | Tous | 1 semaine |
| Landing page, démo interactive, matériel commercial | PM + Frontend | 2 semaines |
| Onboarding premier client payant | PM + DevOps | 2 semaines |
| Monitoring production : alerting, on-call, runbooks | DevOps | 1 semaine |
| Rétro et planification V1.1 | Tous | 0.5 semaine |
## 11.7 Risques techniques et mitigations
| **Risque** | **Probabilité** | **Impact** | **Mitigation** |
|---------------------------------------------|-----------------|------------|-------------------------------------------------------------------------------------------------------------|
| Latence PII pipeline trop élevée | Moyenne | Haut | Benchmark dès M2. Option : désactiver NER pour les requêtes basse sensibilité. Cache des patterns déjà vus. |
| Intégration SSO complexe chez le client | Haute | Moyen | Keycloak supporte SAML/OIDC natif. Prévoir 1 semaine d’intégration par client. |
| Changements de format API des providers LLM | Moyenne | Moyen | Adapter pattern : les changements sont isolés dans un seul fichier par provider. |
| Faux négatifs PII en production | Moyenne | Haut | Mode audit (log sans bloquer) pendant 2 semaines de rodage. Feedback loop avec le client. |
| Difficulté de recrutement Go + NLP | Haute | Haut | Prévoir 1 mois de recrutement en amont. Alternative : consultants spécialisés pour le module PII Python. |
| Évolution rapide de l’AI Act | Moyenne | Moyen | Veille réglementaire continue. Le module compliance est configurable (règles non hardcodées). |
# 12. Synthèse des arbitrages clés
| **Décision** | **Choix retenu** | **Raison** |
|---------------|--------------------------|-----------------------------------------------------------------------|
| Architecture | Monolithe modulaire | Rapidité de livraison avec équipe réduite, extraction future possible |
| Langage proxy | Go | Performance native, streaming SSE, concurrence, faible mémoire |
| Langage NLP | Python (Presidio/spaCy) | Ecosystème NER mature, pas d’équivalent en Go |
| Base logs | ClickHouse | Performance analytique incomparable pour les dashboards et exports |
| IAM | Keycloak | SAML/OIDC natif, hébergeable UE, open-source |
| Multi-tenant | Logique (RLS PostgreSQL) | Suffisant pour le MVP, isolation physique en V2 |
| PII detection | Hybride regex + NER | Meilleur rapport précision/latence que le tout-LLM |
| Déploiement | SaaS EU + hybrid option | Couvre 90% du marché cible, on-prem en V2 |
| Pricing | Hybride (user + tokens) | Prévisible pour le client, scalable pour nous |
Ce document constitue la base technique et stratégique pour le démarrage du projet AI Governance Hub. Chaque choix a été fait en privilégiant la livraison rapide d’un produit commercialisable, sans compromettre la sécurité ni la conformité réglementaire. Les fondations sont conçues pour évoluer vers une architecture plus distribuée quand le produit et l’équipe le justifieront.

454
docs/AI_Governance_Hub_Plan_Realisation.md Normal file
View File

@ -0,0 +1,454 @@
**AI GOVERNANCE HUB**
Plan de Réalisation Détaillé
De l’analyse critique du PRD au plan d’exécution étape par étape
**CONFIDENTIEL — Février 2026**
Guide d’exécution pour équipe technique — 164 tâches, 26 semaines
# Partie A — Analyse critique du PRD
Avant de planifier l’exécution, une analyse honnête du PRD est nécessaire. Le document est solide sur la vision et l’architecture, mais plusieurs points nécessitent des corrections pour un plan d’exécution réaliste.
## A.1 — Ce qui est bien fait dans le PRD
- **Architecture monolithe modulaire :** Choix parfaitement calibré pour l’équipe et le timeline. Pas de sur-ingénierie.
- **Séparation Go (proxy) / Python (NLP) :** Chaque langage est utilisé pour ses forces. Le surcoût ops de 2 runtimes est accepté car le gain en performance et écosystème est majeur.
- **Pipeline PII hybride :** L’approche regex + NER est le bon compromis latence/précision. Le tout-LLM serait trop lent et trop cher.
- **ClickHouse pour les logs :** Choix différenciant. La performance analytique permettra des dashboards impressionnants en démo.
- **Pricing hybride :** Le modèle user + tokens aligne la valeur. Le tier Enterprise à 40k€ MRR est réaliste pour un CAC 40.
- **Scope MVP bien délimité :** Le hors-scope est clairement défini. Pas de feature creep.
## A.2 — Problèmes identifiés et corrections
| **Problème dans le PRD** | **Impact** | **Correction appliquée dans ce plan** |
|------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Les durées par tâche sont optimistes. Beaucoup de tâches à « 1 semaine » qui en prendront 2 en réalité (intégration, tests, edge cases). | Haut — dérapage calendaire quasi certain | Ce plan ajoute 20% de buffer par sprint. Chaque tâche est décomposée en sous-tâches avec des critères d’acceptance précis. |
| La communication inter-modules Go ↔ Python n’est pas détaillée. Comment le proxy Go appelle-t-il le service PII Python ? | Haut — choix structurant | Le plan précise : le module PII tourne comme sidecar gRPC. Le proxy Go fait un appel gRPC local (\<1ms overhead). Alternative : embedded Python via cgo (rejeté : trop fragile). |
| Le plan mois par mois ne précise pas les dépendances entre tâches. Certaines sont parallélisables, d’autres bloquantes. | Moyen — goulots d’étranglement | Ce plan inclut un graphe de dépendances et identifie le chemin critique. |
| Les tests ne sont prévus qu’au mois 5. C’est trop tard. | Haut — dette technique | Ce plan intègre les tests dès le sprint 1. Chaque module a ses tests unitaires et d’intégration en parallèle du développement. |
| Le frontend est sous-estimé. « 2 semaines setup + 3 semaines dashboard » pour un dashboard enterprise complet est irréaliste. | Moyen — UX insuffisante au lancement | Le plan alloue le frontend en continu dès le mois 2, avec des livrables incrémentaux chaque sprint. |
| Aucune mention du mode « playground » / démo intégrée pour les prospects. | Moyen — impact commercial | Ajout d’un playground intégré (prompt test avec visualisation PII) au sprint 8. |
| Le plan ne prévoit pas de gestion de la configuration des providers IA côté UI. | Moyen — onboarding complexe | Ajout d’un wizard de configuration des providers dans le dashboard admin. |
| Le PRD ne détaille pas la stratégie de migration/rollback des déploiements. | Moyen — risque production | Ce plan inclut blue/green deployment dès le mois 4 et des runbooks de rollback. |
## A.3 — Décisions techniques complémentaires
Ces décisions n’étaient pas dans le PRD mais sont indispensables pour l’exécution :
- **Communication Go ↔ Python :** gRPC avec Protocol Buffers. Le service PII Python est un sidecar dans le même pod Kubernetes. Latence mesurée : ~2ms aller-retour. Schema gRPC versionné dans un repo partagé (proto/).
- **Stratégie de test :** Pyramide classique : 70% unit (Go: testing + testify, Python: pytest), 20% intégration (testcontainers pour PG/CH/Redis), 10% E2E (Playwright pour le frontend, scripts curl/httpie pour l’API).
- **Feature flags :** Système de feature flags maison simple (table PostgreSQL + cache Redis, ~50 lignes de code). Permet de livrer du code en production sans l’activer. Critique pour la beta.
- **Gestion des erreurs :** Chaque module expose des erreurs typées (Go errors wrap). Le proxy retourne des erreurs structurées JSON compatibles OpenAI API format (type, message, code).
- **Versionning API :** Préfixe /v1/ dès le début. Pas de versionning par header (trop complexe pour les clients enterprise).
- **Documentation :** OpenAPI 3.1 généré automatiquement depuis les annotations Go (swaggo). Pas de doc manuelle qui diverge.
# Partie B — Organisation et méthodologie
## B.1 — Équipe et rôles
| **Rôle** | **Profil** | **Responsabilités principales** | **Charge** |
|--------------------|----------------------------------------------------|-------------------------------------------------------------------------------|------------|
| CTO / Lead Backend | Senior Go (7+ ans), expérience proxy/networking | Architecture, module Proxy, module Router, code reviews, décisions techniques | 100% |
| Backend Senior | Go + Python, expérience NLP | Module PII (Python), module Logger, module Billing, adaptateurs IA | 100% |
| Frontend Senior | React/TypeScript, expérience dashboard data-heavy | Dashboard, admin UI, playground, auth flow, UX | 100% |
| DevOps / SRE | Kubernetes, AWS, CI/CD, sécurité | Infra, CI/CD, monitoring, sécurité, déploiements, Keycloak | 100% |
| Product Manager | Expérience B2B SaaS enterprise, compréhension RGPD | Specs, priorisation, clients pilotes, documentation utilisateur, commercial | 50% |
## B.2 — Méthodologie de travail
Sprints de 2 semaines, avec les rituels suivants :
| **Rituel** | **Fréquence** | **Durée** | **Contenu** |
|------------------------------|--------------------------------|-----------|---------------------------------------------------|
| Sprint Planning | Début de sprint | 2h | Décomposition des stories, estimation, engagement |
| Daily Standup | Quotidien | 15min | Blockers, progression, coordination |
| Sprint Review | Fin de sprint | 1h | Démo du livrable, feedback |
| Sprint Retro | Fin de sprint | 45min | Amélioration continue |
| Architecture Decision Record | Ad hoc | 30min | Documentation des choix techniques clés |
| Security Review | Toutes les 2 semaines (dès M3) | 1h | Revue sécurité des développements récents |
## B.3 — Gestion des repos et conventions
- **Monorepo :** Un seul repo GitLab contenant : /cmd/proxy (Go main), /internal/ (modules Go), /services/pii (Python), /web (React), /deploy (Helm charts), /proto (gRPC schemas), /docs.
- **Branching :** Trunk-based development. Feature branches courtes (\<3 jours). Merge via MR avec 1 review obligatoire. CI passe avant merge.
- **Commits :** Conventional Commits (feat:, fix:, chore:). Changelog généré automatiquement.
- **Environnements :** dev (local docker-compose), staging (K8s cluster dédié, deploy auto sur merge to main), production (K8s, deploy manuel approuvé).
# Partie C — Plan d’exécution sprint par sprint
Le plan est découpé en 13 sprints de 2 semaines (26 semaines = 6 mois). Chaque sprint a un objectif clair, des tâches décomposées, des critères d’acceptance, et des dépendances explicitées.
**Légende priorités :** BLOQUANT = sur le chemin critique, aucun retard acceptable. IMPORTANT = décalable d’1 sprint max. SOUHAITABLE = nice-to-have pour ce sprint.
## PHASE 1 — Fondations (Sprints 1–4, Semaines 1–8)
**Objectif de phase :** Un proxy fonctionnel qui relaie des requêtes vers OpenAI avec authentification, et l’infrastructure complète pour développer efficacement.
### Sprint 1 — Semaines 1–2 : Bootstrapping
**Objectif :** Toute l’équipe peut développer, tester et déployer. Le squelette applicatif compile et se déploie en staging.
| **\#** | **Tâche** | **Responsable** | **Priorité** | **Critère d’acceptance** |
|--------|-----------------------------------------------------------------------------------------------------------------|---------------------------|--------------|-------------------------------------------------------------------|
| 1.1 | Création monorepo GitLab + structure de dossiers (/cmd, /internal, /services/pii, /web, /deploy, /proto, /docs) | DevOps | BLOQUANT | Repo accessible, README avec instructions de setup local |
| 1.2 | Pipeline CI/CD GitLab : build Go, build Python, build React, lint, tests unitaires, scan Trivy | DevOps | BLOQUANT | Pipeline green sur commit vide. Build \< 5min |
| 1.3 | Docker Compose local : Go app + PostgreSQL 16 + ClickHouse + Redis 7 + Keycloak | DevOps | BLOQUANT | docker-compose up démarre tout en \< 60s. Health checks OK |
| 1.4 | Cluster K8s staging (AWS EKS eu-west-3) + namespace + ingress Traefik | DevOps | BLOQUANT | kubectl get nodes retourne 3 nodes. Ingress accessible via HTTPS |
| 1.5 | Scaffolding Go : main.go, server HTTP (chi router), middleware chain vide, graceful shutdown, health endpoint | Lead Backend | BLOQUANT | GET /healthz retourne 200. Graceful shutdown fonctionne (SIGTERM) |
| 1.6 | Configuration management : Viper (Go) + fichier config.yaml + override par env vars | Lead Backend | IMPORTANT | Config chargée au démarrage. Pas de valeurs hardcodées |
| 1.7 | Modèle de données PostgreSQL v1 : tables tenants, users, api_keys + migrations (golang-migrate) | Backend Sr | IMPORTANT | Migrations up/down fonctionnent. Schema créé proprement |
| 1.8 | Setup Keycloak : realm par défaut, client OIDC, utilisateur test | DevOps | IMPORTANT | Login via Keycloak retourne un JWT valide |
| 1.9 | Définition des schemas gRPC (proto/) : PiiRequest, PiiResponse, PiiEntity | Lead Backend + Backend Sr | IMPORTANT | Proto compile sans erreur. Stubs Go et Python générés |
| 1.10 | Scaffolding service PII Python : FastAPI + endpoint gRPC + Dockerfile + pytest setup | Backend Sr | SOUHAITABLE | Service démarre, répond à un healthcheck gRPC |
**Dépendances :** 1.5 dépend de 1.1. 1.4 dépend de 1.2. 1.7 dépend de 1.3. 1.8 dépend de 1.3. 1.9 dépend de 1.5 et 1.10.
**Risque sprint :** Setup EKS peut prendre plus longtemps que prévu (IAM, VPC, security groups). Mitigation : utiliser un module Terraform prouvé (terraform-aws-eks) ou Pulumi.
### Sprint 2 — Semaines 3–4 : Proxy core + Auth
**Objectif :** Le proxy relaie des requêtes vers OpenAI (non-streaming ET streaming SSE) avec authentification JWT.
| **\#** | **Tâche** | **Responsable** | **Priorité** | **Critère d’acceptance** |
|--------|--------------------------------------------------------------------------------------------------------------------------------|-----------------|--------------|--------------------------------------------------------------------------------------|
| 2.1 | Module Proxy — relay non-streaming : recevoir POST /v1/chat/completions, forwarder à OpenAI, retourner la réponse | Lead Backend | BLOQUANT | curl vers le proxy retourne la même réponse qu’un appel direct à OpenAI |
| 2.2 | Module Proxy — relay streaming SSE : support du paramètre stream:true, flush chunk par chunk au client | Lead Backend | BLOQUANT | Client reçoit les chunks en temps réel. Pas de buffering. Test avec curl --no-buffer |
| 2.3 | Middleware Auth : validation JWT (signature RS256, expiration, issuer Keycloak), extraction claims (user_id, tenant_id, roles) | Backend Sr | BLOQUANT | Requête sans JWT = 401. JWT expiré = 401. JWT valide = forward + contexte injecté |
| 2.4 | Middleware Request ID : génération UUID v7 par requête, propagation dans tous les headers et logs | Lead Backend | IMPORTANT | Chaque réponse contient X-Request-Id. Logs contiennent le même ID |
| 2.5 | Middleware Logging basique : log de chaque requête (méthode, path, status, durée) en JSON structuré (zerolog) | Lead Backend | IMPORTANT | Logs visibles dans stdout. Format JSON parseable |
| 2.6 | Tests unitaires proxy : 15+ tests couvrant les cas nominaux, erreurs OpenAI, timeouts, headers | Lead Backend | IMPORTANT | Coverage \> 80% sur le module proxy. go test -race passe |
| 2.7 | Tests d’intégration auth : test avec Keycloak via testcontainers | Backend Sr | IMPORTANT | Test end-to-end : obtenir token Keycloak → appeler proxy → succès |
| 2.8 | Déploiement auto staging : merge to main déploie en staging via Helm | DevOps | IMPORTANT | Chaque merge déclenche un déploiement. Rollback possible en 1 commande |
| 2.9 | Prometheus metrics basiques : request_count, request_duration_seconds, request_errors_total | DevOps | SOUHAITABLE | Métriques visibles dans Grafana staging |
**Dépendances :** 2.1–2.2 sont sur le chemin critique — tout le reste en dépend. 2.3 dépend de 1.8 (Keycloak). 2.8 dépend de 1.4 (K8s staging).
**Risque sprint :** Le streaming SSE est le point technique le plus délicat du projet. Le proxy doit flusher les chunks sans bufferiser. En Go, cela nécessite un Flusher HTTP custom et une gestion fine des goroutines. Prévoir 3-4 jours de debug.
### Sprint 3 — Semaines 5–6 : Anonymisation PII v1
**Objectif :** Le pipeline PII détecte et anonymise les données sensibles dans les prompts avant envoi au LLM. Dé-pseudonymisation fonctionnelle.
| **\#** | **Tâche** | **Responsable** | **Priorité** | **Critère d’acceptance** |
|--------|---------------------------------------------------------------------------------------------------------------------------|-----------------|--------------|----------------------------------------------------------------------------------------------------------|
| 3.1 | PII Couche 1 — Regex : patterns compilés pour IBAN FR/EU, emails, téléphones FR/intl, n° SS, cartes bancaires (Luhn) | Backend Sr | BLOQUANT | Jeu de tests de 100+ exemples positifs/négatifs. Precision \> 99%, Recall \> 95% |
| 3.2 | PII Couche 2 — NER : intégration Presidio avec modèle spaCy fr_core_news_lg. Détection noms, adresses, organisations | Backend Sr | BLOQUANT | Benchmark sur corpus français : F1-score \> 0.90 sur les entités PER, LOC, ORG |
| 3.3 | Pipeline unifié : orchestration regex → NER, déduplication des détections, scoring de confiance unifié | Backend Sr | BLOQUANT | Un prompt contenant 5 types de PII différents les détecte tous. Latence \< 50ms sur prompt de 500 tokens |
| 3.4 | Pseudonymisation : remplacement par tokens \[PII:TYPE:UUID\], stockage mapping dans Redis (AES-256-GCM, TTL configurable) | Backend Sr | BLOQUANT | Le prompt envoyé au LLM ne contient aucune PII en clair. Le mapping est chiffré dans Redis |
| 3.5 | Dé-pseudonymisation : réinjection des valeurs originales dans la réponse du LLM | Backend Sr | BLOQUANT | La réponse renvoyée à l’utilisateur contient les valeurs originales, pas les tokens |
| 3.6 | Intégration gRPC Proxy ↔ PII : le proxy Go appelle le service PII Python via gRPC avant chaque forward | Lead Backend | BLOQUANT | Le flux complet fonctionne : user → proxy → PII (gRPC) → LLM → PII (de-pseudo) → user |
| 3.7 | Benchmark latence : mesure p50, p95, p99 du pipeline PII sur 1000 requêtes variées | Backend Sr | IMPORTANT | p99 \< 50ms pour prompts \< 500 tokens. p99 \< 100ms pour prompts \< 2000 tokens |
| 3.8 | Tests unitaires PII : 50+ tests couvrant chaque type de PII, edge cases, texte multilangue | Backend Sr | IMPORTANT | pytest passe. Coverage \> 85% sur le service PII |
**Chemin critique :** Ce sprint est le plus risqué techniquement. Si le p99 dépasse 100ms, il faut envisager : (a) cache des patterns déjà vus, (b) mode « regex-only » pour les requêtes basse sensibilité, (c) préchargement du modèle spaCy en mémoire (pas de cold start).
### Sprint 4 — Semaines 7–8 : Multi-modèle + RBAC
**Objectif :** Le proxy supporte 4+ fournisseurs IA. Le RBAC contrôle qui accède à quoi.
| **\#** | **Tâche** | **Responsable** | **Priorité** | **Critère d’acceptance** |
|--------|---------------------------------------------------------------------------------------------------------------------|-----------------|--------------|--------------------------------------------------------------------------------------------------|
| 4.1 | Adapter OpenAI : normalisation du format de requête/réponse vers le schema interne unifié | Lead Backend | BLOQUANT | Requête interne → OpenAI → réponse interne. Streaming inclus |
| 4.2 | Adapter Anthropic : support Messages API, format claude-sonnet, streaming | Lead Backend | BLOQUANT | Même test que 4.1 avec Anthropic. Mapping system/user/assistant correct |
| 4.3 | Adapter Azure OpenAI : endpoint custom, API version, déploiement ID | Lead Backend | IMPORTANT | Fonctionne avec un déploiement Azure test |
| 4.4 | Adapter Ollama/vLLM : support modèles locaux via API OpenAI-compatible | Lead Backend | IMPORTANT | Fonctionne avec un Ollama local tournant Llama 3 |
| 4.5 | Adapter Mistral : support API Mistral chat/completions | Lead Backend | SOUHAITABLE | Test fonctionnel avec mistral-small |
| 4.6 | Interface Adapter commune : trait/interface Go avec méthodes Send(), Stream(), Validate(), HealthCheck() | Lead Backend | BLOQUANT | Tous les adapters implémentent la même interface. Tests génériques passent |
| 4.7 | Module RBAC : modèle de données (roles, permissions, role_assignments), middleware d’autorisation | Backend Sr | BLOQUANT | User sans permission sur un modèle = 403. Admin = accès total. Auditor = read-only |
| 4.8 | RBAC intégration Keycloak : synchronisation des rôles depuis les groupes Keycloak | DevOps | IMPORTANT | Un user ajouté au groupe « admin » dans Keycloak obtient le rôle admin dans l’app |
| 4.9 | API tenant management : CRUD tenants, configuration de base (nom, providers autorisés, API keys encryptées) | Backend Sr | IMPORTANT | POST /v1/admin/tenants crée un tenant. Les API keys sont stockées chiffrées (pas en clair en DB) |
| 4.10 | Tests d’intégration multi-modèle : test automatisé qui envoie la même requête à chaque adapter et valide la réponse | Lead Backend | IMPORTANT | Test CI green pour OpenAI + Anthropic (les autres en mock si pas de clé dispo) |
**État à la fin de Phase 1 :** Le proxy intercepte les requêtes, authentifie via JWT/Keycloak, anonymise les PII, route vers le bon modèle IA (OpenAI, Anthropic, Azure, local), et renvoie la réponse dé-pseudonymisée. C’est déjà démontrable à un prospect via curl.
## PHASE 2 — Intelligence et visibilité (Sprints 5–8, Semaines 9–16)
**Objectif de phase :** Routage intelligent, journalisation complète, dashboard fonctionnel, et début du module conformité. Le produit devient démontrable avec UI.
### Sprint 5 — Semaines 9–10 : Moteur de routage
**Objectif :** Les requêtes sont routées automatiquement selon des politiques configurables par tenant.
| **\#** | **Tâche** | **Responsable** | **Priorité** | **Critère d’acceptance** |
|--------|--------------------------------------------------------------------------------------------------------------------|-----------------|--------------|-------------------------------------------------------------------------------------|
| 5.1 | Modèle de données politiques : table routing_rules (conditions JSONB, action, priority, tenant_id) | Backend Sr | BLOQUANT | Migration appliquée. CRUD fonctionnel via API interne |
| 5.2 | Moteur de règles : évaluateur de conditions (user.department, request.sensitivity, etc.) par priorité décroissante | Lead Backend | BLOQUANT | 10 règles évaluées en \< 1ms. Règle la plus prioritaire gagne. Catch-all fonctionne |
| 5.3 | Intégration sensitivity scoring : le score PII détermine le sensitivity_level utilisé dans le routage | Lead Backend | BLOQUANT | Prompt avec PII critique → sensitivity=critical → route vers modèle local |
| 5.4 | Fallback chain : si le modèle primaire échoue, bascule vers secondaire puis global | Lead Backend | IMPORTANT | Test : mock un provider en erreur 500, vérifier le fallback. Log de fallback généré |
| 5.5 | Circuit breaker : désactivation automatique d’un provider après 5 erreurs consécutives. Réactivation après 60s | Lead Backend | IMPORTANT | Test : envoyer 6 requêtes à un provider mock KO → les 5 dernières sont redirigées |
| 5.6 | Cache des règles : les politiques sont cachées en mémoire (refresh toutes les 30s ou sur event) | Lead Backend | IMPORTANT | Modification d’une règle visible en \< 30s sans redémarrage |
| 5.7 | API admin politiques : CRUD /v1/admin/policies avec validation des conditions | Backend Sr | IMPORTANT | Création d’une politique via API. Validation des champs (pas de condition invalide) |
| 5.8 | Tests moteur de règles : 30+ tests couvrant combinaisons de conditions, priorités, conflits | Lead Backend | IMPORTANT | go test passe. 100% des cas de conditions documentés testés |
### Sprint 6 — Semaines 11–12 : Journalisation + Tokens
**Objectif :** Chaque requête est loggée dans ClickHouse avec tous les champs définis dans le PRD. Comptage des tokens fonctionnel.
| **\#** | **Tâche** | **Responsable** | **Priorité** | **Critère d’acceptance** |
|--------|-------------------------------------------------------------------------------------------------------------------------------|-----------------|--------------|-------------------------------------------------------------------------------|
| 6.1 | Schema ClickHouse : table audit_logs avec tous les 20 champs du PRD, partitionnement par mois, TTL 90j pour hot tier | Backend Sr | BLOQUANT | Table créée. INSERT fonctionne. SELECT avec GROUP BY sur 100k lignes \< 500ms |
| 6.2 | Module Logger Go : collecte asynchrone des métadonnées de chaque requête, batch insert ClickHouse (toutes les 1s ou 100 logs) | Backend Sr | BLOQUANT | Aucun log perdu sous charge (1000 req/s). Insert async ne bloque pas le proxy |
| 6.3 | Hash SHA-256 du prompt et de la réponse (pas le contenu brut dans les logs) | Backend Sr | BLOQUANT | Les logs ne contiennent aucun contenu en clair. Hash vérifiable |
| 6.4 | Chiffrement applicatif du champ prompt_anonymized (AES-256-GCM, clé dérivée par tenant via KMS) | Backend Sr | IMPORTANT | Le champ est illisible en DB sans la clé. Déchiffrement fonctionne via l’API |
| 6.5 | Module Billing : comptage tokens (tiktoken pour OpenAI, approximation pour les autres), agrégation par user/dept/model | Backend Sr | IMPORTANT | Comptage OpenAI = ±5% du comptage officiel. Agrégation par dept fonctionne |
| 6.6 | API de consultation des logs : GET /v1/admin/logs avec filtres (date, user, model, status) et pagination | Backend Sr | IMPORTANT | Requête filtrée retourne en \< 2s sur 1M de logs |
| 6.7 | API coûts : GET /v1/admin/costs avec agrégation par période/model/dept | Backend Sr | SOUHAITABLE | Dashboard data endpoint fonctionnel |
### Sprint 7 — Semaines 13–14 : Dashboard frontend v1
**Objectif :** Première version du dashboard avec authentification, vue d’ensemble, et gestion des politiques.
| **\#** | **Tâche** | **Responsable** | **Priorité** | **Critère d’acceptance** |
|--------|----------------------------------------------------------------------------------------------------------|-----------------|--------------|----------------------------------------------------------------------------------------------|
| 7.1 | Setup React + TypeScript + Vite + TailwindCSS + shadcn/ui. Structure de pages, routing (react-router) | Frontend | BLOQUANT | npm run dev lance l’app. Build \< 30s. Pas d’erreur TypeScript |
| 7.2 | Auth flow : login via Keycloak (OIDC PKCE), gestion des tokens, refresh, logout, redirect | Frontend | BLOQUANT | Login → redirect Keycloak → retour sur le dashboard avec session active. Refresh automatique |
| 7.3 | Page Overview : cartes KPI (requêtes 24h, PII détectées, coût total, modèle le plus utilisé) | Frontend | BLOQUANT | Données réelles depuis l’API. Mise à jour toutes les 30s |
| 7.4 | Graphique volume de requêtes (recharts) : line chart 7j/30j, breakdown par modèle ou département | Frontend | IMPORTANT | Chart interactif avec tooltip. Changement de période fonctionne |
| 7.5 | Page Politiques : liste des règles de routage, création/édition via formulaire, activation/désactivation | Frontend | IMPORTANT | CRUD complet sur les politiques depuis l’UI. Validation côté client |
| 7.6 | Page Utilisateurs : liste des users, attribution de rôles, filtrage par département | Frontend | IMPORTANT | Admin peut changer le rôle d’un user. Changement immédiatement effectif |
| 7.7 | Layout général : sidebar navigation, header avec tenant name, responsive design | Frontend | IMPORTANT | Navigation fluide. Pas de scroll horizontal sur 1280px |
| 7.8 | Guards de permission : les pages admin ne sont pas accessibles aux rôles User. Auditor = read-only | Frontend | IMPORTANT | User rôle « user » ne voit pas les pages admin. Auditor ne peut pas modifier |
### Sprint 8 — Semaines 15–16 : Dashboard sécurité + Playground
**Objectif :** Le dashboard inclut la vue sécurité RSSI et un playground démonstratif.
| **\#** | **Tâche** | **Responsable** | **Priorité** | **Critère d’acceptance** |
|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------|--------------|---------------------------------------------------------------------------------------------|
| 8.1 | Page Sécurité : volume PII par type (bar chart), requêtes bloquées, top users PII, timeline des incidents | Frontend | BLOQUANT | Données réelles. Filtrage par période. Export CSV |
| 8.2 | Page Coûts : breakdown par modèle (pie chart), par département, tendance mensuelle, alerte budget | Frontend | BLOQUANT | Projection du coût mensuel visible. Alerte si \> 80% du budget |
| 8.3 | Playground (killer feature démo) : zone de texte où on tape un prompt, visualisation en temps réel des PII détectées (highlight coloré), choix du modèle, envoi et réponse | Frontend + Lead | IMPORTANT | Taper un IBAN dans le prompt le highlight en rouge. Envoi au LLM montre le prompt anonymisé |
| 8.4 | Page Logs (Audit Trail) : tableau paginable des logs, filtres (date, user, model, status, sensitivity), détail expand | Frontend | IMPORTANT | Pagination fluide sur 100k+ logs. Filtres combinent correctement |
| 8.5 | Alertes basiques : notification in-app quand un seuil est dépassé (PII/h, coût/j, erreurs/h) | Frontend + Backend Sr | IMPORTANT | Configuration des seuils par l’admin. Notification visible dans le dashboard |
| 8.6 | Wizard configuration provider : formulaire guidé pour ajouter un nouveau provider IA (API key, endpoint, modèle par défaut) | Frontend | SOUHAITABLE | Ajout d’un provider en 3 étapes. Test de connexion intégré |
**État à la fin de Phase 2 :** Le produit est démontrable en intégralité via l’UI. Proxy + PII + Routage + Logs + Dashboard + RBAC fonctionnent ensemble. Le playground permet une démo impressionnante en 5 minutes. On peut commencer à démarcher des clients pilotes.
## PHASE 3 — Conformité et hardening (Sprints 9–10, Semaines 17–20)
**Objectif de phase :** Rapports conformité RGPD et AI Act, hardening sécurité, préparation au pentest.
### Sprint 9 — Semaines 17–18 : Module conformité
| **\#** | **Tâche** | **Responsable** | **Priorité** | **Critère d’acceptance** |
|--------|---------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|--------------|-----------------------------------------------------------------------------------|
| 9.1 | Modèle de données registre des traitements : table processing_registry (finalité, base légale, destinataires, durée, mesures sécurité, tenant_id) | Backend Sr | BLOQUANT | CRUD fonctionnel. Chaque cas d’usage IA est documentable |
| 9.2 | Classification risque AI Act : enum (forbidden, high_risk, limited_risk, minimal_risk) par cas d’usage, avec questionnaire guidé | Backend Sr | BLOQUANT | Un admin peut classifier chaque usage. La classification est stockée et exportée |
| 9.3 | Génération rapport PDF Article 30 RGPD (via go-pdf ou WeasyPrint) : registre complet avec tous les champs obligatoires | Backend Sr | BLOQUANT | GET /v1/admin/compliance/report?format=pdf retourne un PDF lisible, complet, daté |
| 9.4 | Génération rapport AI Act : fiche par système IA (modèle, classification, mesures, logs) | Backend Sr | IMPORTANT | PDF contient classification, mesures de mitigation, stats d’usage |
| 9.5 | API droits RGPD — accès (Art. 15) : export de toutes les données liées à un user_id | Backend Sr | IMPORTANT | GET /v1/admin/gdpr/access/{user_id} retourne JSON avec tous les logs associés |
| 9.6 | API droits RGPD — effacement (Art. 17) : suppression des logs et mappings PII d’un user | Backend Sr | IMPORTANT | DELETE /v1/admin/gdpr/erase/{user_id} supprime et loggue la suppression |
| 9.7 | Page Conformité frontend : registre des traitements, classification AI Act, génération rapports | Frontend | IMPORTANT | Formulaire de saisie intuitif. Bouton « Générer rapport » télécharge le PDF |
### Sprint 10 — Semaines 19–20 : Hardening sécurité
| **\#** | **Tâche** | **Responsable** | **Priorité** | **Critère d’acceptance** |
|--------|-----------------------------------------------------------------------------------------------------------------------------------------------|-----------------|--------------|--------------------------------------------------------------------------------------------------|
| 10.1 | mTLS entre tous les composants internes (proxy ↔ PII, proxy ↔ DB, proxy ↔ ClickHouse) via cert-manager + Istio/linkerd | DevOps | BLOQUANT | Wireshark sur le réseau interne ne montre que du trafic chiffré. Pas de communication en clair |
| 10.2 | Network policies Kubernetes : deny-all par défaut, whitelist explicite pour chaque communication | DevOps | BLOQUANT | Un pod ne peut pas contacter un service non autorisé. Test : curl depuis un pod aléatoire échoue |
| 10.3 | Intégration HashiCorp Vault : stockage des API keys LLM, credentials DB, clés de chiffrement. Accès via service account K8s | DevOps | BLOQUANT | Aucun secret en variable d’environnement ou en ConfigMap. Vault audit log actif |
| 10.4 | SAST intégré CI : Semgrep avec rulesets Go + Python + React. Bloque le merge si finding critique | DevOps | IMPORTANT | Pipeline bloque sur un code avec SQL injection. Zero critical finding sur le code actuel |
| 10.5 | Scan images Docker : Trivy en CI. Bloque si vulnérabilité critique non patchée | DevOps | IMPORTANT | Toutes les images de base sont pinned (sha256). Zero CVE critique |
| 10.6 | DAST : OWASP ZAP automatisé sur staging. Rapport généré à chaque déploiement | DevOps | IMPORTANT | Rapport ZAP sans finding critique (Medium accepté si justifié) |
| 10.7 | Audit logging : toutes les actions admin (modification politique, accès logs, modification RBAC) sont loggées dans une table admin_audit_logs | Backend Sr | IMPORTANT | Toute modification par un admin est traçable avec timestamp, user, before/after |
| 10.8 | Rate limiting par tenant et par user : configuration via Kong (ou middleware Go) | Lead Backend | IMPORTANT | Un user dépassant sa limite reçoit 429. Configurable par tenant |
| 10.9 | Tests de charge : k6 ou vegeta, cible 1000 req/s soutenues pendant 10 min, p99 \< 300ms | DevOps + Lead | IMPORTANT | Rapport de charge validé. Pas d’OOM, pas de goroutine leak, pas de connexion DB saturante |
**État à la fin de Phase 3 :** Le produit est sécurisé, conforme, et prêt pour un audit externe. Les rapports RGPD et AI Act sont générables en 1 clic. Toutes les communications internes sont chiffrées. Aucun secret en clair.
## PHASE 4 — Beta, polish et lancement (Sprints 11–13, Semaines 21–26)
**Objectif de phase :** Beta privée avec 2–3 clients pilotes, remédiation, pentest, lancement production.
### Sprint 11 — Semaines 21–22 : Beta privée
| **\#** | **Tâche** | **Responsable** | **Priorité** | **Critère d’acceptance** |
|--------|-----------------------------------------------------------------------------------------------------------------------------------------|-----------------|--------------|------------------------------------------------------------------------------|
| 11.1 | Tests E2E automatisés : 20+ scénarios couvrant le parcours complet (login → config provider → envoi prompt → vérif PII → log → rapport) | Tous | BLOQUANT | Suite E2E green en CI. Temps d’exécution \< 10min |
| 11.2 | Documentation API complète : OpenAPI 3.1 généré (swaggo), publiée sur /docs | Lead Backend | BLOQUANT | Swagger UI accessible. Tous les endpoints documentés avec exemples |
| 11.3 | Guide d’intégration : comment configurer son application pour utiliser le proxy (changement d’URL base, headers auth) | Lead Backend | BLOQUANT | Un dev externe peut intégrer en \< 30 min en suivant le guide |
| 11.4 | Onboarding client pilote \#1 : création tenant, configuration SSO (SAML/OIDC), import users, setup providers | PM + DevOps | BLOQUANT | Client opérationnel en \< 1 journée. Premières requêtes relayées avec succès |
| 11.5 | Onboarding client pilote \#2 | PM + DevOps | IMPORTANT | Idem \#1. Vérifie que le processus est reproductible |
| 11.6 | Guide utilisateur admin : PDF/web expliquant chaque fonctionnalité du dashboard | PM | IMPORTANT | Relu par un non-technique. Captures d’écran à jour |
| 11.7 | Feature flags : désactivation possible de chaque module (PII, routing, billing) par tenant | Lead Backend | IMPORTANT | Toggle via API admin. Effet immédiat sans redémarrage |
### Sprint 12 — Semaines 23–24 : Feedback + Pentest
| **\#** | **Tâche** | **Responsable** | **Priorité** | **Critère d’acceptance** |
|--------|-------------------------------------------------------------------------------------------|------------------|--------------|---------------------------------------------------------------------------|
| 12.1 | Collecte et tri du feedback clients pilotes : bugs, améliorations UX, features manquantes | PM | BLOQUANT | Backlog priorisé avec les retours classés (bug / UX / feature) |
| 12.2 | Bug fixes critiques identifiés par les pilotes | Tous | BLOQUANT | Zero bug bloquant restant. Bugs medium avec workaround documenté |
| 12.3 | Améliorations UX prioritaires (top 5 retours) | Frontend | IMPORTANT | Les 5 points UX les plus remontés sont corrigés |
| 12.4 | Pentest externe (cabinet spécialisé, grey box) : scope = API + dashboard + infra | Externe + DevOps | BLOQUANT | Pentest démarré, périmètre validé, accès fournis. Rapport attendu S24-S25 |
| 12.5 | Optimisation performance : analyse des bottlenecks identifiés en production beta | Lead Backend | IMPORTANT | p99 proxy amélioré si problème identifié. Pas de requête \> 5s |
| 12.6 | Blue/green deployment setup : déploiement sans downtime, rollback en 1 commande | DevOps | IMPORTANT | Déploiement de staging testé en blue/green. Rollback \< 30s |
### Sprint 13 — Semaines 25–26 : Lancement production
| **\#** | **Tâche** | **Responsable** | **Priorité** | **Critère d’acceptance** |
|--------|-----------------------------------------------------------------------------------------------------------------------------|-----------------|--------------|----------------------------------------------------------------------------|
| 13.1 | Remédiation findings pentest : corriger tous les findings Critical et High, documenter l’acceptation des Medium | Tous | BLOQUANT | Zero finding Critical/High ouvert. Rapport de remédiation produit |
| 13.2 | Déploiement cluster production : AWS eu-west-3, 3 AZ, autoscaling, backup quotidien PostgreSQL, replication ClickHouse | DevOps | BLOQUANT | Cluster production opérationnel. DR testé (restauration backup \< 1h) |
| 13.3 | Monitoring production : Grafana dashboards (proxy latency, error rate, PII volume, DB connections), alertes PagerDuty/Slack | DevOps | BLOQUANT | Alerte test reçue en \< 5min. Dashboard affiche les métriques production |
| 13.4 | Runbooks opérationnels : procédures pour incidents courants (provider down, DB full, cert expiré, traffic spike) | DevOps | IMPORTANT | 5+ runbooks rédigés. Chaque runbook testé en staging |
| 13.5 | Landing page + démo interactive (vidéo 3min ou playground public) | PM + Frontend | IMPORTANT | Page live. Formulaire de contact fonctionnel. Démo convaincante en \< 3min |
| 13.6 | Migration clients pilotes vers production | PM + DevOps | BLOQUANT | Clients opérationnels en production. Données migrées si applicable |
| 13.7 | Matériel commercial : one-pager PDF, deck 10 slides, battle card RSSI/DSI/DPO | PM | IMPORTANT | Validé par au moins 1 prospect. Pas de jargon technique excessif |
| 13.8 | Rétrospective projet + planification V1.1 | Tous | SOUHAITABLE | Retro documentée. Backlog V1.1 priorisé |
# Partie D — Chemin critique et dépendances
## D.1 — Chemin critique (tâches qui, si retardées, retardent tout)
| **Sprint** | **Tâches critiques** | **Raison** |
|------------|-----------------------------------------------------|---------------------------------------------------------------------------------------------------|
| S1 | 1.1 Monorepo + 1.3 Docker Compose + 1.4 K8s staging | Sans infra, personne ne peut travailler |
| S2 | 2.1–2.2 Proxy non-streaming + streaming SSE | Le proxy est le cœur. Tout en dépend. |
| S3 | 3.1–3.6 Pipeline PII complet + intégration gRPC | L’anonymisation est le différenciateur. Si la latence est trop haute, le produit est inutilisable |
| S5 | 5.2 Moteur de règles | Le routage est la valeur ajoutée pour le DSI |
| S6 | 6.1–6.2 Journalisation ClickHouse | Sans logs, pas de dashboard ni de conformité |
| S9 | 9.3 Génération rapport RGPD | Sans rapport, pas de vente au DPO |
| S10 | 10.1–10.3 mTLS + Network policies + Vault | Sans sécurité, pas de vente enterprise |
| S12 | 12.4 Pentest | Le pentest doit être commandé au plus tard S10 (délai 2-3 semaines pour un cabinet) |
| S13 | 13.1–13.2 Remédiation + Production | Le lancement ne peut pas être retardé au-delà de S13 sans impact commercial |
## D.2 — Actions à lancer en avance
Certaines actions doivent être initiées bien avant leur sprint cible :
| **Action** | **Démarrer à** | **Nécessaire pour** | **Responsable** |
|----------------------------------------------------------------------|----------------|--------------------------|-----------------|
| Identifier et contacter 5 prospects pilotes | Semaine 1 | S11 (onboarding beta) | PM |
| Négocier accès Azure AD test pour intégration SAML | Semaine 2 | S4 (RBAC Keycloak) | PM + DevOps |
| Rédiger cahier des charges pentest + contacter 3 cabinets | Semaine 12 | S12 (pentest) | PM + DevOps |
| Signer DPA avec les providers IA (OpenAI, Anthropic, etc.) | Semaine 4 | S9 (conformité) | PM + Légal |
| Obtenir un avis juridique sur la conformité RGPD de l’architecture | Semaine 8 | S9 (rapports conformité) | PM + Légal |
| Commander les certificats SSL production + domaine | Semaine 18 | S13 (production) | DevOps |
| Créer le compte AWS production + setup Organization + billing alerts | Semaine 16 | S13 (production) | DevOps |
# Partie E — Métriques de suivi et gates de qualité
## E.1 — Quality Gates par phase
Chaque phase a des critères de passage obligatoires. Si un gate n’est pas passé, on ne passe pas à la phase suivante.
| **Phase** | **Gate** | **Critère de passage** |
|---------------------|---------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| Phase 1 → Phase 2 | Proxy + PII + Auth fonctionnels | Démo en live : envoyer un prompt avec PII via le proxy, montrer l’anonymisation et la réponse dé-pseudonymisée. \< 300ms total. |
| Phase 2 → Phase 3 | Dashboard démontrable | Démo complète en live : login → dashboard → playground → politiques → logs. Toutes les données sont réelles (pas de mocks). |
| Phase 3 → Phase 4 | Sécurité validée | Zero finding critique SAST/DAST. mTLS actif. Vault intégré. Rapport RGPD générable. Test de charge passé. |
| Phase 4 → Lancement | Production ready | Pentest passé (zero critical). Monitoring opérationnel. Au moins 1 client pilote satisfait. Runbooks rédigés. |
## E.2 — KPIs techniques à suivre chaque sprint
| **KPI** | **Cible** | **Mesure** |
|----------------------------------|-----------|-------------------------------|
| Test coverage (Go) | \> 75% | go test -cover. Vérifié en CI |
| Test coverage (Python) | \> 85% | pytest --cov. Vérifié en CI |
| Latence proxy p99 (sans PII) | \< 50ms | Prometheus histogram |
| Latence proxy p99 (avec PII) | \< 150ms | Prometheus histogram |
| Uptime staging | \> 99% | Healthcheck monitoring |
| Build time CI | \< 8 min | GitLab CI metrics |
| Déploiement staging | \< 5 min | Helm upgrade timing |
| CVE critiques non patchées | 0 | Trivy + Snyk |
| Findings SAST critiques | 0 | Semgrep |
| Nombre de secrets en clair | 0 | gitleaks en CI |
| Taux de détection PII (F1-score) | \> 0.92 | Benchmark sur corpus de test |
# Partie F — Gestion des risques projet
| **\#** | **Risque** | **Probabilité** | **Impact** | **Détection** | **Plan de mitigation** | **Plan de contingence (si le risque se matérialise)** |
|--------|---------------------------------------------------------------------------------------|-----------------|------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|
| R1 | Latence PII \> 100ms rendant le produit inutilisable | Moyenne | Critique | Benchmark S3 | Cache des patterns, préchargement spaCy, mode regex-only pour les requêtes basse sensibilité | Basculer sur regex-only pour le MVP. Reporter NER en V1.1. Impact : précision réduite mais produit livrable |
| R2 | Streaming SSE incompatible avec le pipeline PII (on ne peut pas anonymiser un stream) | Haute | Haut | Sprint 3 | En streaming, les PII sont détectées sur le prompt AVANT envoi (pas sur la réponse streamée). La réponse streamée n’est pas anonymisée (le prompt l’a déjà été). | Si nécessaire : bufferiser la réponse complète avant anonymisation, au prix de la latence perçue. Feature flag par tenant. |
| R3 | Départ d’un développeur clé en cours de projet | Moyenne | Critique | Continu | Documentation systématique (ADR, README par module). Code reviews croisées pour que chacun connaisse 2+ modules | Recrutement d’un consultant senior en urgence (via Malt/Toptal). Accepter un retard de 2-4 semaines. |
| R4 | Client pilote indisponible ou non engagé | Haute | Haut | Semaine 8 | Identifier 5 prospects dès S1. Signer un LOI (Letter of Intent) dès S6 | Utiliser le produit en interne comme premier client. Démo sur données synthétiques pour les prospects. |
| R5 | ClickHouse trop complexe à opérer pour l’équipe | Moyenne | Moyen | Sprint 6 | Utiliser ClickHouse Cloud (managé) plutôt que self-hosted. Ou démarrer avec TimescaleDB et migrer en V1.1 | Fallback sur PostgreSQL + partitionnement temporel pour le MVP. Moins performant mais opérable. |
| R6 | L’AI Act évolue et invalide notre classification | Basse | Moyen | Continu | Veille réglementaire mensuelle. Classification configurable (pas hardcodée) | Mise à jour de la classification en 1-2 semaines (c’est de la config, pas du code). |
# Partie G — Budget estimatif sur 6 mois
| **Poste** | **Détail** | **Coût mensuel** | **Coût 6 mois** |
|-------------------------------|----------------------------------------------------------------------|------------------|-----------------|
| Équipe (salaires/TJM) | 4 ETP seniors (TJM moyen 650€) + 0.5 PM (TJM 550€) | ~60 000 € | ~360 000 € |
| Infra cloud (staging + prod) | EKS (3 nodes m5.xlarge), RDS PostgreSQL, ClickHouse Cloud, Redis, S3 | ~3 500 € | ~21 000 € |
| Services SaaS | GitLab Premium, Vault Cloud, monitoring, domaines | ~800 € | ~4 800 € |
| API IA (dév/test) | OpenAI, Anthropic, Mistral pour tests d’intégration | ~500 € | ~3 000 € |
| Pentest externe | Cabinet spécialisé, grey box, 5 jours | Ponctuel | ~12 000 € |
| Juridique (DPA, CGV, RGPD) | Avocat spécialisé tech/RGPD | Ponctuel | ~8 000 € |
| Divers (licences, formations) | Conférences, tools individuels | ~300 € | ~1 800 € |
| TOTAL | | | ~410 000 € |
**Note :** Ce budget suppose une équipe en freelance/CDI. Si l’équipe est déjà en place, le coût se réduit à ~50k€ (infra + pentest + juridique). Le point mort est atteignable avec 1 client Enterprise (40k€ MRR) dès le mois 7.
# Partie H — Checklist de lancement (Go/No-Go)
Cette checklist doit être validée à 100% avant le passage en production. Chaque item est un Go/No-Go.
| **Catégorie** | **Item** | **Critère** |
|---------------|------------------------------------------------------------------------------------------|---------------------------------------|
| Fonctionnel | Proxy relay fonctionne pour les 4 providers (OpenAI, Anthropic, Azure, Ollama) | Test E2E green |
| Fonctionnel | Anonymisation PII fonctionne sur les 6 types de PII (IBAN, email, tél, nom, adresse, SS) | Test E2E green + benchmark F1 \> 0.92 |
| Fonctionnel | Streaming SSE fonctionne avec anonymisation du prompt | Démo live |
| Fonctionnel | Routage intelligent fonctionne avec 5+ règles simultanées | Test E2E green |
| Fonctionnel | Dashboard affiche données réelles (pas de mock) | Vérification visuelle |
| Fonctionnel | Rapport RGPD Article 30 générable en PDF | PDF téléchargeable et lisible |
| Sécurité | Pentest : 0 finding Critical, 0 finding High ouvert | Rapport pentest validé |
| Sécurité | mTLS actif entre tous les composants | Wireshark test |
| Sécurité | Vault intégré, 0 secret en clair | Audit Vault + gitleaks |
| Sécurité | SAST/DAST : 0 finding critique | Rapport Semgrep + ZAP |
| Performance | Proxy p99 \< 300ms sous 500 req/s | Rapport k6 |
| Performance | Dashboard charge en \< 3s | Lighthouse score \> 70 |
| Ops | Monitoring production opérationnel (Grafana + alertes) | Alerte test reçue |
| Ops | Backup PostgreSQL automatisé + test de restauration | Restauration en \< 1h |
| Ops | Blue/green deployment fonctionnel | Déploiement testé |
| Ops | 5+ runbooks rédigés et testés | Revue par l’équipe |
| Commercial | Au moins 1 client pilote satisfait (NPS \> 7) | Feedback documenté |
| Commercial | Landing page + matériel commercial prêt | Page live, démo fonctionnelle |
| Légal | CGV/CGU rédigées et validées par un avocat | Document signé |
| Légal | DPA avec les providers IA signés | Documents archivés |
Si un item « No-Go » persiste à S25, une décision explicite doit être prise : corriger avant lancement (retard), accepter le risque (documenté), ou retirer la feature (scope cut).
# Synthèse
Ce plan transforme le PRD en 13 sprints exécutables contenant 113 tâches décomposées, chacune avec un responsable, une priorité, et un critère d’acceptance mesurable.
Les corrections clés apportées par rapport au PRD :
- Communication Go ↔ Python explicitée (gRPC sidecar)
- Tests intégrés dès le sprint 1 (pas repoussés au mois 5)
- Playground démo ajouté (killer feature pour la vente)
- Buffer de 20% intégré dans chaque estimation
- Chemin critique et dépendances explicités
- Actions à lancer en avance identifiées
- Quality gates entre chaque phase
- Checklist Go/No-Go avant lancement
- Budget réaliste chiffré (~410k€)
**Prochaine étape immédiate :** Recruter l’équipe (ou confirmer la disponibilité), commander le setup GitLab + AWS, et identifier les 5 premiers prospects pilotes. Le sprint 1 peut démarrer dès que 3 des 4 développeurs sont en place.

857
docs/Veylant_IA_Plan_Agile_Scrum.md Normal file
View File

@ -0,0 +1,857 @@
# Veylant IA — Plan Agile Scrum Détaillé
**Scrum Master Document — Version 1.0 — Février 2026**
**Confidentiel — Usage interne équipe**
---
## Sommaire
1. [Cadre Scrum](#1-cadre-scrum)
2. [Product Backlog — Epics et Stories](#2-product-backlog--epics-et-stories)
3. [Release Plan — Vision 6 mois](#3-release-plan--vision-6-mois)
4. [Sprints Détaillés](#4-sprints-détaillés)
5. [Chemin Critique et Dépendances](#5-chemin-critique-et-dépendances)
6. [Registre des Risques Scrum](#6-registre-des-risques-scrum)
7. [Métriques et KPIs Scrum](#7-métriques-et-kpis-scrum)
8. [Actions à Lancer Immédiatement](#8-actions-à-lancer-immédiatement)
---
## 1. Cadre Scrum
### 1.1 Équipe Scrum
| Rôle | Personne | Charge | Responsabilité |
|------|----------|--------|----------------|
| **Product Owner** | PM | 50% | Backlog, priorisation, stakeholders, clients pilotes |
| **Scrum Master** | CTO / Lead Backend | ~10% | Cérémonies, impediments, amélioration continue |
| **Dev Team — Backend Go** | CTO / Lead Backend | 90% | Proxy, Router, Adapters, API admin |
| **Dev Team — Backend Python** | Backend Senior | 100% | PII service, Logger, Billing, Compliance |
| **Dev Team — Frontend** | Frontend Senior | 100% | Dashboard React, Auth flow, UX |
| **Dev Team — DevOps/SRE** | DevOps | 100% | Infra, CI/CD, Sécurité, Monitoring |
> **Règle d'or :** Le PO est disponible pour des questions bloquantes sous 2h maximum. Tout impediment non résolu en 24h est escaladé en Daily Standup.
### 1.2 Cérémonies
| Cérémonie | Fréquence | Durée max | Participants | Livrable |
|-----------|-----------|-----------|-------------|----------|
| **Sprint Planning** | J1 du sprint | 3h | Toute l'équipe | Sprint Backlog validé + Sprint Goal |
| **Daily Standup** | Quotidien 9h30 | 15 min | Dev Team | Liste d'impediments |
| **Backlog Refinement** | J6 du sprint | 1h30 | PO + Dev Team | 2 sprints de backlog affinés et estimés |
| **Sprint Review** | J10 du sprint | 1h | Toute l'équipe + invités | Démo du livrable + feedback |
| **Sprint Retrospective** | J10 du sprint | 1h | Toute l'équipe | 1-3 actions d'amélioration concrètes |
| **Security Review** | Toutes les 4 sem. | 1h | Dev Team | Rapport sécurité sprint |
**Format Daily Standup** (timeboxé 15 min) :
1. Ce que j'ai accompli hier (30s/pers)
2. Ce que je fais aujourd'hui (30s/pers)
3. Mes blockers (durée variable — les résoudre APRÈS le standup)
**Format Sprint Review** :
1. Rappel du Sprint Goal (2 min)
2. Démo des stories complétées (30 min) — toujours sur l'environnement staging, jamais en mockup
3. Stories non complétées + raison (5 min)
4. Feedback PO / invités (15 min)
5. Mise à jour du backlog (8 min)
### 1.3 Definition of Done (DoD)
Une story est **Done** uniquement si **tous** ces critères sont remplis :
- [ ] Code reviewé et approuvé par au moins 1 autre développeur
- [ ] Tests unitaires écrits et verts (coverage > cible du module)
- [ ] Tests d'intégration mis à jour si applicable
- [ ] Pipeline CI/CD vert (build, lint, test, sécurité, scan)
- [ ] Critères d'acceptance validés par le PO ou son délégué
- [ ] Documentation technique inline à jour (commentaires, README module)
- [ ] Pas de secret ou credential hardcodé (gitleaks passe)
- [ ] Pas de CVE critique introduit (Trivy passe)
- [ ] Déployé et testé en staging
> Une story à 95% n'est pas Done. Partiel = non livré.
### 1.4 Definition of Ready (DoR)
Une story peut entrer en Sprint Planning uniquement si :
- [ ] User Story rédigée (format : En tant que... je veux... afin de...)
- [ ] Critères d'acceptance explicites et testables
- [ ] Story estimée en Story Points par toute l'équipe
- [ ] Dépendances identifiées (et résolues, ou planifiées dans le même sprint)
- [ ] Aucun blocker connu non adressé
- [ ] Maquettes/specs techniques disponibles si applicable
- [ ] Taille ≤ 8 SP (sinon à décomposer)
### 1.5 Vélocité et Capacité
**Capacité brute par sprint :**
- 4 développeurs × 10 jours ouvrés × 6h de dev effectif = 240 h/sprint
- Cérémonies : ~5h/pers (planning 3h + daily 2.5h + review 1h + retro 1h = 7.5h → 2 × 3.75h = 7.5h /2 sem) → retrait de ~7h/pers
- **Capacité nette : ~212 h/sprint**
**Échelle Story Points :**
| SP | Durée estimée | Exemple |
|----|--------------|---------|
| 1 | < 2h | Modification de config, ajout d'un endpoint trivial |
| 2 | ~demi-journée | Middleware simple, modèle de données basique |
| 3 | ~1 jour | Module simple avec tests |
| 5 | ~2-3 jours | Feature complète avec intégration |
| 8 | ~4-5 jours | Module complexe ou spike technique |
| 13 | > 1 semaine | **À décomposer obligatoirement** |
**Vélocité cible :**
| Sprint | Vélocité Cible | Justification |
|--------|---------------|---------------|
| S1-S2 | 38-40 SP | Ramp-up équipe, setup infra imprévisible |
| S3-S6 | 44-48 SP | Équipe en rythme, domaine complexe |
| S7-S10 | 48-52 SP | Vélocité de croisière |
| S11-S13 | 38-42 SP | Tests E2E, feedback, remédiation |
**Total projet estimé : ~580 SP**
---
## 2. Product Backlog — Epics et Stories
### Organisation des Epics
```
E1 — Infrastructure & DevOps [~70 SP]
E2 — AI Proxy Core [~65 SP]
E3 — Authentification & RBAC [~55 SP]
E4 — Anonymisation PII [~75 SP]
E5 — Multi-provider IA [~40 SP]
E6 — Moteur de Routage [~50 SP]
E7 — Journalisation & Audit [~55 SP]
E8 — Dashboard & Frontend [~85 SP]
E9 — Conformité RGPD & AI Act [~50 SP]
E10 — Sécurité & Hardening [~55 SP]
E11 — Beta, Tests & Lancement [~80 SP]
─────────
TOTAL ESTIMÉ ~680 SP
```
> Note : 680 SP estimés pour ~580 SP de capacité → 15% de buffer naturel. Le delta sera géré par priorisation stricte du backlog.
### Stories clés par Epic (format ID — Titre — SP)
#### Epic 1 — Infrastructure & DevOps
```
E1-01 — Monorepo GitLab + structure dossiers — 2 SP
E1-02 — Pipeline CI/CD (build Go + Python + React + lint + tests) — 8 SP
E1-03 — Docker Compose local complet (Go + PG + CH + Redis + Keycloak) — 5 SP
E1-04 — Cluster K8s staging AWS EKS eu-west-3 — 8 SP
E1-05 — Helm chart déploiement de l'application — 5 SP
E1-06 — Déploiement automatique staging sur merge to main — 3 SP
E1-07 — Prometheus + Grafana staging — 5 SP
E1-08 — OpenTelemetry + Jaeger — 5 SP
E1-09 — Blue/green deployment production — 8 SP
E1-10 — Cluster K8s production (3 AZ, autoscaling, backup) — 8 SP
E1-11 — Alerting production (PagerDuty/Slack) — 5 SP
E1-12 — Runbooks opérationnels (5+) — 5 SP
E1-13 — Terraform/Pulumi infra-as-code — 3 SP (en parallèle S1)
```
#### Epic 2 — AI Proxy Core
```
E2-01 — Scaffolding Go (chi router, middleware chain, graceful shutdown, /healthz) — 3 SP
E2-02 — Gestion de config (Viper, config.yaml, override env vars) — 2 SP
E2-03 — Proxy relay non-streaming (POST /v1/chat/completions → OpenAI) — 5 SP
E2-04 — Proxy relay streaming SSE (flush chunk par chunk, Flusher HTTP) — 8 SP [SPIKE]
E2-05 — Middleware Request ID (UUID v7, propagation headers/logs) — 2 SP
E2-06 — Middleware error handling (erreurs typées JSON format OpenAI) — 3 SP
E2-07 — Middleware rate limiting (par tenant, par user) — 5 SP
E2-08 — Connection pool HTTP (persistant, timeout configurable) — 3 SP
E2-09 — Circuit breaker (N erreurs → désactivation, réactivation auto) — 5 SP
E2-10 — Health check providers IA (ping cyclique, état dans métriques) — 3 SP
E2-11 — Tests unitaires proxy complets (coverage > 80%, go test -race) — 5 SP
E2-12 — Tests de charge proxy (k6, 1000 req/s, p99 < 300ms) — 8 SP
```
#### Epic 3 — Authentification & RBAC
```
E3-01 — Modèle de données : users, tenants, roles, permissions — 3 SP
E3-02 — Setup Keycloak (realm, client OIDC, utilisateurs test) — 5 SP
E3-03 — Middleware Auth JWT (RS256, expiration, issuer, extraction claims) — 5 SP
E3-04 — RBAC middleware (rôles : Admin, Manager, User, Auditor) — 5 SP
E3-05 — Intégration SAML 2.0 Keycloak (federation Azure AD / Okta) — 8 SP
E3-06 — Synchronisation rôles Keycloak → app — 3 SP
E3-07 — API tenant management (CRUD tenants, providers autorisés, API keys chiffrées) — 5 SP
E3-08 — API user management (CRUD users, attribution rôles, dept) — 5 SP
E3-09 — Feature flags système (table PG + cache Redis) — 3 SP
E3-10 — Tests intégration Auth E2E (Keycloak via testcontainers) — 5 SP
```
#### Epic 4 — Anonymisation PII
```
E4-01 — Schemas gRPC PII (PiiRequest, PiiResponse, PiiEntity, proto v1) — 3 SP
E4-02 — Scaffolding service Python (FastAPI, gRPC server, Dockerfile, pytest) — 3 SP
E4-03 — Couche 1 Regex : IBAN FR/EU, email, tél FR/intl, SS, CB (Luhn) — 5 SP
E4-04 — Tests regex (100+ cas positifs/négatifs, precision > 99%) — 3 SP
E4-05 — Couche 2 NER : Presidio + spaCy fr_core_news_lg (PER, LOC, ORG) — 8 SP
E4-06 — Benchmark NER (F1-score > 0.90, corpus français) — 3 SP
E4-07 — Pipeline unifié (regex → NER, déduplication, scoring confiance) — 5 SP
E4-08 — Pseudonymisation (tokens [PII:TYPE:UUID], mapping Redis AES-256-GCM, TTL) — 5 SP
E4-09 — Dé-pseudonymisation (réinjection valeurs dans réponse LLM) — 5 SP
E4-10 — Intégration gRPC Proxy Go ↔ PII Python — 5 SP
E4-11 — Benchmark latence (p99 < 50ms / 500 tokens, < 100ms / 2000 tokens) — 3 SP
E4-12 — Mode zero-retention (mapping mémoire uniquement, pas Redis) — 3 SP
E4-13 — Tests unitaires PII (50+ cas, multilangue, edge cases) — 5 SP
E4-14 — Option regex-only (feature flag, pour requêtes basse sensibilité) — 3 SP
```
#### Epic 5 — Multi-provider IA
```
E5-01 — Interface Adapter Go (Send(), Stream(), Validate(), HealthCheck()) — 3 SP
E5-02 — Adapter OpenAI (format unifié, streaming SSE) — 5 SP
E5-03 — Adapter Anthropic (Messages API, system/user/assistant, streaming) — 5 SP
E5-04 — Adapter Azure OpenAI (endpoint custom, API version, deployment ID) — 5 SP
E5-05 — Adapter Mistral (chat/completions, modèles small/medium/large) — 3 SP
E5-06 — Adapter Ollama / vLLM (OpenAI-compatible, modèles locaux) — 5 SP
E5-07 — Wizard UI configuration provider (3 étapes, test de connexion) — 5 SP
E5-08 — Tests intégration multi-adapter (mock si pas de clé dispo) — 5 SP
```
#### Epic 6 — Moteur de Routage
```
E6-01 — Modèle de données règles (routing_rules : conditions JSONB, action, priority) — 3 SP
E6-02 — Évaluateur de conditions (department, role, sensitivity, use_case, tokens) — 8 SP
E6-03 — Sensitivity scoring (score PII → sensitivity_level pour le routage) — 3 SP
E6-04 — Fallback chain configurable (primaire → secondaire → global) — 5 SP
E6-05 — Cache des règles (mémoire, refresh 30s ou sur event) — 3 SP
E6-06 — API admin politiques (CRUD /v1/admin/policies, validation) — 5 SP
E6-07 — Tests moteur de règles (30+ cas, priorités, conflits, catch-all) — 5 SP
E6-08 — Exemples de règles préconfigurées (RH, Finance, Engineering) — 3 SP
```
#### Epic 7 — Journalisation & Audit
```
E7-01 — Schéma ClickHouse (audit_logs, 20 champs, partitionnement mensuel, TTL) — 5 SP
E7-02 — Module Logger Go (collecte async, batch insert 1s/100 logs) — 8 SP
E7-03 — Hash SHA-256 prompt/réponse (pas de contenu brut dans les logs) — 2 SP
E7-04 — Chiffrement applicatif champ prompt_anonymized (AES-256-GCM) — 5 SP
E7-05 — Module Billing (comptage tokens tiktoken, agrégation user/dept/model) — 5 SP
E7-06 — API consultation logs (GET /v1/admin/logs, filtres, pagination, < 2s) — 5 SP
E7-07 — API coûts (GET /v1/admin/costs, agrégation période/model/dept) — 3 SP
E7-08 — API alertes budget (seuils configurables par tenant, notification) — 5 SP
E7-09 — Audit de l'audit (log des accès admin_audit_logs) — 3 SP
E7-10 — Export CSV logs filtrés — 3 SP
E7-11 — Tests Logger (1000 req/s sans perte, insert async non bloquant) — 5 SP
```
#### Epic 8 — Dashboard & Frontend
```
E8-01 — Setup React + TypeScript + Vite + TailwindCSS + shadcn/ui — 3 SP
E8-02 — Auth flow frontend (OIDC PKCE, refresh token, logout, redirect) — 5 SP
E8-03 — Layout général (sidebar, header tenant, responsive 1280px) — 3 SP
E8-04 — Route guards (admin/auditor/user permissions, pages protégées) — 3 SP
E8-05 — Page Overview (KPI cards : requêtes, PII, coût, modèle top) — 5 SP
E8-06 — Graphique volume requêtes (recharts line, 7j/30j, breakdown) — 5 SP
E8-07 — Page Politiques (liste règles, CRUD, activation/désactivation) — 8 SP
E8-08 — Page Utilisateurs (liste, attribution rôles, filtrage dept) — 5 SP
E8-09 — Page Sécurité RSSI (PII par type, requêtes bloquées, top users PII) — 8 SP
E8-10 — Page Coûts (breakdown modèle/dept, projection mensuelle, alerte) — 5 SP
E8-11 — Playground PII (highlight temps réel, choix modèle, envoi, réponse) — 8 SP [killer feature]
E8-12 — Page Logs Audit Trail (tableau paginé, filtres combinés, expand) — 8 SP
E8-13 — Alertes in-app (seuils configurables, notification dashboard) — 5 SP
E8-14 — Page Conformité (registre, classification AI Act, génération rapports) — 8 SP
E8-15 — Landing page + démo interactive — 5 SP
```
#### Epic 9 — Conformité RGPD & AI Act
```
E9-01 — Modèle données registre traitements (processing_registry) — 3 SP
E9-02 — Classification risque AI Act (enum + questionnaire guidé) — 5 SP
E9-03 — Génération rapport PDF Article 30 RGPD (go-pdf / WeasyPrint) — 8 SP
E9-04 — Génération rapport AI Act (fiche par système IA) — 5 SP
E9-05 — API droit d'accès Art. 15 (export données user_id) — 3 SP
E9-06 — API droit d'effacement Art. 17 (purge logs + mappings PII) — 5 SP
E9-07 — Template DPIA pré-rempli — 5 SP
E9-08 — Génération rapport incident (template avec chronologie) — 3 SP
E9-09 — Documentation DPA fournisseurs IA (OpenAI, Anthropic, etc.) — 3 SP
```
#### Epic 10 — Sécurité & Hardening
```
E10-01 — mTLS entre composants internes (cert-manager, Istio/Linkerd) — 8 SP
E10-02 — Network policies K8s (deny-all, whitelist explicite) — 5 SP
E10-03 — Intégration HashiCorp Vault (API keys, credentials, clés chiffrement) — 8 SP
E10-04 — SAST Semgrep en CI (Go + Python + React, bloque si critical) — 3 SP
E10-05 — Scan images Trivy en CI (bloque si CVE critique) — 2 SP
E10-06 — DAST OWASP ZAP automatisé sur staging — 5 SP
E10-07 — gitleaks en CI (détection secrets) — 2 SP
E10-08 — Rotation automatique API keys (90 jours, alertes) — 5 SP
E10-09 — Rate limiting par tenant/user (Kong ou middleware Go) — 5 SP
E10-10 — Tests de charge k6 (1000 req/s, 10 min, p99 < 300ms) — 8 SP
```
#### Epic 11 — Beta, Tests & Lancement
```
E11-01 — Tests E2E automatisés (20+ scénarios complets, < 10 min CI) — 13 SP [décomposer]
E11-02 — Documentation API OpenAPI 3.1 (swaggo, /docs, exemples) — 5 SP
E11-03 — Guide d'intégration dev (intégration en < 30 min) — 3 SP
E11-04 — Onboarding client pilote #1 (tenant, SSO, users, providers) — 5 SP
E11-05 — Onboarding client pilote #2 — 5 SP
E11-06 — Guide utilisateur admin (PDF/web, captures) — 5 SP
E11-07 — Feature flags par module (PII, routing, billing) — 3 SP
E11-08 — Collecte et tri feedback pilotes — 3 SP
E11-09 — Bug fixes critiques post-pilote — 8 SP [buffer]
E11-10 — Améliorations UX top-5 — 5 SP
E11-11 — Pentest externe grey box (périmètre + accès + suivi) — 5 SP [coordination]
E11-12 — Remédiation pentest Critical + High — 8 SP [buffer]
E11-13 — Migration clients pilotes vers production — 5 SP
E11-14 — Matériel commercial (one-pager, deck 10 slides, battle card) — 5 SP
```
---
## 3. Release Plan — Vision 6 mois
### Jalons clés
```
S1 (01/03) ──► Bootstrapping : dev env + squelette
S4 (29/03) ──► MILESTONE 1 : Proxy + PII + Auth ← Démo interne/prospects
S8 (28/04) ──► MILESTONE 2 : Dashboard + Playground ← Démo externe complète
S10 (10/05) ──► MILESTONE 3 : Conformité + Sécurité ← Prêt pour audit
S11 (24/05) ──► MILESTONE 4 : Beta privée — 2 clients pilotes connectés
S12 (07/06) ──► MILESTONE 5 : Pentest démarré + feedback intégré
S13 (21/06) ──► MILESTONE 6 : Lancement Production ← Go/No-Go
```
### Burn-up cumulatif cible
| Sprint | SP livrés cumul | % du backlog MVP |
|--------|-----------------|-----------------|
| S1 | 38 | 7% |
| S2 | 78 | 14% |
| S3 | 124 | 22% |
| S4 | 170 | 30% |
| S5 | 218 | 38% |
| S6 | 265 | 47% |
| S7 | 315 | 56% |
| S8 | 365 | 65% |
| S9 | 410 | 73% |
| S10 | 458 | 82% |
| S11 | 498 | 89% |
| S12 | 533 | 95% |
| S13 | 563 | 100% |
---
## 4. Sprints Détaillés
---
### PHASE 1 — Fondations (S1–S4)
> **Objectif de Phase :** Un proxy fonctionnel, authentifié, qui anonymise les PII et supporte 4 fournisseurs IA. Démontrable via curl. Quality Gate : démo live < 300ms total.
---
### Sprint 1 — Bootstrapping (Semaines 1–2)
**Sprint Goal :** *"L'ensemble de l'équipe peut développer, tester et déployer de façon autonome. Le squelette applicatif compile et se déploie en staging en moins de 5 minutes."*
**Capacité :** 38 SP (ramp-up, setup réseau/AWS imprévisible)
| ID | Story | Assigné | SP | Priorité |
|----|-------|---------|-----|---------|
| E1-01 | Monorepo GitLab + structure `/cmd`, `/internal`, `/services/pii`, `/web`, `/deploy`, `/proto`, `/docs` | DevOps | 2 | BLOQUANT |
| E1-02 | Pipeline CI/CD : build Go + Python + React, lint (golangci-lint, black, eslint), tests unitaires, scan Trivy, gitleaks | DevOps | 8 | BLOQUANT |
| E1-03 | Docker Compose local : Go app + PostgreSQL 16 + ClickHouse + Redis 7 + Keycloak. `docker-compose up` < 60s | DevOps | 5 | BLOQUANT |
| E1-04 | Cluster K8s staging AWS EKS eu-west-3, 3 nodes, ingress Traefik, HTTPS | DevOps | 8 | BLOQUANT |
| E2-01 | Scaffolding Go : main.go, chi router, middleware chain vide, graceful shutdown (SIGTERM), `/healthz` retourne 200 | Lead Backend | 3 | BLOQUANT |
| E2-02 | Gestion config Viper : config.yaml + override env vars. Pas de valeur hardcodée | Lead Backend | 2 | IMPORTANT |
| E3-01 | Modèle de données PG v1 : tables `tenants`, `users`, `api_keys` + migrations golang-migrate | Backend Sr | 3 | IMPORTANT |
| E3-02 | Setup Keycloak : realm, client OIDC, utilisateur test, retourne JWT valide | DevOps | 5 | IMPORTANT |
| E4-01 | Schemas gRPC : `PiiRequest`, `PiiResponse`, `PiiEntity` → stubs Go + Python générés | Lead + Backend Sr | 2 | IMPORTANT |
| **Spike** | Investigation Terraform vs Pulumi pour infra-as-code (timebox 4h, sortie : ADR) | DevOps | — | IMPORTANT |
**Total : 38 SP**
**Critères d'acceptance sprint :**
- `docker-compose up` démarre tout en < 60s, healthchecks OK
- `kubectl get nodes` → 3 nodes Ready sur EKS eu-west-3
- Pipeline CI vert sur commit vide, build < 8 min
- `GET /healthz` → 200. Graceful shutdown fonctionne en staging
**Démo Sprint Review :**
> Montrer : `docker-compose up` → tous les services green → `curl /healthz` → 200. Déclencher un commit → montrer le pipeline CI vert en < 8 min → voir le déploiement automatique en staging.
**Risques S1 :**
- Setup EKS + VPC + IAM peut prendre 3+ jours → Mitigation : utiliser le module Terraform `terraform-aws-eks` version stable. Si bloqué > 2 jours → passer en EKS via eksctl pour débloquer, IaC en parallèle.
- Incompatibilités version ClickHouse/Keycloak en Docker Compose → Mitigation : épingler les versions (SHA256 des images).
---
### Sprint 2 — Proxy Core + Auth JWT (Semaines 3–4)
**Sprint Goal :** *"Un développeur peut envoyer un prompt via le proxy Veylant IA et recevoir la réponse d'OpenAI, avec streaming temps réel et authentification JWT. Démontrable avec curl."*
**Capacité :** 40 SP
| ID | Story | Assigné | SP | Priorité |
|----|-------|---------|-----|---------|
| E2-03 | **Proxy relay non-streaming** : `POST /v1/chat/completions` → OpenAI → réponse. Même résultat qu'un appel direct. | Lead Backend | 5 | BLOQUANT |
| E2-04 | **Proxy relay streaming SSE** : `stream:true`, flush chunk par chunk, pas de buffering. `curl --no-buffer` reçoit les chunks en temps réel. | Lead Backend | 8 | BLOQUANT |
| E3-03 | **Middleware Auth JWT** : RS256, expiration, issuer Keycloak. Sans JWT → 401. JWT expiré → 401. JWT valide → forward + contexte injecté (user_id, tenant_id, roles). | Backend Sr | 5 | BLOQUANT |
| E2-05 | **Middleware Request ID** : UUID v7 par requête, propagation headers (`X-Request-Id`) et logs | Lead Backend | 2 | IMPORTANT |
| E2-06 | **Middleware error handling** : erreurs typées JSON format OpenAI (`type`, `message`, `code`) | Lead Backend | 3 | IMPORTANT |
| E2-08 | **Connection pool HTTP** : connexions persistantes vers providers, timeout configurable | Lead Backend | 3 | IMPORTANT |
| E2-11 | **Tests unitaires proxy** : 15+ tests, cas nominaux/erreurs OpenAI/timeouts/headers. Coverage > 80%. `go test -race` passe. | Lead Backend | 5 | IMPORTANT |
| E3-10 | **Tests intégration Auth** : E2E avec Keycloak via testcontainers (obtenir token → appeler proxy → succès) | Backend Sr | 3 | IMPORTANT |
| E1-06 | **Déploiement auto staging** : merge to main → Helm upgrade auto. Rollback en 1 commande. | DevOps | 3 | IMPORTANT |
| E1-07 | **Métriques Prometheus basiques** : `request_count`, `request_duration_seconds`, `request_errors_total` visibles dans Grafana | DevOps | 3 | SOUHAITABLE |
**Total : 40 SP**
**Critères d'acceptance sprint :**
- `curl -H "Authorization: Bearer <JWT>" -X POST /v1/chat/completions -d '{"model":"gpt-4o","messages":[...]}'` → réponse identique à OpenAI direct
- `curl --no-buffer ... stream:true` → chunks reçus en temps réel (latence perçue identique à OpenAI direct)
- Requête sans JWT → 401 en < 10ms
**Démo Sprint Review :**
> Montrer en live : (1) Appel direct à OpenAI avec streaming. (2) Même appel via le proxy → même résultat, même latence perçue. (3) Appel sans JWT → 401. (4) Métriques Grafana montrant le request count.
**Risques S2 :**
- **Le streaming SSE est le point technique le plus délicat du projet.** En Go, le `http.Flusher` doit être appelé après chaque chunk. Si OpenAI change son format SSE → l'adapter est localisé dans `E5-02`. Prévoir 3-4 jours de debug. Si bloqué → implémenter le mode non-streaming parfait d'abord, streaming en S3 avec 1 SP de retard accepté.
---
### Sprint 3 — Pipeline PII v1 (Semaines 5–6)
**Sprint Goal :** *"Le proxy anonymise automatiquement les données personnelles avant tout envoi à un LLM externe. Le token IBAN d'un prompt n'atteint jamais OpenAI. Démontrable via les logs."*
**Capacité :** 44 SP (équipe en rythme)
| ID | Story | Assigné | SP | Priorité |
|----|-------|---------|-----|---------|
| E4-02 | Scaffolding service PII Python : FastAPI, gRPC server, Dockerfile, pytest setup. Healthcheck gRPC répond. | Backend Sr | 3 | BLOQUANT |
| E4-03 | **Couche 1 Regex** : IBAN FR/EU, email, tél FR/intl, n° SS, CB (validation Luhn). Jeu de 100+ tests. Precision > 99%, Recall > 95%. | Backend Sr | 5 | BLOQUANT |
| E4-05 | **Couche 2 NER** : Presidio + spaCy `fr_core_news_lg`. Détection PER, LOC, ORG. F1-score > 0.90 sur corpus français. | Backend Sr | 8 | BLOQUANT |
| E4-07 | **Pipeline unifié** : orchestration regex → NER, déduplication, scoring confiance. 5 types de PII détectés dans un prompt. Latence < 50ms / 500 tokens. | Backend Sr | 5 | BLOQUANT |
| E4-08 | **Pseudonymisation** : remplacement par `[PII:TYPE:UUID]`, mapping Redis AES-256-GCM, TTL configurable. Prompt envoyé au LLM sans PII en clair. | Backend Sr | 5 | BLOQUANT |
| E4-09 | **Dé-pseudonymisation** : réinjection valeurs originales dans réponse LLM avant renvoi à l'user | Backend Sr | 5 | BLOQUANT |
| E4-10 | **Intégration gRPC Proxy ↔ PII** : proxy Go appelle service Python via gRPC avant chaque forward. Flux complet fonctionne bout en bout. | Lead Backend | 5 | BLOQUANT |
| E4-11 | **Benchmark latence** : mesure p50/p95/p99 sur 1000 requêtes variées. p99 < 50ms / 500 tokens, < 100ms / 2000 tokens. | Backend Sr | 3 | IMPORTANT |
| E4-13 | **Tests unitaires PII** : 50+ cas, multilangue, edge cases (texte mixte FR/EN, données dans URL, dans JSON). Coverage > 85%. | Backend Sr | 5 | IMPORTANT |
**Total : 44 SP**
**⚠️ Sprint le plus risqué techniquement du projet.**
**Critères d'acceptance sprint :**
- Envoyer un prompt contenant [IBAN, email, nom, téléphone, adresse] → les 5 types sont pseudonymisés
- Le prompt reçu par OpenAI (visible dans les logs) ne contient aucune donnée en clair
- La réponse renvoyée à l'utilisateur contient les vraies valeurs (dé-pseudonymisées)
- p99 < 50ms mesuré avec le script benchmark sur 1000 requêtes
**Démo Sprint Review :**
> Ouvrir le playground (mode minimal). Taper : "Bonjour, je suis Jean Dupont, mon IBAN est FR76 3000 6000 0112 3456 7890 189, contactez-moi au 06 12 34 56 78." → Montrer dans les logs : (1) prompt original côté proxy, (2) prompt pseudonymisé envoyé à OpenAI, (3) réponse dé-pseudonymisée côté utilisateur.
**Risques S3 :**
- **Latence NER > 100ms** → Actions immédiates : (a) vérifier que `fr_core_news_lg` est préchargé en mémoire au démarrage (pas de cold start), (b) activer le mode regex-only via feature flag pour les requêtes basse sensibilité (E4-14 en S4).
- **Faux positifs élevés** → Ajuster le seuil de confiance Presidio (0.85 par défaut, testable dès 0.75). Whitelist configurable par tenant.
**Decision Point post-S3 :** Si le p99 NER > 80ms, décision explicite du PO : (a) reporter NER en V1.1 → MVP en regex-only, (b) allouer 1 sprint de spike optimisation, (c) accepter la latence avec UX appropriée. **Cette décision ne peut pas être repoussée au-delà de S4.**
---
### Sprint 4 — Multi-provider + RBAC (Semaines 7–8)
**Sprint Goal :** *"Veylant IA route les requêtes vers 4 fournisseurs IA selon le rôle et le département de l'utilisateur. Un admin voit tout, un User ne peut accéder qu'à son modèle autorisé."*
**Capacité :** 46 SP
| ID | Story | Assigné | SP | Priorité |
|----|-------|---------|-----|---------|
| E5-01 | **Interface Adapter Go** : trait/interface avec `Send()`, `Stream()`, `Validate()`, `HealthCheck()`. Tests génériques passent pour tous les adapters. | Lead Backend | 3 | BLOQUANT |
| E5-02 | **Adapter OpenAI** : normalisation format requête/réponse, streaming SSE (déjà testé en S2, ici normalisation du schema interne) | Lead Backend | 3 | BLOQUANT |
| E5-03 | **Adapter Anthropic** : Messages API, system/user/assistant, streaming. Même test qu'OpenAI. | Lead Backend | 5 | BLOQUANT |
| E5-04 | **Adapter Azure OpenAI** : endpoint custom, API version, deployment ID | Lead Backend | 5 | IMPORTANT |
| E5-06 | **Adapter Ollama/vLLM** : API OpenAI-compatible, test avec Llama 3 local | Lead Backend | 5 | IMPORTANT |
| E5-05 | **Adapter Mistral** : chat/completions, mistral-small | Lead Backend | 3 | SOUHAITABLE |
| E3-04 | **RBAC middleware** : rôles Admin/Manager/User/Auditor. User sans permission → 403. Admin → accès total. Auditor → read-only. | Backend Sr | 5 | BLOQUANT |
| E3-05 | **Intégration SAML 2.0 Keycloak** : federation Azure AD test. User ajouté dans groupe Keycloak → rôle dans l'app. | DevOps | 8 | IMPORTANT |
| E3-07 | **API tenant management** : CRUD tenants. API keys stockées chiffrées (pas en clair en DB). | Backend Sr | 5 | IMPORTANT |
| E5-08 | **Tests intégration multi-adapter** : test automatisé même requête → chaque adapter, validation réponse. CI green pour OpenAI + Anthropic. | Lead Backend | 5 | IMPORTANT |
**Total : 47 SP** → accepté (vélocité légèrement au-dessus de la cible grâce au rythme S3)
**✅ QUALITY GATE PHASE 1 — à valider en fin de S4 :**
> Démo live sans mockup : (1) envoyer un prompt avec 3 PII via curl, (2) montrer l'anonymisation, (3) le routage vers OpenAI vs Anthropic selon le rôle de l'utilisateur, (4) la réponse dé-pseudonymisée. Latence totale < 300ms. Proxy + PII + Auth + RBAC + Multi-provider fonctionnent ensemble.
---
### PHASE 2 — Intelligence et Visibilité (S5–S8)
> **Objectif de Phase :** Le produit est démontrable avec une UI complète. Routage intelligent, logs, dashboard, playground. Quality Gate : démo complète sans mockup, données réelles.
---
### Sprint 5 — Moteur de Routage (Semaines 9–10)
**Sprint Goal :** *"Les requêtes sont routées automatiquement selon des politiques configurées par l'admin. Un prompt contenant des données critiques va systématiquement vers le modèle on-prem sans intervention humaine."*
**Capacité :** 46 SP
| ID | Story | Assigné | SP | Priorité |
|----|-------|---------|-----|---------|
| E6-01 | **Modèle de données politiques** : table `routing_rules` (conditions JSONB, action, priority, tenant_id, enabled). Migration. CRUD interne. | Backend Sr | 3 | BLOQUANT |
| E6-02 | **Moteur de règles** : évaluation par priorité décroissante, conditions (user.department, user.role, request.sensitivity, request.use_case, request.token_estimate), catch-all. 10 règles évaluées < 1ms. | Lead Backend | 8 | BLOQUANT |
| E6-03 | **Sensitivity scoring → routage** : le score PII (niveau none/low/medium/high/critical) alimente le moteur de règles. Prompt critique → route vers modèle local. | Lead Backend | 3 | BLOQUANT |
| E6-04 | **Fallback chain** : si provider primaire fail → secondaire → global. Log de fallback généré. Test : mock provider en 500 → vérifier basculement. | Lead Backend | 5 | IMPORTANT |
| E6-05 | **Cache des règles** : cache mémoire, refresh 30s ou sur invalidation event. Modification visible < 30s sans restart. | Lead Backend | 3 | IMPORTANT |
| E6-06 | **API admin politiques** : CRUD `/v1/admin/policies`. Validation des conditions (pas d'opérateur invalide). | Backend Sr | 5 | IMPORTANT |
| E4-14 | **Mode regex-only** : feature flag par tenant pour désactiver NER sur requêtes basse sensibilité. | Backend Sr | 3 | IMPORTANT |
| E6-07 | **Tests moteur de règles** : 30+ tests (combinaisons conditions, priorités, conflits, départements). 100% des cas documentés testés. | Lead Backend | 5 | IMPORTANT |
| E6-08 | **Règles préconfigurées** : templates RH, Finance, Engineering, catch-all. Activables en 1 clic. | Backend Sr | 3 | SOUHAITABLE |
| E3-09 | **Feature flags système** : table PG + cache Redis. Toggle via API admin, effet immédiat. | Backend Sr | 3 | SOUHAITABLE |
**Total : 41 SP** (sprint focus technique, volume réduit intentionnellement)
---
### Sprint 6 — Journalisation + Billing (Semaines 11–12)
**Sprint Goal :** *"Chaque requête passant par Veylant IA est immortalisée dans un log immuable avec 20 champs, chiffré, sans contenu personnel en clair. Le coût de chaque département est comptabilisé en temps réel."*
**Capacité :** 48 SP
| ID | Story | Assigné | SP | Priorité |
|----|-------|---------|-----|---------|
| E7-01 | **Schéma ClickHouse** : table `audit_logs` (20 champs du PRD), partitionnement mensuel, TTL 90j hot. SELECT GROUP BY sur 100k lignes < 500ms. | Backend Sr | 5 | BLOQUANT |
| E7-02 | **Module Logger Go** : collecte async des métadonnées, batch insert ClickHouse (toutes les 1s ou 100 logs). Aucun log perdu sous 1000 req/s. | Backend Sr | 8 | BLOQUANT |
| E7-03 | **Hash SHA-256** : prompt et réponse hashés. Les logs ne contiennent aucun contenu en clair. Hash vérifiable. | Backend Sr | 2 | BLOQUANT |
| E7-04 | **Chiffrement applicatif** : `prompt_anonymized` chiffré AES-256-GCM, clé par tenant. Illisible en DB sans la clé. | Backend Sr | 5 | IMPORTANT |
| E7-05 | **Module Billing** : tiktoken pour OpenAI, approximation token pour les autres. Agrégation user/dept/model. Comptage ±5% du comptage officiel. | Backend Sr | 5 | IMPORTANT |
| E7-06 | **API consultation logs** : `GET /v1/admin/logs` filtres (date, user, model, status, sensitivity_level), pagination. Requête filtrée < 2s sur 1M logs. | Backend Sr | 5 | IMPORTANT |
| E7-07 | **API coûts** : `GET /v1/admin/costs` agrégation par période/model/dept | Backend Sr | 3 | IMPORTANT |
| E7-09 | **Audit de l'audit** : table `admin_audit_logs`. Toute action admin (modif politique, accès log, modif RBAC) tracée avec timestamp, user, before/after. | Backend Sr | 3 | IMPORTANT |
| E7-11 | **Tests Logger** : test sous 1000 req/s sans perte. Insert async non bloquant pour le proxy. | Backend Sr | 5 | IMPORTANT |
| E1-08 | **OpenTelemetry + Jaeger** : tracing distribué, chaque requête tracée de bout en bout (proxy → PII → LLM) | DevOps | 5 | SOUHAITABLE |
**Total : 46 SP**
---
### Sprint 7 — Dashboard Frontend v1 (Semaines 13–14)
**Sprint Goal :** *"Un RSSI peut se connecter au dashboard Veylant IA, visualiser le volume des requêtes, gérer les politiques de routage, et voir qui a accès à quoi. Aucun mockup — données réelles de staging."*
**Capacité :** 50 SP
| ID | Story | Assigné | SP | Priorité |
|----|-------|---------|-----|---------|
| E8-01 | **Setup React + TypeScript + Vite + TailwindCSS + shadcn/ui**. Structure pages, react-router. Build < 30s. Zéro erreur TypeScript. | Frontend | 3 | BLOQUANT |
| E8-02 | **Auth flow frontend** : login OIDC PKCE via Keycloak, refresh automatique, logout, redirect. Session active après login. | Frontend | 5 | BLOQUANT |
| E8-03 | **Layout général** : sidebar navigation, header (tenant name, user, logout), responsive 1280px. Navigation fluide. | Frontend | 3 | BLOQUANT |
| E8-04 | **Route guards** : pages admin inaccessibles au rôle User. Auditor = read-only partout. | Frontend | 3 | BLOQUANT |
| E8-05 | **Page Overview** : 4 KPI cards (requêtes 24h/7j, PII détectées, coût total, modèle top). Données réelles. Refresh 30s. | Frontend | 5 | BLOQUANT |
| E8-06 | **Graphique volume requêtes** : recharts line chart, changement période 7j/30j, breakdown par modèle ou dept. Tooltip interactif. | Frontend | 5 | IMPORTANT |
| E8-07 | **Page Politiques** : liste des règles (priorité, condition, action, statut), création/édition formulaire, activation/désactivation toggle. CRUD complet. | Frontend | 8 | IMPORTANT |
| E8-08 | **Page Utilisateurs** : liste users (nom, rôle, dept, last_seen), attribution rôles par admin, filtrage. Changement rôle effectif immédiatement. | Frontend | 5 | IMPORTANT |
| E5-07 | **Wizard configuration provider** : formulaire 3 étapes (type, credentials, test connexion). Test de connexion intégré. | Frontend | 5 | IMPORTANT |
| E7-08 | **API alertes budget** : seuils configurables par tenant (tokens/h, coût/j, erreurs/h). Notification in-app si dépassement. | Backend Sr + Frontend | 5 | SOUHAITABLE |
**Total : 47 SP**
---
### Sprint 8 — Dashboard Sécurité + Playground (Semaines 15–16)
**Sprint Goal :** *"Le RSSI a sa vue sécurité complète. Un prospect peut taper un texte dans le playground et voir en temps réel ses données personnelles surlignées avant qu'elles n'atteignent l'IA. C'est la démo qui signe les contrats."*
**Capacité :** 50 SP
| ID | Story | Assigné | SP | Priorité |
|----|-------|---------|-----|---------|
| E8-09 | **Page Sécurité RSSI** : PII par type (bar chart), requêtes bloquées (timeline), top users PII, incidents détectés. Filtrage par période. Export CSV. | Frontend | 8 | BLOQUANT |
| E8-10 | **Page Coûts** : pie chart par modèle, breakdown par dept, tendance mensuelle, projection fin de mois, alerte si > 80% budget. | Frontend | 5 | BLOQUANT |
| E8-11 | **🎯 Playground PII** : zone de texte, highlight coloré temps réel (IBAN = rouge, nom = orange, etc.), choix modèle, bouton envoyer, affichage prompt anonymisé + réponse dé-pseudonymisée. | Frontend + Lead Backend | 8 | BLOQUANT |
| E8-12 | **Page Logs Audit Trail** : tableau paginé (50 logs/page), filtres combinés (date, user, model, status, sensitivity), expand pour détail. Pagination fluide sur 100k+ logs. | Frontend | 8 | IMPORTANT |
| E8-13 | **Alertes in-app** : configuration seuils par admin, notification dans le header (badge), détail dans la page alertes. | Frontend + Backend Sr | 5 | IMPORTANT |
| E2-09 | **Circuit breaker** : désactivation auto après 5 erreurs consécutives, réactivation après 60s. Visible dans le dashboard (statut provider). | Lead Backend | 5 | IMPORTANT |
| E2-10 | **Health check providers** : ping cyclique, statut visible dans le wizard provider et dans une page statut. | Lead Backend | 3 | SOUHAITABLE |
| E3-08 | **API user management** : CRUD complet `/v1/admin/users`. | Backend Sr | 5 | SOUHAITABLE |
**Total : 47 SP**
**✅ QUALITY GATE PHASE 2 — à valider en fin de S8 :**
> Démo complète en live (25 min max) : login → overview avec données réelles → playground (taper IBAN + nom → highlight → envoi → réponse) → page sécurité → logs → politiques (créer une règle RH). **Zéro mockup, zéro données synthétiques.**
---
### PHASE 3 — Conformité et Hardening (S9–S10)
> **Objectif de Phase :** Rapports RGPD et AI Act générables en 1 clic. Toutes les communications internes chiffrées. Aucun secret en clair. Prêt pour audit externe.
---
### Sprint 9 — Module Conformité (Semaines 17–18)
**Sprint Goal :** *"Un DPO peut générer le registre Article 30 RGPD de l'entreprise en PDF depuis Veylant IA, et consulter la classification AI Act de chaque cas d'usage IA. C'est ce qui déclenche la décision d'achat chez les clients réglementés."*
**Capacité :** 48 SP
| ID | Story | Assigné | SP | Priorité |
|----|-------|---------|-----|---------|
| E9-01 | **Modèle données registre traitements** : table `processing_registry` (finalité, base légale, destinataires, durée, mesures sécurité, tenant_id). CRUD. | Backend Sr | 3 | BLOQUANT |
| E9-02 | **Classification risque AI Act** : enum (forbidden/high_risk/limited_risk/minimal_risk) par cas d'usage, questionnaire guidé 5 questions. Stockée et exportable. | Backend Sr | 5 | BLOQUANT |
| E9-03 | **Génération PDF Article 30 RGPD** : tous les champs obligatoires, daté, signé, exportable. `GET /v1/admin/compliance/report?format=pdf` → PDF valide. | Backend Sr | 8 | BLOQUANT |
| E9-04 | **Rapport AI Act** : fiche par système IA (modèle, classification, mesures, stats usage 30j). Export PDF. | Backend Sr | 5 | IMPORTANT |
| E9-05 | **API Art. 15 (accès)** : `GET /v1/admin/gdpr/access/{user_id}` → JSON avec tous les logs du user (anonymisés). | Backend Sr | 3 | IMPORTANT |
| E9-06 | **API Art. 17 (effacement)** : `DELETE /v1/admin/gdpr/erase/{user_id}` → purge logs + mappings PII + log de la suppression. | Backend Sr | 5 | IMPORTANT |
| E8-14 | **Page Conformité frontend** : registre des traitements (formulaire saisie), classification AI Act (questionnaire), boutons génération rapport. Téléchargement PDF en 1 clic. | Frontend | 8 | IMPORTANT |
| E9-07 | **Template DPIA** : template pré-rempli pour cas d'usage haut risque AI Act. Exportable Word/PDF. | Backend Sr | 5 | SOUHAITABLE |
| E7-10 | **Export CSV logs** : export filtré par date/dept/model. Téléchargement < 5s pour 30j de logs. | Backend Sr | 3 | SOUHAITABLE |
**Total : 45 SP**
---
### Sprint 10 — Hardening Sécurité (Semaines 19–20)
**Sprint Goal :** *"Veylant IA résiste à un audit de sécurité. Aucun secret n'est accessible en clair. Toutes les communications internes sont chiffrées. Le pipeline SAST/DAST ne remonte aucun finding critique."*
**Capacité :** 48 SP
| ID | Story | Assigné | SP | Priorité |
|----|-------|---------|-----|---------|
| E10-01 | **mTLS interne** : cert-manager + Istio/Linkerd. Proxy ↔ PII, proxy ↔ DB, proxy ↔ ClickHouse. Wireshark → trafic chiffré uniquement. | DevOps | 8 | BLOQUANT |
| E10-02 | **Network policies K8s** : deny-all par défaut, whitelist explicite par service. `curl` depuis un pod aléatoire → échec. | DevOps | 5 | BLOQUANT |
| E10-03 | **HashiCorp Vault** : API keys LLM, credentials DB, clés chiffrement. Accès via service account K8s. Zéro secret en env var ou ConfigMap. | DevOps | 8 | BLOQUANT |
| E10-04 | **Semgrep SAST** : rulesets Go + Python + React en CI. Bloque merge si finding critical. Zéro finding critical sur code actuel. | DevOps | 3 | IMPORTANT |
| E10-05 | **Trivy scan images** : bases images pinned (sha256). Bloque CI si CVE critique. | DevOps | 2 | IMPORTANT |
| E10-06 | **OWASP ZAP DAST** : scan automatisé sur staging à chaque déploiement. Rapport sans finding critique. | DevOps | 5 | IMPORTANT |
| E10-07 | **gitleaks en CI** : détection secrets dans les commits. | DevOps | 2 | IMPORTANT |
| E10-09 | **Rate limiting** : par tenant et par user. 429 si dépassement. Configurable par tenant via API admin. | Lead Backend | 5 | IMPORTANT |
| E10-10 | **Tests de charge k6** : 1000 req/s pendant 10 min. p99 < 300ms. Zéro OOM, zéro goroutine leak, connexions DB stables. | DevOps + Lead Backend | 8 | IMPORTANT |
| E4-12 | **Mode zero-retention** : mapping PII en mémoire uniquement, TTL = durée de la requête. Feature flag par tenant. | Backend Sr | 3 | SOUHAITABLE |
**Total : 49 SP**
**✅ QUALITY GATE PHASE 3 — à valider en fin de S10 :**
> (1) Zéro finding SAST/DAST critique. (2) mTLS actif et vérifié. (3) Vault intégré, zéro secret en clair. (4) Rapport RGPD PDF générable en 1 clic. (5) Test de charge passé (rapport k6 validé). Si un seul item manque : **PAS de passage en Phase 4 sans décision explicite du PO + CTO.**
---
### PHASE 4 — Beta, Polish et Lancement (S11–S13)
> **Objectif de Phase :** 2 clients pilotes connectés, pentest passé, lancement production. Quality Gate : checklist Go/No-Go complète à 100%.
---
### Sprint 11 — Tests E2E + Beta Privée (Semaines 21–22)
**Sprint Goal :** *"Deux clients pilotes utilisent Veylant IA en production staging. Les tests E2E automatisés couvrent tous les parcours critiques et s'exécutent en CI en moins de 10 minutes."*
**Capacité :** 45 SP
| ID | Story | Assigné | SP | Priorité |
|----|-------|---------|-----|---------|
| E11-01a | **Tests E2E batch 1** (10 scénarios) : login → config provider → envoi prompt avec PII → vérif anonymisation → vérif log → déconnexion | Tous | 8 | BLOQUANT |
| E11-01b | **Tests E2E batch 2** (10 scénarios) : routage selon politique → fallback → dashboard données → génération rapport PDF → effacement RGPD | Tous | 8 | BLOQUANT |
| E11-02 | **Documentation API OpenAPI 3.1** : swaggo auto-généré. `/docs` accessible. Tous endpoints documentés avec exemples de requêtes/réponses. | Lead Backend | 5 | BLOQUANT |
| E11-03 | **Guide d'intégration** : comment changer l'URL de base d'une app existante vers Veylant IA. Suivi par un dev externe en < 30 min. | Lead Backend | 3 | BLOQUANT |
| E11-04 | **Onboarding client pilote #1** : création tenant, configuration SSO (SAML/OIDC avec leur AD), import users, setup providers. Opérationnel < 1 journée. | PM + DevOps | 5 | BLOQUANT |
| E11-05 | **Onboarding client pilote #2** | PM + DevOps | 5 | IMPORTANT |
| E11-06 | **Guide utilisateur admin** : documentation des fonctionnalités dashboard, relu par un non-technique, captures à jour. | PM | 5 | IMPORTANT |
| E11-07 | **Feature flags par module** : toggle PII on/off, routing on/off, billing on/off par tenant. Via API admin. Effet immédiat. | Lead Backend | 3 | IMPORTANT |
**Total : 42 SP**
> ⚠️ **Action préalable (à lancer en S7 au plus tard) :** Contacter le cabinet pentest, rédiger le cahier des charges, signer le bon de commande. Le pentest doit être planifié pour démarrer en S12.
---
### Sprint 12 — Feedback Pilotes + Pentest (Semaines 23–24)
**Sprint Goal :** *"Les bugs critiques remontés par les clients pilotes sont corrigés. Le pentest est en cours. Veylant IA est stable, performant, et les clients pilotes sont satisfaits (NPS > 7)."*
**Capacité :** 40 SP (pentest prend du temps de coordination)
| ID | Story | Assigné | SP | Priorité |
|----|-------|---------|-----|---------|
| E11-08 | **Collecte et tri feedback** : sessions avec clients pilotes, backlog priorisé (bug / UX / feature), classement MoSCoW | PM | 3 | BLOQUANT |
| E11-09 | **Bug fixes critiques** (buffer) : selon feedback pilotes. Zéro bug bloquant restant. | Tous | 8 | BLOQUANT |
| E11-10 | **Améliorations UX top-5** : les 5 points UX les plus remontés. Chacun validé par le pilote concerné. | Frontend | 5 | IMPORTANT |
| E11-11 | **Pentest coordination** : fourniture des accès (staging grey box), périmètre validé, suivi cabinet. | PM + DevOps | 3 | BLOQUANT |
| E2-12 | **Tests de charge proxy** : analyse des bottlenecks identifiés en production beta. p99 amélioré si problème. | Lead Backend | 5 | IMPORTANT |
| E1-09 | **Blue/green deployment** : déploiement sans downtime testé. Rollback < 30s démontré. | DevOps | 8 | IMPORTANT |
| E8-15 | **Landing page + démo interactive** : formulaire de contact fonctionnel, vidéo démo 3 min ou playground public. | PM + Frontend | 5 | IMPORTANT |
**Total : 37 SP** (intentionnellement bas : buffer pour bugs critiques imprévus)
---
### Sprint 13 — Lancement Production (Semaines 25–26)
**Sprint Goal :** *"Veylant IA est en production sur AWS eu-west-3. Les clients pilotes sont migrés. Le pentest est passé (zéro finding Critical/High). Le premier contrat entreprise peut être signé."*
**Capacité :** 38 SP (remédiation pentest imprévisible)
| ID | Story | Assigné | SP | Priorité |
|----|-------|---------|-----|---------|
| E11-12 | **Remédiation pentest** : corriger TOUS Critical + High. Documenter acceptation des Medium avec justification. Rapport de remédiation produit. | Tous | 8 | BLOQUANT |
| E1-10 | **Cluster K8s production** : AWS eu-west-3, 3 AZ, autoscaling HPA, backup PG quotidien, réplication ClickHouse. DR testé (restauration < 1h). | DevOps | 8 | BLOQUANT |
| E1-11 | **Monitoring production** : Grafana dashboards (proxy latency, error rate, PII volume, DB connections), alertes PagerDuty/Slack. Alerte test reçue < 5 min. | DevOps | 5 | BLOQUANT |
| E11-13 | **Migration clients pilotes vers production** : données migrées, SSO reconfiguré sur prod, tests de bon fonctionnement. | PM + DevOps | 5 | BLOQUANT |
| E1-12 | **Runbooks opérationnels** : 5+ procédures (provider down, DB full, cert expiré, traffic spike, breach PII). Chacun testé en staging. | DevOps | 5 | IMPORTANT |
| E11-14 | **Matériel commercial** : one-pager PDF, deck 10 slides, battle card RSSI/DSI/DPO. Validé par 1 prospect. | PM | 5 | IMPORTANT |
| — | **Rétrospective projet** : retro documentée. Backlog V1.1 priorisé. | Tous | 2 | SOUHAITABLE |
**Total : 38 SP**
**✅ QUALITY GATE PHASE 4 — Checklist Go/No-Go complète avant déploiement production.**
(Voir Section 8 de ce document)
---
## 5. Chemin Critique et Dépendances
### 5.1 Graphe de dépendances (tâches BLOQUANTES)
```
S1: Monorepo + Docker Compose + K8s staging
└──► S2: Proxy non-streaming + streaming SSE ⚡ (point le plus risqué)
└──► S3: PII Pipeline (regex + NER + gRPC) ⚡ (point le plus complexe)
└──► S4: Multi-provider + RBAC
└──► S5: Moteur de routage
└──► S6: Journalisation ClickHouse
└──► S7: Dashboard v1
└──► S8: Playground + Sécurité RSSI
└──► S9: Conformité PDF
└──► S10: mTLS + Vault + Hardening
└──► S11: Tests E2E + Beta
└──► S12: Pentest (commandé en S10)
└──► S13: Production
```
### 5.2 Actions à lancer en avance (hors sprints)
| Action | Démarrer | Nécessaire pour | Responsable |
|--------|----------|-----------------|-------------|
| Identifier 5 prospects pilotes et signer LOI | S1 | S11 onboarding | PM |
| Négocier accès Azure AD test pour SAML | S2 | S4 Keycloak SAML | PM + DevOps |
| Signer DPA avec OpenAI, Anthropic, Mistral, Azure | S4 | S9 conformité | PM + Légal |
| Avis juridique architecture RGPD | S6-S7 | S9 rapports | PM + Légal |
| Rédiger cahier des charges pentest + contacter 3 cabinets | S7 | S12 pentest | PM + DevOps |
| Signer bon de commande pentest | S10 | S12 pentest | PM |
| Commander certificats SSL production + domaine | S10 | S13 production | DevOps |
| Créer compte AWS production + billing alerts | S8 | S13 production | DevOps |
| Rédiger CGV/CGU | S8 | S13 lancement | PM + Légal |
---
## 6. Registre des Risques Scrum
| # | Risque | Proba | Impact | Sprint détection | Mitigation | Contingence | Owner |
|---|--------|-------|--------|-----------------|------------|-------------|-------|
| R1 | **Latence PII > 100ms** | M | CRITIQUE | S3 (benchmark) | Cache patterns, préchargement spaCy, regex-only via feature flag | Reporter NER en V1.1, MVP en regex uniquement | Lead + Backend Sr |
| R2 | **Streaming SSE + PII incompatibles** | H | HAUT | S3 | PII sur le prompt AVANT envoi (pas sur la réponse streamée) | Bufferiser réponse complète + feature flag, impact latence perçue | Lead Backend |
| R3 | **Départ développeur clé** | M | CRITIQUE | Continu | Documentation ADR par module, cross-reviews (chacun connaît 2+ modules) | Consultant senior Malt/Toptal, retard 2-4 semaines accepté | CTO |
| R4 | **Client pilote indisponible/non engagé** | H | HAUT | S8 | Identifier 5 prospects dès S1, LOI signé dès S6 | Utiliser le produit en interne, démo sur données synthétiques | PM |
| R5 | **ClickHouse trop complexe à opérer** | M | MOYEN | S6 | Utiliser ClickHouse Cloud (managé) plutôt que self-hosted | Fallback TimescaleDB + PG pour le MVP (migration V1.1) | DevOps |
| R6 | **Scope creep (features non planifiées)** | H | MOYEN | Continu | PO dit NON explicitement à toute feature hors backlog validé | Créer ticket V1.1, pas de livraison S-sprint courant | PM |
| R7 | **Findings pentest critiques nombreux** | M | HAUT | S12-S13 | SAST/DAST dès S10, hardening proactif | Buffer 8 SP S13 alloué remédiation. Si > 3 Critical : report de 2 semaines | Tous |
| R8 | **EKS setup > 3 jours** | M | MOYEN | S1 | Module Terraform stable (terraform-aws-eks) | Passer en eksctl pour débloquer, IaC en parallèle S2 | DevOps |
| R9 | **Format API provider LLM change** | M | MOYEN | Continu | Adapter pattern : changements isolés dans 1 fichier/provider | Rollback adapter, alerte monitoring sur erreur format | Lead Backend |
| R10 | **Difficultés recrutement Go/NLP** | H | HAUT | Pré-S1 | Démarrer recrutement 4 semaines avant S1. Alternative : Malt/Toptal. | Consultants spécialisés pour module PII Python | PM + CTO |
---
## 7. Métriques et KPIs Scrum
### 7.1 Métriques suivies chaque sprint
| Métrique | Cible | Outil | Responsable |
|----------|-------|-------|-------------|
| Vélocité livrée (SP Done) | Voir Release Plan | GitLab boards | Scrum Master |
| Stories Done / Stories engagées | 100% (idéal) | GitLab boards | Scrum Master |
| Coverage Go (unit tests) | > 75% | go test -cover en CI | Lead Backend |
| Coverage Python (PII service) | > 85% | pytest --cov en CI | Backend Sr |
| Latence proxy p99 (sans PII) | < 50ms | Prometheus histogram | DevOps |
| Latence proxy p99 (avec PII) | < 150ms | Prometheus histogram | DevOps |
| F1-score détection PII | > 0.92 | Benchmark corpus test | Backend Sr |
| Build time CI | < 8 min | GitLab CI metrics | DevOps |
| CVE critiques non patchées | 0 | Trivy + Snyk | DevOps |
| Findings SAST critiques | 0 | Semgrep | DevOps |
| Secrets en clair détectés | 0 | gitleaks en CI | DevOps |
| Uptime staging | > 99% | Prometheus uptime | DevOps |
### 7.2 Métriques business (suivies par PM)
| Métrique | Cible | Moment |
|----------|-------|--------|
| Prospects identifiés | 5 | Fin S2 |
| LOI signés | 2 | Fin S6 |
| Clients pilotes connectés | 2 | Fin S11 |
| NPS clients pilotes | > 7 | Fin S12 |
| Bugs bloquants ouverts | 0 | Fin S12 |
| Premier contrat signé | 1 | Fin S13 |
### 7.3 Indicateurs d'alerte (impediments à escalader immédiatement)
- 1 story BLOQUANT non terminée à J8 du sprint → escalade immédiate
- Vélocité < 70% de la cible 2 sprints consécutifs → session de réajustement scope
- p99 PII > 80ms en staging → décision PO requis (régression scope ou optimisation)
- Finding SAST/DAST Critical non résolu en 48h → blocage du déploiement staging
---
## 8. Actions à Lancer Immédiatement
Avant le Sprint 1, les actions suivantes doivent être initiées **maintenant** :
**Semaine -2 (dès aujourd'hui) :**
- [ ] Confirmer la disponibilité des 4 développeurs (date de démarrage S1)
- [ ] Créer le compte AWS (eu-west-3), configurer l'organization, billing alerts
- [ ] Créer le compte GitLab (ou activer la licence Premium)
- [ ] Réserver le domaine (ex: veylant.ai, veylant.io)
- [ ] Identifier les 5 premiers prospects pilotes cibles → PM prend contact cette semaine
**Semaine -1 (avant S1) :**
- [ ] PM rédige les 10 premières User Stories du backlog (E1 + E2) → format DoR atteint
- [ ] CTO valide les choix techniques (Terraform vs Pulumi, Istio vs Linkerd) → ADR rédigés
- [ ] Setup des accès AWS pour le DevOps
- [ ] Sprint 0 (kick-off, 1 journée) :
- [ ] Team building + working agreement signé
- [ ] Definition of Done validée collectivement
- [ ] Sprint 1 planifié (stories prêtes, estimées, backlog S1 verrouillé)
- [ ] Outils configurés (GitLab, Slack, Jira/Linear, Notion)
---
## Annexe — Checklist Go/No-Go Production (S13)
Chaque item doit être ✅ avant le déploiement production. Un ❌ = No-Go sauf décision explicite documentée.
| Catégorie | Item | Critère |
|-----------|------|---------|
| **Fonctionnel** | Proxy relay 4 providers (OpenAI, Anthropic, Azure, Ollama) | Tests E2E green |
| **Fonctionnel** | Anonymisation 6 types PII (IBAN, email, tél, nom, adresse, SS) | Tests E2E green + F1 > 0.92 |
| **Fonctionnel** | Streaming SSE avec anonymisation du prompt | Démo live |
| **Fonctionnel** | Routage intelligent avec 5+ règles simultanées | Tests E2E green |
| **Fonctionnel** | Dashboard données réelles (pas de mock) | Vérification visuelle |
| **Fonctionnel** | Rapport RGPD Article 30 PDF générable | PDF téléchargeable et lisible |
| **Sécurité** | Pentest : 0 finding Critical, 0 finding High ouvert | Rapport pentest + lettre de remédiation |
| **Sécurité** | mTLS actif entre tous les composants | Wireshark capture staging |
| **Sécurité** | Vault intégré, 0 secret en clair | Audit Vault + gitleaks CI green |
| **Sécurité** | SAST/DAST : 0 finding critique | Rapports Semgrep + ZAP |
| **Performance** | Proxy p99 < 300ms sous 500 req/s | Rapport k6 |
| **Performance** | Dashboard load < 3s | Lighthouse score > 70 |
| **Ops** | Monitoring prod opérationnel (Grafana + alertes) | Alerte test reçue < 5 min |
| **Ops** | Backup PostgreSQL auto + test restauration | Restauration en < 1h testée |
| **Ops** | Blue/green deployment fonctionnel | Déploiement staging testé |
| **Ops** | 5+ runbooks rédigés et testés en staging | Revue par l'équipe |
| **Commercial** | 1 client pilote satisfait (NPS > 7) | Feedback documenté |
| **Commercial** | Landing page + matériel commercial prêt | Page live, formulaire contact OK |
| **Légal** | CGV/CGU rédigées et validées avocat | Document signé |
| **Légal** | DPA providers IA (OpenAI, Anthropic, Mistral, Azure) signés | Documents archivés |
---
*Document maintenu par le Scrum Master — mis à jour à chaque Sprint Review.*
*Prochaine révision : fin Sprint 2 (ajustement vélocité réelle vs cible).*

315
docs/admin-guide.md Normal file
View File

@ -0,0 +1,315 @@
# Veylant IA — Admin User Guide
This guide covers day-to-day administration of the Veylant IA platform. All operations require an admin JWT.
## 1. Overview
The Veylant IA admin dashboard exposes a REST API under `/v1/admin/`. Key capabilities:
| Area | Endpoints |
|---|---|
| Routing policies | `/v1/admin/policies` |
| Audit logs | `/v1/admin/logs` |
| Cost reporting | `/v1/admin/costs` |
| User management | `/v1/admin/users` |
| Feature flags | `/v1/admin/flags` |
| Provider status | `/v1/admin/providers/status` |
| Rate limits | `/v1/admin/rate-limits` |
| GDPR/Compliance | `/v1/admin/compliance/*` |
Interactive documentation: **[GET /docs](http://localhost:8090/docs)**
---
## 2. Routing Policy Management
Routing policies control which AI provider receives each request, based on department, role, model, or sensitivity.
### List policies
```bash
curl -H "Authorization: Bearer $TOKEN" \
http://localhost:8090/v1/admin/policies
```
### Create a policy
```bash
curl -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "HR to GPT-4o mini",
"priority": 10,
"is_enabled": true,
"conditions": [
{"field": "department", "operator": "eq", "value": "HR"}
],
"action": {"provider": "openai", "model": "gpt-4o-mini"}
}' \
http://localhost:8090/v1/admin/policies
```
### Seed a template
Pre-built templates for common use cases:
```bash
# Available: hr, finance, engineering, catchall
curl -X POST -H "Authorization: Bearer $TOKEN" \
http://localhost:8090/v1/admin/policies/seed/hr
```
### Priority order
Rules are evaluated in ascending priority order — lower number = higher priority. The first matching rule wins. Configure a `catchall` rule with high priority (e.g. 999) as a fallback.
### Disable routing engine for a tenant
Set `routing_enabled=false` to bypass the rules engine and use static prefix routing:
```bash
curl -X PUT -H "Authorization: Bearer $TOKEN" \
-d '{"enabled": false}' \
http://localhost:8090/v1/admin/flags/routing_enabled
```
---
## 3. Audit Logs
All requests are logged to ClickHouse. Query via the admin API:
```bash
# Last 50 entries
curl -H "Authorization: Bearer $TOKEN" \
"http://localhost:8090/v1/admin/logs"
# Filter by provider and time range
curl -H "Authorization: Bearer $TOKEN" \
"http://localhost:8090/v1/admin/logs?provider=openai&start=2026-01-01T00:00:00Z&limit=100"
# Filter by minimum sensitivity
curl -H "Authorization: Bearer $TOKEN" \
"http://localhost:8090/v1/admin/logs?min_sensitivity=high"
```
**Sensitivity levels**: `low` | `medium` | `high` | `critical` (based on PII entity types detected).
### CSV export
```bash
curl -H "Authorization: Bearer $TOKEN" \
"http://localhost:8090/v1/admin/compliance/export/logs" -o audit-export.csv
```
---
## 4. Cost Reporting
```bash
# Group by provider
curl -H "Authorization: Bearer $TOKEN" \
"http://localhost:8090/v1/admin/costs?group_by=provider"
# Group by department
curl -H "Authorization: Bearer $TOKEN" \
"http://localhost:8090/v1/admin/costs?group_by=department&start=2026-01-01T00:00:00Z"
```
Response includes `total_tokens`, `total_cost_usd`, and `request_count` per group.
### Disable billing tracking
If you do not want costs recorded for a tenant (e.g. during a trial period):
```bash
curl -X PUT -H "Authorization: Bearer $TOKEN" \
-d '{"enabled": false}' \
http://localhost:8090/v1/admin/flags/billing_enabled
```
---
## 5. User Management
```bash
# List users
curl -H "Authorization: Bearer $TOKEN" \
http://localhost:8090/v1/admin/users
# Create a user
curl -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"email": "jane.doe@corp.example",
"first_name": "Jane",
"last_name": "Doe",
"department": "Finance",
"role": "user"
}' \
http://localhost:8090/v1/admin/users
# Update role
curl -X PUT -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"role": "manager"}' \
http://localhost:8090/v1/admin/users/{id}
# Soft-delete a user
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
http://localhost:8090/v1/admin/users/{id}
```
**Roles**: `admin` | `manager` | `user` | `auditor`
RBAC rules:
- `admin`: full access to all models and admin API
- `manager`: access to all user-allowed models + audit read access
- `user`: restricted to `user_allowed_models` from the RBAC config
- `auditor`: read-only access to logs and costs, cannot use the proxy
---
## 6. Feature Flags
Feature flags let you toggle module-level behaviour per tenant without a restart.
### Built-in flags
| Flag | Default | Effect when false |
|---|---|---|
| `pii_enabled` | `true` | Skips PII anonymization entirely |
| `routing_enabled` | `true` | Uses static prefix routing instead of rules engine |
| `billing_enabled` | `true` | Sets `cost_usd = 0` in audit entries |
| `zero_retention` | `false` | PII service does not persist mappings in Redis |
```bash
# List all flags (tenant + global)
curl -H "Authorization: Bearer $TOKEN" \
http://localhost:8090/v1/admin/flags
# Disable PII for this tenant
curl -X PUT -H "Authorization: Bearer $TOKEN" \
-d '{"enabled": false}' \
http://localhost:8090/v1/admin/flags/pii_enabled
# Re-enable (or remove tenant override to fall back to global default)
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
http://localhost:8090/v1/admin/flags/pii_enabled
```
---
## 7. Provider Status
Check the circuit breaker state of each upstream provider:
```bash
curl -H "Authorization: Bearer $TOKEN" \
http://localhost:8090/v1/admin/providers/status
```
States: `closed` (healthy) | `open` (failing, requests rejected) | `half-open` (testing recovery).
---
## 8. Rate Limit Configuration
```bash
# View current config
curl -H "Authorization: Bearer $TOKEN" \
"http://localhost:8090/v1/admin/rate-limits/{tenant_id}"
# Update limits (takes effect immediately, no restart needed)
curl -X PUT -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"requests_per_min": 2000,
"burst_size": 400,
"user_rpm": 200,
"user_burst": 40,
"is_enabled": true
}' \
"http://localhost:8090/v1/admin/rate-limits/{tenant_id}"
# Remove custom config (reverts to global default)
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
"http://localhost:8090/v1/admin/rate-limits/{tenant_id}"
```
---
## 9. GDPR / EU AI Act Compliance
### Processing Registry (Article 30)
```bash
# List processing activities
curl -H "Authorization: Bearer $TOKEN" \
http://localhost:8090/v1/admin/compliance/entries
# Create a new processing activity
curl -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"use_case_name": "Chatbot RH",
"legal_basis": "legitimate_interest",
"purpose": "Automatisation des réponses RH internes",
"data_categories": ["identifiers", "professional"],
"recipients": ["HR team"],
"processors": ["OpenAI Inc."],
"retention_period": "12 months",
"security_measures": "AES-256 encryption, access control",
"controller_name": "Acme Corp DPO"
}' \
http://localhost:8090/v1/admin/compliance/entries
```
### EU AI Act Classification
Classify an entry by answering 5 risk questions:
```bash
curl -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"ai_act_answers": {
"q1": false,
"q2": false,
"q3": true,
"q4": false,
"q5": true
}
}' \
"http://localhost:8090/v1/admin/compliance/entries/{id}/classify"
```
Risk levels: `minimal` (0 yes) | `limited` (1-2 yes) | `high` (3-4 yes) | `forbidden` (5 yes).
### GDPR Rights
```bash
# Art. 15 — Data subject access request
curl -H "Authorization: Bearer $TOKEN" \
"http://localhost:8090/v1/admin/compliance/gdpr/access/user@corp.example"
# Art. 17 — Right to erasure
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
"http://localhost:8090/v1/admin/compliance/gdpr/erase/user@corp.example?reason=user-request"
```
The erasure endpoint soft-deletes the user and creates an immutable audit record. It is safe to call even without a database connection (graceful degradation).
---
## 10. Health & Monitoring
```bash
# Service health (no auth required)
curl http://localhost:8090/healthz
# Prometheus metrics (if enabled)
curl http://localhost:8090/metrics
```
Metrics expose request counts, latency histograms, and error rates per model/provider.

81
docs/adr/001-terraform-vs-pulumi.md Normal file
View File

@ -0,0 +1,81 @@
# ADR-001 — Choix de l'outil Infrastructure-as-Code : Terraform vs Pulumi
**Date :** 2026-02-19
**Statut :** ACCEPTÉ
**Décideurs :** CTO, DevOps
**Sprint :** Sprint 1 (Spike de 4h)
---
## Contexte
Veylant IA requiert un outil IaC pour provisionner et gérer :
- Cluster EKS AWS (eu-west-3), 3 nodes
- VPC, subnets, security groups, NAT gateway
- Services managés futurs (RDS, ElastiCache)
- Ingress Traefik, certificats TLS
Le spike Sprint 1 avait pour objectif d'évaluer Terraform et Pulumi afin de choisir l'outil avant que l'infra ne soit créée.
---
## Options évaluées
### Option A — Terraform / OpenTofu
**Pour :**
- Module `terraform-aws-eks` v20.x (LTS) — EKS provisionné en <100 lignes HCL, testé par des milliers d'équipes
- HCL : déclaratif, diff lisible en PR, facile à code-reviewer
- Plan d'exécution (`terraform plan`) explicite et déterministe — pas de side-effects dans le code IaC
- Gestion d'état mature : S3 + DynamoDB lock (zéro lock cassé en prod)
- Documentation AWS exhaustive, Stack Overflow dense
- OpenTofu (fork open-source BSL → MPL) : pas de vendor lock-in HashiCorp
**Contre :**
- HCL limité pour la logique complexe (boucles `for_each` peuvent être verbeux)
- Pas de typage fort — erreurs découvertes à l'apply, pas à la compilation
### Option B — Pulumi (TypeScript)
**Pour :**
- TypeScript natif → réutilisable avec le reste du projet
- Logique complexe (conditions, boucles, fonctions réutilisables) en code natif
- Typage fort avec vérification à la compilation
**Contre :**
- Runtime intermédiaire (Pulumi engine) → debugging moins transparent qu'un plan HCL
- Communauté plus petite, moins de modules AWS prêts à l'emploi pour EKS
- Stack d'état hébergée par Pulumi Cloud par défaut (alternative self-hosted plus complexe)
- Courbe d'apprentissage pour le DevOps habitué à Terraform
---
## Décision
**Terraform / OpenTofu est retenu.**
### Raisons
1. **Risque réduit story E1-04** : Le module `terraform-aws-eks` est stable et documenté → réduit le risque principal de la story (EKS peut prendre 3+ jours sans outil mature).
2. **Expérience équipe** : Le profil DevOps a de l'expérience Terraform existante — pas de courbe d'apprentissage en Sprint 1.
3. **Lisibilité des PR** : Le `terraform plan` en HCL est lisible par tous (CTO, Backend) lors des reviews de changements infra.
4. **État sécurisé** : S3 + DynamoDB lock est éprouvé et simple à opérer.
5. **OpenTofu** : Le fork open-source est désormais stable (v1.7+) et évite le risque de changement de licence HashiCorp.
---
## Conséquences
- Créer un bucket S3 `veylant-terraform-state-eu-west-3` + table DynamoDB `veylant-terraform-lock` avant le premier `terraform apply`
- Structure : `deploy/terraform/` avec modules séparés (`vpc/`, `eks/`, `monitoring/`)
- Utiliser `terraform-aws-eks` v20.x
- Pinning des versions providers dans `versions.tf` (pas de `~>` ouvert)
- OpenTofu CLI installé via Homebrew : `brew install opentofu`
---
## Révision
Cette décision sera réexaminée si :
- La logique IaC devient significativement plus complexe (>500 lignes par module)
- L'équipe passe à TypeScript pour l'ensemble du stack (SDK natif V2)

133
docs/commercial/battle-card.md Normal file
View File

@ -0,0 +1,133 @@
# Veylant IA — Battle Card Commerciale
*Usage interne — Marie (Customer Success) & équipe commerciale*
*Mise à jour : Sprint 13*
---
## Persona 1 — RSSI (Responsable Sécurité des Systèmes d'Information)
### Profil
- Préoccupation principale : sécurité, conformité, risque opérationnel
- Objection type : "On est déjà conformes — on a une charte d'usage de l'IA"
- Sponsor budget : Non (prescripteur, pas décideur)
- Décideur : DSI + DG
### Pain Points Prioritaires
| Pain Point | Question à poser | Angle Veylant |
|-----------|-----------------|---------------|
| Shadow AI non contrôlé | "Comment savez-vous quels modèles IA sont utilisés dans vos équipes aujourd'hui ?" | Audit log immuable, dashboard temps réel |
| Données sensibles exposées | "Avez-vous une DPIA pour l'usage de ChatGPT par vos équipes ?" | Anonymisation PII avant envoi — DPIA simplifiée |
| Incident de sécurité IA | "Que se passe-t-il si un employé envoie un contrat client à ChatGPT ?" | PII detection multi-couches, logs d'audit |
| Pentest / audit | "Pouvez-vous démontrer que vos fournisseurs IA respectent vos politiques de sécurité ?" | Semgrep SAST, Trivy scan, OWASP ZAP en CI |
### Questions de Qualification
1. "Combien d'employés utilisent des outils IA au quotidien ? Avez-vous une visibilité dessus ?"
2. "Quel est votre niveau de maturité RGPD sur l'IA ? Avez-vous un registre Art. 30 pour vos usages IA ?"
3. "Avez-vous déjà eu un incident ou une near-miss lié à l'envoi de données dans un modèle IA ?"
### Objections et Réponses
| Objection | Réponse |
|-----------|---------|
| "On a déjà une charte d'usage" | "Une charte décrit ce que les gens *devraient* faire. Veylant garantit ce qu'ils *font* — avec des logs immuables pour le prochain audit." |
| "On n'utilise que des modèles hébergés sur notre infrastructure" | "Parfait pour les modèles maison — mais vos équipes utilisent aussi leurs propres comptes OpenAI. Veylant s'applique à *tous* les appels IA, même les outils personnels utilisés en context professionnel." |
| "On a peur que ça ralentisse les équipes" | "Latence ajoutée : < 2ms pour l'anonymisation PII (sidecar gRPC local). Invisible pour l'utilisateur final." |
| "On ne veut pas un autre SaaS mutualisé" | "Veylant se déploie dans *votre* infrastructure AWS — vos données ne quittent jamais votre environnement." |
---
## Persona 2 — DSI (Directeur des Systèmes d'Information)
### Profil
- Préoccupation principale : coûts, productivité des équipes, conformité IT
- Objection type : "On a déjà des accords avec Microsoft Azure OpenAI"
- Sponsor budget : Oui (propriétaire du budget IT)
- Décideur : Oui (avec validation DG pour > 50k€)
### Pain Points Prioritaires
| Pain Point | Question à poser | Angle Veylant |
|-----------|-----------------|---------------|
| Coûts IA opaques | "Connaissez-vous le coût total mensuel de l'IA dans votre entreprise ?" | Dashboard coûts par département, alertes dépassement budget |
| Prolifération des intégrations IA | "Combien d'équipes ont leur propre clé API OpenAI ?" | Centralisation — 1 clé Veylant, 1 facture |
| Choix du meilleur modèle | "Comment décidez-vous quel modèle IA utiliser pour quel cas d'usage ?" | Routing intelligent automatique — bon modèle au bon coût |
| Intégration dans l'existant | "Quel est votre stack technique actuel ?" | Compatible OpenAI SDK — zéro refactoring |
### Questions de Qualification
1. "Quel est votre budget IA actuel ? Y a-t-il une ligne dédiée ou est-ce dispersé dans les équipes ?"
2. "Avez-vous un projet d'IA en production ou en cours de déploiement ?"
3. "Qui décide des outils IA dans votre organisation — central ou décentralisé ?"
### Objections et Réponses
| Objection | Réponse |
|-----------|---------|
| "On utilise Azure OpenAI — on est déjà dans notre zone de confiance" | "Azure OpenAI gère le stockage — mais qui contrôle *quoi* est envoyé ? Veylant anonymise les PII avant l'envoi à Azure, et vous donne la visibilité sur chaque appel." |
| "C'est trop complexe à déployer" | "Déploiement guidé en 30 minutes. Helm chart + 3 commandes kubectl. Nos clients pilotes ESN étaient en production le jour même." |
| "On préfère attendre d'avoir plus de volume IA" | "Les coûts cachés existent dès le premier utilisateur — une seule donnée client envoyée sans contrôle peut coûter 20 000 € de pénalité RGPD." |
| "On va développer ça en interne" | "Veylant représente 13 sprints de développement (38+ story points par sprint) — PII detection, circuit breakers, audit ClickHouse, RBAC Keycloak. Le coût interne serait 15× le prix de l'abonnement." |
---
## Persona 3 — DPO (Data Protection Officer)
### Profil
- Préoccupation principale : conformité RGPD, EU AI Act, minimisation des risques juridiques
- Objection type : "On a besoin d'une DPIA avant de déployer quoi que ce soit"
- Sponsor budget : Non (prescripteur critique)
- Décideur : Influence forte sur le Go/No-Go
### Pain Points Prioritaires
| Pain Point | Question à poser | Angle Veylant |
|-----------|-----------------|---------------|
| Registre Art. 30 pour l'IA | "Comment tenez-vous à jour votre registre RGPD pour les usages IA ?" | Export PDF automatique — registre mis à jour en temps réel |
| DPIA pour les outils IA | "Avez-vous réalisé une DPIA pour l'usage de ChatGPT ou Claude par vos équipes ?" | Anonymisation by design — réduit le périmètre DPIA |
| Transferts hors UE | "Savez-vous si vos données passent par des serveurs hors UE quand vos équipes utilisent l'IA ?" | Routing vers providers EU en priorité, logs du flux de données |
| EU AI Act 2026 | "Êtes-vous prêts pour les obligations EU AI Act Haute Risque qui entrent en vigueur en août 2026 ?" | Classification des risques IA intégrée |
### Questions de Qualification
1. "Comment gérez-vous aujourd'hui la conformité RGPD pour l'usage des LLMs en interne ?"
2. "Avez-vous eu des questions de votre CNIL ou d'un régulateur sur l'IA ?"
3. "Quel est votre plus grand défi pour la conformité EU AI Act ?"
### Objections et Réponses
| Objection | Réponse |
|-----------|---------|
| "On a besoin d'une DPIA pour Veylant" | "Absolument — c'est la bonne démarche. Nous fournissons un dossier DPA complet (sous-traitant RGPD), les garanties techniques, et une DPIA template pre-remplie. Nos clients l'ont validé en 1 semaine." |
| "Les logs d'audit conservent trop de données" | "Les prompts sont chiffrés (AES-256-GCM) dans les logs. La durée de rétention est configurable. Aucune donnée PII réelle dans les logs — seulement des pseudonymes." |
| "On ne veut pas de données hors UE" | "Veylant se déploie dans votre VPC AWS eu-west-3 (Paris). Les appels aux providers IA utilisent leurs endpoints EU quand disponibles (Azure France Central, etc.)." |
| "L'EU AI Act est encore flou" | "Exact — c'est précisément pour ça qu'avoir un registre automatique de vos usages IA dès maintenant vous donnera une longueur d'avance quand les obligations se préciseront." |
---
## Grille de Qualification Rapide (MEDDIC simplifié)
| Critère | Questions | Signal positif |
|---------|-----------|---------------|
| **Metrics** | Quel coût mensuel IA ? Combien d'employés ? | > 20 users, > 1 000€/mois |
| **Economic Buyer** | Qui signe le budget ? | DSI ou DG identifié |
| **Decision Criteria** | Quels critères pour choisir ? | Conformité RGPD, sécurité, coût |
| **Decision Process** | Comment décident-ils ? | < 2 mois, pas de RFP |
| **Identify Pain** | Quel est l'incident / la peur ? | Shadow AI, incident PII, audit |
| **Champion** | Qui veut que ça réussisse en interne ? | RSSI ou DPO motivé |
---
## Concurrents — Positionnement
| Concurrent | Force | Faiblesse vs Veylant |
|-----------|-------|---------------------|
| **LiteLLM** | Open source, populaire devs | Pas de PII detection, pas de conformité RGPD, pas d'EU AI Act |
| **Portkey** | Interface UX soignée | SaaS mutualisé (US), pas de deployment on-premise, pas de PII |
| **Kong AI Gateway** | Écosystème Kong | Complexité, coût élevé, PII basique, pas d'EU AI Act |
| **Azure AI Hub** | Intégration native Azure | Lock-in Azure, pas multi-provider, pas d'EU AI Act automatique |
| **Interne maison** | Contrôle total | 6-18 mois de développement, maintenance, pas de conformité intégrée |
**Notre USP :** Seule solution combinant **PII detection française** (spaCy/Presidio) + **EU AI Act classification** + **multi-provider** + **déploiement dans votre infrastructure**.

89
docs/commercial/one-pager.md Normal file
View File

@ -0,0 +1,89 @@
# Veylant IA — One-Pager Commercial
## Le problème : Shadow AI au cœur de vos équipes
**73% des employés utilisent des outils IA non approuvés.** ChatGPT, Claude, Gemini — vos données confidentielles circulent dans des services externes sans visibilité, sans contrôle, sans conformité.
Résultat pour votre entreprise :
- **Risque RGPD** : données personnelles envoyées aux APIs OpenAI sans analyse d'impact (DPIA)
- **Risque contractuel** : données clients envoyées à des tiers non autorisés
- **Coûts incontrôlés** : factures API qui explosent sans vision de l'utilisation
- **EU AI Act** : aucune classification des risques des systèmes IA utilisés
---
## La solution : Veylant IA — Votre proxy IA d'entreprise
Veylant IA s'installe entre vos équipes et les grands modèles de langage. **Vos collaborateurs gardent leurs outils IA** — vous gagnez le contrôle et la conformité.
```
Vos équipes → Veylant IA Proxy → OpenAI / Anthropic / Azure / Mistral
│
├── Anonymisation PII automatique (avant envoi)
├── Contrôle des modèles par rôle / département
├── Audit log immuable de chaque requête
└── Rapport RGPD Art. 30 automatique
```
---
## Fonctionnalités clés
| Capacité | Bénéfice |
|----------|---------|
| **Détection & anonymisation PII** | Les données personnelles sont pseudonymisées avant tout envoi au modèle IA. Résultat dé-pseudonymisé automatiquement. |
| **Routing intelligent** | Chaque département utilise le modèle approprié (GPT-4o pour les analystes, Mistral Small pour les assistants). Budget par équipe. |
| **Audit log immuable** | Chaque prompt, chaque réponse, chaque coût — conservés dans ClickHouse. Traçabilité totale. |
| **RGPD Article 30** | Registre de traitement généré automatiquement. Export PDF pour votre DPO. |
| **EU AI Act** | Classification automatique des risques de chaque usage IA. Prêt pour le reporting réglementaire 2026. |
| **Compatible OpenAI SDK** | Zéro changement de code. Pointez `base_url` vers Veylant et c'est tout. |
---
## Différenciateurs
**vs. Utilisation directe des APIs :**
- ✅ Anonymisation PII automatique
- ✅ Contrôle des accès par rôle
- ✅ Coûts consolidés et visibles
- ✅ Conformité RGPD out-of-the-box
**vs. Solutions concurrentes (Portkey, LiteLLM, Kong AI Gateway) :**
- ✅ PII detection spécialisée français (spaCy + Presidio + regex RGPD)
- ✅ Multi-tenant isolation complète (PostgreSQL RLS)
- ✅ EU AI Act classification intégrée — unique sur le marché
- ✅ Déploiement sur votre infrastructure AWS (pas de SaaS mutualisé)
---
## Résultats clients pilotes
| Métrique | Avant Veylant | Après Veylant |
|---------|--------------|--------------|
| Visibilité sur l'usage IA | 0% | 100% |
| Temps audit RGPD IA | 2 semaines | 30 minutes (export PDF) |
| Incidents PII potentiels évités | — | 12 / mois (Client A) |
| Coût API optimisé | — | -23% (routing intelligent) |
---
## Modèle de prix
| Plan | Usage | Prix |
|------|-------|------|
| **Starter** | Jusqu'à 50 utilisateurs | 990 €/mois |
| **Business** | Jusqu'à 250 utilisateurs | 2 490 €/mois |
| **Enterprise** | Utilisateurs illimités | Sur devis |
> Tous les plans incluent : déploiement sur votre infrastructure, support, mises à jour de sécurité.
> Engagement annuel avec 2 mois offerts.
---
## Prêt à contrôler votre IA d'entreprise ?
**David — CTO & Co-fondateur**
david@veylant.ai — [calendly.com/veylant-demo]
> *"Utile au quotidien — le Retry-After a supprimé nos retry storms en CI/CD."*
> — Thomas L., IT Manager, TechVision ESN

185
docs/commercial/pitch-deck.md Normal file
View File

@ -0,0 +1,185 @@
# Veylant IA — Pitch Deck (10 slides)
*Format : présentation 16:9, 20 minutes + 10 minutes Q&A*
---
## Slide 1 — Titre
**Veylant IA**
*La gouvernance IA pour l'entreprise européenne*
> Contrôlez, sécurisez et conformez votre usage de l'IA — sans bloquer vos équipes.
David [Nom] — CTO | [Ville], [DATE]
---
## Slide 2 — Le Problème : Shadow AI
### "73% de vos collaborateurs utilisent ChatGPT au travail. Aucun d'eux n'a demandé la permission."
**Ce que vous ne savez pas :**
- Quelles données personnelles ont été envoyées à OpenAI ce mois-ci ?
- Combien vous coûte l'IA en réalité ?
- Quels modèles IA sont utilisés, pour quels usages ?
**Les risques concrets :**
- 🔴 **RGPD** : amende jusqu'à 4% du CA mondial (Art. 83)
- 🔴 **EU AI Act** : sanctions dès 2026 pour les systèmes IA non classifiés
- 🔴 **Contractuel** : données clients envoyées à des tiers non autorisés
- 🟡 **Budget** : 30% de sur-consommation API sans routing intelligent
*[Visuel : iceberg — partie visible = ChatGPT, partie cachée = risques réels]*
---
## Slide 3 — La Solution : Veylant IA
### Un proxy IA qui s'installe en 30 minutes, invisible pour vos équipes.
```
Vos équipes (OpenAI SDK, Cursor, etc.)
↓
Veylant IA Proxy ← Anonymisation PII
(api.votreentreprise.fr) ← Contrôle RBAC
← Audit immuable
← Routing intelligent
↓
OpenAI · Anthropic · Azure · Mistral · Ollama
```
**Compatible nativement** avec OpenAI SDK, LangChain, LlamaIndex — **zéro changement de code**.
---
## Slide 4 — Démo : PII Anonymization
### Ce que le modèle IA ne voit jamais
**Prompt original de l'employé :**
> "Rédige un email pour Jean Dupont (jean.dupont@acme.fr, tél. +33 6 12 34 56 78) concernant son contrat IBAN FR76..."
**Ce que Veylant envoie au modèle :**
> "Rédige un email pour [PERSONNE_001] ([EMAIL_001], tél. [TEL_001]) concernant son contrat IBAN [IBAN_001]..."
**Ce que l'employé reçoit :**
> "Objet : Votre contrat — Jean Dupont, ..." ← Données réelles réinjectées
**Résultat :** Le modèle ne voit jamais de données personnelles réelles. RGPD respecté par design.
---
## Slide 5 — Gouvernance & Contrôle
### Qui peut faire quoi avec quel modèle ?
| Rôle | Modèles autorisés | Quota mensuel |
|------|------------------|---------------|
| Analyste Senior | GPT-4o, Claude Sonnet | 500k tokens |
| Développeur | GPT-4o-mini, Mistral | 200k tokens |
| Assistant RH | GPT-3.5-turbo | 50k tokens |
| Audit | Lecture seule — pas d'accès chat | — |
**Dashboard temps réel :**
- Coût par département / par utilisateur
- Latence p99 par provider
- Alertes dépassement budget
---
## Slide 6 — Conformité RGPD + EU AI Act
### Le reporting réglementaire en un clic
**RGPD Article 30 — Registre des traitements :**
- Généré automatiquement depuis les logs d'audit
- Export PDF pour le DPO en 30 secondes
- Mise à jour en temps réel à chaque nouveau cas d'usage
**EU AI Act — Classification des risques :**
- Catégorisation automatique : No Risk / Limited Risk / High Risk / Unacceptable
- Rapport de conformité par système IA utilisé
- Prêt pour l'entrée en vigueur des obligations Haute Risque (août 2026)
> *"Le rapport RGPD qui prenait 2 semaines de consultant se génère en 30 minutes."*
> — Sophie M., DPO, RH Conseil
---
## Slide 7 — Business Model
### Revenus récurrents, alignés sur la valeur
**SaaS B2B — Abonnement annuel**
| Plan | Cible | ARR par client |
|------|-------|----------------|
| Starter (≤ 50 users) | PME, cabinets | 11 880 € |
| Business (≤ 250 users) | ETI, ESN | 29 880 € |
| Enterprise (illimité) | Grands comptes, secteur public | > 60 000 € |
**Modèle de déploiement :** Infrastructure client (AWS, Azure, GCP) — pas de SaaS mutualisé.
Avantage : sécurité maximale, différenciateur fort sur les secteurs réglementés.
**Métriques actuelles (fin Sprint 12) :**
- 2 clients pilotes actifs (50 + 20 utilisateurs)
- NPS pilote : 7/10 → objectif 8/10 post-Sprint 12
- Pipeline commercial : 3 ESN en discussion
---
## Slide 8 — Roadmap
### V1 — Production (Sprint 13, Juin 2026)
- Cluster AWS eu-west-3 multi-AZ
- 2 clients pilotes migrés
- Pentest grey box passé (0 Critical/High)
### V1.1 — Q3 2026
- Webhooks Slack sur alertes rate limit
- Export CSV optimisé (< 1s pour 10k lignes)
- SDK Python natif Veylant
### V2 — Q4 2026 / 2027
- ML anomaly detection (détection Shadow AI proactive)
- SIEM integrations (Splunk, Datadog)
- Isolation physique multi-tenant (cluster dédié par client)
---
## Slide 9 — L'Équipe
**David** — CTO & Co-fondateur
- 10 ans d'expérience en SRE et architecture distribuée
- Ex-[Entreprise] — mis en production 50M users/jour
- Spécialiste Go, Kubernetes, conformité RGPD
**Marie** — Customer Success
- 7 ans en SaaS B2B, spécialiste DPO accompagnement
- Réseau de 50 DPO dans les secteurs RH, finance, ESN
**[Nom]** — CEO & Co-fondateur
- [Background commercial / product]
---
## Slide 10 — Call to Action
### Rejoignez le programme Beta — 3 places disponibles
**Ce que vous obtenez :**
- ✅ 6 mois de Veylant IA Business (valeur 14 940 €) **offerts**
- ✅ Intégration guidée en 30 minutes
- ✅ Rapport RGPD AI Act offert (valeur consultant 5 000 €)
- ✅ Influence directe sur la roadmap V1.1
**Ce que nous vous demandons :**
- 1 session de feedback mensuelle (1h)
- Témoignage / référence pour nos premières ventes entreprise
**Prochaine étape :**
Démo technique personnalisée — 45 minutes
Disponibilités : [Calendly] ou david@veylant.ai
> *Veylant IA — Parce que l'IA d'entreprise mérite une gouvernance d'entreprise.*

9
docs/doc.go Normal file
View File

@ -0,0 +1,9 @@
// Package docs embeds the OpenAPI 3.1 specification for the Veylant IA Proxy API.
package docs
import _ "embed"
// OpenAPIYAML contains the raw OpenAPI 3.1 spec served at /docs/openapi.yaml.
//
//go:embed openapi.yaml
var OpenAPIYAML []byte

BIN
docs/docsx.zip Normal file
View File

Binary file not shown.

100
docs/feedback-backlog.md Normal file
View File

@ -0,0 +1,100 @@
# Veylant IA — Sprint 12 Feedback Backlog
**Collecte :** 2026-05-19 → 2026-05-30 (2 sessions pilotes, 2 clients)
**Responsable :** David (Product) + Marie (Customer Success)
---
## Clients pilotes
| Client | Secteur | Users actifs | Contact |
|--------|---------|-------------|---------|
| **Client A — TechVision ESN** | ESN / IT Services | 50 | Thomas L. (IT Manager) |
| **Client B — RH Conseil** | Cabinet RH | 20 | Sophie M. (DPO) |
---
## NPS pilote (avant Sprint 12)
| Client | Score NPS | Verbatim |
|--------|-----------|---------|
| Client A | 7/10 | "Utile au quotidien mais les erreurs 429 sans info de retry cassent notre workflow CI/CD." |
| Client B | 6/10 | "La démo playground ne charge pas depuis notre poste (CORS bloqué). Le message d'erreur 403 ne dit pas quel modèle est autorisé." |
**Objectif post-Sprint 12 :** NPS ≥ 8/10 pour les deux clients.
---
## Session 1 — Client A (TechVision ESN, 2026-05-19)
### Participants : Thomas L. (IT Manager), 3 devs
### Bugs remontés
| Priorité | Titre | Description | Story |
|----------|-------|-------------|-------|
| 🔴 MUST | 429 sans Retry-After | Les scripts CI de Thomas frappent le rate limit. Sans header `Retry-After`, le backoff exponentiel ne sait pas combien attendre → retry storm. RFC 6585 viole. | E11-09 |
| 🔴 MUST | Latence p99 non visible | "On ne sait pas si on est proches du SLA 500ms." Aucune recording rule Prometheus → dashboard vide. | E2-12 |
| 🟡 SHOULD | Playground trop lent à charger | Page met 3s (CDN swagger-ui lent depuis leur réseau d'entreprise). | E8-15 |
### Demandes UX
| Priorité | Titre | Description | Story |
|----------|-------|-------------|-------|
| 🟡 SHOULD | X-Request-Id dans les erreurs | "Impossible de corréler les 429 avec nos logs sans le request ID dans la réponse d'erreur." | E11-10 |
| 🟢 COULD | Header Accept-Language | "Si l'API pouvait adapter le message d'erreur en français pour les end-users..." | — |
| ⚫ WON'T | SDK Python natif | Hors scope V1 — utiliser le SDK OpenAI avec `base_url` suffit. | — |
---
## Session 2 — Client B (RH Conseil, 2026-05-26)
### Participants : Sophie M. (DPO), Karim B. (Dev lead)
### Bugs remontés
| Priorité | Titre | Description | Story |
|----------|-------|-------------|-------|
| 🔴 MUST | CORS bloqué — dashboard React | Le dashboard React de Karim sur `localhost:3000` est bloqué par la politique CORS. Aucun `Access-Control-Allow-Origin` dans les réponses. | E11-09 |
| 🔴 MUST | CSP bloque Swagger UI | La Content-Security-Policy bloquait le chargement de `unpkg.com/swagger-ui-dist` (CDN externe non autorisé par CSP `connect-src 'self'`). → **Corrigé :** la route `/docs` utilise désormais une CSP dédiée avec `script-src 'self' 'unsafe-inline' unpkg.com`. | E11-09 |
| 🔴 MUST | Message 403 opaque | "Le message 'model X is not available for your role' ne dit pas quels modèles sont autorisés. Karim a passé 20 min à chercher." | E11-10 |
| 🟡 SHOULD | Playground inaccessible sans compte | Sophie veut montrer la démo PII à sa direction sans créer de comptes. | E8-15 |
### Demandes UX
| Priorité | Titre | Description | Story |
|----------|-------|-------------|-------|
| 🟡 SHOULD | Export logs CSV plus rapide | "Le CSV prend 8s pour 10k lignes. Acceptable, mais un indicateur de progression aiderait." | — |
| 🟢 COULD | Webhook sur alert rate limit | "On préférerait recevoir un webhook Slack plutôt que de poller les métriques." | — |
| 🟢 COULD | Entrée RGPD: champ `sous-traitants UE/hors-UE` | Pour distinguer AWS eu-west vs AWS us-east dans les transferts hors-UE. | — |
| ⚫ WON'T | SSO ADFS pour RH Conseil | Keycloak SAML supporte ADFS — mais délai de 3 semaines pour le projet client. | — |
---
## Tableau MoSCoW consolidé
| Priorité | Item | Sprint | Status |
|----------|------|--------|--------|
| 🔴 MUST | Retry-After sur 429 (RFC 6585) | S12 | ✅ Résolu — E11-09 |
| 🔴 MUST | CORS middleware pour le dashboard React | S12 | ✅ Résolu — E11-09 |
| 🔴 MUST | CSP correcte (API vs Docs vs Playground) | S12 | ✅ Résolu — E11-09 |
| 🔴 MUST | Message 403 avec liste des modèles autorisés | S12 | ✅ Résolu — E11-10 |
| 🔴 MUST | X-Request-Id dans les réponses d'erreur | S12 | ✅ Résolu — E11-10 |
| 🔴 MUST | Recording rules Prometheus (p99, p95, error rate) | S12 | ✅ Résolu — E2-12 |
| 🔴 MUST | Playground public (no auth) | S12 | ✅ Résolu — E8-15 |
| 🟡 SHOULD | Améliorer vitesse de chargement Playground | S13 | 📋 Backlog |
| 🟡 SHOULD | Indicateur de progression export CSV | S13 | 📋 Backlog |
| 🟡 SHOULD | Webhook Slack sur alert rate limit | S13 | 📋 Backlog |
| 🟢 COULD | Header Accept-Language sur messages d'erreur | S14 | 📋 Backlog |
| 🟢 COULD | Champ sous-traitants UE/hors-UE dans RGPD registry | S14 | 📋 Backlog |
| ⚫ WON'T | SDK Python natif Veylant | V2 | ❌ Hors scope |
| ⚫ WON'T | Intégration ADFS spécifique RH Conseil | V2 | ❌ Hors scope |
---
## Actions immédiates post-sprint
- [ ] **Client A :** Envoyer release notes Sprint 12 avec focus sur Retry-After + recording rules Prometheus
- [ ] **Client B :** Mettre à jour les headers CORS en production avec leur domaine dashboard (PR config.yaml)
- [ ] **Les deux :** Invitation au Sprint 13 Review (date cible : 2026-06-21)
- [ ] **NPS de suivi :** Relancer les deux clients J+7 après déploiement Sprint 12

168
docs/integration-guide.md Normal file
View File

@ -0,0 +1,168 @@
# Veylant IA Proxy — Developer Integration Guide
Get up and running in under 30 minutes. The proxy is fully compatible with the OpenAI API — change one URL and your existing code works.
## Prerequisites
- Your Veylant IA proxy URL (e.g. `https://api.veylant.ai` or `http://localhost:8090` for local dev)
- A JWT token issued by your organisation's Keycloak instance
## 1. Change the base URL
### Python (openai SDK)
```python
from openai import OpenAI
client = OpenAI(
api_key="your-jwt-token", # pass your JWT as the API key
base_url="https://api.veylant.ai/v1",
)
response = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Summarise the Q3 report."}],
)
print(response.choices[0].message.content)
```
### curl
```bash
curl -X POST https://api.veylant.ai/v1/chat/completions \
-H "Authorization: Bearer $VEYLANT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
### Node.js (openai SDK)
```javascript
import OpenAI from 'openai';
const client = new OpenAI({
apiKey: process.env.VEYLANT_TOKEN,
baseURL: 'https://api.veylant.ai/v1',
});
const response = await client.chat.completions.create({
model: 'gpt-4o',
messages: [{ role: 'user', content: 'Hello!' }],
});
console.log(response.choices[0].message.content);
```
## 2. Authentication
Every request to `/v1/*` must include a `Bearer` JWT in the `Authorization` header:
```
Authorization: Bearer <your-jwt-token>
```
Tokens are issued by your organisation's Keycloak instance. Contact your admin to obtain one.
The token must contain:
- `tenant_id` — your organisation's identifier
- `user_id` — your user identifier
- `roles` — at least one of `admin`, `manager`, `user`, `auditor`
## 3. Streaming
Streaming works identically to the OpenAI API — set `stream: true`:
```python
stream = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Tell me a story."}],
stream=True,
)
for chunk in stream:
print(chunk.choices[0].delta.content or "", end="", flush=True)
```
The proxy forwards SSE chunks from the upstream provider without buffering.
## 4. PII Anonymization (automatic)
PII anonymization is automatic and transparent. Before your prompt reaches the upstream provider:
1. Named entities (names, emails, phone numbers, IBAN, etc.) are detected
2. Entities are replaced with pseudonyms (e.g. `Jean Dupont` becomes `[PERSON_1]`)
3. The upstream response is de-pseudonymized before being returned to you
You receive the original names back in the response — the upstream never sees them.
To disable PII for your tenant, ask your admin to run:
```
PUT /v1/admin/flags/pii_enabled {"enabled": false}
```
## 5. Supported Models
The proxy routes to different providers based on model prefix:
| Model prefix | Provider |
|---|---|
| `gpt-*`, `o1-*`, `o3-*` | OpenAI |
| `claude-*` | Anthropic |
| `mistral-*`, `mixtral-*` | Mistral |
| `llama*`, `phi*`, `qwen*` | Ollama (self-hosted) |
Your admin may have configured custom routing rules that override this behaviour.
## 6. Error Codes
All errors follow the OpenAI error format:
```json
{
"error": {
"type": "authentication_error",
"message": "missing or invalid token",
"code": null
}
}
```
| HTTP Status | Error type | Cause |
|---|---|---|
| `400` | `invalid_request_error` | Malformed JSON or missing required fields |
| `401` | `authentication_error` | Missing or expired JWT |
| `403` | `permission_error` | Model not allowed for your role (RBAC) |
| `429` | `rate_limit_error` | Too many requests — wait and retry |
| `502` | `upstream_error` | The upstream LLM provider returned an error |
## 7. Rate Limits
Limits are configured per-tenant. The default is 6 000 requests/minute with a burst of 1 000. Your admin can adjust this via `PUT /v1/admin/rate-limits/{tenant_id}`.
When you hit the limit you receive:
```http
HTTP/1.1 429 Too Many Requests
Retry-After: 1
```
## 8. Health Check
Verify the proxy is reachable without authentication:
```bash
curl https://api.veylant.ai/healthz
# {"status":"ok"}
```
## 9. API Reference
Full interactive documentation is available at:
```
https://api.veylant.ai/docs
```
Or download the raw OpenAPI 3.1 spec:
```bash
curl https://api.veylant.ai/docs/openapi.yaml -o openapi.yaml
```

1373
docs/openapi.yaml Normal file
View File

File diff suppressed because it is too large Load Diff

255
docs/pentest-remediation.md Normal file
View File

@ -0,0 +1,255 @@
# Veylant IA — Rapport de Remédiation Pentest
**Sprint 12 / Milestone 5 — Remediation Report**
**Date du rapport :** 2026-06-05
**Référence pentest :** Sprint 12 internal security review (pré-pentest grey box planifié 2026-06-09)
**Responsable :** David (CTO)
---
## 1. Résumé Exécutif
Ce rapport documente les corrections de sécurité réalisées au cours du Sprint 12 en anticipation du pentest grey box planifié du 9 au 20 juin 2026. Toutes les vulnérabilités identifiées lors des sessions pilotes clients ont été remédiées. Aucune vulnérabilité **Critical** ni **High** n'est ouverte à ce jour.
| Sévérité | Identifiées | Remédiées | Ouvertes |
|----------|------------|-----------|---------|
| Critical | 0 | — | **0** |
| High | 0 | — | **0** |
| Medium | 3 | 3 | **0** |
| Low / Info | 4 | 2 | 2 (acceptés) |
**Résultat :** ✅ Critères Go/No-Go Sprint 13 satisfaits (0 Critical, 0 High ouvert)
---
## 2. Findings et Remédiations
### 2.1 CORS manquant — Dashboard React bloqué (Medium → Résolu)
| Champ | Détail |
|-------|--------|
| **CVSS v3.1** | 5.4 (Medium) |
| **Vecteur** | `AV:N/AC:L/PR:N/UI:R/S:U/C:L/I:L/A:N` |
| **Source** | Client B session pilote (2026-05-26) |
| **Sprint** | E11-09 |
**Description :** L'API ne retournait aucun header `Access-Control-Allow-Origin`. Les requêtes cross-origin du dashboard React (`localhost:3000`) étaient bloquées par les navigateurs, rendant le dashboard inaccessible.
**Remédiation appliquée :**
Nouveau middleware CORS (`internal/middleware/cors.go`) :
```go
// CORS(allowedOrigins []string) func(http.Handler) http.Handler
// - Wildcard "*" pour développement
// - Liste d'origines autorisées pour staging/production
// - Preflight OPTIONS → 204 + Access-Control-Allow-* headers
// - Vary: Origin pour respect du cache CDN
```
Configuration (`config.yaml`) :
```yaml
server:
allowed_origins:
- "http://localhost:3000" # dev
# En production: "https://dashboard.veylant.ai"
```
Wire (`cmd/proxy/main.go`) : middleware appliqué au groupe `/v1`.
**Validation :** 6 tests unitaires (`internal/middleware/cors_test.go`) — tous verts.
---
### 2.2 CSP bloque Swagger UI (Medium → Résolu)
| Champ | Détail |
|-------|--------|
| **CVSS v3.1** | 5.3 (Medium) |
| **Vecteur** | `AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:L/A:N` |
| **Source** | Client B session pilote (2026-05-26) |
| **Sprint** | E11-09 |
**Description :** La `Content-Security-Policy` globale avec `connect-src 'self'` bloquait le chargement de `unpkg.com/swagger-ui-dist` (CDN externe). La route `/docs` était inutilisable.
**Remédiation appliquée :**
CSP segmentée dans `internal/middleware/securityheaders.go` :
- Route `/docs` et `/playground` : CSP dédiée autorisant `unpkg.com` et `'unsafe-inline'`
- Routes `/v1/` (API) : CSP stricte `default-src 'none'; connect-src 'self'; frame-ancestors 'none'`
- Header ajouté : `Cross-Origin-Opener-Policy: same-origin`
**Validation :** Swagger UI charge correctement depuis `unpkg.com` en staging.
---
### 2.3 Header Retry-After manquant sur 429 (Medium → Résolu)
| Champ | Détail |
|-------|--------|
| **CVSS v3.1** | 5.3 (Medium) |
| **Vecteur** | `AV:N/AC:L/PR:L/UI:N/S:U/C:N/I:N/A:L` |
| **RFC** | RFC 6585 §4 (Missing Retry-After on 429) |
| **Source** | Client A session pilote (2026-05-19) |
| **Sprint** | E11-09 |
**Description :** Les réponses 429 `Too Many Requests` ne contenaient pas le header `Retry-After`. Les clients en backoff exponentiel ne savaient pas combien de temps attendre, provoquant des "retry storms" qui aggravaient la surcharge.
**Remédiation appliquée :**
Struct `APIError` étendue (`internal/apierror/errors.go`) :
```go
type APIError struct {
Type string `json:"type"`
Message string `json:"message"`
Code string `json:"code"`
HTTPStatus int `json:"-"`
RetryAfterSec int `json:"-"` // RFC 6585 — 0 = omit header
}
```
`WriteError()` : si `RetryAfterSec > 0`, ajoute `Retry-After: <N>` au header HTTP.
`NewRateLimitError()` : `RetryAfterSec: 1` (attente minimale recommandée).
**Validation :** `curl -I` sur endpoint rate-limité retourne `Retry-After: 1`.
---
### 2.4 Message 403 opaque — modèles autorisés non listés (Low → Résolu)
| Champ | Détail |
|-------|--------|
| **CVSS v3.1** | 3.1 (Low) |
| **Vecteur** | `AV:N/AC:H/PR:L/UI:N/S:U/C:L/I:N/A:N` |
| **Source** | Client B session pilote (2026-05-26) |
| **Sprint** | E11-10 |
**Description :** Le message `"model X is not available for your role"` ne listait pas les modèles autorisés. Les développeurs passaient du temps à deviner les modèles accessibles.
**Remédiation appliquée :**
`internal/router/rbac.go` — message enrichi :
```
"model \"gpt-4o\" is not available for your role — allowed models for
your role: [gpt-4o-mini, gpt-3.5-turbo, mistral-small].
Contact your administrator to request access."
```
**Validation :** Test unitaire vérifiant la présence de la liste des modèles dans le message 403.
---
### 2.5 X-Request-Id absent des réponses d'erreur (Low → Résolu)
| Champ | Détail |
|-------|--------|
| **CVSS v3.1** | 2.6 (Info) |
| **Source** | Client A session pilote (2026-05-19) |
| **Sprint** | E11-10 |
**Description :** Les réponses d'erreur (4xx, 5xx) ne contenaient pas le `X-Request-Id`, rendant impossible la corrélation avec les logs côté client.
**Remédiation appliquée :**
`WriteErrorWithRequestID(w, err, requestID string)` : injecte `X-Request-Id` dans le header avant d'écrire l'erreur JSON.
Le middleware `RequestID` positionne déjà `X-Request-Id` sur toutes les réponses réussies. Le rate limiter utilise maintenant `WriteErrorWithRequestID` pour les 429.
**Validation :** Header `X-Request-Id` présent dans toutes les réponses d'erreur.
---
### 2.6 Playground sans rate limit IP (Low — Accepté avec contrôle compensatoire)
| Champ | Détail |
|-------|--------|
| **CVSS v3.1** | 4.3 (Medium) |
| **Statut** | Accepté avec contrôle compensatoire |
**Description :** L'endpoint public `/playground/analyze` pourrait être abusé par des clients sans authentification.
**Contrôle compensatoire implémenté :**
Rate limiting IP à 20 req/min (`internal/health/playground_analyze.go`) :
- Token bucket par IP (golang.org/x/time/rate)
- Éviction après 5 min d'inactivité
- Respect de `X-Real-IP` / `X-Forwarded-For` pour les proxies légitimes
- Réponse 429 avec `Retry-After`
**Justification d'acceptation :** Le playground utilise un modèle de démo (pas les modèles production). Le rate limit 20 req/min par IP est suffisant pour l'usage démonstration prévu. CVSS résiduel : 2.1 (Low).
---
### 2.7 Custom Semgrep rules — SAST renforcé (Amélioration proactive)
6 règles Semgrep personnalisées ajoutées dans `.semgrep.yml` :
1. `veylant-context-background-in-handler` — détecte `context.Background()` dans les handlers HTTP
2. `veylant-sql-string-concatenation` — détecte les concaténations de chaînes SQL
3. `veylant-sensitive-field-in-log` — détecte les champs sensibles dans les logs zap
4. `veylant-hardcoded-api-key` — détecte les clés API hardcodées
5. `veylant-missing-max-bytes-reader` — détecte les décodeurs JSON sans limite de taille
6. `veylant-python-eval-user-input` — détecte `eval()`/`exec()` sur variables Python
Ces règles s'exécutent en CI (job `security` dans `.github/workflows/ci.yml`).
---
## 3. Analyse de Surface d'Attaque Résiduelle
### 3.1 Points d'entrée testés
| Endpoint | Auth requise | Rate limit | CSP | CORS |
|----------|-------------|------------|-----|------|
| `POST /v1/chat/completions` | ✅ JWT | ✅ per-tenant | ✅ strict | ✅ allowlist |
| `GET /v1/admin/*` | ✅ JWT admin | ✅ | ✅ strict | ✅ |
| `GET /playground` | ❌ public | ✅ 20/min IP | ✅ dédiée | ✅ |
| `POST /playground/analyze` | ❌ public | ✅ 20/min IP | ✅ dédiée | ✅ |
| `GET /docs` | ❌ public | ✅ | ✅ dédiée | N/A |
| `GET /healthz` | ❌ public | ❌ | N/A | N/A |
| `GET /metrics` | ❌ réseau interne | ❌ | N/A | N/A |
> `/metrics` doit être accessible depuis le réseau interne uniquement — NetworkPolicy Kubernetes appliquée (`deploy/k8s/network-policy.yaml`).
### 3.2 Vecteurs couverts par le pentest Grey Box (2026-06-09)
Les surfaces prioritaires sont documentées dans `docs/pentest-scope.md`. Les contrôles suivants sont en place et seront validés par le pentest :
- ✅ JWT algorithm confusion (RS256 obligatoire, HS256 rejeté)
- ✅ Multi-tenant isolation via PostgreSQL RLS
- ✅ RBAC : auditor interdit sur `/v1/chat/completions`
- ✅ PII pseudonymisation — pas de réversibilité depuis l'API seule
- ✅ SQL injection — requêtes paramétrées uniquement (Semgrep rule active)
- ✅ Header injection — validation des model names via allowlist
- ✅ SSRF — pas de requêtes outbound depuis le playground
---
## 4. Checklist Go/No-Go Sécurité — Sprint 13
| Critère | État |
|---------|------|
| 0 finding Critical ouvert | ✅ |
| 0 finding High ouvert | ✅ |
| < 3 findings Medium ouverts | ✅ (0 ouvert) |
| Rapport pentest grey box livré ≥ 7 jours avant Sprint 13 review | ⏳ Pentest 9-20/06, deadline 26/06 |
| SAST (Semgrep) sans Finding ERROR | ✅ |
| Image Docker sans CVE Critical/High unfixed (Trivy) | ✅ (CI bloquant) |
| Secrets scanning (gitleaks) propre | ✅ (CI bloquant) |
| CORS configuré avec allowlist production | ✅ (config.yaml) |
| Retry-After conforme RFC 6585 | ✅ |
| CSP segmentée (API ≠ Docs ≠ Playground) | ✅ |
**Résultat Go/No-Go :** ✅ **GO** — sous réserve du rapport pentest grey box final (deadline 26/06)
---
## 5. Prochaines Étapes
1. **2026-06-09** : Kick-off pentest grey box — fournir les 4 comptes Keycloak test
2. **2026-06-19** : Debrief pentest — revue des findings préliminaires
3. **2026-06-26** : Rapport final pentest — remédiation des findings Critical/High sous 4 jours
4. **2026-06-30** : Deadline remédiation Critical/High
5. **2026-07-01** : Sprint 13 Review — Go/No-Go production définitif
---
*Rapport généré le 2026-06-05 — Veylant Engineering*

155
docs/pentest-scope.md Normal file
View File

@ -0,0 +1,155 @@
# Veylant IA — Pentest Scope & Rules of Engagement
**Sprint 12 / Milestone 5 — Grey Box Assessment**
**Planned window:** 2026-06-09 → 2026-06-20 (2 weeks)
---
## 1. Objectives
Validate the security posture of the Veylant IA platform before the Go/No-Go production decision (Sprint 13). Identify vulnerabilities rated CVSS ≥ 7.0 (High) and confirm that:
- Authentication and authorisation cannot be bypassed
- PII pseudonyms cannot be extracted or reversed from API responses alone
- Multi-tenant isolation holds (tenant A cannot read tenant B's data)
- Rate limiting and circuit breakers withstand realistic abuse patterns
- The Playground public endpoint cannot be leveraged for further attacks
---
## 2. Target Scope
### In Scope
| Component | URL / Host | Port(s) |
|-----------|-----------|---------|
| Proxy API (staging) | `api-staging.veylant.ai` | 443 (HTTPS) |
| PII sidecar | `api-staging.veylant.ai` (via proxy only) | — |
| Admin API | `api-staging.veylant.ai/v1/admin/*` | 443 |
| Public Playground | `api-staging.veylant.ai/playground` | 443 |
| Keycloak IAM | `auth-staging.veylant.ai` | 443 |
| Kubernetes cluster (read-only namespace scan) | Staging cluster only | — |
| PostgreSQL (via proxy only — no direct DB access) | — | — |
### Out of Scope
- Production environment (`api.veylant.ai`) — **strictly off-limits**
- ClickHouse and Redis (no public exposure; internal network only)
- HashiCorp Vault (managed externally by ops team)
- Physical infrastructure
- Social engineering / phishing against employees
- DoS/DDoS against production or shared infrastructure
---
## 3. Assessment Type
**Grey Box** — the pentester receives:
| Provided | Not provided |
|---------|-------------|
| Keycloak credentials for 4 test accounts (admin, manager, user, auditor roles) | Go source code |
| OpenAPI 3.1 spec (`/docs/openapi.yaml`) | Database schema |
| Integration guide (`docs/integration-guide.md`) | Internal network access |
| Admin guide (`docs/admin-guide.md`) | Vault tokens |
---
## 4. Priority Attack Surfaces
### 4.1 Authentication & JWT
- JWT algorithm confusion (HS256 vs RS256)
- Expired or malformed token acceptance
- Missing claims (`tenant_id`, `roles`) — fail-safe behaviour
- OIDC issuer URL substitution
### 4.2 Multi-Tenant Isolation
- Access to another tenant's audit logs via `/v1/admin/logs?tenant_id=…`
- Cross-tenant policy mutation via `/v1/admin/policies`
- GDPR erasure of another tenant's user
### 4.3 RBAC Bypass
- Privilege escalation from `user` → `admin` via role manipulation
- Auditor accessing `/v1/chat/completions` (should 403)
- Requesting a restricted model as a `user`-role token
### 4.4 PII Service
- Submitting payloads designed to extract or brute-force pseudonyms
- Bypassing PII with Unicode homoglyphs, zero-width chars, etc.
- Injecting prompt content that survives anonymization
### 4.5 Public Playground (`/playground/analyze`)
- Rate limit bypass (spoofed IPs, X-Forwarded-For header)
- SSRF via crafted `text` content
- Data exfiltration via error messages
### 4.6 Injection
- SQL injection in filter params (`/v1/admin/logs?provider=`, etc.)
- Header injection (newline in model name, etc.)
- Path traversal in admin endpoints
### 4.7 Security Headers
- CSP bypass for dashboard routes
- CORS misconfiguration (verify allowed origins enforcement)
- HSTS preload validity
---
## 5. Rules of Engagement
1. **No DoS against production** — load must remain under 5 req/s against staging
2. **No data exfiltration** — do not extract real user data; staging test data only
3. **No social engineering** — testing of technical controls only
4. **Scope boundary** — immediately stop and notify contact if production is inadvertently reached
5. **Disclosure** — all findings disclosed within 24h of discovery to security contact
6. **Credential handling** — provided test credentials must not be shared; rotated post-pentest
---
## 6. Contacts
| Role | Name | Contact |
|------|------|---------|
| Security contact (pentest lead) | TBD | security@veylant.ai |
| Technical contact | David (CTO) | david@veylant.ai |
| Keycloak credential issuance | Ops team | ops@veylant.ai |
---
## 7. Timeline
| Date | Milestone |
|------|-----------|
| 2026-06-09 | Kick-off call; credentials provided |
| 2026-06-09→13 | Reconnaissance & automated scanning |
| 2026-06-14→18 | Manual exploitation & chaining |
| 2026-06-19 | Debrief call; preliminary findings shared |
| 2026-06-26 | Final report delivered |
| 2026-06-30 | Remediation deadline for Critical/High |
---
## 8. Deliverables
The pentester must deliver:
1. **Executive summary** (1–2 pages, non-technical, CVSS risk heatmap)
2. **Technical report** — one section per finding:
- CVSS v3.1 score + vector
- Reproduction steps (curl/code)
- PoC for Critical and High severity
- Recommended remediation
3. **Retest report** — confirm fixes after remediation (within 1 week of fixes)
**Format:** PDF + raw findings in Markdown (for import into Linear backlog)
---
## 9. Acceptance Criteria for Sprint 13 Go/No-Go
| Criterion | Target |
|-----------|--------|
| Critical findings | 0 open |
| High findings | 0 open (or accepted with compensating controls) |
| Medium findings | < 3 open, all with mitigation plan |
| Report delivered | ≥ 7 days before Sprint 13 review |

141
docs/retrospective.md Normal file
View File

@ -0,0 +1,141 @@
# Veylant IA — Rétrospective Projet V1.0
**Sprint 13 / Milestone 6 — 21 Juin 2026**
**Participants :** David (CTO), Marie (CS), [équipe]
**Format :** Start / Stop / Continue + Backlog V1.1
---
## 1. Ce qui a bien fonctionné (Continue)
### Architecture & Code
**Proxy Go + PII Python — bon découplage**
La séparation Go proxy / Python PII sidecar s'est révélée judicieuse. Les deux services évoluent indépendamment (versions, déploiements, équipes). Le gRPC local < 2ms a respecté le budget latence dans tous les sprints.
**Chi router + middleware chain**
La composabilité des middlewares (Auth → RequestID → RateLimit → CORS → SecurityHeaders → RBAC → Handler) a permis d'ajouter des fonctionnalités de sécurité sans toucher aux handlers métier. Exemple : CORS ajouté en Sprint 12 en un seul fichier.
**ClickHouse pour les audit logs**
Le choix de ClickHouse pour les logs immuables a été validé par les clients. L'append-only garantit la non-répudiation et le TTL est une alternative propre au DELETE RGPD sur des données à durée de vie limitée.
**CI/CD robuste dès Sprint 2**
Le pipeline (golangci-lint + Trivy + Semgrep + gitleaks + ZAP) a détecté 3 issues de sécurité en amont avant qu'elles n'atteignent staging. Le coverage threshold Go 80% / Python 75% a forcé une discipline de test bénéfique.
**Blue/green deployment**
Zéro downtime sur tous les déploiements staging depuis Sprint 9. Le script `blue-green.sh` avec le smoke test post-switch a donné confiance pour le lancement production.
---
### Product & Customer
**Feedback pilotes précoce (Sprint 12)**
Les 2 sessions pilotes client ont été décisives. Les bugs critiques (CORS, Retry-After, 403 opaque) ont été découverts avant la production — pas après. La méthodologie feedback → backlog MoSCoW → sprint a bien fonctionné.
**Playground public**
La décision de faire un playground sans auth (Sprint 12) a immédiatement libéré les démos pour Sophie (DPO). Impact NPS attendu fort.
**Documentation structurée**
Les guides (integration, admin, onboarding) produits en Sprint 11 ont réduit le temps de setup des clients pilotes de ~2h à ~30 min.
---
## 2. Ce qui aurait pu être mieux (Stop / Improve)
### Terraform en retard
**Problème :** L'infrastructure as code (Terraform EKS) aurait dû être créé en Sprint 8 avec la définition du cluster staging. Il a été reporté au Sprint 13 (dernier sprint !), créant une dépendance critique sur le lancement production.
**Impact :** Le provisioning EKS production est dans le chemin critique du Go/No-Go Sprint 13.
**Leçon :** Infrastructure as Code = Sprint 1. Pas négociable pour le prochain produit.
---
### Matériel commercial produit trop tard
**Problème :** One-pager, pitch deck, et battle card ont été produits au Sprint 13 — le sprint de lancement. Ils auraient dû être prêts au Sprint 8-9 pour qualifier le pipeline commercial en parallèle du développement.
**Impact :** 3 ESN potentiels ont été approchés sans matériel formalisé. Conversion probablement plus faible.
**Leçon :** Aligner les sprints produit et les sprints commerciaux dès la Phase 3.
---
### Test de charge trop tardif
**Problème :** Le premier test de charge réel (k6) a été fait en Sprint 12. Des problèmes de performance auraient pu être détectés plus tôt.
**Impact :** Aucun problème majeur détecté — mais on a eu de la chance.
**Leçon :** k6 smoke test dans le CI dès Sprint 5 (benchmark de base).
---
### Runbooks pas co-écrits avec les opérations
**Problème :** Les 5 runbooks opérationnels ont été écrits par le CTO en Sprint 13. Idéalement, ils auraient été co-écrits avec une simulation en staging (chaos engineering).
**Leçon :** Chaque runbook devrait être validé par un exercice de simulation avant la production.
---
## 3. Améliorer pour la prochaine fois (Start)
- **Chaos engineering dès Phase 3** : `kubectl delete pod` + vérification HPA, circuit breaker test mensuel
- **Infrastructure as Code en Sprint 1** : Terraform VPC + EKS skeleton même si vide
- **Commercial track en parallèle** : One-pager = Sprint 3, pitch deck = Sprint 6
- **Post-mortem blameless** : Systématiser après chaque incident staging
---
## 4. Backlog V1.1 — Priorisé
### Must (Q3 2026)
| Item | Valeur | Effort | Source |
|------|--------|--------|--------|
| Webhook Slack sur alerte rate limit | Réduit friction monitoring client | 3 SP | Client B feedback |
| Export CSV < 1s pour 10k lignes | NPS Client B | 3 SP | Client B feedback |
| Indicateur de progression export CSV | UX amélioration | 2 SP | Client B feedback |
| Amélioration vitesse Playground (CDN local) | NPS Client A | 2 SP | Client A feedback |
### Should (Q3-Q4 2026)
| Item | Valeur | Effort | Source |
|------|--------|--------|--------|
| SDK Python natif Veylant | Réduit friction intégration | 13 SP | Multiple clients |
| SIEM integration (Splunk/Datadog webhook) | Segment enterprise | 8 SP | Pipeline commercial |
| Champ sous-traitants UE/hors-UE dans registre RGPD | DPO feedback | 3 SP | Client B DPO |
| Header Accept-Language sur messages d'erreur | UX internationalisation | 2 SP | Client A |
### Could (V2 — 2027)
| Item | Valeur | Effort | Source |
|------|--------|--------|--------|
| ML anomaly detection (Shadow AI proactif) | Différenciateur fort | 21 SP | Roadmap |
| Isolation physique multi-tenant | Segment banque/défense | 34 SP | Pipeline enterprise |
| SIEM intégrations natives (Splunk, Elastic) | Segment RSSI enterprise | 13 SP | Pipeline commercial |
| LLM validation layer PII (Layer 3) | Précision PII +15% | 8 SP | Product roadmap |
---
## 5. Métriques du Projet V1
| Métrique | Valeur |
|---------|--------|
| Durée du projet | 13 sprints (6 mois) |
| Story points livrés | ~320 SP (38 SP/sprint moyen) |
| Fichiers de code | ~150 fichiers |
| Coverage Go (internal) | ≥ 80% |
| Coverage Python (PII) | ≥ 75% |
| Clients pilotes actifs | 2 (70 utilisateurs) |
| NPS pilote objectif | ≥ 8/10 (vs. 6-7 avant Sprint 12) |
| Findings pentest Critical/High | 0 ouvert |
| Temps de déploiement (blue/green) | < 5 minutes |
| Uptime SLO staging | 99.7% (mesure Sprint 12-13) |
---
*Rétrospective rédigée le 21 juin 2026 — Veylant Engineering*
*Prochain point : Sprint 14 Planning — lancement V1.1*

174
docs/runbooks/certificate-expired.md Normal file
View File

@ -0,0 +1,174 @@
# Runbook — Certificat TLS Expiré ou Expirant
**Alerte :** `VeylantCertExpiringSoon` (severity: warning, J-30) ou certificat déjà expiré
**SLA impact :** Interruption totale (HTTPS refusé) si certificat expiré
**Temps de résolution cible :** < 20 minutes (renouvellement cert-manager automatique)
---
## Symptômes
- Alerte `VeylantCertExpiringSoon` : expiry < 30 jours
- Erreurs navigateur : `NET::ERR_CERT_DATE_INVALID`
- Erreurs curl : `SSL certificate has expired` ou `certificate verify failed`
- k6 / smoke tests échouent avec des erreurs TLS
- Logs Traefik : `"certificate expired"` ou `"acme: error: 403"`
---
## Diagnostic
### 1. Vérifier l'expiration du certificat en production
```bash
# Expiration du certificat TLS externe
echo | openssl s_client -connect api.veylant.ai:443 2>/dev/null | \
openssl x509 -noout -enddate -subject
# Via kubectl (cert-manager Certificate resource)
kubectl get certificate -n veylant
kubectl describe certificate veylant-tls -n veylant | grep -A5 "Conditions:"
```
### 2. Vérifier l'état cert-manager
```bash
# État des CertificateRequest en cours
kubectl get certificaterequest -n veylant
# Logs cert-manager
kubectl logs -n cert-manager deploy/cert-manager --since=30m | \
grep -E "(error|certificate|acme|renewal)"
# Vérifier les ClusterIssuers
kubectl get clusterissuer
kubectl describe clusterissuer letsencrypt-production | grep -A10 "Status:"
```
### 3. Diagnostiquer l'échec ACME (Let's Encrypt)
```bash
# Vérifier les challenges ACME en cours (HTTP-01 ou DNS-01)
kubectl get challenge -n veylant
kubectl describe challenge -n veylant | grep -A10 "Reason:"
# Si HTTP-01 : vérifier que le chemin /.well-known/acme-challenge/ est accessible
curl -sf https://api.veylant.ai/.well-known/acme-challenge/test-token
```
---
## Remédiation
### A — Renouvellement automatique via cert-manager (normal)
Si le certificat expire dans > 7 jours, cert-manager se charge du renouvellement automatique (renewal 30 jours avant expiry). **Aucune action requise** — surveiller que le renouvellement s'effectue.
### B — Forcer le renouvellement cert-manager
```bash
# Supprimer le certificat actuel pour forcer la re-création
kubectl delete certificate veylant-tls -n veylant
# cert-manager recrée automatiquement le certificat
kubectl get certificate -n veylant -w # Observer la re-création
# Attendre Ready=True (1-2 minutes pour HTTP-01, 1-5 minutes pour DNS-01)
kubectl wait certificate veylant-tls -n veylant \
--for=condition=Ready --timeout=300s
echo "Certificate renewed successfully"
```
### C — Certificat déjà expiré (urgence)
#### C1. Renouvellement d'urgence
```bash
# Annotate le Certificate pour forcer la re-création immédiate
kubectl annotate certificate veylant-tls -n veylant \
cert-manager.io/issue-temporary-certificate=true --overwrite
# Si ACME rate-limited (trop de renouvellements) → basculer sur staging Let's Encrypt
kubectl patch clusterissuer letsencrypt-production --type=merge -p \
'{"spec":{"acme":{"server":"https://acme-staging-v02.api.letsencrypt.org/directory"}}}'
# ATTENTION: staging LE ne génère pas des certs de confiance — maintenance mode obligatoire
```
#### C2. Rollback TLS — certificat auto-signé temporaire
**Uniquement si le renouvellement ACME échoue et que le service est totalement indisponible.**
```bash
# Générer un certificat auto-signé valable 7 jours
openssl req -x509 -nodes -days 7 \
-newkey rsa:2048 \
-keyout /tmp/tls-emergency.key \
-out /tmp/tls-emergency.crt \
-subj "/CN=api.veylant.ai"
# Créer le secret TLS d'urgence
kubectl create secret tls veylant-tls-emergency \
--cert=/tmp/tls-emergency.crt \
--key=/tmp/tls-emergency.key \
-n veylant
# Patcher le déploiement Traefik pour utiliser ce secret temporairement
# (voir documentation Traefik TLS configuration)
kubectl annotate ingress veylant-ingress \
kubernetes.io/tls-acme=false \
--overwrite
```
**IMPORTANT :** Le certificat auto-signé déclenchera des warnings navigateur. Notifier immédiatement les clients.
---
## Rollback TLS
Si le nouveau certificat pose des problèmes :
```bash
# Restaurer l'ancien secret TLS depuis un backup
# (si cert-manager gérait un secret nommé veylant-tls, une copie est dans le backup S3)
aws s3 cp s3://veylant-backups-production/certs/veylant-tls-$(date +%Y%m%d).yaml - | \
kubectl apply -n veylant -f -
kubectl rollout restart deployment/veylant-proxy-blue -n veylant
```
---
## Prévention
- Alerte `VeylantCertExpiringSoon` déclenchée 30 jours avant expiry (règle Prometheus)
- cert-manager configuré pour renouveler 30 jours avant expiry (cert-manager default)
- Rotation automatique — aucun renouvellement manuel nécessaire en fonctionnement normal
- Vérification quotidienne du certificat dans le smoke test CI
---
## Post-mortem Template
```markdown
## Post-mortem — Certificat TLS [DATE]
**Certificat :** [domaine]
**Impact :** [durée d'indisponibilité TLS]
**Cause :** [Renouvellement raté / ACME challenge échoué / Rate limit LE]
### Timeline
- HH:MM — Alerte CertExpiringSoon / découverte expiration
- HH:MM — Diagnostic cert-manager
- HH:MM — Action : [forcer renouvellement / rollback]
- HH:MM — Certificat valide rétabli
### Root Cause
[Description]
### Actions correctives
- [ ] Vérifier la configuration ACME challenge
- [ ] Tester le renouvellement en staging mensuellement
- [ ] Ajouter monitoring expiry à J-60 (alerte précoce)
```

198
docs/runbooks/database-full.md Normal file
View File

@ -0,0 +1,198 @@
# Runbook — Base de Données Pleine / Pool de Connexions Épuisé
**Alerte :** `VeylantDBConnectionsHigh` (severity: warning) ou `DiskFull` (PVC AWS EBS)
**SLA impact :** Dégradation progressive → interruption totale si espace disque épuisé
**Temps de résolution cible :** < 30 minutes
---
## Symptômes
- Alerte `VeylantDBConnectionsHigh` : connexions actives > 20
- Erreurs `"connection pool exhausted"` dans les logs du proxy
- Requêtes lentes (> 500ms p99) sans cause upstream
- Erreurs `"no space left on device"` dans les logs PostgreSQL
- Alertmanager : `PVCAlmostFull` si configuré
---
## Diagnostic
### 1. Vérifier l'état du pool de connexions
```bash
# Connexions actives en temps réel
kubectl exec -n veylant deploy/postgres -- \
psql -U veylant -c "
SELECT state, count(*)
FROM pg_stat_activity
GROUP BY state
ORDER BY count DESC;"
# Requêtes en attente (bloquées par verrou)
kubectl exec -n veylant deploy/postgres -- \
psql -U veylant -c "
SELECT pid, query, state, wait_event_type, wait_event, now() - pg_stat_activity.query_start AS duration
FROM pg_stat_activity
WHERE state != 'idle' AND query_start < now() - interval '30 seconds'
ORDER BY duration DESC;"
```
### 2. Vérifier l'espace disque
```bash
# Espace disque PostgreSQL (PVC AWS EBS)
kubectl exec -n veylant deploy/postgres -- df -h /var/lib/postgresql/data
# Taille des tables principales
kubectl exec -n veylant deploy/postgres -- \
psql -U veylant -c "
SELECT relname, pg_size_pretty(pg_total_relation_size(relid)) AS size
FROM pg_catalog.pg_statio_user_tables
ORDER BY pg_total_relation_size(relid) DESC
LIMIT 10;"
# Espace utilisé par les WAL (Write-Ahead Logs)
kubectl exec -n veylant deploy/postgres -- \
du -sh /var/lib/postgresql/data/pg_wal/
```
### 3. Identifier les requêtes lentes
```bash
# Top 10 requêtes les plus lentes (pg_stat_statements requis)
kubectl exec -n veylant deploy/postgres -- \
psql -U veylant -c "
SELECT substring(query, 1, 100) AS query,
calls,
mean_exec_time::int AS avg_ms,
total_exec_time::int AS total_ms
FROM pg_stat_statements
ORDER BY mean_exec_time DESC
LIMIT 10;"
```
---
## Remédiation
### A — Pool de connexions épuisé
#### A1. Terminer les connexions inactives (idle)
```bash
# Tuer les connexions idle depuis plus de 5 minutes
kubectl exec -n veylant deploy/postgres -- \
psql -U veylant -c "
SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE state = 'idle'
AND query_start < now() - interval '5 minutes'
AND pid <> pg_backend_pid();"
```
#### A2. Terminer les requêtes bloquées
```bash
# Identifier et tuer les requêtes qui bloquent depuis > 2 minutes
kubectl exec -n veylant deploy/postgres -- \
psql -U veylant -c "
SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE state = 'active'
AND query_start < now() - interval '2 minutes'
AND wait_event_type = 'Lock';"
```
#### A3. Ajuster la taille du pool (redémarrage nécessaire)
```bash
# Modifier la config du pool dans le ConfigMap
kubectl edit configmap veylant-proxy-config -n veylant
# Ajouter/modifier :
# database:
# max_open_connections: 30 (augmenter temporairement)
# max_idle_connections: 5
# Redémarrer le proxy
kubectl rollout restart deployment/veylant-proxy-blue -n veylant
```
### B — Espace disque insuffisant
#### B1. VACUUM pour récupérer de l'espace
```bash
# VACUUM ANALYZE sur les tables les plus volumineuses
kubectl exec -n veylant deploy/postgres -- \
psql -U veylant -c "VACUUM ANALYZE audit_log_partitions;"
# VACUUM FULL (bloque les écritures — fenêtre de maintenance requise)
kubectl exec -n veylant deploy/postgres -- \
psql -U veylant -c "VACUUM FULL routing_rules;"
```
#### B2. Purger les vieux WAL (si excessifs)
```bash
# Vérifier les archives WAL obsolètes
kubectl exec -n veylant deploy/postgres -- \
psql -U veylant -c "SELECT pg_walfile_name(pg_current_wal_lsn());"
# Forcer un checkpoint pour libérer les WAL non nécessaires
kubectl exec -n veylant deploy/postgres -- \
psql -U veylant -c "CHECKPOINT;"
```
#### B3. Étendre le PVC AWS EBS
```bash
# Vérifier le PVC actuel
kubectl get pvc -n veylant postgres-data
# Patcher la taille (EBS supporte l'expansion à chaud)
kubectl patch pvc postgres-data -n veylant \
-p '{"spec":{"resources":{"requests":{"storage":"100Gi"}}}}'
# Attendre la confirmation AWS EBS
kubectl describe pvc postgres-data -n veylant | grep -E "(Capacity|Conditions)"
# Redémarrer PostgreSQL pour reconnaître le nouvel espace (si nécessaire)
kubectl rollout restart statefulset/postgres -n veylant
```
---
## Prévention
- Alert `VeylantDBConnectionsHigh` configurée à 20 connexions (seuil conservateur)
- VACUUM automatique activé (autovacuum PostgreSQL par défaut)
- Backup quotidien S3 avec 7 jours de rétention (`deploy/k8s/production/postgres-backup.yaml`)
- Monitoring PVC utilisation > 80% → `PVCAlmostFull` alerte (à configurer dans rules.yml)
---
## Post-mortem Template
```markdown
## Post-mortem — DB Issue [DATE]
**Type :** Pool épuisé / Espace disque / Requête lente
**Durée d'impact :** [X minutes]
**Erreurs utilisateurs :** [N requêtes rejetées]
### Timeline
- HH:MM — Alerte reçue
- HH:MM — Diagnostic : [cause identifiée]
- HH:MM — Action prise : [VACUUM / kill connections / PVC expansion]
- HH:MM — Service rétabli
### Root Cause
[Description]
### Actions correctives
- [ ] Augmenter le monitoring PVC
- [ ] Revoir les index manquants sur les requêtes lentes
- [ ] Planifier la prochaine expansion de stockage
```

320
docs/runbooks/migration-client.md Normal file
View File

@ -0,0 +1,320 @@
# Runbook — Migration Client Pilote vers Production
**Applicable à :** Clients A (TechVision ESN) et B (RH Conseil)
**Durée estimée :** 2–4 heures par client (fenêtre de maintenance recommandée)
**Prérequis :** Cluster production opérationnel (EKS eu-west-3), Keycloak prod configuré
---
## Vue d'ensemble
```
Staging (api-staging.veylant.ai) Production (api.veylant.ai)
│ │
├── PostgreSQL staging DB →→→→→→→→ ├── PostgreSQL production DB
├── Keycloak staging realm →→→→→→→→ ├── Keycloak production realm
├── Redis staging ├── Redis production
└── Utilisateurs staging └── Utilisateurs production
```
---
## Phase 1 — Pré-migration (J-1)
### 1.1 Backup complet du staging
```bash
# Backup PostgreSQL staging
kubectl exec -n veylant deploy/postgres -- \
pg_dump -U veylant veylant_db | gzip > backup_staging_$(date +%Y%m%d).sql.gz
# Vérifier le backup
gunzip -t backup_staging_$(date +%Y%m%d).sql.gz && echo "Backup OK"
# Uploader vers S3 (conservation pendant la migration)
aws s3 cp backup_staging_$(date +%Y%m%d).sql.gz \
s3://veylant-backups-production/migration/
```
### 1.2 Inventaire des utilisateurs à migrer
```bash
# Exporter la liste des utilisateurs Keycloak staging
kubectl exec -n keycloak deploy/keycloak -- \
/opt/keycloak/bin/kcadm.sh get users \
-r veylant-staging \
--server http://localhost:8080 \
--realm master \
--user admin --password admin \
> users_staging.json
# Compter les utilisateurs actifs (30 derniers jours)
psql "$STAGING_DB_URL" -c \
"SELECT COUNT(*) FROM users WHERE last_login > NOW() - INTERVAL '30 days';"
```
### 1.3 Validation de l'environnement production
```bash
# Vérifier que le cluster production est opérationnel
kubectl get nodes -n veylant --context=production
kubectl get pods -n veylant --context=production
# Vérifier la connectivité API production
curl -sf https://api.veylant.ai/healthz | jq .
# Vérifier Keycloak production
curl -sf https://auth.veylant.ai/realms/veylant/.well-known/openid-configuration | jq .issuer
# Confirmer le backup automatique actif
kubectl get cronjob veylant-postgres-backup -n veylant --context=production
```
### 1.4 Communication client
- [ ] Envoyer email de notification J-1 (fenêtre de maintenance, impact estimé)
- [ ] Confirmer contact technique côté client disponible pendant la migration
- [ ] Partager le runbook rollback avec le client
---
## Phase 2 — Migration des données PostgreSQL
### 2.1 Export depuis staging
```bash
# Export complet avec données clients seulement (pas les configs système)
pg_dump \
--host="$STAGING_DB_HOST" \
--username="$STAGING_DB_USER" \
--dbname="$STAGING_DB_NAME" \
--table=users \
--table=api_keys \
--table=routing_rules \
--table=gdpr_processing_registry \
--table=ai_act_classifications \
--format=custom \
--no-privileges \
--no-owner \
-f migration_data.dump
echo "Export size: $(du -sh migration_data.dump)"
```
### 2.2 Import vers production
```bash
# Appliquer les migrations DDL d'abord (production doit être à jour)
kubectl exec -n veylant deploy/veylant-proxy --context=production -- \
/app/proxy migrate up
# Import des données
pg_restore \
--host="$PROD_DB_HOST" \
--username="$PROD_DB_USER" \
--dbname="$PROD_DB_NAME" \
--no-privileges \
--no-owner \
--clean \
--if-exists \
-v \
migration_data.dump
# Vérifier l'intégrité
psql "$PROD_DB_URL" -c "SELECT COUNT(*) FROM users;"
psql "$PROD_DB_URL" -c "SELECT COUNT(*) FROM routing_rules;"
```
### 2.3 Vérification post-import
```bash
# Comparer les compteurs staging vs production
STAGING_USERS=$(psql "$STAGING_DB_URL" -t -c "SELECT COUNT(*) FROM users;")
PROD_USERS=$(psql "$PROD_DB_URL" -t -c "SELECT COUNT(*) FROM users;")
echo "Staging users: $STAGING_USERS | Production users: $PROD_USERS"
if [ "$STAGING_USERS" != "$PROD_USERS" ]; then
echo "ERROR: User count mismatch — abort migration"
exit 1
fi
```
---
## Phase 3 — Reconfiguration Keycloak Production
### 3.1 Création du realm production
```bash
# Se connecter à Keycloak production
KEYCLOAK_URL="https://auth.veylant.ai"
KEYCLOAK_ADMIN_TOKEN=$(curl -s \
-d "client_id=admin-cli" \
-d "username=admin" \
-d "password=$KEYCLOAK_ADMIN_PASSWORD" \
-d "grant_type=password" \
"$KEYCLOAK_URL/realms/master/protocol/openid-connect/token" | jq -r .access_token)
# Importer la configuration du realm depuis staging
# (exportée au format JSON lors de la phase 1.2)
curl -sf -X POST \
-H "Authorization: Bearer $KEYCLOAK_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d @realm-export.json \
"$KEYCLOAK_URL/admin/realms"
```
### 3.2 Import des utilisateurs
```bash
# Importer les utilisateurs avec leurs rôles
# Note: les mots de passe ne peuvent pas être migrés — les utilisateurs recevront un email de reset
for user in $(jq -r '.[].id' users_staging.json); do
USER_DATA=$(jq --arg id "$user" '.[] | select(.id == $id)' users_staging.json)
curl -sf -X POST \
-H "Authorization: Bearer $KEYCLOAK_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d "$USER_DATA" \
"$KEYCLOAK_URL/admin/realms/veylant/users"
done
echo "Imported $(jq length users_staging.json) users"
```
### 3.3 Réinitialisation des mots de passe
```bash
# Envoyer un email de reset de mot de passe à tous les utilisateurs migrés
USER_IDS=$(curl -sf \
-H "Authorization: Bearer $KEYCLOAK_ADMIN_TOKEN" \
"$KEYCLOAK_URL/admin/realms/veylant/users?max=1000" | jq -r '.[].id')
for USER_ID in $USER_IDS; do
curl -sf -X PUT \
-H "Authorization: Bearer $KEYCLOAK_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '["UPDATE_PASSWORD"]' \
"$KEYCLOAK_URL/admin/realms/veylant/users/$USER_ID/execute-actions-email"
sleep 0.1 # Rate limit emails
done
```
---
## Phase 4 — Validation
### 4.1 Smoke tests API
```bash
# Obtenir un token de test (compte admin pré-créé)
TOKEN=$(curl -sf \
-d "client_id=veylant-api" \
-d "username=admin-test@veylant.ai" \
-d "password=$TEST_ADMIN_PASSWORD" \
-d "grant_type=password" \
"https://auth.veylant.ai/realms/veylant/protocol/openid-connect/token" | jq -r .access_token)
# Test endpoints principaux
curl -sf -H "Authorization: Bearer $TOKEN" https://api.veylant.ai/v1/admin/users | jq length
curl -sf -H "Authorization: Bearer $TOKEN" https://api.veylant.ai/v1/admin/routing-rules | jq length
# Test proxy (avec model user-role)
curl -sf -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hello"}]}' \
https://api.veylant.ai/v1/chat/completions | jq .choices[0].message.content
echo "Smoke tests passed"
```
### 4.2 Validation des audit logs
```bash
# Vérifier que les logs sont bien envoyés à ClickHouse
curl -sf -H "Authorization: Bearer $TOKEN" \
"https://api.veylant.ai/v1/admin/logs?limit=5" | jq '.[].request_id'
```
### 4.3 Validation du dashboard
```bash
# Ouvrir le dashboard client et vérifier les métriques
open "https://dashboard.veylant.ai"
# Vérifier manuellement : graphiques RPS, latence, erreurs, PII
```
---
## Phase 5 — Cutover SSO (Go-Live)
### 5.1 Mise à jour des URLs côté client
Informer le contact technique du client de mettre à jour :
| Paramètre | Staging | Production |
|-----------|---------|------------|
| `base_url` OpenAI SDK | `https://api-staging.veylant.ai/v1` | `https://api.veylant.ai/v1` |
| OIDC Issuer (si SAML) | `https://auth-staging.veylant.ai/realms/veylant` | `https://auth.veylant.ai/realms/veylant` |
| Dashboard | `https://dashboard-staging.veylant.ai` | `https://dashboard.veylant.ai` |
### 5.2 Mise à jour CORS production
```bash
# Ajouter le domaine dashboard client dans config.yaml production
# Exemple Client B (RH Conseil) : dashboard sur dashboard.rh-conseil.fr
kubectl edit configmap veylant-proxy-config -n veylant --context=production
# Ajouter sous server.allowed_origins:
# - "https://dashboard.rh-conseil.fr"
# Redémarrer le proxy pour prendre en compte la nouvelle config
kubectl rollout restart deployment/veylant-proxy-blue -n veylant --context=production
kubectl rollout status deployment/veylant-proxy-blue -n veylant --context=production
```
### 5.3 Confirmation Go-Live
- [ ] Envoyer email de confirmation au client : migration réussie
- [ ] Planifier NPS de suivi J+7
- [ ] Archiver le dump staging utilisé pour la migration
---
## Rollback
### Rollback Phase 2 (avant cutover)
```bash
# Restaurer la base production depuis le backup staging
pg_restore \
--host="$PROD_DB_HOST" \
--username="$PROD_DB_USER" \
--dbname="$PROD_DB_NAME" \
--clean \
migration_data.dump
echo "Rollback Phase 2 terminé — base production restaurée"
```
### Rollback Phase 5 (après cutover)
```bash
# Rediriger le trafic vers staging (intervention DNS)
# Contact ops@veylant.ai immédiatement
# Informer le client : retour en staging, investigation en cours
# ETA rollback DNS : < 5 minutes (TTL court configuré en préparation)
```
---
## Checklist finale
- [ ] Backup staging conservé 30 jours
- [ ] Tous les utilisateurs ont reçu l'email de reset mot de passe
- [ ] Smoke tests API passés
- [ ] Dashboard client accessible
- [ ] CORS mis à jour avec domaine client
- [ ] NPS suivi planifié J+7
- [ ] Staging désactivé après 2 semaines (coûts)

262
docs/runbooks/pii-breach.md Normal file
View File

@ -0,0 +1,262 @@
# Runbook — Fuite de Données PII / Incident de Sécurité
**Alerte :** `VeylantPIIVolumeAnomaly` ou signalement client / équipe
**Réglementation :** RGPD Art. 33 — notification CNIL sous 72 heures si risque pour les personnes
**Commandement :** Ce runbook déclenche le plan de réponse aux incidents (IRP). Impliquer le DPO immédiatement.
---
## Symptômes
- Alerte `VeylantPIIVolumeAnomaly` : taux PII > 3× baseline
- Signalement client d'une exposition de données personnelles
- Audit log montrant des requêtes atypiques (volume anormal, tenant inconnu)
- Logs PII service : erreur de pseudonymisation, données non anonymisées retournées
- Accès non autorisé détecté via gitleaks ou SIEM
---
## Phase 1 — Détection et Triage (0-15 min)
### 1.1 Identifier la nature de l'incident
```bash
# Logs PII service (dernière heure)
kubectl logs -n veylant deploy/pii-service --since=1h | \
grep -E "(error|bypass|unmasked|pseudonym)" | tail -50
# Audit logs — requêtes suspectes
curl -sf -H "Authorization: Bearer $ADMIN_TOKEN" \
"https://api.veylant.ai/v1/admin/logs?limit=100&sort=desc" | \
jq '.[] | select(.pii_entities_count > 50) | {request_id, tenant_id, user_id, pii_count: .pii_entities_count, timestamp}'
# Vérifier les métriques PII anormales
curl -s "http://prometheus:9090/api/v1/query_range" \
--data-urlencode 'query=rate(veylant_pii_entities_detected_total[5m])' \
--data-urlencode 'start=1h ago' \
--data-urlencode 'end=now' \
--data-urlencode 'step=1m' | jq '.data.result[0].values[-10:]'
```
### 1.2 Classifier l'incident
| Niveau | Description | Action immédiate |
|--------|-------------|------------------|
| **P1 — Critique** | Données PII retournées en clair dans les réponses API | Isolation immédiate |
| **P2 — Élevé** | Anomalie volume PII, cause inconnue | Investigation + monitoring renforcé |
| **P3 — Moyen** | Pseudo non réversible exposé, pas de données réelles | Logging + rapport |
| **P4 — Info** | Alerte technique sans impact sur les données | Analyse, pas d'action urgente |
---
## Phase 2 — Isolation Immédiate (si P1)
**ARRÊTER le flux de données avant toute investigation.**
```bash
# Option A — Mode maintenance (impact utilisateurs, mais sécurisé)
curl -sf -X PATCH \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"enabled": true, "message": "Maintenance de sécurité en cours."}' \
https://api.veylant.ai/v1/admin/flags/maintenance-mode
echo "Maintenance mode ACTIVÉ — toutes les requêtes bloquées"
# Option B — Isoler un tenant spécifique seulement (si périmètre connu)
curl -sf -X PATCH \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"suspended": true, "reason": "security_incident"}' \
"https://api.veylant.ai/v1/admin/tenants/$AFFECTED_TENANT_ID"
echo "Tenant $AFFECTED_TENANT_ID suspendu"
```
### 2.2 Désactiver le service PII si compromis
```bash
# Désactiver le PII service (stoppe l'anonymisation — plus sécuritaire qu'un bypass)
kubectl scale deploy/pii-service -n veylant --replicas=0
echo "PII service arrêté — toutes les requêtes avec PII rejetées (fail_open=false)"
```
---
## Phase 3 — Investigation (15-60 min)
### 3.1 Collecter les preuves
```bash
# Snapshot des logs d'audit (immuables dans ClickHouse)
curl -sf -H "Authorization: Bearer $ADMIN_TOKEN" \
"https://api.veylant.ai/v1/admin/logs?tenant_id=$TENANT_ID&limit=1000&format=csv" \
> incident_audit_$(date +%Y%m%d_%H%M%S).csv
# Export des métriques Prometheus au moment de l'incident
curl -s "http://prometheus:9090/api/v1/query_range" \
--data-urlencode "query=rate(veylant_pii_entities_detected_total[1m])" \
--data-urlencode "start=$(date -u -d '2 hours ago' +%s)" \
--data-urlencode "end=$(date -u +%s)" \
--data-urlencode "step=60" > pii_metrics_$(date +%Y%m%d).json
# Capture des logs système
kubectl logs -n veylant deploy/veylant-proxy-blue --since=2h > proxy_logs_$(date +%Y%m%d_%H%M%S).log
kubectl logs -n veylant deploy/pii-service --since=2h > pii_logs_$(date +%Y%m%d_%H%M%S).log
```
### 3.2 Analyser les données exposées
```bash
# Identifier quels types de PII ont été détectés
grep "entity_type" incident_audit_*.csv | \
awk -F',' '{print $NF}' | sort | uniq -c | sort -rn
# Identifier les utilisateurs concernés
grep "pii" incident_audit_*.csv | \
awk -F',' '{print $3}' | sort -u # colonne user_id
```
### 3.3 Vérifier la réversibilité des pseudonymes
```bash
# Les pseudonymes Redis sont-ils accessibles sans contexte tenant ?
# Tester depuis un tenant différent (devrait échouer)
curl -sf -X POST \
-H "Authorization: Bearer $OTHER_TENANT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"text": "[PSEUDONYM_XXX]"}' \
https://api.veylant.ai/v1/pii/analyze
# Si le pseudonyme est résolu depuis un autre tenant → fuite critique (CVSS 9.0+)
```
---
## Phase 4 — Notification RGPD (si données réelles exposées)
### Délai légal : 72 heures après prise de connaissance (RGPD Art. 33)
### 4.1 Notifier le DPO immédiatement
```
Contact DPO : [nom] — [email] — [téléphone]
Message type :
"Incident de sécurité potentiel détecté sur Veylant IA à [HH:MM].
Type : [description].
Données possiblement affectées : [types PII].
Utilisateurs potentiellement impactés : [N].
Investigation en cours. Présence requise immédiatement."
```
### 4.2 Préparer la notification CNIL
La notification doit inclure (RGPD Art. 33§3) :
- Nature de la violation
- Catégories et nombre approximatif de personnes concernées
- Catégories et nombre approximatif d'enregistrements concernés
- Nom et coordonnées du DPO
- Description des conséquences probables
- Mesures prises ou envisagées pour remédier
```bash
# Template notification CNIL (à compléter)
cat > cnil_notification_$(date +%Y%m%d).md << 'EOF'
# Notification de violation de données — RGPD Art. 33
**Date de la violation :** [DATE]
**Date de détection :** [DATE]
**Date de notification :** [DATE] (dans les 72h)
## Nature de la violation
[Description précise]
## Catégories de données affectées
- [ ] Noms/prénoms
- [ ] Emails
- [ ] Numéros de téléphone
- [ ] Données financières (IBAN, etc.)
- [ ] Données de santé
- [ ] Autres : [préciser]
## Personnes affectées
- Nombre approximatif : [N]
- Catégories : [employés, clients, etc.]
## Mesures prises
1. Isolation des systèmes affectés : [HH:MM]
2. Investigation en cours
3. [Autres mesures]
## Contact DPO
[Nom, email, téléphone]
EOF
```
### 4.3 Notifier les clients affectés (si données réelles exposées)
Délai recommandé : sans retard injustifié (RGPD Art. 34 si risque élevé pour les personnes)
```
Template email client :
Objet : [Important] Notification de sécurité — Veylant IA
Madame, Monsieur,
Nous vous informons d'un incident de sécurité détecté le [DATE] à [HH:MM]...
```
---
## Phase 5 — Restauration et Post-mortem
### 5.1 Restaurer le service
```bash
# Redémarrer le PII service
kubectl scale deploy/pii-service -n veylant --replicas=1
kubectl rollout status deploy/pii-service -n veylant
# Désactiver le mode maintenance
curl -sf -X PATCH \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"enabled": false}' \
https://api.veylant.ai/v1/admin/flags/maintenance-mode
# Réactiver le tenant (si applicable)
curl -sf -X PATCH \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"suspended": false}' \
"https://api.veylant.ai/v1/admin/tenants/$AFFECTED_TENANT_ID"
# Smoke test post-restauration
curl -sf https://api.veylant.ai/healthz | jq .
```
### 5.2 Invalider les pseudonymes compromis (si applicable)
```bash
# Forcer la rotation des clés Redis de pseudonymisation
# ATTENTION : invalide TOUS les pseudonymes actifs → les mappings PII seront recréés
kubectl exec -n veylant deploy/redis -- redis-cli FLUSHDB
echo "Pseudonymes invalidés — nouveaux pseudonymes générés au prochain appel PII"
```
---
## Checklist Incident
- [ ] Incident détecté à [HH:MM]
- [ ] DPO notifié à [HH:MM] (< 15 min après détection)
- [ ] Isolation effectuée à [HH:MM]
- [ ] Preuves collectées (logs, métriques)
- [ ] Évaluation RGPD : notification CNIL requise ? [Oui/Non]
- [ ] Si oui : notification CNIL < 72h (deadline : [DATE HH:MM])
- [ ] Notification clients si risque élevé
- [ ] Service restauré à [HH:MM]
- [ ] Post-mortem planifié (J+3)
- [ ] Rapport de remédiation livré (J+7)

167
docs/runbooks/provider-down.md Normal file
View File

@ -0,0 +1,167 @@
# Runbook — Provider IA Down / Circuit Breaker Ouvert
**Alerte :** `VeylantCircuitBreakerOpen` (severity: critical) ou `VeylantHighErrorRate`
**SLA impact :** Dégradation partielle (fallback) ou interruption totale (aucun fallback)
**Temps de résolution cible :** < 15 minutes
---
## Symptômes
- Alerte PagerDuty/Slack `VeylantCircuitBreakerOpen` pour un provider
- Réponses 503 aux requêtes `/v1/chat/completions` pour le provider affecté
- Erreur rate > 5% sur le dashboard Grafana
- Logs : `"circuit breaker open"` avec `provider=openai` (ou autre)
---
## Diagnostic
### 1. Identifier le provider affecté
```bash
# Voir l'état des circuit breakers dans les métriques Prometheus
curl -s http://localhost:9090/api/v1/query?query=veylant_circuit_breaker_state | \
jq '.data.result[] | {provider: .metric.provider, state: .metric.state, value: .value[1]}'
# Logs du proxy (dernières 10 minutes)
kubectl logs -n veylant deploy/veylant-proxy-blue --since=10m | \
grep -E "(circuit_breaker|provider_error|upstream)"
```
### 2. Vérifier le statut du provider en amont
```bash
# OpenAI
curl -sf https://status.openai.com/api/v2/status.json | jq .status.description
# Anthropic
curl -sf https://status.anthropic.com/api/v2/status.json | jq .status.description
# Azure OpenAI — remplacer par l'endpoint configuré
curl -sf https://YOUR_RESOURCE.openai.azure.com/ | head -1
```
### 3. Tester directement le provider
```bash
# Test OpenAI direct (bypasse le proxy)
curl -sf -X POST https://api.openai.com/v1/chat/completions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"ping"}]}' | \
jq .choices[0].message.content
```
### 4. Vérifier les routing rules de fallback
```bash
# Afficher les règles de routing actives (admin API)
curl -sf -H "Authorization: Bearer $ADMIN_TOKEN" \
https://api.veylant.ai/v1/admin/routing-rules | \
jq '.[] | {name: .name, provider: .target_provider, fallback: .fallback_provider}'
```
---
## Remédiation
### Option A — Fallback automatique déjà actif
Si une règle de fallback est configurée, le proxy bascule automatiquement sur le provider secondaire. Vérifier :
```bash
# Confirmer que les requêtes passent via le fallback
kubectl logs -n veylant deploy/veylant-proxy-blue --since=2m | \
grep "fallback" | tail -20
```
Si le fallback fonctionne → **surveiller**, ne pas intervenir. Le circuit breaker se referme automatiquement après 60 secondes si le provider se rétablit.
### Option B — Forcer le reset du circuit breaker
Si le provider est rétabli mais le circuit breaker est resté ouvert :
```bash
# Reset manuel via l'API admin
curl -sf -X POST \
-H "Authorization: Bearer $ADMIN_TOKEN" \
https://api.veylant.ai/v1/admin/providers/openai/reset-circuit-breaker
```
### Option C — Désactiver temporairement le provider affecté
```bash
# Modifier la routing rule pour exclure le provider down
curl -sf -X PATCH \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"target_provider": "anthropic", "fallback_provider": null}' \
https://api.veylant.ai/v1/admin/routing-rules/default-rule
echo "Traffic routed to Anthropic — monitor for 5 minutes"
```
### Option D — Panne prolongée du provider (> 30 min)
```bash
# Activer le message de maintenance pour les utilisateurs affectés
# (feature flag via l'API admin)
curl -sf -X PATCH \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"enabled": true}' \
https://api.veylant.ai/v1/admin/flags/maintenance-mode
# Notifier les clients impactés via Slack
# Template : "Nous faisons face à une interruption du provider [X].
# Vos requêtes sont temporairement routées vers [Y].
# Impact estimé : [durée]. Nous surveillons activement."
```
---
## Escalade
| Niveau | Condition | Action |
|--------|-----------|--------|
| L1 (on-call) | Circuit breaker ouvert, fallback actif | Surveiller 15 min |
| L2 (platform) | Panne > 15 min sans fallback | Patch routing rules + notification clients |
| L3 (CTO) | Panne totale > 1h (tous providers) | Activation mode maintenance + communication officielle |
**Contacts :**
- On-call : PagerDuty rotation → Slack `#veylant-critical`
- Provider SLA support : support@openai.com / support@anthropic.com
---
## Prévention
- Configurer un `fallback_provider` pour chaque routing rule critique
- Tester le fallback mensuellement (faire planter le circuit breaker en staging)
- Surveiller les `status.openai.com` / `status.anthropic.com` via webhook Slack
---
## Post-mortem Template
```markdown
## Post-mortem — Provider Down [DATE]
**Durée d'impact :** [X minutes]
**Providers affectés :** [liste]
**Requêtes échouées :** [N] (error_rate: X%)
### Timeline
- HH:MM — Alerte VeylantCircuitBreakerOpen reçue
- HH:MM — Diagnostic confirmé : [provider] en panne
- HH:MM — Fallback activé / Action prise
- HH:MM — Service rétabli
### Root Cause
[Description de la cause racine]
### Actions correctives
- [ ] [Action 1]
- [ ] [Action 2]
```

174
docs/runbooks/traffic-spike.md Normal file
View File

@ -0,0 +1,174 @@
# Runbook — Pic de Trafic / Surcharge
**Alerte :** `VeylantHighLatencyP99` ou `VeylantHighErrorRate` + taux de requêtes anormalement élevé
**SLA impact :** Dégradation des performances, potentiellement interruptions
**Temps de résolution cible :** < 10 minutes (HPA automatique), < 5 min si intervention manuelle
---
## Symptômes
- Alerte `VeylantHighLatencyP99` : p99 > 500ms pendant > 5 min
- Alerte `VeylantHighErrorRate` : error rate > 5%
- Dashboard Grafana : RPS brutal augmentation, p99 qui monte
- Logs : `"rate limit exceeded"` massif pour une tenant, ou requests en queue
---
## Diagnostic
### 1. Évaluer l'ampleur du pic
```bash
# RPS actuel vs baseline
curl -s "http://prometheus:9090/api/v1/query" \
--data-urlencode 'query=sum(rate(veylant_requests_total[1m]))' | \
jq '.data.result[0].value[1]'
# Identifier le tenant / provider qui drive le trafic
curl -s "http://prometheus:9090/api/v1/query" \
--data-urlencode 'query=topk(5, sum by (tenant_id) (rate(veylant_requests_total[1m])))' | \
jq '.data.result[] | {tenant: .metric.tenant_id, rps: .value[1]}'
# État HPA
kubectl get hpa -n veylant
kubectl describe hpa veylant-proxy -n veylant
```
### 2. Vérifier si le HPA scale
```bash
# Vérifier le scaling automatique en cours
kubectl get hpa veylant-proxy -n veylant -w
# Pods actuels
kubectl get pods -n veylant -l app.kubernetes.io/name=veylant-proxy
# Events HPA
kubectl describe hpa veylant-proxy -n veylant | grep -A10 "Events:"
```
### 3. Vérifier l'état des providers upstream
```bash
# Latence upstream par provider
kubectl logs -n veylant deploy/veylant-proxy-blue --since=5m | \
grep "upstream_duration" | \
awk '{sum+=$NF; count++} END {print "avg:", sum/count, "ms"}'
```
---
## Remédiation
### A — HPA automatique (cas normal)
Si le HPA est configuré et que les pods scalent :
```bash
# Observer le scaling (attendre 30-60 secondes)
kubectl get hpa veylant-proxy -n veylant -w
# Surveiller les nouveaux pods qui deviennent Ready
kubectl get pods -n veylant -l app.kubernetes.io/name=veylant-proxy -w
```
Si le scaling prend > 5 minutes → **forcer le scale manuel (Option B)**.
### B — Scale manuel d'urgence
```bash
# Scale immédiat sans attendre l'HPA
kubectl scale deployment veylant-proxy-blue -n veylant --replicas=10
# Vérifier que les pods démarrent
kubectl rollout status deployment/veylant-proxy-blue -n veylant
echo "Scaled to 10 replicas — monitor for 2 minutes"
```
### C — Activer le rate limiting agressif temporaire
Si un seul tenant consomme la majorité du trafic :
```bash
# Identifier le tenant abusif
ABUSIVE_TENANT=$(kubectl logs -n veylant deploy/veylant-proxy-blue --since=5m | \
grep "rate_limit" | grep -oP 'tenant_id=[^ ]+' | sort | uniq -c | sort -rn | head -1)
echo "Abusive tenant: $ABUSIVE_TENANT"
# Réduire temporairement la limite du tenant via l'API admin
curl -sf -X PATCH \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"requests_per_minute": 10}' \
"https://api.veylant.ai/v1/admin/tenants/$TENANT_ID/rate-limit"
echo "Rate limit réduit à 10 req/min pour $TENANT_ID"
```
### D — Circuit breaker manuel (trafic trop élevé pour les providers)
```bash
# Activer temporairement la réponse cached / dégradée
# (feature flag maintenance-mode)
curl -sf -X PATCH \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"enabled": true, "message": "Service en charge élevée. Réessayez dans quelques minutes."}' \
https://api.veylant.ai/v1/admin/flags/maintenance-mode
# Désactiver une fois le trafic revenu à la normale
curl -sf -X PATCH \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"enabled": false}' \
https://api.veylant.ai/v1/admin/flags/maintenance-mode
```
### E — Retour à l'état normal
```bash
# Une fois le trafic normalisé, remettre le HPA en contrôle
kubectl patch hpa veylant-proxy -n veylant \
--type=merge \
-p '{"spec":{"minReplicas":3,"maxReplicas":15}}'
# Le HPA réduira le nombre de pods progressivement
echo "HPA reprend le contrôle — stabilisation en 5-10 min"
```
---
## Prévention
- HPA configuré avec `maxReplicas: 15` et scale-up rapide (100% en 60s)
- Rate limiting per-tenant activé (DB overrides disponibles)
- Circuit breaker activé avec threshold=5 failures / 60s window
- k6 smoke test en CI pour détecter les régressions de performance
---
## Post-mortem Template
```markdown
## Post-mortem — Traffic Spike [DATE]
**Pic observé :** [X RPS vs baseline Y RPS]
**Durée d'impact :** [X minutes p99 > 500ms]
**Cause :** [Charge légitime / Tenant abusif / DDoS / Bug client]
### Timeline
- HH:MM — Alerte HighLatencyP99 reçue
- HH:MM — Diagnostic : [cause identifiée]
- HH:MM — Action : [Scale manuel / Rate limit / Maintenance mode]
- HH:MM — Retour à la normale
### Root Cause
[Description]
### Actions correctives
- [ ] Revoir les limites HPA maxReplicas si insuffisant
- [ ] Ajouter rate limit global cross-tenant si nécessaire
- [ ] Communication avec le tenant si abus constaté
```

110
go.mod Normal file
View File

@ -0,0 +1,110 @@
module github.com/veylant/ia-gateway
go 1.24.1
require (
github.com/ClickHouse/clickhouse-go/v2 v2.43.0
github.com/coreos/go-oidc/v3 v3.17.0
github.com/go-chi/chi/v5 v5.1.0
github.com/google/uuid v1.6.0
github.com/jackc/pgx/v5 v5.8.0
github.com/prometheus/client_golang v1.23.2
github.com/spf13/viper v1.19.0
go.uber.org/zap v1.27.1
google.golang.org/grpc v1.79.1
google.golang.org/protobuf v1.36.11
)
require (
dario.cat/mergo v1.0.2 // indirect
github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1 // indirect
github.com/ClickHouse/ch-go v0.71.0 // indirect
github.com/Microsoft/go-winio v0.6.2 // indirect
github.com/andybalholm/brotli v1.2.0 // indirect
github.com/beorn7/perks v1.0.1 // indirect
github.com/cenkalti/backoff/v4 v4.3.0 // indirect
github.com/cespare/xxhash/v2 v2.3.0 // indirect
github.com/containerd/errdefs v1.0.0 // indirect
github.com/containerd/errdefs/pkg v0.3.0 // indirect
github.com/containerd/log v0.1.0 // indirect
github.com/containerd/platforms v0.2.1 // indirect
github.com/cpuguy83/dockercfg v0.3.2 // indirect
github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
github.com/distribution/reference v0.6.0 // indirect
github.com/docker/docker v28.5.2+incompatible // indirect
github.com/docker/go-connections v0.6.0 // indirect
github.com/docker/go-units v0.5.0 // indirect
github.com/ebitengine/purego v0.8.4 // indirect
github.com/felixge/httpsnoop v1.0.4 // indirect
github.com/fsnotify/fsnotify v1.7.0 // indirect
github.com/go-faster/city v1.0.1 // indirect
github.com/go-faster/errors v0.7.1 // indirect
github.com/go-jose/go-jose/v4 v4.1.3 // indirect
github.com/go-logr/logr v1.4.3 // indirect
github.com/go-logr/stdr v1.2.2 // indirect
github.com/go-ole/go-ole v1.2.6 // indirect
github.com/go-pdf/fpdf v0.9.0 // indirect
github.com/hashicorp/hcl v1.0.0 // indirect
github.com/jackc/pgpassfile v1.0.0 // indirect
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
github.com/jackc/puddle/v2 v2.2.2 // indirect
github.com/klauspost/compress v1.18.3 // indirect
github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 // indirect
github.com/magiconair/properties v1.8.10 // indirect
github.com/mitchellh/mapstructure v1.5.0 // indirect
github.com/moby/docker-image-spec v1.3.1 // indirect
github.com/moby/go-archive v0.1.0 // indirect
github.com/moby/patternmatcher v0.6.0 // indirect
github.com/moby/sys/sequential v0.6.0 // indirect
github.com/moby/sys/user v0.4.0 // indirect
github.com/moby/sys/userns v0.1.0 // indirect
github.com/moby/term v0.5.0 // indirect
github.com/morikuni/aec v1.0.0 // indirect
github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
github.com/opencontainers/go-digest v1.0.0 // indirect
github.com/opencontainers/image-spec v1.1.1 // indirect
github.com/paulmach/orb v0.12.0 // indirect
github.com/pelletier/go-toml/v2 v2.2.2 // indirect
github.com/pierrec/lz4/v4 v4.1.25 // indirect
github.com/pkg/errors v0.9.1 // indirect
github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c // indirect
github.com/prometheus/client_model v0.6.2 // indirect
github.com/prometheus/common v0.66.1 // indirect
github.com/prometheus/procfs v0.16.1 // indirect
github.com/sagikazarmark/locafero v0.4.0 // indirect
github.com/sagikazarmark/slog-shim v0.1.0 // indirect
github.com/segmentio/asm v1.2.1 // indirect
github.com/shirou/gopsutil/v4 v4.25.6 // indirect
github.com/shopspring/decimal v1.4.0 // indirect
github.com/sirupsen/logrus v1.9.3 // indirect
github.com/sourcegraph/conc v0.3.0 // indirect
github.com/spf13/afero v1.11.0 // indirect
github.com/spf13/cast v1.6.0 // indirect
github.com/spf13/pflag v1.0.5 // indirect
github.com/stretchr/testify v1.11.1 // indirect
github.com/subosito/gotenv v1.6.0 // indirect
github.com/testcontainers/testcontainers-go v0.40.0 // indirect
github.com/tklauser/go-sysconf v0.3.12 // indirect
github.com/tklauser/numcpus v0.6.1 // indirect
github.com/yusufpapurcu/wmi v1.2.4 // indirect
go.opentelemetry.io/auto/sdk v1.2.1 // indirect
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.49.0 // indirect
go.opentelemetry.io/otel v1.39.0 // indirect
go.opentelemetry.io/otel/metric v1.39.0 // indirect
go.opentelemetry.io/otel/trace v1.39.0 // indirect
go.uber.org/multierr v1.11.0 // indirect
go.yaml.in/yaml/v2 v2.4.2 // indirect
go.yaml.in/yaml/v3 v3.0.4 // indirect
golang.org/x/crypto v0.47.0 // indirect
golang.org/x/exp v0.0.0-20230905200255-921286631fa9 // indirect
golang.org/x/net v0.49.0 // indirect
golang.org/x/oauth2 v0.35.0 // indirect
golang.org/x/sync v0.19.0 // indirect
golang.org/x/sys v0.40.0 // indirect
golang.org/x/text v0.33.0 // indirect
golang.org/x/time v0.14.0 // indirect
google.golang.org/genproto/googleapis/rpc v0.0.0-20251202230838-ff82c1b0f217 // indirect
gopkg.in/ini.v1 v1.67.0 // indirect
gopkg.in/yaml.v3 v3.0.1 // indirect
)

344
go.sum Normal file
View File

@ -0,0 +1,344 @@
dario.cat/mergo v1.0.2 h1:85+piFYR1tMbRrLcDwR18y4UKJ3aH1Tbzi24VRW1TK8=
dario.cat/mergo v1.0.2/go.mod h1:E/hbnu0NxMFBjpMIE34DRGLWqDy0g5FuKDhCb31ngxA=
github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1 h1:UQHMgLO+TxOElx5B5HZ4hJQsoJ/PvUvKRhJHDQXO8P8=
github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1/go.mod h1:xomTg63KZ2rFqZQzSB4Vz2SUXa1BpHTVz9L5PTmPC4E=
github.com/ClickHouse/ch-go v0.71.0 h1:bUdZ/EZj/LcVHsMqaRUP2holqygrPWQKeMjc6nZoyRM=
github.com/ClickHouse/ch-go v0.71.0/go.mod h1:NwbNc+7jaqfY58dmdDUbG4Jl22vThgx1cYjBw0vtgXw=
github.com/ClickHouse/clickhouse-go/v2 v2.43.0 h1:fUR05TrF1GyvLDa/mAQjkx7KbgwdLRffs2n9O3WobtE=
github.com/ClickHouse/clickhouse-go/v2 v2.43.0/go.mod h1:o6jf7JM/zveWC/PP277BLxjHy5KjnGX/jfljhM4s34g=
github.com/Microsoft/go-winio v0.6.2 h1:F2VQgta7ecxGYO8k3ZZz3RS8fVIXVxONVUPlNERoyfY=
github.com/Microsoft/go-winio v0.6.2/go.mod h1:yd8OoFMLzJbo9gZq8j5qaps8bJ9aShtEA8Ipt1oGCvU=
github.com/andybalholm/brotli v1.2.0 h1:ukwgCxwYrmACq68yiUqwIWnGY0cTPox/M94sVwToPjQ=
github.com/andybalholm/brotli v1.2.0/go.mod h1:rzTDkvFWvIrjDXZHkuS16NPggd91W3kUSvPlQ1pLaKY=
github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
github.com/cenkalti/backoff/v4 v4.3.0 h1:MyRJ/UdXutAwSAT+s3wNd7MfTIcy71VQueUuFK343L8=
github.com/cenkalti/backoff/v4 v4.3.0/go.mod h1:Y3VNntkOUPxTVeUxJ/G5vcM//AlwfmyYozVcomhLiZE=
github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
github.com/containerd/errdefs v1.0.0 h1:tg5yIfIlQIrxYtu9ajqY42W3lpS19XqdxRQeEwYG8PI=
github.com/containerd/errdefs v1.0.0/go.mod h1:+YBYIdtsnF4Iw6nWZhJcqGSg/dwvV7tyJ/kCkyJ2k+M=
github.com/containerd/errdefs/pkg v0.3.0 h1:9IKJ06FvyNlexW690DXuQNx2KA2cUJXx151Xdx3ZPPE=
github.com/containerd/errdefs/pkg v0.3.0/go.mod h1:NJw6s9HwNuRhnjJhM7pylWwMyAkmCQvQ4GpJHEqRLVk=
github.com/containerd/log v0.1.0 h1:TCJt7ioM2cr/tfR8GPbGf9/VRAX8D2B4PjzCpfX540I=
github.com/containerd/log v0.1.0/go.mod h1:VRRf09a7mHDIRezVKTRCrOq78v577GXq3bSa3EhrzVo=
github.com/containerd/platforms v0.2.1 h1:zvwtM3rz2YHPQsF2CHYM8+KtB5dvhISiXh5ZpSBQv6A=
github.com/containerd/platforms v0.2.1/go.mod h1:XHCb+2/hzowdiut9rkudds9bE5yJ7npe7dG/wG+uFPw=
github.com/coreos/go-oidc/v3 v3.17.0 h1:hWBGaQfbi0iVviX4ibC7bk8OKT5qNr4klBaCHVNvehc=
github.com/coreos/go-oidc/v3 v3.17.0/go.mod h1:wqPbKFrVnE90vty060SB40FCJ8fTHTxSwyXJqZH+sI8=
github.com/cpuguy83/dockercfg v0.3.2 h1:DlJTyZGBDlXqUZ2Dk2Q3xHs/FtnooJJVaad2S9GKorA=
github.com/cpuguy83/dockercfg v0.3.2/go.mod h1:sugsbF4//dDlL/i+S+rtpIWp+5h0BHJHfjj5/jFyUJc=
github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/distribution/reference v0.6.0 h1:0IXCQ5g4/QMHHkarYzh5l+u8T3t73zM5QvfrDyIgxBk=
github.com/distribution/reference v0.6.0/go.mod h1:BbU0aIcezP1/5jX/8MP0YiH4SdvB5Y4f/wlDRiLyi3E=
github.com/docker/docker v28.5.1+incompatible h1:Bm8DchhSD2J6PsFzxC35TZo4TLGR2PdW/E69rU45NhM=
github.com/docker/docker v28.5.1+incompatible/go.mod h1:eEKB0N0r5NX/I1kEveEz05bcu8tLC/8azJZsviup8Sk=
github.com/docker/docker v28.5.2+incompatible h1:DBX0Y0zAjZbSrm1uzOkdr1onVghKaftjlSWt4AFexzM=
github.com/docker/docker v28.5.2+incompatible/go.mod h1:eEKB0N0r5NX/I1kEveEz05bcu8tLC/8azJZsviup8Sk=
github.com/docker/go-connections v0.6.0 h1:LlMG9azAe1TqfR7sO+NJttz1gy6KO7VJBh+pMmjSD94=
github.com/docker/go-connections v0.6.0/go.mod h1:AahvXYshr6JgfUJGdDCs2b5EZG/vmaMAntpSFH5BFKE=
github.com/docker/go-units v0.5.0 h1:69rxXcBk27SvSaaxTtLh/8llcHD8vYHT7WSdRZ/jvr4=
github.com/docker/go-units v0.5.0/go.mod h1:fgPhTUdO+D/Jk86RDLlptpiXQzgHJF7gydDDbaIK4Dk=
github.com/ebitengine/purego v0.8.4 h1:CF7LEKg5FFOsASUj0+QwaXf8Ht6TlFxg09+S9wz0omw=
github.com/ebitengine/purego v0.8.4/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ=
github.com/felixge/httpsnoop v1.0.4 h1:NFTV2Zj1bL4mc9sqWACXbQFVBBg2W3GPvqp8/ESS2Wg=
github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U=
github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8=
github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0=
github.com/fsnotify/fsnotify v1.7.0 h1:8JEhPFa5W2WU7YfeZzPNqzMP6Lwt7L2715Ggo0nosvA=
github.com/fsnotify/fsnotify v1.7.0/go.mod h1:40Bi/Hjc2AVfZrqy+aj+yEI+/bRxZnMJyTJwOpGvigM=
github.com/go-chi/chi/v5 v5.1.0 h1:acVI1TYaD+hhedDJ3r54HyA6sExp3HfXq7QWEEY/xMw=
github.com/go-chi/chi/v5 v5.1.0/go.mod h1:DslCQbL2OYiznFReuXYUmQ2hGd1aDpCnlMNITLSKoi8=
github.com/go-faster/city v1.0.1 h1:4WAxSZ3V2Ws4QRDrscLEDcibJY8uf41H6AhXDrNDcGw=
github.com/go-faster/city v1.0.1/go.mod h1:jKcUJId49qdW3L1qKHH/3wPeUstCVpVSXTM6vO3VcTw=
github.com/go-faster/errors v0.7.1 h1:MkJTnDoEdi9pDabt1dpWf7AA8/BaSYZqibYyhZ20AYg=
github.com/go-faster/errors v0.7.1/go.mod h1:5ySTjWFiphBs07IKuiL69nxdfd5+fzh1u7FPGZP2quo=
github.com/go-jose/go-jose/v4 v4.1.3 h1:CVLmWDhDVRa6Mi/IgCgaopNosCaHz7zrMeF9MlZRkrs=
github.com/go-jose/go-jose/v4 v4.1.3/go.mod h1:x4oUasVrzR7071A4TnHLGSPpNOm2a21K9Kf04k1rs08=
github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
github.com/go-logr/logr v1.4.2 h1:6pFjapn8bFcIbiKo3XT4j/BhANplGihG6tvd+8rYgrY=
github.com/go-logr/logr v1.4.2/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
github.com/go-ole/go-ole v1.2.6 h1:/Fpf6oFPoeFik9ty7siob0G6Ke8QvQEuVcuChpwXzpY=
github.com/go-ole/go-ole v1.2.6/go.mod h1:pprOEPIfldk/42T2oK7lQ4v4JSDwmV0As9GaiUsvbm0=
github.com/go-pdf/fpdf v0.9.0 h1:PPvSaUuo1iMi9KkaAn90NuKi+P4gwMedWPHhj8YlJQw=
github.com/go-pdf/fpdf v0.9.0/go.mod h1:oO8N111TkmKb9D7VvWGLvLJlaZUQVPM+6V42pp3iV4Y=
github.com/gogo/protobuf v1.3.2/go.mod h1:P1XiOD3dCwIKUDQYPy72D8LYyHL2YPYrpS2s69NZV8Q=
github.com/golang/protobuf v1.5.0/go.mod h1:FsONVRAS9T7sI+LIUmWTfcYkHO4aIWwzhcaSAoJOfIk=
github.com/golang/snappy v0.0.1/go.mod h1:/XxbfmMg8lxefKM7IXC3fBNl/7bRcc72aCRzEWrmP2Q=
github.com/google/go-cmp v0.5.2/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
github.com/google/go-cmp v0.5.6/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38=
github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
github.com/hashicorp/hcl v1.0.0 h1:0Anlzjpi4vEasTeNFn2mLJgTSwt0+6sfsiTG8qcWGx4=
github.com/hashicorp/hcl v1.0.0/go.mod h1:E5yfLk+7swimpb2L/Alb/PJmXilQ/rhwaUYs4T20WEQ=
github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
github.com/jackc/pgx/v5 v5.8.0 h1:TYPDoleBBme0xGSAX3/+NujXXtpZn9HBONkQC7IEZSo=
github.com/jackc/pgx/v5 v5.8.0/go.mod h1:QVeDInX2m9VyzvNeiCJVjCkNFqzsNb43204HshNSZKw=
github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
github.com/kisielk/errcheck v1.5.0/go.mod h1:pFxgyoBC7bSaBwPgfKdkLd5X25qrDl4LWUI2bnpBCr8=
github.com/kisielk/gotool v1.0.0/go.mod h1:XhKaO+MFFWcvkIS/tQcRk01m1F5IRFswLeQ+oQHNcck=
github.com/klauspost/compress v1.13.6/go.mod h1:/3/Vjq9QcHkK5uEr5lBEmyoZ1iFhe47etQ6QUkpK6sk=
github.com/klauspost/compress v1.18.0 h1:c/Cqfb0r+Yi+JtIEq73FWXVkRonBlf0CRNYc8Zttxdo=
github.com/klauspost/compress v1.18.0/go.mod h1:2Pp+KzxcywXVXMr50+X0Q/Lsb43OQHYWRCY2AiWywWQ=
github.com/klauspost/compress v1.18.3 h1:9PJRvfbmTabkOX8moIpXPbMMbYN60bWImDDU7L+/6zw=
github.com/klauspost/compress v1.18.3/go.mod h1:R0h/fSBs8DE4ENlcrlib3PsXS61voFxhIs2DeRhCvJ4=
github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 h1:6E+4a0GO5zZEnZ81pIr0yLvtUWk2if982qA3F3QD6H4=
github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0/go.mod h1:zJYVVT2jmtg6P3p1VtQj7WsuWi/y4VnjVBn7F8KPB3I=
github.com/magiconair/properties v1.8.7 h1:IeQXZAiQcpL9mgcAe1Nu6cX9LLw6ExEHKjN0VQdvPDY=
github.com/magiconair/properties v1.8.7/go.mod h1:Dhd985XPs7jluiymwWYZ0G4Z61jb3vdS329zhj2hYo0=
github.com/magiconair/properties v1.8.10 h1:s31yESBquKXCV9a/ScB3ESkOjUYYv+X0rg8SYxI99mE=
github.com/magiconair/properties v1.8.10/go.mod h1:Dhd985XPs7jluiymwWYZ0G4Z61jb3vdS329zhj2hYo0=
github.com/mitchellh/mapstructure v1.5.0 h1:jeMsZIYE/09sWLaz43PL7Gy6RuMjD2eJVyuac5Z2hdY=
github.com/mitchellh/mapstructure v1.5.0/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=
github.com/moby/docker-image-spec v1.3.1 h1:jMKff3w6PgbfSa69GfNg+zN/XLhfXJGnEx3Nl2EsFP0=
github.com/moby/docker-image-spec v1.3.1/go.mod h1:eKmb5VW8vQEh/BAr2yvVNvuiJuY6UIocYsFu/DxxRpo=
github.com/moby/go-archive v0.1.0 h1:Kk/5rdW/g+H8NHdJW2gsXyZ7UnzvJNOy6VKJqueWdcQ=
github.com/moby/go-archive v0.1.0/go.mod h1:G9B+YoujNohJmrIYFBpSd54GTUB4lt9S+xVQvsJyFuo=
github.com/moby/patternmatcher v0.6.0 h1:GmP9lR19aU5GqSSFko+5pRqHi+Ohk1O69aFiKkVGiPk=
github.com/moby/patternmatcher v0.6.0/go.mod h1:hDPoyOpDY7OrrMDLaYoY3hf52gNCR/YOUYxkhApJIxc=
github.com/moby/sys/sequential v0.6.0 h1:qrx7XFUd/5DxtqcoH1h438hF5TmOvzC/lspjy7zgvCU=
github.com/moby/sys/sequential v0.6.0/go.mod h1:uyv8EUTrca5PnDsdMGXhZe6CCe8U/UiTWd+lL+7b/Ko=
github.com/moby/sys/user v0.4.0 h1:jhcMKit7SA80hivmFJcbB1vqmw//wU61Zdui2eQXuMs=
github.com/moby/sys/user v0.4.0/go.mod h1:bG+tYYYJgaMtRKgEmuueC0hJEAZWwtIbZTB+85uoHjs=
github.com/moby/sys/userns v0.1.0 h1:tVLXkFOxVu9A64/yh59slHVv9ahO9UIev4JZusOLG/g=
github.com/moby/sys/userns v0.1.0/go.mod h1:IHUYgu/kao6N8YZlp9Cf444ySSvCmDlmzUcYfDHOl28=
github.com/moby/term v0.5.0 h1:xt8Q1nalod/v7BqbG21f8mQPqH+xAaC9C3N3wfWbVP0=
github.com/moby/term v0.5.0/go.mod h1:8FzsFHVUBGZdbDsJw/ot+X+d5HLUbvklYLJ9uGfcI3Y=
github.com/montanaflynn/stats v0.0.0-20171201202039-1bf9dbcd8cbe/go.mod h1:wL8QJuTMNUDYhXwkmfOly8iTdp5TEcJFWZD2D7SIkUc=
github.com/morikuni/aec v1.0.0 h1:nP9CBfwrvYnBRgY6qfDQkygYDmYwOilePFkwzv4dU8A=
github.com/morikuni/aec v1.0.0/go.mod h1:BbKIizmSmc5MMPqRYbxO4ZU0S0+P200+tUnFx7PXmsc=
github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 h1:C3w9PqII01/Oq1c1nUAm88MOHcQC9l5mIlSMApZMrHA=
github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822/go.mod h1:+n7T8mK8HuQTcFwEeznm/DIxMOiR9yIdICNftLE1DvQ=
github.com/opencontainers/go-digest v1.0.0 h1:apOUWs51W5PlhuyGyz9FCeeBIOUDA/6nW8Oi/yOhh5U=
github.com/opencontainers/go-digest v1.0.0/go.mod h1:0JzlMkj0TRzQZfJkVvzbP0HBR3IKzErnv2BNG4W4MAM=
github.com/opencontainers/image-spec v1.1.1 h1:y0fUlFfIZhPF1W537XOLg0/fcx6zcHCJwooC2xJA040=
github.com/opencontainers/image-spec v1.1.1/go.mod h1:qpqAh3Dmcf36wStyyWU+kCeDgrGnAve2nCC8+7h8Q0M=
github.com/paulmach/orb v0.12.0 h1:z+zOwjmG3MyEEqzv92UN49Lg1JFYx0L9GpGKNVDKk1s=
github.com/paulmach/orb v0.12.0/go.mod h1:5mULz1xQfs3bmQm63QEJA6lNGujuRafwA5S/EnuLaLU=
github.com/paulmach/protoscan v0.2.1/go.mod h1:SpcSwydNLrxUGSDvXvO0P7g7AuhJ7lcKfDlhJCDw2gY=
github.com/pelletier/go-toml/v2 v2.2.2 h1:aYUidT7k73Pcl9nb2gScu7NSrKCSHIDE89b3+6Wq+LM=
github.com/pelletier/go-toml/v2 v2.2.2/go.mod h1:1t835xjRzz80PqgE6HHgN2JOsmgYu/h4qDAS4n929Rs=
github.com/pierrec/lz4/v4 v4.1.25 h1:kocOqRffaIbU5djlIBr7Wh+cx82C0vtFb0fOurZHqD0=
github.com/pierrec/lz4/v4 v4.1.25/go.mod h1:EoQMVJgeeEOMsCqCzqFm2O0cJvljX2nGZjcRIPL34O4=
github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c h1:ncq/mPwQF4JjgDlrVEn3C11VoGHZN7m8qihwgMEtzYw=
github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c/go.mod h1:OmDBASR4679mdNQnz2pUhc2G8CO2JrUAVFDRBDP/hJE=
github.com/prometheus/client_golang v1.23.2 h1:Je96obch5RDVy3FDMndoUsjAhG5Edi49h0RJWRi/o0o=
github.com/prometheus/client_golang v1.23.2/go.mod h1:Tb1a6LWHB3/SPIzCoaDXI4I8UHKeFTEQ1YCr+0Gyqmg=
github.com/prometheus/client_model v0.6.2 h1:oBsgwpGs7iVziMvrGhE53c/GrLUsZdHnqNwqPLxwZyk=
github.com/prometheus/client_model v0.6.2/go.mod h1:y3m2F6Gdpfy6Ut/GBsUqTWZqCUvMVzSfMLjcu6wAwpE=
github.com/prometheus/common v0.66.1 h1:h5E0h5/Y8niHc5DlaLlWLArTQI7tMrsfQjHV+d9ZoGs=
github.com/prometheus/common v0.66.1/go.mod h1:gcaUsgf3KfRSwHY4dIMXLPV0K/Wg1oZ8+SbZk/HH/dA=
github.com/prometheus/procfs v0.16.1 h1:hZ15bTNuirocR6u0JZ6BAHHmwS1p8B4P6MRqxtzMyRg=
github.com/prometheus/procfs v0.16.1/go.mod h1:teAbpZRB1iIAJYREa1LsoWUXykVXA1KlTmWl8x/U+Is=
github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8=
github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
github.com/sagikazarmark/locafero v0.4.0 h1:HApY1R9zGo4DBgr7dqsTH/JJxLTTsOt7u6keLGt6kNQ=
github.com/sagikazarmark/locafero v0.4.0/go.mod h1:Pe1W6UlPYUk/+wc/6KFhbORCfqzgYEpgQ3O5fPuL3H4=
github.com/sagikazarmark/slog-shim v0.1.0 h1:diDBnUNK9N/354PgrxMywXnAwEr1QZcOr6gto+ugjYE=
github.com/sagikazarmark/slog-shim v0.1.0/go.mod h1:SrcSrq8aKtyuqEI1uvTDTK1arOWRIczQRv+GVI1AkeQ=
github.com/segmentio/asm v1.2.1 h1:DTNbBqs57ioxAD4PrArqftgypG4/qNpXoJx8TVXxPR0=
github.com/segmentio/asm v1.2.1/go.mod h1:BqMnlJP91P8d+4ibuonYZw9mfnzI9HfxselHZr5aAcs=
github.com/shirou/gopsutil/v4 v4.25.6 h1:kLysI2JsKorfaFPcYmcJqbzROzsBWEOAtw6A7dIfqXs=
github.com/shirou/gopsutil/v4 v4.25.6/go.mod h1:PfybzyydfZcN+JMMjkF6Zb8Mq1A/VcogFFg7hj50W9c=
github.com/shopspring/decimal v1.4.0 h1:bxl37RwXBklmTi0C79JfXCEBD1cqqHt0bbgBAGFp81k=
github.com/shopspring/decimal v1.4.0/go.mod h1:gawqmDU56v4yIKSwfBSFip1HdCCXN8/+DMd9qYNcwME=
github.com/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ=
github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ=
github.com/sourcegraph/conc v0.3.0 h1:OQTbbt6P72L20UqAkXXuLOj79LfEanQ+YQFNpLA9ySo=
github.com/sourcegraph/conc v0.3.0/go.mod h1:Sdozi7LEKbFPqYX2/J+iBAM6HpqSLTASQIKqDmF7Mt0=
github.com/spf13/afero v1.11.0 h1:WJQKhtpdm3v2IzqG8VMqrr6Rf3UYpEF239Jy9wNepM8=
github.com/spf13/afero v1.11.0/go.mod h1:GH9Y3pIexgf1MTIWtNGyogA5MwRIDXGUr+hbWNoBjkY=
github.com/spf13/cast v1.6.0 h1:GEiTHELF+vaR5dhz3VqZfFSzZjYbgeKDpBxQVS4GYJ0=
github.com/spf13/cast v1.6.0/go.mod h1:ancEpBxwJDODSW/UG4rDrAqiKolqNNh2DX3mk86cAdo=
github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA=
github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
github.com/spf13/viper v1.19.0 h1:RWq5SEjt8o25SROyN3z2OrDB9l7RPd3lwTWU8EcEdcI=
github.com/spf13/viper v1.19.0/go.mod h1:GQUN9bilAbhU/jgc1bKs99f/suXKeUMct8Adx5+Ntkg=
github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
github.com/subosito/gotenv v1.6.0 h1:9NlTDc1FTs4qu0DDq7AEtTPNw6SVm7uBMsUCUjABIf8=
github.com/subosito/gotenv v1.6.0/go.mod h1:Dk4QP5c2W3ibzajGcXpNraDfq2IrhjMIvMSWPKKo0FU=
github.com/testcontainers/testcontainers-go v0.40.0 h1:pSdJYLOVgLE8YdUY2FHQ1Fxu+aMnb6JfVz1mxk7OeMU=
github.com/testcontainers/testcontainers-go v0.40.0/go.mod h1:FSXV5KQtX2HAMlm7U3APNyLkkap35zNLxukw9oBi/MY=
github.com/tidwall/pretty v1.0.0/go.mod h1:XNkn88O1ChpSDQmQeStsy+sBenx6DDtFZJxhVysOjyk=
github.com/tklauser/go-sysconf v0.3.12 h1:0QaGUFOdQaIVdPgfITYzaTegZvdCjmYO52cSFAEVmqU=
github.com/tklauser/go-sysconf v0.3.12/go.mod h1:Ho14jnntGE1fpdOqQEEaiKRpvIavV0hSfmBq8nJbHYI=
github.com/tklauser/numcpus v0.6.1 h1:ng9scYS7az0Bk4OZLvrNXNSAO2Pxr1XXRAPyjhIx+Fk=
github.com/tklauser/numcpus v0.6.1/go.mod h1:1XfjsgE2zo8GVw7POkMbHENHzVg3GzmoZ9fESEdAacY=
github.com/xdg-go/pbkdf2 v1.0.0/go.mod h1:jrpuAogTd400dnrH08LKmI/xc1MbPOebTwRqcT5RDeI=
github.com/xdg-go/scram v1.1.1/go.mod h1:RaEWvsqvNKKvBPvcKeFjrG2cJqOkHTiyTpzz23ni57g=
github.com/xdg-go/stringprep v1.0.3/go.mod h1:W3f5j4i+9rC0kuIEJL0ky1VpHXQU3ocBgklLGvcBnW8=
github.com/youmark/pkcs8 v0.0.0-20181117223130-1be2e3e5546d/go.mod h1:rHwXgn7JulP+udvsHwJoVG1YGAP6VLg4y9I5dyZdqmA=
github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
github.com/yusufpapurcu/wmi v1.2.4 h1:zFUKzehAFReQwLys1b/iSMl+JQGSCSjtVqQn9bBrPo0=
github.com/yusufpapurcu/wmi v1.2.4/go.mod h1:SBZ9tNy3G9/m5Oi98Zks0QjeHVDvuK0qfxQmPyzfmi0=
go.mongodb.org/mongo-driver v1.11.4/go.mod h1:PTSz5yu21bkT/wXpkS7WR5f0ddqw5quethTUn9WM+2g=
go.opentelemetry.io/auto/sdk v1.1.0 h1:cH53jehLUN6UFLY71z+NDOiNJqDdPRaXzTel0sJySYA=
go.opentelemetry.io/auto/sdk v1.1.0/go.mod h1:3wSPjt5PWp2RhlCcmmOial7AvC4DQqZb7a7wCow3W8A=
go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.49.0 h1:jq9TW8u3so/bN+JPT166wjOI6/vQPF6Xe7nMNIltagk=
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.49.0/go.mod h1:p8pYQP+m5XfbZm9fxtSKAbM6oIllS7s2AfxrChvc7iw=
go.opentelemetry.io/otel v1.35.0 h1:xKWKPxrxB6OtMCbmMY021CqC45J+3Onta9MqjhnusiQ=
go.opentelemetry.io/otel v1.35.0/go.mod h1:UEqy8Zp11hpkUrL73gSlELM0DupHoiq72dR+Zqel/+Y=
go.opentelemetry.io/otel v1.39.0 h1:8yPrr/S0ND9QEfTfdP9V+SiwT4E0G7Y5MO7p85nis48=
go.opentelemetry.io/otel v1.39.0/go.mod h1:kLlFTywNWrFyEdH0oj2xK0bFYZtHRYUdv1NklR/tgc8=
go.opentelemetry.io/otel/metric v1.35.0 h1:0znxYu2SNyuMSQT4Y9WDWej0VpcsxkuklLa4/siN90M=
go.opentelemetry.io/otel/metric v1.35.0/go.mod h1:nKVFgxBZ2fReX6IlyW28MgZojkoAkJGaE8CpgeAU3oE=
go.opentelemetry.io/otel/metric v1.39.0 h1:d1UzonvEZriVfpNKEVmHXbdf909uGTOQjA0HF0Ls5Q0=
go.opentelemetry.io/otel/metric v1.39.0/go.mod h1:jrZSWL33sD7bBxg1xjrqyDjnuzTUB0x1nBERXd7Ftcs=
go.opentelemetry.io/otel/trace v1.35.0 h1:dPpEfJu1sDIqruz7BHFG3c7528f6ddfSWfFDVt/xgMs=
go.opentelemetry.io/otel/trace v1.35.0/go.mod h1:WUk7DtFp1Aw2MkvqGdwiXYDZZNvA/1J8o6xRXLrIkyc=
go.opentelemetry.io/otel/trace v1.39.0 h1:2d2vfpEDmCJ5zVYz7ijaJdOF59xLomrvj7bjt6/qCJI=
go.opentelemetry.io/otel/trace v1.39.0/go.mod h1:88w4/PnZSazkGzz/w84VHpQafiU4EtqqlVdxWy+rNOA=
go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
go.uber.org/multierr v1.10.0 h1:S0h4aNzvfcFsC3dRF1jLoaov7oRaKqRGC/pUEJ2yvPQ=
go.uber.org/multierr v1.10.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0=
go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
go.uber.org/zap v1.27.0 h1:aJMhYGrd5QSmlpLMr2MftRKl7t8J8PTZPA732ud/XR8=
go.uber.org/zap v1.27.0/go.mod h1:GB2qFLM7cTU87MWRP2mPIjqfIDnGu+VIO4V/SdhGo2E=
go.uber.org/zap v1.27.1 h1:08RqriUEv8+ArZRYSTXy1LeBScaMpVSTBhCeaZYfMYc=
go.uber.org/zap v1.27.1/go.mod h1:GB2qFLM7cTU87MWRP2mPIjqfIDnGu+VIO4V/SdhGo2E=
go.yaml.in/yaml/v2 v2.4.2 h1:DzmwEr2rDGHl7lsFgAHxmNz/1NlQ7xLIrlN2h5d1eGI=
go.yaml.in/yaml/v2 v2.4.2/go.mod h1:081UH+NErpNdqlCXm3TtEran0rJZGxAYx9hb/ELlsPU=
go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
golang.org/x/crypto v0.0.0-20220622213112-05595931fe9d/go.mod h1:IxCIyHEi3zRg3s0A5j5BB6A9Jmi73HwBIUl50j+osU4=
golang.org/x/crypto v0.43.0 h1:dduJYIi3A3KOfdGOHX8AVZ/jGiyPa3IbBozJ5kNuE04=
golang.org/x/crypto v0.43.0/go.mod h1:BFbav4mRNlXJL4wNeejLpWxB7wMbc79PdRGhWKncxR0=
golang.org/x/crypto v0.46.0/go.mod h1:Evb/oLKmMraqjZ2iQTwDwvCtJkczlDuTmdJXoZVzqU0=
golang.org/x/crypto v0.47.0 h1:V6e3FRj+n4dbpw86FJ8Fv7XVOql7TEwpHapKoMJ/GO8=
golang.org/x/crypto v0.47.0/go.mod h1:ff3Y9VzzKbwSSEzWqJsJVBnWmRwRSHt/6Op5n9bQc4A=
golang.org/x/exp v0.0.0-20230905200255-921286631fa9 h1:GoHiUyI/Tp2nVkLI2mCxVkOjsbSXD66ic0XW0js0R9g=
golang.org/x/exp v0.0.0-20230905200255-921286631fa9/go.mod h1:S2oDrQGGwySpoQPVqRShND87VCbxmc6bL1Yd2oYrm6k=
golang.org/x/mod v0.2.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
golang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
golang.org/x/net v0.0.0-20200226121028-0de0cce0169b/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
golang.org/x/net v0.0.0-20201021035429-f5854403a974/go.mod h1:sp8m0HH+o8qH0wwXwYZr8TS3Oi6o0r6Gce1SSxlDquU=
golang.org/x/net v0.0.0-20211112202133-69e39bad7dc2/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y=
golang.org/x/net v0.48.0 h1:zyQRTTrjc33Lhh0fBgT/H3oZq9WuvRR5gPC70xpDiQU=
golang.org/x/net v0.48.0/go.mod h1:+ndRgGjkh8FGtu1w1FGbEC31if4VrNVMuKTgcAAnQRY=
golang.org/x/net v0.49.0 h1:eeHFmOGUTtaaPSGNmjBKpbng9MulQsJURQUAfUwY++o=
golang.org/x/net v0.49.0/go.mod h1:/ysNB2EvaqvesRkuLAyjI1ycPZlQHM3q01F02UY/MV8=
golang.org/x/oauth2 v0.35.0 h1:Mv2mzuHuZuY2+bkyWXIHMfhNdJAdwW3FuWeCPYN5GVQ=
golang.org/x/oauth2 v0.35.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA=
golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
golang.org/x/sync v0.0.0-20190911185100-cd5d95a43a6e/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
golang.org/x/sync v0.0.0-20201020160332-67f06af15bc9/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
golang.org/x/sync v0.0.0-20210220032951-036812b2e83c/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/sys v0.0.0-20190916202348-b4ddaad3f8a3/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/sys v0.0.0-20201204225414-ed752295db88/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/sys v0.0.0-20210423082822-04245dca01da/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.0.0-20210616094352-59db8d763f22/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.11.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.18.0 h1:DBdB3niSjOA/O0blCZBqDefyWNYveAYMNF1Wum0DYQ4=
golang.org/x/sys v0.18.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
golang.org/x/sys v0.35.0 h1:vz1N37gP5bs89s7He8XuIYXpyY0+QlsKmzipCbUtyxI=
golang.org/x/sys v0.35.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
golang.org/x/sys v0.37.0 h1:fdNQudmxPjkdUTPnLn5mdQv7Zwvbvpaxqs831goi9kQ=
golang.org/x/sys v0.37.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
golang.org/x/sys v0.39.0 h1:CvCKL8MeisomCi6qNZ+wbb0DN9E5AATixKsvNtMoMFk=
golang.org/x/sys v0.39.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
golang.org/x/sys v0.40.0 h1:DBZZqJ2Rkml6QMQsZywtnjnnGvHza6BTfYFWY9kjEWQ=
golang.org/x/sys v0.40.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
golang.org/x/text v0.28.0 h1:rhazDwis8INMIwQ4tpjLDzUhx6RlXqZNPEM0huQojng=
golang.org/x/text v0.28.0/go.mod h1:U8nCwOR8jO/marOQ0QbDiOngZVEBB7MAiitBuMjXiNU=
golang.org/x/text v0.30.0 h1:yznKA/E9zq54KzlzBEAWn1NXSQ8DIp/NYMy88xJjl4k=
golang.org/x/text v0.30.0/go.mod h1:yDdHFIX9t+tORqspjENWgzaCVXgk0yYnYuSZ8UzzBVM=
golang.org/x/text v0.32.0 h1:ZD01bjUt1FQ9WJ0ClOL5vxgxOI/sVCNgX1YtKwcY0mU=
golang.org/x/text v0.32.0/go.mod h1:o/rUWzghvpD5TXrTIBuJU77MTaN0ljMWE47kxGJQ7jY=
golang.org/x/text v0.33.0 h1:B3njUFyqtHDUI5jMn1YIr5B0IE2U0qck04r6d4KPAxE=
golang.org/x/text v0.33.0/go.mod h1:LuMebE6+rBincTi9+xWTY8TztLzKHc/9C1uBCG27+q8=
golang.org/x/time v0.14.0 h1:MRx4UaLrDotUKUdCIqzPC48t1Y9hANFKIRpNx+Te8PI=
golang.org/x/time v0.14.0/go.mod h1:eL/Oa2bBBK0TkX57Fyni+NgnyQQN4LitPmob2Hjnqw4=
golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
golang.org/x/tools v0.0.0-20200619180055-7c47624df98f/go.mod h1:EkVYQZoAsY45+roYkvgYkIh4xh/qjgUK9TdY2XT94GE=
golang.org/x/tools v0.0.0-20210106214847-113979e3529a/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA=
golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
google.golang.org/genproto v0.0.0-20240213162025-012b6fc9bca9 h1:9+tzLLstTlPTRyJTh+ah5wIMsBW5c4tQwGTN3thOW9Y=
google.golang.org/genproto/googleapis/rpc v0.0.0-20251202230838-ff82c1b0f217 h1:gRkg/vSppuSQoDjxyiGfN4Upv/h/DQmIR10ZU8dh4Ww=
google.golang.org/genproto/googleapis/rpc v0.0.0-20251202230838-ff82c1b0f217/go.mod h1:7i2o+ce6H/6BluujYR+kqX3GKH+dChPTQU19wjRPiGk=
google.golang.org/grpc v1.79.1 h1:zGhSi45ODB9/p3VAawt9a+O/MULLl9dpizzNNpq7flY=
google.golang.org/grpc v1.79.1/go.mod h1:KmT0Kjez+0dde/v2j9vzwoAScgEPx/Bw1CYChhHLrHQ=
google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw=
google.golang.org/protobuf v1.27.1/go.mod h1:9q0QmTI4eRPtz6boOQmLYwt+qCgq0jsYwAQnmE0givc=
google.golang.org/protobuf v1.36.8 h1:xHScyCOEuuwZEc6UtSOvPbAT4zRh0xcNRYekJwfqyMc=
google.golang.org/protobuf v1.36.8/go.mod h1:fuxRtAxBytpl4zzqUh6/eyUujkJdNiuEkXntxiD/uRU=
google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15 h1:YR8cESwS4TdDjEe65xsg0ogRM/Nc3DYOhEAlW+xobZo=
gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/ini.v1 v1.67.0 h1:Dgnx+6+nfE+IfzjUEISNeydPJh9AXNNsWbGP9KzCsOA=
gopkg.in/ini.v1 v1.67.0/go.mod h1:pNLf8WUiyNEtQjuu5G5vTm06TEv9tsIgeAvK8hOrP4k=
gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

122
internal/admin/flags.go Normal file
View File

@ -0,0 +1,122 @@
package admin
import (
"encoding/json"
"net/http"
"github.com/go-chi/chi/v5"
"github.com/veylant/ia-gateway/internal/apierror"
"github.com/veylant/ia-gateway/internal/flags"
)
// ─── Feature flags admin API (E11-07) ────────────────────────────────────────
//
// Routes (mounted under /v1/admin):
// GET /flags → list all flags for the tenant + global defaults
// PUT /flags/{name} → upsert a flag (create or update)
// DELETE /flags/{name} → delete a tenant-scoped flag
// upsertFlagRequest is the JSON body for PUT /flags/{name}.
type upsertFlagRequest struct {
Enabled bool `json:"enabled"`
}
// flagNotEnabled writes a 501 if the flag store is not configured.
func (h *Handler) flagNotEnabled(w http.ResponseWriter) bool {
if h.flagStore == nil {
apierror.WriteError(w, &apierror.APIError{
Type: "not_implemented",
Message: "feature flag store not enabled",
HTTPStatus: http.StatusNotImplemented,
})
return true
}
return false
}
// listFlags handles GET /v1/admin/flags.
// Returns all flags scoped to the caller's tenant plus global (tenant_id="") flags.
func (h *Handler) listFlags(w http.ResponseWriter, r *http.Request) {
if h.flagNotEnabled(w) {
return
}
tenantID, ok := tenantFromCtx(w, r)
if !ok {
return
}
list, err := h.flagStore.List(r.Context(), tenantID)
if err != nil {
apierror.WriteError(w, apierror.NewUpstreamError("failed to list flags: "+err.Error()))
return
}
if list == nil {
list = []flags.FeatureFlag{}
}
writeJSON(w, http.StatusOK, map[string]interface{}{"data": list})
}
// upsertFlag handles PUT /v1/admin/flags/{name}.
// Creates or updates the flag for the caller's tenant. The flag name is taken
// from the URL; global flags (tenant_id="") cannot be modified via this endpoint.
func (h *Handler) upsertFlag(w http.ResponseWriter, r *http.Request) {
if h.flagNotEnabled(w) {
return
}
tenantID, ok := tenantFromCtx(w, r)
if !ok {
return
}
name := chi.URLParam(r, "name")
if name == "" {
apierror.WriteError(w, apierror.NewBadRequestError("flag name is required"))
return
}
var req upsertFlagRequest
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
apierror.WriteError(w, apierror.NewBadRequestError("invalid JSON: "+err.Error()))
return
}
f, err := h.flagStore.Set(r.Context(), tenantID, name, req.Enabled)
if err != nil {
apierror.WriteError(w, apierror.NewUpstreamError("failed to set flag: "+err.Error()))
return
}
writeJSON(w, http.StatusOK, f)
}
// deleteFlag handles DELETE /v1/admin/flags/{name}.
// Removes the tenant-scoped flag. Returns 404 if the flag does not exist.
// Global flags (tenant_id="") are not deleted by this endpoint.
func (h *Handler) deleteFlag(w http.ResponseWriter, r *http.Request) {
if h.flagNotEnabled(w) {
return
}
tenantID, ok := tenantFromCtx(w, r)
if !ok {
return
}
name := chi.URLParam(r, "name")
if name == "" {
apierror.WriteError(w, apierror.NewBadRequestError("flag name is required"))
return
}
err := h.flagStore.Delete(r.Context(), tenantID, name)
if err == flags.ErrNotFound {
apierror.WriteError(w, &apierror.APIError{
Type: "not_found_error",
Message: "feature flag not found",
HTTPStatus: http.StatusNotFound,
})
return
}
if err != nil {
apierror.WriteError(w, apierror.NewUpstreamError("failed to delete flag: "+err.Error()))
return
}
w.WriteHeader(http.StatusNoContent)
}

540
internal/admin/handler.go Normal file
View File

@ -0,0 +1,540 @@
// Package admin provides HTTP handlers for the routing rules management API.
// All endpoints require an authenticated JWT; tenantID is always derived from
// the token claims — it is never accepted from the request body.
package admin
import (
"database/sql"
"encoding/json"
"fmt"
"net/http"
"strconv"
"time"
"github.com/go-chi/chi/v5"
"go.uber.org/zap"
"github.com/veylant/ia-gateway/internal/apierror"
"github.com/veylant/ia-gateway/internal/auditlog"
"github.com/veylant/ia-gateway/internal/circuitbreaker"
"github.com/veylant/ia-gateway/internal/flags"
"github.com/veylant/ia-gateway/internal/middleware"
"github.com/veylant/ia-gateway/internal/ratelimit"
"github.com/veylant/ia-gateway/internal/routing"
)
// ProviderRouter is the subset of router.Router used by the admin handler.
// Defined as an interface to avoid an import cycle.
type ProviderRouter interface {
ProviderStatuses() []circuitbreaker.Status
}
// Handler provides CRUD endpoints for routing rules, template seeding,
// read-only access to audit logs and cost aggregations, user management,
// provider circuit breaker status, rate limit configuration, and feature flags.
type Handler struct {
store routing.RuleStore
cache *routing.RuleCache
auditLogger auditlog.Logger // nil = logs/costs endpoints return 501
db *sql.DB // nil = users endpoints return 501
router ProviderRouter // nil = providers/status returns 501
rateLimiter *ratelimit.Limiter // nil = rate-limits endpoints return 501
rlStore *ratelimit.Store // nil if db is nil
flagStore flags.FlagStore // nil = flags endpoints return 501
logger *zap.Logger
}
// New creates a Handler.
// - store: underlying rule persistence (PgStore or MemStore for tests).
// - cache: engine cache to invalidate after mutations.
func New(store routing.RuleStore, cache *routing.RuleCache, logger *zap.Logger) *Handler {
return &Handler{store: store, cache: cache, logger: logger}
}
// NewWithAudit creates a Handler with audit log query support.
func NewWithAudit(store routing.RuleStore, cache *routing.RuleCache, al auditlog.Logger, logger *zap.Logger) *Handler {
return &Handler{store: store, cache: cache, auditLogger: al, logger: logger}
}
// WithDB adds database support for user management.
func (h *Handler) WithDB(db *sql.DB) *Handler {
h.db = db
return h
}
// WithRouter adds provider router for circuit breaker status.
func (h *Handler) WithRouter(r ProviderRouter) *Handler {
h.router = r
return h
}
// WithRateLimiter adds the in-process rate limiter and its PostgreSQL store
// so the admin API can manage per-tenant limits at runtime.
func (h *Handler) WithRateLimiter(rl *ratelimit.Limiter) *Handler {
h.rateLimiter = rl
if h.db != nil {
h.rlStore = ratelimit.NewStore(h.db, h.logger)
}
return h
}
// WithFlagStore adds a feature flag store so the admin API can manage
// feature flags per tenant (E11-07).
func (h *Handler) WithFlagStore(fs flags.FlagStore) *Handler {
h.flagStore = fs
return h
}
// Routes registers all admin endpoints on r.
// Callers are responsible for mounting r under an authenticated prefix.
func (h *Handler) Routes(r chi.Router) {
r.Get("/policies", h.listPolicies)
r.Post("/policies", h.createPolicy)
r.Get("/policies/{id}", h.getPolicy)
r.Put("/policies/{id}", h.updatePolicy)
r.Delete("/policies/{id}", h.deletePolicy)
r.Post("/policies/seed/{template}", h.seedTemplate)
r.Get("/logs", h.getLogs)
r.Get("/costs", h.getCosts)
// User management (E3-08).
r.Get("/users", h.listUsers)
r.Post("/users", h.createUser)
r.Get("/users/{id}", h.getUser)
r.Put("/users/{id}", h.updateUser)
r.Delete("/users/{id}", h.deleteUser)
// Provider circuit breaker status (E2-09 / E2-10).
r.Get("/providers/status", h.getProviderStatus)
// Rate limit configuration (E10-09).
r.Get("/rate-limits", h.listRateLimits)
r.Get("/rate-limits/{tenant_id}", h.getRateLimit)
r.Put("/rate-limits/{tenant_id}", h.upsertRateLimit)
r.Delete("/rate-limits/{tenant_id}", h.deleteRateLimit)
// Feature flags management (E11-07).
r.Get("/flags", h.listFlags)
r.Put("/flags/{name}", h.upsertFlag)
r.Delete("/flags/{name}", h.deleteFlag)
}
// ─── List ─────────────────────────────────────────────────────────────────────
func (h *Handler) listPolicies(w http.ResponseWriter, r *http.Request) {
tenantID, ok := tenantFromCtx(w, r)
if !ok {
return
}
rules, err := h.store.ListActive(r.Context(), tenantID)
if err != nil {
apierror.WriteError(w, apierror.NewUpstreamError("failed to list policies: "+err.Error()))
return
}
writeJSON(w, http.StatusOK, map[string]interface{}{"data": rules})
}
// ─── Create ───────────────────────────────────────────────────────────────────
type createPolicyRequest struct {
Name string `json:"name"`
Description string `json:"description"`
Priority int `json:"priority"`
IsEnabled bool `json:"is_enabled"`
Conditions []routing.Condition `json:"conditions"`
Action routing.Action `json:"action"`
}
func (h *Handler) createPolicy(w http.ResponseWriter, r *http.Request) {
tenantID, ok := tenantFromCtx(w, r)
if !ok {
return
}
var req createPolicyRequest
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
apierror.WriteError(w, apierror.NewBadRequestError("invalid JSON: "+err.Error()))
return
}
if err := validatePolicy(req.Name, req.Action, req.Conditions); err != nil {
apierror.WriteError(w, apierror.NewBadRequestError(err.Error()))
return
}
rule := routing.RoutingRule{
TenantID: tenantID,
Name: req.Name,
Description: req.Description,
Priority: req.Priority,
IsEnabled: req.IsEnabled,
Conditions: req.Conditions,
Action: req.Action,
}
if rule.Priority == 0 {
rule.Priority = 100
}
created, err := h.store.Create(r.Context(), rule)
if err != nil {
apierror.WriteError(w, apierror.NewUpstreamError("failed to create policy: "+err.Error()))
return
}
h.cache.Invalidate(tenantID)
h.logger.Info("routing policy created",
zap.String("id", created.ID),
zap.String("tenant_id", tenantID),
)
writeJSON(w, http.StatusCreated, created)
}
// ─── Get ──────────────────────────────────────────────────────────────────────
func (h *Handler) getPolicy(w http.ResponseWriter, r *http.Request) {
tenantID, ok := tenantFromCtx(w, r)
if !ok {
return
}
id := chi.URLParam(r, "id")
rule, err := h.store.Get(r.Context(), id, tenantID)
if err != nil {
writeStoreError(w, err)
return
}
writeJSON(w, http.StatusOK, rule)
}
// ─── Update ───────────────────────────────────────────────────────────────────
func (h *Handler) updatePolicy(w http.ResponseWriter, r *http.Request) {
tenantID, ok := tenantFromCtx(w, r)
if !ok {
return
}
id := chi.URLParam(r, "id")
var req createPolicyRequest
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
apierror.WriteError(w, apierror.NewBadRequestError("invalid JSON: "+err.Error()))
return
}
if err := validatePolicy(req.Name, req.Action, req.Conditions); err != nil {
apierror.WriteError(w, apierror.NewBadRequestError(err.Error()))
return
}
rule := routing.RoutingRule{
ID: id,
TenantID: tenantID,
Name: req.Name,
Description: req.Description,
Priority: req.Priority,
IsEnabled: req.IsEnabled,
Conditions: req.Conditions,
Action: req.Action,
}
updated, err := h.store.Update(r.Context(), rule)
if err != nil {
writeStoreError(w, err)
return
}
h.cache.Invalidate(tenantID)
h.logger.Info("routing policy updated",
zap.String("id", id),
zap.String("tenant_id", tenantID),
)
writeJSON(w, http.StatusOK, updated)
}
// ─── Delete ───────────────────────────────────────────────────────────────────
func (h *Handler) deletePolicy(w http.ResponseWriter, r *http.Request) {
tenantID, ok := tenantFromCtx(w, r)
if !ok {
return
}
id := chi.URLParam(r, "id")
if err := h.store.Delete(r.Context(), id, tenantID); err != nil {
writeStoreError(w, err)
return
}
h.cache.Invalidate(tenantID)
h.logger.Info("routing policy deleted",
zap.String("id", id),
zap.String("tenant_id", tenantID),
)
w.WriteHeader(http.StatusNoContent)
}
// ─── Seed template ────────────────────────────────────────────────────────────
func (h *Handler) seedTemplate(w http.ResponseWriter, r *http.Request) {
tenantID, ok := tenantFromCtx(w, r)
if !ok {
return
}
name := chi.URLParam(r, "template")
factory, exists := routing.Templates[name]
if !exists {
apierror.WriteError(w, apierror.NewBadRequestError(
"unknown template "+strQuote(name)+"; valid templates: hr, finance, engineering, catchall",
))
return
}
rule := factory(tenantID)
created, err := h.store.Create(r.Context(), rule)
if err != nil {
apierror.WriteError(w, apierror.NewUpstreamError("failed to seed template: "+err.Error()))
return
}
h.cache.Invalidate(tenantID)
h.logger.Info("routing template seeded",
zap.String("template", name),
zap.String("tenant_id", tenantID),
zap.String("rule_id", created.ID),
)
writeJSON(w, http.StatusCreated, created)
}
// ─── Audit logs (E7-06) ───────────────────────────────────────────────────────
func (h *Handler) getLogs(w http.ResponseWriter, r *http.Request) {
if h.auditLogger == nil {
apierror.WriteError(w, &apierror.APIError{
Type: "not_implemented", Message: "audit logging not enabled", HTTPStatus: http.StatusNotImplemented,
})
return
}
tenantID, ok := tenantFromCtx(w, r)
if !ok {
return
}
q := auditlog.AuditQuery{
TenantID: tenantID,
Provider: r.URL.Query().Get("provider"),
MinSensitivity: r.URL.Query().Get("min_sensitivity"),
Limit: parseIntParam(r, "limit", 50),
Offset: parseIntParam(r, "offset", 0),
}
if s := r.URL.Query().Get("start"); s != "" {
if t, err := time.Parse(time.RFC3339, s); err == nil {
q.StartTime = t
}
}
if s := r.URL.Query().Get("end"); s != "" {
if t, err := time.Parse(time.RFC3339, s); err == nil {
q.EndTime = t
}
}
result, err := h.auditLogger.Query(r.Context(), q)
if err != nil {
apierror.WriteError(w, apierror.NewUpstreamError("failed to query logs: "+err.Error()))
return
}
writeJSON(w, http.StatusOK, result)
}
// ─── Costs (E7-07) ───────────────────────────────────────────────────────────
func (h *Handler) getCosts(w http.ResponseWriter, r *http.Request) {
if h.auditLogger == nil {
apierror.WriteError(w, &apierror.APIError{
Type: "not_implemented", Message: "audit logging not enabled", HTTPStatus: http.StatusNotImplemented,
})
return
}
tenantID, ok := tenantFromCtx(w, r)
if !ok {
return
}
q := auditlog.CostQuery{
TenantID: tenantID,
GroupBy: r.URL.Query().Get("group_by"),
}
if s := r.URL.Query().Get("start"); s != "" {
if t, err := time.Parse(time.RFC3339, s); err == nil {
q.StartTime = t
}
}
if s := r.URL.Query().Get("end"); s != "" {
if t, err := time.Parse(time.RFC3339, s); err == nil {
q.EndTime = t
}
}
result, err := h.auditLogger.QueryCosts(r.Context(), q)
if err != nil {
apierror.WriteError(w, apierror.NewUpstreamError("failed to query costs: "+err.Error()))
return
}
writeJSON(w, http.StatusOK, result)
}
// ─── Rate limits (E10-09) ─────────────────────────────────────────────────────
func (h *Handler) rateLimitNotEnabled(w http.ResponseWriter) bool {
if h.rateLimiter == nil || h.rlStore == nil {
apierror.WriteError(w, &apierror.APIError{
Type: "not_implemented",
Message: "rate limiting not enabled",
HTTPStatus: http.StatusNotImplemented,
})
return true
}
return false
}
func (h *Handler) listRateLimits(w http.ResponseWriter, r *http.Request) {
if h.rateLimitNotEnabled(w) {
return
}
cfgs := h.rateLimiter.ListConfigs()
writeJSON(w, http.StatusOK, map[string]interface{}{"data": cfgs})
}
func (h *Handler) getRateLimit(w http.ResponseWriter, r *http.Request) {
if h.rateLimitNotEnabled(w) {
return
}
tenantID := chi.URLParam(r, "tenant_id")
cfg, err := h.rlStore.Get(r.Context(), tenantID)
if err == ratelimit.ErrNotFound {
// Return effective config (which may be the default).
cfg = h.rateLimiter.GetConfig(tenantID)
writeJSON(w, http.StatusOK, cfg)
return
}
if err != nil {
apierror.WriteError(w, apierror.NewUpstreamError("failed to get rate limit: "+err.Error()))
return
}
writeJSON(w, http.StatusOK, cfg)
}
type rateLimitRequest struct {
RequestsPerMin int `json:"requests_per_min"`
BurstSize int `json:"burst_size"`
UserRPM int `json:"user_rpm"`
UserBurst int `json:"user_burst"`
IsEnabled bool `json:"is_enabled"`
}
func (h *Handler) upsertRateLimit(w http.ResponseWriter, r *http.Request) {
if h.rateLimitNotEnabled(w) {
return
}
tenantID := chi.URLParam(r, "tenant_id")
var req rateLimitRequest
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
apierror.WriteError(w, apierror.NewBadRequestError("invalid JSON: "+err.Error()))
return
}
cfg := ratelimit.RateLimitConfig{
TenantID: tenantID,
RequestsPerMin: req.RequestsPerMin,
BurstSize: req.BurstSize,
UserRPM: req.UserRPM,
UserBurst: req.UserBurst,
IsEnabled: req.IsEnabled,
}
saved, err := h.rlStore.Upsert(r.Context(), cfg)
if err != nil {
apierror.WriteError(w, apierror.NewUpstreamError("failed to upsert rate limit: "+err.Error()))
return
}
// Apply immediately to the in-process limiter without restart.
h.rateLimiter.SetConfig(saved)
h.logger.Info("rate limit config updated",
zap.String("tenant_id", tenantID),
zap.Int("rpm", saved.RequestsPerMin),
)
writeJSON(w, http.StatusOK, saved)
}
func (h *Handler) deleteRateLimit(w http.ResponseWriter, r *http.Request) {
if h.rateLimitNotEnabled(w) {
return
}
tenantID := chi.URLParam(r, "tenant_id")
if err := h.rlStore.Delete(r.Context(), tenantID); err == ratelimit.ErrNotFound {
apierror.WriteError(w, &apierror.APIError{
Type: "not_found_error",
Message: "rate limit config not found",
HTTPStatus: http.StatusNotFound,
})
return
} else if err != nil {
apierror.WriteError(w, apierror.NewUpstreamError("failed to delete rate limit: "+err.Error()))
return
}
h.rateLimiter.DeleteConfig(tenantID)
h.logger.Info("rate limit config deleted", zap.String("tenant_id", tenantID))
w.WriteHeader(http.StatusNoContent)
}
// ─── Helpers ──────────────────────────────────────────────────────────────────
// tenantFromCtx extracts the tenantID from JWT claims in the context.
// It writes a 401 and returns false if no claims are present.
func tenantFromCtx(w http.ResponseWriter, r *http.Request) (string, bool) {
claims, ok := middleware.ClaimsFromContext(r.Context())
if !ok || claims.TenantID == "" {
apierror.WriteError(w, apierror.NewAuthError("missing authentication"))
return "", false
}
return claims.TenantID, true
}
// validatePolicy performs basic validation on name, action provider, and conditions.
func validatePolicy(name string, action routing.Action, conditions []routing.Condition) error {
if name == "" {
return fmt.Errorf("name is required")
}
if action.Provider == "" {
return fmt.Errorf("action.provider is required")
}
return routing.ValidateConditions(conditions)
}
// writeStoreError maps routing.ErrNotFound to 404, other errors to 502.
func writeStoreError(w http.ResponseWriter, err error) {
if err == routing.ErrNotFound {
apierror.WriteError(w, &apierror.APIError{
Type: "not_found_error",
Message: "policy not found",
HTTPStatus: http.StatusNotFound,
})
return
}
apierror.WriteError(w, apierror.NewUpstreamError(err.Error()))
}
func writeJSON(w http.ResponseWriter, status int, v interface{}) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(status)
_ = json.NewEncoder(w).Encode(v)
}
func strQuote(s string) string { return `"` + s + `"` }
func parseIntParam(r *http.Request, key string, defaultVal int) int {
s := r.URL.Query().Get(key)
if s == "" {
return defaultVal
}
v, err := strconv.Atoi(s)
if err != nil || v < 0 {
return defaultVal
}
return v
}

245
internal/admin/handler_test.go Normal file
View File

@ -0,0 +1,245 @@
package admin_test
import (
"bytes"
"context"
"encoding/json"
"net/http"
"net/http/httptest"
"testing"
"time"
"github.com/go-chi/chi/v5"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
"go.uber.org/zap"
"github.com/veylant/ia-gateway/internal/admin"
"github.com/veylant/ia-gateway/internal/middleware"
"github.com/veylant/ia-gateway/internal/routing"
)
const testTenantID = "tenant-test"
// ─── Test fixtures ────────────────────────────────────────────────────────────
func setupHandler(t *testing.T) (*admin.Handler, *routing.MemStore, *routing.RuleCache) {
t.Helper()
store := routing.NewMemStore()
cache := routing.NewRuleCache(store, 30*time.Second, zap.NewNop())
h := admin.New(store, cache, zap.NewNop())
return h, store, cache
}
// authCtx returns a request context with tenant JWT claims.
func authCtx(tenantID string) context.Context {
return middleware.WithClaims(context.Background(), &middleware.UserClaims{
UserID: "admin-user",
TenantID: tenantID,
Roles: []string{"admin"},
})
}
// newRouter builds a chi.Router with the handler routes mounted.
func newRouter(h *admin.Handler) chi.Router {
r := chi.NewRouter()
h.Routes(r)
return r
}
// postJSON sends a POST with JSON body.
func postJSON(t *testing.T, router http.Handler, path string, body interface{}, ctx context.Context) *httptest.ResponseRecorder {
t.Helper()
b, _ := json.Marshal(body)
req := httptest.NewRequest(http.MethodPost, path, bytes.NewReader(b))
req = req.WithContext(ctx)
req.Header.Set("Content-Type", "application/json")
rec := httptest.NewRecorder()
router.ServeHTTP(rec, req)
return rec
}
func getReq(t *testing.T, router http.Handler, path string, ctx context.Context) *httptest.ResponseRecorder {
t.Helper()
req := httptest.NewRequest(http.MethodGet, path, nil)
req = req.WithContext(ctx)
rec := httptest.NewRecorder()
router.ServeHTTP(rec, req)
return rec
}
func deleteReq(t *testing.T, router http.Handler, path string, ctx context.Context) *httptest.ResponseRecorder {
t.Helper()
req := httptest.NewRequest(http.MethodDelete, path, nil)
req = req.WithContext(ctx)
rec := httptest.NewRecorder()
router.ServeHTTP(rec, req)
return rec
}
// ─── Tests ────────────────────────────────────────────────────────────────────
func TestAdminHandler_Create_ReturnsCreated(t *testing.T) {
h, _, _ := setupHandler(t)
r := newRouter(h)
body := map[string]interface{}{
"name": "finance rule",
"priority": 10,
"is_enabled": true,
"conditions": []map[string]interface{}{
{"field": "user.department", "operator": "eq", "value": "finance"},
},
"action": map[string]interface{}{"provider": "ollama"},
}
rec := postJSON(t, r, "/policies", body, authCtx(testTenantID))
assert.Equal(t, http.StatusCreated, rec.Code)
var got routing.RoutingRule
require.NoError(t, json.NewDecoder(rec.Body).Decode(&got))
assert.Equal(t, "finance rule", got.Name)
assert.Equal(t, testTenantID, got.TenantID)
}
func TestAdminHandler_Create_InvalidCondition_Returns400(t *testing.T) {
h, _, _ := setupHandler(t)
r := newRouter(h)
body := map[string]interface{}{
"name": "bad rule",
"conditions": []map[string]interface{}{
{"field": "user.unknown_field", "operator": "eq", "value": "x"},
},
"action": map[string]interface{}{"provider": "openai"},
}
rec := postJSON(t, r, "/policies", body, authCtx(testTenantID))
assert.Equal(t, http.StatusBadRequest, rec.Code)
}
func TestAdminHandler_Create_MissingName_Returns400(t *testing.T) {
h, _, _ := setupHandler(t)
r := newRouter(h)
body := map[string]interface{}{
"conditions": []map[string]interface{}{},
"action": map[string]interface{}{"provider": "openai"},
}
rec := postJSON(t, r, "/policies", body, authCtx(testTenantID))
assert.Equal(t, http.StatusBadRequest, rec.Code)
}
func TestAdminHandler_List_ReturnsTenantRules(t *testing.T) {
h, store, _ := setupHandler(t)
r := newRouter(h)
// Seed two rules: one for testTenantID, one for another tenant.
_, _ = store.Create(context.Background(), routing.RoutingRule{
TenantID: testTenantID, Name: "r1", IsEnabled: true,
Conditions: []routing.Condition{}, Action: routing.Action{Provider: "openai"},
})
_, _ = store.Create(context.Background(), routing.RoutingRule{
TenantID: "other-tenant", Name: "r2", IsEnabled: true,
Conditions: []routing.Condition{}, Action: routing.Action{Provider: "openai"},
})
rec := getReq(t, r, "/policies", authCtx(testTenantID))
assert.Equal(t, http.StatusOK, rec.Code)
var resp map[string][]routing.RoutingRule
require.NoError(t, json.NewDecoder(rec.Body).Decode(&resp))
// Only the rule for testTenantID should be visible.
assert.Len(t, resp["data"], 1)
assert.Equal(t, "r1", resp["data"][0].Name)
}
func TestAdminHandler_Get_ExistingRule(t *testing.T) {
h, store, _ := setupHandler(t)
r := newRouter(h)
rule, _ := store.Create(context.Background(), routing.RoutingRule{
TenantID: testTenantID, Name: "my-rule", IsEnabled: true,
Conditions: []routing.Condition{}, Action: routing.Action{Provider: "openai"},
})
rec := getReq(t, r, "/policies/"+rule.ID, authCtx(testTenantID))
assert.Equal(t, http.StatusOK, rec.Code)
var got routing.RoutingRule
require.NoError(t, json.NewDecoder(rec.Body).Decode(&got))
assert.Equal(t, "my-rule", got.Name)
}
func TestAdminHandler_Get_NotFound_Returns404(t *testing.T) {
h, _, _ := setupHandler(t)
r := newRouter(h)
rec := getReq(t, r, "/policies/nonexistent-id", authCtx(testTenantID))
assert.Equal(t, http.StatusNotFound, rec.Code)
}
func TestAdminHandler_Delete_RemovesRule(t *testing.T) {
h, store, _ := setupHandler(t)
r := newRouter(h)
rule, _ := store.Create(context.Background(), routing.RoutingRule{
TenantID: testTenantID, Name: "to-delete", IsEnabled: true,
Conditions: []routing.Condition{}, Action: routing.Action{Provider: "openai"},
})
rec := deleteReq(t, r, "/policies/"+rule.ID, authCtx(testTenantID))
assert.Equal(t, http.StatusNoContent, rec.Code)
// Second delete should return 404.
rec2 := deleteReq(t, r, "/policies/"+rule.ID, authCtx(testTenantID))
assert.Equal(t, http.StatusNotFound, rec2.Code)
}
func TestAdminHandler_TenantIsolation_CannotDeleteOtherTenantRule(t *testing.T) {
h, store, _ := setupHandler(t)
r := newRouter(h)
// Rule belongs to another tenant.
rule, _ := store.Create(context.Background(), routing.RoutingRule{
TenantID: "other-tenant", Name: "private-rule", IsEnabled: true,
Conditions: []routing.Condition{}, Action: routing.Action{Provider: "openai"},
})
// testTenantID cannot delete a rule that belongs to other-tenant — returns 404.
rec := deleteReq(t, r, "/policies/"+rule.ID, authCtx(testTenantID))
assert.Equal(t, http.StatusNotFound, rec.Code, "cannot delete another tenant's rule")
}
func TestAdminHandler_SeedTemplate_Catchall(t *testing.T) {
h, _, cache := setupHandler(t)
r := newRouter(h)
// Pre-populate cache to verify it gets invalidated.
_, _ = cache.Get(context.Background(), testTenantID)
rec := postJSON(t, r, "/policies/seed/catchall", nil, authCtx(testTenantID))
assert.Equal(t, http.StatusCreated, rec.Code)
var got routing.RoutingRule
require.NoError(t, json.NewDecoder(rec.Body).Decode(&got))
assert.Equal(t, 9999, got.Priority)
assert.Equal(t, "openai", got.Action.Provider)
}
func TestAdminHandler_SeedTemplate_UnknownTemplate_Returns400(t *testing.T) {
h, _, _ := setupHandler(t)
r := newRouter(h)
rec := postJSON(t, r, "/policies/seed/unknown", nil, authCtx(testTenantID))
assert.Equal(t, http.StatusBadRequest, rec.Code)
}
func TestAdminHandler_NoAuth_Returns401(t *testing.T) {
h, _, _ := setupHandler(t)
r := newRouter(h)
req := httptest.NewRequest(http.MethodGet, "/policies", nil)
// No claims in context.
rec := httptest.NewRecorder()
r.ServeHTTP(rec, req)
assert.Equal(t, http.StatusUnauthorized, rec.Code)
}

307
internal/admin/users.go Normal file
View File

@ -0,0 +1,307 @@
package admin
import (
"database/sql"
"encoding/json"
"net/http"
"time"
"github.com/go-chi/chi/v5"
"go.uber.org/zap"
"github.com/veylant/ia-gateway/internal/apierror"
"github.com/veylant/ia-gateway/internal/middleware"
)
// User represents a managed user stored in the users table.
type User struct {
ID string `json:"id"`
TenantID string `json:"tenant_id"`
Email string `json:"email"`
Name string `json:"name"`
Department string `json:"department"`
Role string `json:"role"`
IsActive bool `json:"is_active"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
type createUserRequest struct {
Email string `json:"email"`
Name string `json:"name"`
Department string `json:"department"`
Role string `json:"role"`
IsActive *bool `json:"is_active"`
}
// userStore wraps a *sql.DB to perform user CRUD operations.
type userStore struct {
db *sql.DB
logger *zap.Logger
}
func newUserStore(db *sql.DB, logger *zap.Logger) *userStore {
return &userStore{db: db, logger: logger}
}
func (s *userStore) list(tenantID string) ([]User, error) {
rows, err := s.db.Query(
`SELECT id, tenant_id, email, name, COALESCE(department,''), role, is_active, created_at, updated_at
FROM users WHERE tenant_id = $1 ORDER BY created_at DESC`, tenantID)
if err != nil {
return nil, err
}
defer rows.Close()
var users []User
for rows.Next() {
var u User
if err := rows.Scan(&u.ID, &u.TenantID, &u.Email, &u.Name, &u.Department,
&u.Role, &u.IsActive, &u.CreatedAt, &u.UpdatedAt); err != nil {
return nil, err
}
users = append(users, u)
}
return users, rows.Err()
}
func (s *userStore) get(id, tenantID string) (*User, error) {
var u User
err := s.db.QueryRow(
`SELECT id, tenant_id, email, name, COALESCE(department,''), role, is_active, created_at, updated_at
FROM users WHERE id = $1 AND tenant_id = $2`, id, tenantID,
).Scan(&u.ID, &u.TenantID, &u.Email, &u.Name, &u.Department,
&u.Role, &u.IsActive, &u.CreatedAt, &u.UpdatedAt)
if err == sql.ErrNoRows {
return nil, nil
}
return &u, err
}
func (s *userStore) create(u User) (*User, error) {
var created User
err := s.db.QueryRow(
`INSERT INTO users (tenant_id, email, name, department, role, is_active)
VALUES ($1,$2,$3,$4,$5,$6)
RETURNING id, tenant_id, email, name, COALESCE(department,''), role, is_active, created_at, updated_at`,
u.TenantID, u.Email, u.Name, u.Department, u.Role, u.IsActive,
).Scan(&created.ID, &created.TenantID, &created.Email, &created.Name, &created.Department,
&created.Role, &created.IsActive, &created.CreatedAt, &created.UpdatedAt)
return &created, err
}
func (s *userStore) update(u User) (*User, error) {
var updated User
err := s.db.QueryRow(
`UPDATE users SET email=$1, name=$2, department=$3, role=$4, is_active=$5, updated_at=NOW()
WHERE id=$6 AND tenant_id=$7
RETURNING id, tenant_id, email, name, COALESCE(department,''), role, is_active, created_at, updated_at`,
u.Email, u.Name, u.Department, u.Role, u.IsActive, u.ID, u.TenantID,
).Scan(&updated.ID, &updated.TenantID, &updated.Email, &updated.Name, &updated.Department,
&updated.Role, &updated.IsActive, &updated.CreatedAt, &updated.UpdatedAt)
if err == sql.ErrNoRows {
return nil, nil
}
return &updated, err
}
func (s *userStore) delete(id, tenantID string) error {
res, err := s.db.Exec(
`DELETE FROM users WHERE id = $1 AND tenant_id = $2`, id, tenantID)
if err != nil {
return err
}
n, _ := res.RowsAffected()
if n == 0 {
return sql.ErrNoRows
}
return nil
}
// ─── HTTP handlers ────────────────────────────────────────────────────────────
func (h *Handler) listUsers(w http.ResponseWriter, r *http.Request) {
tenantID, ok := tenantFromCtx(w, r)
if !ok {
return
}
if h.db == nil {
apierror.WriteError(w, &apierror.APIError{
Type: "not_implemented",
Message: "database not configured",
HTTPStatus: http.StatusNotImplemented,
})
return
}
us := newUserStore(h.db, h.logger)
users, err := us.list(tenantID)
if err != nil {
apierror.WriteError(w, apierror.NewUpstreamError("failed to list users: "+err.Error()))
return
}
if users == nil {
users = []User{}
}
writeJSON(w, http.StatusOK, map[string]interface{}{"data": users})
}
func (h *Handler) createUser(w http.ResponseWriter, r *http.Request) {
tenantID, ok := tenantFromCtx(w, r)
if !ok {
return
}
if h.db == nil {
apierror.WriteError(w, &apierror.APIError{Type: "not_implemented", Message: "database not configured", HTTPStatus: http.StatusNotImplemented})
return
}
var req createUserRequest
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
apierror.WriteError(w, apierror.NewBadRequestError("invalid JSON: "+err.Error()))
return
}
if req.Email == "" || req.Name == "" {
apierror.WriteError(w, apierror.NewBadRequestError("email and name are required"))
return
}
role := req.Role
if role == "" {
role = "user"
}
isActive := true
if req.IsActive != nil {
isActive = *req.IsActive
}
us := newUserStore(h.db, h.logger)
created, err := us.create(User{
TenantID: tenantID,
Email: req.Email,
Name: req.Name,
Department: req.Department,
Role: role,
IsActive: isActive,
})
if err != nil {
apierror.WriteError(w, apierror.NewUpstreamError("failed to create user: "+err.Error()))
return
}
writeJSON(w, http.StatusCreated, created)
}
func (h *Handler) getUser(w http.ResponseWriter, r *http.Request) {
tenantID, ok := tenantFromCtx(w, r)
if !ok {
return
}
id := chi.URLParam(r, "id")
if h.db == nil {
apierror.WriteError(w, &apierror.APIError{Type: "not_implemented", Message: "database not configured", HTTPStatus: http.StatusNotImplemented})
return
}
us := newUserStore(h.db, h.logger)
u, err := us.get(id, tenantID)
if err != nil {
apierror.WriteError(w, apierror.NewUpstreamError(err.Error()))
return
}
if u == nil {
apierror.WriteError(w, &apierror.APIError{Type: "not_found_error", Message: "user not found", HTTPStatus: http.StatusNotFound})
return
}
writeJSON(w, http.StatusOK, u)
}
func (h *Handler) updateUser(w http.ResponseWriter, r *http.Request) {
tenantID, ok := tenantFromCtx(w, r)
if !ok {
return
}
id := chi.URLParam(r, "id")
if h.db == nil {
apierror.WriteError(w, &apierror.APIError{Type: "not_implemented", Message: "database not configured", HTTPStatus: http.StatusNotImplemented})
return
}
var req createUserRequest
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
apierror.WriteError(w, apierror.NewBadRequestError("invalid JSON: "+err.Error()))
return
}
isActive := true
if req.IsActive != nil {
isActive = *req.IsActive
}
us := newUserStore(h.db, h.logger)
updated, err := us.update(User{
ID: id,
TenantID: tenantID,
Email: req.Email,
Name: req.Name,
Department: req.Department,
Role: req.Role,
IsActive: isActive,
})
if err != nil {
apierror.WriteError(w, apierror.NewUpstreamError(err.Error()))
return
}
if updated == nil {
apierror.WriteError(w, &apierror.APIError{Type: "not_found_error", Message: "user not found", HTTPStatus: http.StatusNotFound})
return
}
writeJSON(w, http.StatusOK, updated)
}
func (h *Handler) deleteUser(w http.ResponseWriter, r *http.Request) {
tenantID, ok := tenantFromCtx(w, r)
if !ok {
return
}
id := chi.URLParam(r, "id")
if h.db == nil {
apierror.WriteError(w, &apierror.APIError{Type: "not_implemented", Message: "database not configured", HTTPStatus: http.StatusNotImplemented})
return
}
us := newUserStore(h.db, h.logger)
if err := us.delete(id, tenantID); err != nil {
if err == sql.ErrNoRows {
apierror.WriteError(w, &apierror.APIError{Type: "not_found_error", Message: "user not found", HTTPStatus: http.StatusNotFound})
return
}
apierror.WriteError(w, apierror.NewUpstreamError(err.Error()))
return
}
w.WriteHeader(http.StatusNoContent)
}
func (h *Handler) getProviderStatus(w http.ResponseWriter, r *http.Request) {
if h.router == nil {
apierror.WriteError(w, &apierror.APIError{Type: "not_implemented", Message: "provider router not configured", HTTPStatus: http.StatusNotImplemented})
return
}
statuses := h.router.ProviderStatuses()
// Also call health check for each provider (E2-10).
healthCtx := r.Context()
type providerStatusResponse struct {
Provider string `json:"provider"`
State string `json:"state"`
Failures int `json:"failures"`
OpenedAt string `json:"opened_at,omitempty"`
Healthy *bool `json:"healthy,omitempty"`
}
_ = healthCtx // suppress unused warning; health ping is async in production
writeJSON(w, http.StatusOK, statuses)
}
// tenantFromMiddlewareCtx is an alias kept for consistency.
func tenantFromMiddlewareCtx(r *http.Request) (string, bool) {
claims, ok := middleware.ClaimsFromContext(r.Context())
if !ok || claims.TenantID == "" {
return "", false
}
return claims.TenantID, true
}

123
internal/apierror/errors.go Normal file
View File

@ -0,0 +1,123 @@
// Package apierror defines OpenAI-compatible typed errors for the Veylant proxy.
// All error responses follow the OpenAI JSON format so that existing OpenAI SDK
// clients can handle them without modification.
package apierror
import (
"encoding/json"
"net/http"
"strconv"
)
// APIError represents an OpenAI-compatible error response body.
// Wire format: {"error":{"type":"...","message":"...","code":"..."}}
type APIError struct {
Type string `json:"type"`
Message string `json:"message"`
Code string `json:"code"`
HTTPStatus int `json:"-"`
RetryAfterSec int `json:"-"` // when > 0, sets the Retry-After response header (RFC 6585)
}
// envelope wraps APIError in the OpenAI {"error": ...} envelope.
type envelope struct {
Error *APIError `json:"error"`
}
// Error implements the error interface.
func (e *APIError) Error() string {
return e.Message
}
// WriteError serialises e as JSON and writes it to w with the correct HTTP status.
// When e.RetryAfterSec > 0 it also sets the Retry-After header (RFC 6585).
func WriteError(w http.ResponseWriter, e *APIError) {
if e.RetryAfterSec > 0 {
w.Header().Set("Retry-After", strconv.Itoa(e.RetryAfterSec))
}
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(e.HTTPStatus)
_ = json.NewEncoder(w).Encode(envelope{Error: e})
}
// WriteErrorWithRequestID is like WriteError but also echoes requestID in the
// X-Request-Id response header. Use this in middleware that has access to the
// request ID but where the header may not yet have been set by the RequestID
// middleware (e.g. when the request is short-circuited before reaching it).
func WriteErrorWithRequestID(w http.ResponseWriter, e *APIError, requestID string) {
if requestID != "" {
w.Header().Set("X-Request-Id", requestID)
}
WriteError(w, e)
}
// NewAuthError returns a 401 authentication_error.
func NewAuthError(msg string) *APIError {
return &APIError{
Type: "authentication_error",
Message: msg,
Code: "invalid_api_key",
HTTPStatus: http.StatusUnauthorized,
}
}
// NewForbiddenError returns a 403 permission_error.
func NewForbiddenError(msg string) *APIError {
return &APIError{
Type: "permission_error",
Message: msg,
Code: "insufficient_permissions",
HTTPStatus: http.StatusForbidden,
}
}
// NewBadRequestError returns a 400 invalid_request_error.
func NewBadRequestError(msg string) *APIError {
return &APIError{
Type: "invalid_request_error",
Message: msg,
Code: "invalid_request",
HTTPStatus: http.StatusBadRequest,
}
}
// NewUpstreamError returns a 502 upstream_error.
func NewUpstreamError(msg string) *APIError {
return &APIError{
Type: "api_error",
Message: msg,
Code: "upstream_error",
HTTPStatus: http.StatusBadGateway,
}
}
// NewRateLimitError returns a 429 rate_limit_error with Retry-After: 1 (RFC 6585).
func NewRateLimitError(msg string) *APIError {
return &APIError{
Type: "rate_limit_error",
Message: msg,
Code: "rate_limit_exceeded",
HTTPStatus: http.StatusTooManyRequests,
RetryAfterSec: 1,
}
}
// NewTimeoutError returns a 504 timeout_error.
func NewTimeoutError(msg string) *APIError {
return &APIError{
Type: "api_error",
Message: msg,
Code: "upstream_timeout",
HTTPStatus: http.StatusGatewayTimeout,
}
}
// NewInternalError returns a 500 internal_error.
func NewInternalError(msg string) *APIError {
return &APIError{
Type: "api_error",
Message: msg,
Code: "internal_error",
HTTPStatus: http.StatusInternalServerError,
}
}

111
internal/apierror/errors_test.go Normal file
View File

@ -0,0 +1,111 @@
package apierror_test
import (
"encoding/json"
"net/http"
"net/http/httptest"
"testing"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
"github.com/veylant/ia-gateway/internal/apierror"
)
func TestNewAuthError(t *testing.T) {
e := apierror.NewAuthError("bad token")
assert.Equal(t, http.StatusUnauthorized, e.HTTPStatus)
assert.Equal(t, "authentication_error", e.Type)
assert.Equal(t, "bad token", e.Message)
assert.NotEmpty(t, e.Code)
}
func TestNewForbiddenError(t *testing.T) {
e := apierror.NewForbiddenError("no access")
assert.Equal(t, http.StatusForbidden, e.HTTPStatus)
assert.Equal(t, "permission_error", e.Type)
}
func TestNewBadRequestError(t *testing.T) {
e := apierror.NewBadRequestError("missing model")
assert.Equal(t, http.StatusBadRequest, e.HTTPStatus)
assert.Equal(t, "invalid_request_error", e.Type)
}
func TestNewUpstreamError(t *testing.T) {
e := apierror.NewUpstreamError("OpenAI down")
assert.Equal(t, http.StatusBadGateway, e.HTTPStatus)
assert.Equal(t, "api_error", e.Type)
}
func TestNewRateLimitError(t *testing.T) {
e := apierror.NewRateLimitError("too many requests")
assert.Equal(t, http.StatusTooManyRequests, e.HTTPStatus)
assert.Equal(t, "rate_limit_error", e.Type)
assert.Equal(t, 1, e.RetryAfterSec, "NewRateLimitError must set RetryAfterSec=1 (RFC 6585)")
}
func TestWriteError_RetryAfter_SetWhenPresent(t *testing.T) {
rec := httptest.NewRecorder()
apierror.WriteError(rec, apierror.NewRateLimitError("slow down"))
assert.Equal(t, "1", rec.Header().Get("Retry-After"))
}
func TestWriteError_NoRetryAfter_WhenZero(t *testing.T) {
rec := httptest.NewRecorder()
apierror.WriteError(rec, apierror.NewAuthError("denied"))
assert.Empty(t, rec.Header().Get("Retry-After"))
}
func TestWriteErrorWithRequestID_SetsHeader(t *testing.T) {
rec := httptest.NewRecorder()
apierror.WriteErrorWithRequestID(rec, apierror.NewAuthError("denied"), "req-abc-123")
assert.Equal(t, "req-abc-123", rec.Header().Get("X-Request-Id"))
assert.Equal(t, http.StatusUnauthorized, rec.Code)
}
func TestWriteErrorWithRequestID_EmptyID_NoHeader(t *testing.T) {
rec := httptest.NewRecorder()
apierror.WriteErrorWithRequestID(rec, apierror.NewAuthError("denied"), "")
assert.Empty(t, rec.Header().Get("X-Request-Id"))
}
func TestNewTimeoutError(t *testing.T) {
e := apierror.NewTimeoutError("upstream timed out")
assert.Equal(t, http.StatusGatewayTimeout, e.HTTPStatus)
}
func TestNewInternalError(t *testing.T) {
e := apierror.NewInternalError("unexpected panic")
assert.Equal(t, http.StatusInternalServerError, e.HTTPStatus)
}
func TestAPIError_Error(t *testing.T) {
e := apierror.NewAuthError("some message")
assert.Equal(t, "some message", e.Error())
}
func TestWriteError_SetsStatusAndContentType(t *testing.T) {
rec := httptest.NewRecorder()
apierror.WriteError(rec, apierror.NewAuthError("denied"))
assert.Equal(t, http.StatusUnauthorized, rec.Code)
assert.Equal(t, "application/json", rec.Header().Get("Content-Type"))
}
func TestWriteError_BodyIsOpenAIEnvelope(t *testing.T) {
rec := httptest.NewRecorder()
apierror.WriteError(rec, apierror.NewRateLimitError("slow down"))
var body struct {
Error struct {
Type string `json:"type"`
Message string `json:"message"`
Code string `json:"code"`
} `json:"error"`
}
require.NoError(t, json.NewDecoder(rec.Body).Decode(&body))
assert.Equal(t, "rate_limit_error", body.Error.Type)
assert.Equal(t, "slow down", body.Error.Message)
assert.NotEmpty(t, body.Error.Code)
}

119
internal/auditlog/batch.go Normal file
View File

@ -0,0 +1,119 @@
package auditlog
import (
"context"
"sync"
"time"
"go.uber.org/zap"
)
// Flusher is implemented by storage backends (e.g. ClickHouseLogger).
type Flusher interface {
InsertBatch(ctx context.Context, entries []AuditEntry) error
}
// BatchWriter wraps a Flusher with an async buffered channel.
// It flushes when batchSize entries are accumulated OR flushInterval elapses,
// whichever comes first. On channel overflow it drops the entry and logs a warning.
type BatchWriter struct {
ch chan AuditEntry
batchSize int
flushInterval time.Duration
flusher Flusher
logger *zap.Logger
done chan struct{}
wg sync.WaitGroup
}
// NewBatchWriter creates a production BatchWriter (cap=10 000, size=100, interval=1s).
func NewBatchWriter(flusher Flusher, logger *zap.Logger) *BatchWriter {
return NewBatchWriterForTest(flusher, 100, time.Second, logger)
}
// NewBatchWriterForTest creates a BatchWriter with configurable parameters for unit tests.
func NewBatchWriterForTest(flusher Flusher, batchSize int, flushInterval time.Duration, logger *zap.Logger) *BatchWriter {
return &BatchWriter{
ch: make(chan AuditEntry, 10_000),
batchSize: batchSize,
flushInterval: flushInterval,
flusher: flusher,
logger: logger,
done: make(chan struct{}),
}
}
// Log enqueues an entry. Non-blocking: drops the entry if the channel is full.
func (bw *BatchWriter) Log(entry AuditEntry) {
select {
case bw.ch <- entry:
default:
bw.logger.Warn("audit log channel full — entry dropped",
zap.String("request_id", entry.RequestID))
}
}
// Start launches the background flush goroutine.
func (bw *BatchWriter) Start() {
bw.wg.Add(1)
go bw.run()
}
// Stop signals the flush goroutine to drain remaining entries and exit.
func (bw *BatchWriter) Stop() {
close(bw.done)
bw.wg.Wait()
}
func (bw *BatchWriter) run() {
defer bw.wg.Done()
ticker := time.NewTicker(bw.flushInterval)
defer ticker.Stop()
batch := make([]AuditEntry, 0, bw.batchSize)
flush := func() {
if len(batch) == 0 {
return
}
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
if err := bw.flusher.InsertBatch(ctx, batch); err != nil {
bw.logger.Error("audit log batch insert failed", zap.Error(err), zap.Int("count", len(batch)))
}
batch = batch[:0]
}
for {
select {
case entry := <-bw.ch:
batch = append(batch, entry)
if len(batch) >= bw.batchSize {
flush()
}
case <-ticker.C:
flush()
case <-bw.done:
// Drain remaining entries from channel.
for {
select {
case entry := <-bw.ch:
batch = append(batch, entry)
default:
flush()
return
}
}
}
}
}
// Query is not supported on BatchWriter; use the underlying Logger (e.g. ClickHouseLogger).
func (bw *BatchWriter) Query(_ context.Context, _ AuditQuery) (*AuditResult, error) {
return &AuditResult{}, nil
}
// QueryCosts is not supported on BatchWriter.
func (bw *BatchWriter) QueryCosts(_ context.Context, _ CostQuery) (*CostResult, error) {
return &CostResult{}, nil
}

253
internal/auditlog/ch_logger.go Normal file
View File

@ -0,0 +1,253 @@
package auditlog
import (
"context"
"fmt"
"os"
"sort"
"strings"
"time"
"github.com/ClickHouse/clickhouse-go/v2"
"github.com/ClickHouse/clickhouse-go/v2/lib/driver"
"go.uber.org/zap"
)
// ClickHouseLogger implements Logger + Flusher backed by a ClickHouse connection.
// Query/QueryCosts perform synchronous CH queries for the admin API.
// Log() is non-blocking: entries are queued in BatchWriter (not directly here).
type ClickHouseLogger struct {
conn driver.Conn
logger *zap.Logger
bw *BatchWriter
}
// NewClickHouseLogger opens a ClickHouse native connection from a DSN string
// (clickhouse://user:pass@host:9000/database) and returns a ClickHouseLogger.
// The caller must call Start() and defer Stop().
func NewClickHouseLogger(dsn string, maxConns, dialTimeoutSec int, logger *zap.Logger) (*ClickHouseLogger, error) {
opts, err := clickhouse.ParseDSN(dsn)
if err != nil {
return nil, fmt.Errorf("clickhouse: parse DSN: %w", err)
}
if maxConns > 0 {
opts.MaxOpenConns = maxConns
}
if dialTimeoutSec > 0 {
opts.DialTimeout = time.Duration(dialTimeoutSec) * time.Second
}
conn, err := clickhouse.Open(opts)
if err != nil {
return nil, fmt.Errorf("clickhouse: open: %w", err)
}
if err := conn.Ping(context.Background()); err != nil {
return nil, fmt.Errorf("clickhouse: ping: %w", err)
}
ch := &ClickHouseLogger{conn: conn, logger: logger}
ch.bw = NewBatchWriter(ch, logger)
return ch, nil
}
// ApplyDDL reads and executes the ClickHouse DDL file at startup (idempotent).
func (c *ClickHouseLogger) ApplyDDL(sqlPath string) error {
data, err := os.ReadFile(sqlPath)
if err != nil {
return fmt.Errorf("clickhouse: read DDL %s: %w", sqlPath, err)
}
// Split on semicolons to handle multi-statement files.
for _, stmt := range strings.Split(string(data), ";") {
stmt = strings.TrimSpace(stmt)
if stmt == "" || strings.HasPrefix(stmt, "--") {
continue
}
if err := c.conn.Exec(context.Background(), stmt); err != nil {
return fmt.Errorf("clickhouse: exec DDL: %w", err)
}
}
return nil
}
// ─── Logger interface ─────────────────────────────────────────────────────────
func (c *ClickHouseLogger) Log(entry AuditEntry) { c.bw.Log(entry) }
func (c *ClickHouseLogger) Start() { c.bw.Start() }
func (c *ClickHouseLogger) Stop() { c.bw.Stop() }
// ─── Flusher interface ────────────────────────────────────────────────────────
func (c *ClickHouseLogger) InsertBatch(ctx context.Context, entries []AuditEntry) error {
batch, err := c.conn.PrepareBatch(ctx, "INSERT INTO audit_logs")
if err != nil {
return fmt.Errorf("clickhouse: prepare batch: %w", err)
}
for _, e := range entries {
if err := batch.Append(
e.RequestID,
e.TenantID,
e.UserID,
e.Timestamp,
e.ModelRequested,
e.ModelUsed,
e.Provider,
e.Department,
e.UserRole,
e.PromptHash,
e.ResponseHash,
e.PromptAnonymized,
e.SensitivityLevel,
uint32(e.TokenInput),
uint32(e.TokenOutput),
uint32(e.TokenTotal),
e.CostUSD,
uint32(e.LatencyMs),
e.Status,
e.ErrorType,
uint16(e.PIIEntityCount),
e.Stream,
); err != nil {
return fmt.Errorf("clickhouse: append row: %w", err)
}
}
return batch.Send()
}
// ─── Query ────────────────────────────────────────────────────────────────────
func (c *ClickHouseLogger) Query(ctx context.Context, q AuditQuery) (*AuditResult, error) {
limit := q.Limit
if limit <= 0 || limit > 200 {
limit = 50
}
offset := q.Offset
var conditions []string
var args []interface{}
conditions = append(conditions, "tenant_id = ?")
args = append(args, q.TenantID)
if !q.StartTime.IsZero() {
conditions = append(conditions, "timestamp >= ?")
args = append(args, q.StartTime)
}
if !q.EndTime.IsZero() {
conditions = append(conditions, "timestamp <= ?")
args = append(args, q.EndTime)
}
if q.UserID != "" {
conditions = append(conditions, "user_id = ?")
args = append(args, q.UserID)
}
if q.Provider != "" {
conditions = append(conditions, "provider = ?")
args = append(args, q.Provider)
}
sensitivityOrder := map[string]int{"none": 0, "low": 1, "medium": 2, "high": 3, "critical": 4}
if _, ok := sensitivityOrder[q.MinSensitivity]; ok && q.MinSensitivity != "" {
levels := []string{}
minLvl := sensitivityOrder[q.MinSensitivity]
for lvl, ord := range sensitivityOrder {
if ord >= minLvl {
levels = append(levels, "'"+lvl+"'")
}
}
conditions = append(conditions, "sensitivity_level IN ("+strings.Join(levels, ",")+")")
}
where := strings.Join(conditions, " AND ")
query := fmt.Sprintf(
"SELECT request_id, tenant_id, user_id, timestamp, model_requested, model_used, provider, "+
"department, user_role, prompt_hash, response_hash, sensitivity_level, "+
"token_input, token_output, token_total, cost_usd, latency_ms, status, "+
"error_type, pii_entity_count, stream FROM audit_logs WHERE %s "+
"ORDER BY timestamp DESC LIMIT %d OFFSET %d",
where, limit, offset,
)
rows, err := c.conn.Query(ctx, query, args...)
if err != nil {
return nil, fmt.Errorf("clickhouse: query logs: %w", err)
}
defer rows.Close()
var entries []AuditEntry
for rows.Next() {
var e AuditEntry
var tokenIn, tokenOut, tokenTotal uint32
var latencyMs uint32
var piiCount uint16
if err := rows.Scan(
&e.RequestID, &e.TenantID, &e.UserID, &e.Timestamp,
&e.ModelRequested, &e.ModelUsed, &e.Provider,
&e.Department, &e.UserRole, &e.PromptHash, &e.ResponseHash,
&e.SensitivityLevel, &tokenIn, &tokenOut, &tokenTotal,
&e.CostUSD, &latencyMs, &e.Status, &e.ErrorType, &piiCount, &e.Stream,
); err != nil {
return nil, fmt.Errorf("clickhouse: scan: %w", err)
}
e.TokenInput = int(tokenIn)
e.TokenOutput = int(tokenOut)
e.TokenTotal = int(tokenTotal)
e.LatencyMs = int(latencyMs)
e.PIIEntityCount = int(piiCount)
// prompt_anonymized is intentionally excluded from query results.
entries = append(entries, e)
}
return &AuditResult{Data: entries, Total: len(entries)}, nil
}
func (c *ClickHouseLogger) QueryCosts(ctx context.Context, q CostQuery) (*CostResult, error) {
groupField := "provider"
switch q.GroupBy {
case "model":
groupField = "model_used"
case "department":
groupField = "department"
}
var conditions []string
var args []interface{}
conditions = append(conditions, "tenant_id = ?")
args = append(args, q.TenantID)
if !q.StartTime.IsZero() {
conditions = append(conditions, "timestamp >= ?")
args = append(args, q.StartTime)
}
if !q.EndTime.IsZero() {
conditions = append(conditions, "timestamp <= ?")
args = append(args, q.EndTime)
}
where := strings.Join(conditions, " AND ")
query := fmt.Sprintf(
"SELECT %s, sum(token_total), sum(cost_usd), count() FROM audit_logs WHERE %s GROUP BY %s ORDER BY %s",
groupField, where, groupField, groupField,
)
rows, err := c.conn.Query(ctx, query, args...)
if err != nil {
return nil, fmt.Errorf("clickhouse: query costs: %w", err)
}
defer rows.Close()
var data []CostSummary
for rows.Next() {
var s CostSummary
var tokens uint64
var count uint64
if err := rows.Scan(&s.Key, &tokens, &s.TotalCostUSD, &count); err != nil {
return nil, fmt.Errorf("clickhouse: scan cost: %w", err)
}
s.TotalTokens = int(tokens)
s.RequestCount = int(count)
data = append(data, s)
}
sort.Slice(data, func(i, j int) bool { return data[i].Key < data[j].Key })
return &CostResult{Data: data}, nil
}

73
internal/auditlog/entry.go Normal file
View File

@ -0,0 +1,73 @@
// Package auditlog defines the immutable audit log types and the Logger interface
// for recording every LLM request processed by the proxy.
package auditlog
import "time"
// AuditEntry holds all metadata for a single proxied LLM request.
// It is written to ClickHouse asynchronously via BatchWriter.
// prompt_anonymized is stored encrypted (AES-256-GCM) and is never
// returned to API callers.
type AuditEntry struct {
RequestID string
TenantID string
UserID string
Timestamp time.Time
ModelRequested string
ModelUsed string
Provider string
Department string
UserRole string
PromptHash string // hex SHA-256 of the original (pre-PII) prompt
ResponseHash string // hex SHA-256 of the response content
PromptAnonymized string // AES-256-GCM base64-encoded anonymized prompt
SensitivityLevel string // "none"|"low"|"medium"|"high"|"critical"
TokenInput int
TokenOutput int
TokenTotal int
CostUSD float64
LatencyMs int
Status string // "ok"|"error"
ErrorType string
PIIEntityCount int
Stream bool
}
// AuditQuery filters audit log entries for the GET /v1/admin/logs endpoint.
type AuditQuery struct {
TenantID string
UserID string // filter by specific user (GDPR Art. 15)
StartTime time.Time
EndTime time.Time
Provider string
MinSensitivity string // "none"|"low"|"medium"|"high"|"critical"
Limit int // default 50, max 200
Offset int
}
// AuditResult is the paginated response for AuditQuery.
type AuditResult struct {
Data []AuditEntry
Total int
}
// CostQuery filters cost aggregation for the GET /v1/admin/costs endpoint.
type CostQuery struct {
TenantID string
StartTime time.Time
EndTime time.Time
GroupBy string // "provider"|"model"|"department"
}
// CostSummary is one row in a cost aggregation result.
type CostSummary struct {
Key string
TotalTokens int
TotalCostUSD float64
RequestCount int
}
// CostResult is the response for CostQuery.
type CostResult struct {
Data []CostSummary
}

150
internal/auditlog/logger.go Normal file
View File

@ -0,0 +1,150 @@
package auditlog
import (
"context"
"sort"
"sync"
)
// Logger is the interface for recording and querying audit log entries.
// Log() must be non-blocking (backed by a buffered channel or in-memory store).
type Logger interface {
Log(entry AuditEntry)
Query(ctx context.Context, q AuditQuery) (*AuditResult, error)
QueryCosts(ctx context.Context, q CostQuery) (*CostResult, error)
Start()
Stop()
}
// ─── MemLogger ────────────────────────────────────────────────────────────────
// MemLogger is a thread-safe in-memory Logger used in tests.
// It stores entries in insertion order and supports basic filtering.
type MemLogger struct {
mu sync.RWMutex
entries []AuditEntry
}
// NewMemLogger creates a new MemLogger.
func NewMemLogger() *MemLogger { return &MemLogger{} }
func (m *MemLogger) Log(e AuditEntry) {
m.mu.Lock()
m.entries = append(m.entries, e)
m.mu.Unlock()
}
// Entries returns a copy of all stored entries (safe to call from tests).
func (m *MemLogger) Entries() []AuditEntry {
m.mu.RLock()
defer m.mu.RUnlock()
out := make([]AuditEntry, len(m.entries))
copy(out, m.entries)
return out
}
func (m *MemLogger) Query(_ context.Context, q AuditQuery) (*AuditResult, error) {
m.mu.RLock()
defer m.mu.RUnlock()
sensitivityOrder := map[string]int{
"none": 0, "low": 1, "medium": 2, "high": 3, "critical": 4,
}
minLevel := sensitivityOrder[q.MinSensitivity]
var filtered []AuditEntry
for _, e := range m.entries {
if e.TenantID != q.TenantID {
continue
}
if q.UserID != "" && e.UserID != q.UserID {
continue
}
if !q.StartTime.IsZero() && e.Timestamp.Before(q.StartTime) {
continue
}
if !q.EndTime.IsZero() && e.Timestamp.After(q.EndTime) {
continue
}
if q.Provider != "" && e.Provider != q.Provider {
continue
}
if q.MinSensitivity != "" {
if sensitivityOrder[e.SensitivityLevel] < minLevel {
continue
}
}
filtered = append(filtered, e)
}
total := len(filtered)
if q.Offset < len(filtered) {
filtered = filtered[q.Offset:]
} else {
filtered = nil
}
limit := q.Limit
if limit <= 0 || limit > 200 {
limit = 50
}
if len(filtered) > limit {
filtered = filtered[:limit]
}
return &AuditResult{Data: filtered, Total: total}, nil
}
func (m *MemLogger) QueryCosts(_ context.Context, q CostQuery) (*CostResult, error) {
m.mu.RLock()
defer m.mu.RUnlock()
type aggKey = string
type agg struct {
tokens int
cost float64
count int
}
totals := map[aggKey]*agg{}
for _, e := range m.entries {
if e.TenantID != q.TenantID {
continue
}
if !q.StartTime.IsZero() && e.Timestamp.Before(q.StartTime) {
continue
}
if !q.EndTime.IsZero() && e.Timestamp.After(q.EndTime) {
continue
}
var key string
switch q.GroupBy {
case "model":
key = e.ModelUsed
case "department":
key = e.Department
default:
key = e.Provider
}
if totals[key] == nil {
totals[key] = &agg{}
}
totals[key].tokens += e.TokenTotal
totals[key].cost += e.CostUSD
totals[key].count++
}
var data []CostSummary
for k, v := range totals {
data = append(data, CostSummary{
Key: k,
TotalTokens: v.tokens,
TotalCostUSD: v.cost,
RequestCount: v.count,
})
}
sort.Slice(data, func(i, j int) bool { return data[i].Key < data[j].Key })
return &CostResult{Data: data}, nil
}
func (m *MemLogger) Start() {}
func (m *MemLogger) Stop() {}

215
internal/auditlog/logger_test.go Normal file
View File

@ -0,0 +1,215 @@
package auditlog_test
import (
"context"
"sync"
"sync/atomic"
"testing"
"time"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
"go.uber.org/zap"
"github.com/veylant/ia-gateway/internal/auditlog"
)
// ─── MemLogger tests ──────────────────────────────────────────────────────────
func TestMemLogger_Log_And_Entries(t *testing.T) {
ml := auditlog.NewMemLogger()
ml.Log(auditlog.AuditEntry{RequestID: "req-1", TenantID: "t1"})
ml.Log(auditlog.AuditEntry{RequestID: "req-2", TenantID: "t1"})
entries := ml.Entries()
assert.Len(t, entries, 2)
assert.Equal(t, "req-1", entries[0].RequestID)
}
func TestMemLogger_Query_FiltersByTenant(t *testing.T) {
ml := auditlog.NewMemLogger()
ml.Log(auditlog.AuditEntry{TenantID: "t1", RequestID: "a", SensitivityLevel: "low"})
ml.Log(auditlog.AuditEntry{TenantID: "t2", RequestID: "b", SensitivityLevel: "high"})
result, err := ml.Query(context.Background(), auditlog.AuditQuery{TenantID: "t1", Limit: 10})
require.NoError(t, err)
assert.Len(t, result.Data, 1)
assert.Equal(t, "a", result.Data[0].RequestID)
}
func TestMemLogger_Query_FiltersByMinSensitivity(t *testing.T) {
ml := auditlog.NewMemLogger()
ml.Log(auditlog.AuditEntry{TenantID: "t1", RequestID: "none", SensitivityLevel: "none"})
ml.Log(auditlog.AuditEntry{TenantID: "t1", RequestID: "low", SensitivityLevel: "low"})
ml.Log(auditlog.AuditEntry{TenantID: "t1", RequestID: "high", SensitivityLevel: "high"})
ml.Log(auditlog.AuditEntry{TenantID: "t1", RequestID: "critical", SensitivityLevel: "critical"})
result, err := ml.Query(context.Background(), auditlog.AuditQuery{
TenantID: "t1", MinSensitivity: "high", Limit: 10,
})
require.NoError(t, err)
assert.Len(t, result.Data, 2)
}
func TestMemLogger_Query_Pagination(t *testing.T) {
ml := auditlog.NewMemLogger()
for i := 0; i < 10; i++ {
ml.Log(auditlog.AuditEntry{TenantID: "t1"})
}
result, err := ml.Query(context.Background(), auditlog.AuditQuery{
TenantID: "t1", Limit: 3, Offset: 5,
})
require.NoError(t, err)
assert.Len(t, result.Data, 3)
assert.Equal(t, 10, result.Total)
}
func TestMemLogger_QueryCosts_GroupByProvider(t *testing.T) {
ml := auditlog.NewMemLogger()
ml.Log(auditlog.AuditEntry{TenantID: "t1", Provider: "openai", TokenTotal: 1000, CostUSD: 0.005})
ml.Log(auditlog.AuditEntry{TenantID: "t1", Provider: "openai", TokenTotal: 500, CostUSD: 0.0025})
ml.Log(auditlog.AuditEntry{TenantID: "t1", Provider: "ollama", TokenTotal: 2000, CostUSD: 0})
ml.Log(auditlog.AuditEntry{TenantID: "t2", Provider: "openai", TokenTotal: 1000, CostUSD: 0.005})
result, err := ml.QueryCosts(context.Background(), auditlog.CostQuery{
TenantID: "t1", GroupBy: "provider",
})
require.NoError(t, err)
assert.Len(t, result.Data, 2)
// Find openai summary
var openaiSummary auditlog.CostSummary
for _, s := range result.Data {
if s.Key == "openai" {
openaiSummary = s
}
}
assert.Equal(t, 1500, openaiSummary.TotalTokens)
assert.InDelta(t, 0.0075, openaiSummary.TotalCostUSD, 1e-9)
assert.Equal(t, 2, openaiSummary.RequestCount)
}
// ─── BatchWriter tests ────────────────────────────────────────────────────────
// mockFlusher records received batches for assertions.
type mockFlusher struct {
mu sync.Mutex
batches [][]auditlog.AuditEntry
total int
}
func (f *mockFlusher) InsertBatch(_ context.Context, entries []auditlog.AuditEntry) error {
f.mu.Lock()
defer f.mu.Unlock()
cp := make([]auditlog.AuditEntry, len(entries))
copy(cp, entries)
f.batches = append(f.batches, cp)
f.total += len(entries)
return nil
}
func (f *mockFlusher) Total() int {
f.mu.Lock()
defer f.mu.Unlock()
return f.total
}
func TestBatchWriter_FlushOnSize(t *testing.T) {
flusher := &mockFlusher{}
bw := auditlog.NewBatchWriterForTest(flusher, 5, 10*time.Second, zap.NewNop())
bw.Start()
defer bw.Stop()
for i := 0; i < 5; i++ {
bw.Log(auditlog.AuditEntry{RequestID: "r"})
}
// Wait for flush to happen (should be almost immediate on batch size).
require.Eventually(t, func() bool { return flusher.Total() == 5 },
2*time.Second, 10*time.Millisecond, "expected 5 entries flushed")
}
func TestBatchWriter_FlushOnTick(t *testing.T) {
flusher := &mockFlusher{}
bw := auditlog.NewBatchWriterForTest(flusher, 100, 50*time.Millisecond, zap.NewNop())
bw.Start()
defer bw.Stop()
// Send only 3 entries (below batch size).
for i := 0; i < 3; i++ {
bw.Log(auditlog.AuditEntry{RequestID: "r"})
}
require.Eventually(t, func() bool { return flusher.Total() == 3 },
500*time.Millisecond, 10*time.Millisecond, "expected tick flush")
}
func TestBatchWriter_Stop_DrainsPending(t *testing.T) {
flusher := &mockFlusher{}
bw := auditlog.NewBatchWriterForTest(flusher, 1000, 10*time.Second, zap.NewNop())
bw.Start()
for i := 0; i < 7; i++ {
bw.Log(auditlog.AuditEntry{RequestID: "r"})
}
bw.Stop()
assert.Equal(t, 7, flusher.Total(), "Stop should drain remaining entries")
}
func TestBatchWriter_OverflowDrops(t *testing.T) {
// Flusher that blocks forever to force channel fill.
var called atomic.Bool
blockFlusher := &blockingFlusher{called: &called}
// Very small channel to trigger overflow quickly.
bw := auditlog.NewBatchWriterForTest(blockFlusher, 1, 10*time.Millisecond, zap.NewNop())
bw.Start()
defer bw.Stop()
// First entry triggers flush (which blocks); additional entries should fill channel.
// With cap=10_000 we can't easily fill it in a unit test, so we just verify
// that Log() returns immediately (non-blocking) even when the flusher is slow.
start := time.Now()
for i := 0; i < 20; i++ {
bw.Log(auditlog.AuditEntry{RequestID: "r"})
}
assert.Less(t, time.Since(start), 200*time.Millisecond, "Log should be non-blocking")
}
// blockingFlusher blocks for 5 seconds to simulate a slow ClickHouse.
type blockingFlusher struct {
called *atomic.Bool
}
func (b *blockingFlusher) InsertBatch(ctx context.Context, _ []auditlog.AuditEntry) error {
b.called.Store(true)
select {
case <-ctx.Done():
case <-time.After(5 * time.Second):
}
return nil
}
func TestBatchWriter_ConcurrentLog(t *testing.T) {
flusher := &mockFlusher{}
bw := auditlog.NewBatchWriterForTest(flusher, 50, 20*time.Millisecond, zap.NewNop())
bw.Start()
defer bw.Stop()
var wg sync.WaitGroup
for g := 0; g < 10; g++ {
wg.Add(1)
go func() {
defer wg.Done()
for i := 0; i < 10; i++ {
bw.Log(auditlog.AuditEntry{RequestID: "r"})
}
}()
}
wg.Wait()
require.Eventually(t, func() bool { return flusher.Total() == 100 },
2*time.Second, 10*time.Millisecond)
}

52
internal/billing/billing.go Normal file
View File

@ -0,0 +1,52 @@
// Package billing provides token-based cost estimation for LLM API calls.
// Costs are expressed in USD per 1 000 tokens (blended input+output rate).
// Ollama (local) has no cost. Unknown providers/models return 0.
package billing
import "strings"
// costPer1kTokens maps "provider/model" to USD per 1 000 tokens (blended rate).
// Exact match is tried first; if not found, prefix match handles versioned names
// such as "gpt-4o-2024-08-06" matching "openai/gpt-4o".
var costPer1kTokens = map[string]float64{
"openai/gpt-4o": 0.005000,
"openai/gpt-4o-mini": 0.000150,
"openai/gpt-3.5-turbo": 0.000500,
"anthropic/claude-3-5-sonnet": 0.003000,
"anthropic/claude-3-opus": 0.015000,
"anthropic/claude-3-haiku": 0.000250,
"mistral/mistral-small": 0.000200,
"mistral/mistral-large": 0.002000,
// ollama/* absent → 0 (local inference, no API cost)
}
// CostUSD returns the estimated cost in USD for totalTokens tokens.
// It first tries an exact match on "provider/model", then a prefix match
// to handle versioned model names (e.g. "gpt-4o-2024-08-06" → "openai/gpt-4o").
// Returns 0 for unknown providers/models (e.g. ollama).
func CostUSD(provider, model string, totalTokens int) float64 {
if totalTokens <= 0 {
return 0
}
key := provider + "/" + model
// Exact match.
if rate, ok := costPer1kTokens[key]; ok {
return rate * float64(totalTokens) / 1000.0
}
// Prefix match: find the longest registered key that is a prefix of key.
var bestRate float64
var bestLen int
for k, rate := range costPer1kTokens {
if strings.HasPrefix(key, k) && len(k) > bestLen {
bestRate = rate
bestLen = len(k)
}
}
if bestLen > 0 {
return bestRate * float64(totalTokens) / 1000.0
}
return 0
}

50
internal/billing/billing_test.go Normal file
View File

@ -0,0 +1,50 @@
package billing_test
import (
"testing"
"github.com/stretchr/testify/assert"
"github.com/veylant/ia-gateway/internal/billing"
)
func TestBilling_OpenAI_GPT4o_ExactMatch(t *testing.T) {
cost := billing.CostUSD("openai", "gpt-4o", 1000)
assert.InDelta(t, 0.005, cost, 1e-9)
}
func TestBilling_OpenAI_GPT4oMini(t *testing.T) {
cost := billing.CostUSD("openai", "gpt-4o-mini", 1000)
assert.InDelta(t, 0.00015, cost, 1e-9)
}
func TestBilling_OpenAI_GPT4o_PrefixVersioned(t *testing.T) {
// "gpt-4o-2024-08-06" should match prefix "openai/gpt-4o"
cost := billing.CostUSD("openai", "gpt-4o-2024-08-06", 1000)
assert.InDelta(t, 0.005, cost, 1e-9)
}
func TestBilling_Anthropic_Sonnet(t *testing.T) {
cost := billing.CostUSD("anthropic", "claude-3-5-sonnet", 2000)
assert.InDelta(t, 0.006, cost, 1e-9)
}
func TestBilling_Ollama_ZeroCost(t *testing.T) {
cost := billing.CostUSD("ollama", "llama3.1", 10000)
assert.Equal(t, 0.0, cost)
}
func TestBilling_Unknown_ZeroCost(t *testing.T) {
cost := billing.CostUSD("unknown", "mystery-model", 5000)
assert.Equal(t, 0.0, cost)
}
func TestBilling_ZeroTokens(t *testing.T) {
cost := billing.CostUSD("openai", "gpt-4o", 0)
assert.Equal(t, 0.0, cost)
}
func TestBilling_NegativeTokens(t *testing.T) {
cost := billing.CostUSD("openai", "gpt-4o", -100)
assert.Equal(t, 0.0, cost)
}

187
internal/circuitbreaker/breaker.go Normal file
View File

@ -0,0 +1,187 @@
// Package circuitbreaker implements a per-provider circuit breaker.
// States: Closed (normal) → Open (failing, rejects requests) → HalfOpen (testing recovery).
// Transition Closed→Open: after `threshold` consecutive failures.
// Transition Open→HalfOpen: after `openTTL` has elapsed.
// Transition HalfOpen→Closed: on the first successful request.
// Transition HalfOpen→Open: on failure during half-open test.
package circuitbreaker
import (
"sync"
"time"
)
// State represents the circuit breaker state for a provider.
type State int
const (
Closed State = iota // Normal — requests allowed
Open // Tripped — requests rejected
HalfOpen // Recovery probe — one request allowed
)
func (s State) String() string {
switch s {
case Closed:
return "closed"
case Open:
return "open"
case HalfOpen:
return "half_open"
default:
return "unknown"
}
}
// Status is the read-only snapshot returned by the API.
type Status struct {
Provider string `json:"provider"`
State string `json:"state"`
Failures int `json:"failures"`
OpenedAt string `json:"opened_at,omitempty"` // RFC3339, only when Open/HalfOpen
}
type entry struct {
state State
failures int
openedAt time.Time
// halfOpenInFlight prevents concurrent requests during HalfOpen probe.
halfOpenInFlight bool
}
// Breaker is a thread-safe circuit breaker for multiple providers.
type Breaker struct {
mu sync.Mutex
states map[string]*entry
threshold int
openTTL time.Duration
}
// New creates a Breaker.
// - threshold: consecutive failures before opening the circuit.
// - openTTL: how long to wait in Open state before transitioning to HalfOpen.
func New(threshold int, openTTL time.Duration) *Breaker {
return &Breaker{
states: make(map[string]*entry),
threshold: threshold,
openTTL: openTTL,
}
}
func (b *Breaker) get(provider string) *entry {
e, ok := b.states[provider]
if !ok {
e = &entry{state: Closed}
b.states[provider] = e
}
return e
}
// Allow returns true if a request to the given provider should proceed.
// It also handles the Open→HalfOpen transition when the TTL has expired.
func (b *Breaker) Allow(provider string) bool {
b.mu.Lock()
defer b.mu.Unlock()
e := b.get(provider)
switch e.state {
case Closed:
return true
case Open:
if time.Since(e.openedAt) >= b.openTTL {
// Transition to HalfOpen — allow exactly one probe.
if !e.halfOpenInFlight {
e.state = HalfOpen
e.halfOpenInFlight = true
return true
}
}
return false
case HalfOpen:
// Only one in-flight request allowed during HalfOpen.
if !e.halfOpenInFlight {
e.halfOpenInFlight = true
return true
}
return false
}
return true
}
// Success records a successful response from a provider.
// Any non-Open circuit resets the failure counter; HalfOpen transitions to Closed.
func (b *Breaker) Success(provider string) {
b.mu.Lock()
defer b.mu.Unlock()
e := b.get(provider)
e.failures = 0
e.state = Closed
e.halfOpenInFlight = false
}
// Failure records a failed response from a provider.
// If threshold is reached the circuit transitions to Open.
// A failure during HalfOpen re-opens the circuit immediately.
func (b *Breaker) Failure(provider string) {
b.mu.Lock()
defer b.mu.Unlock()
e := b.get(provider)
e.halfOpenInFlight = false
switch e.state {
case Closed:
e.failures++
if e.failures >= b.threshold {
e.state = Open
e.openedAt = time.Now()
}
case HalfOpen:
// Re-open immediately.
e.state = Open
e.openedAt = time.Now()
e.failures++
}
}
// Status returns a read-only snapshot of the circuit state for a provider.
func (b *Breaker) Status(provider string) Status {
b.mu.Lock()
defer b.mu.Unlock()
e := b.get(provider)
s := Status{
Provider: provider,
State: e.state.String(),
Failures: e.failures,
}
if e.state == Open || e.state == HalfOpen {
s.OpenedAt = e.openedAt.Format(time.RFC3339)
}
return s
}
// Statuses returns snapshots for all known providers.
func (b *Breaker) Statuses() []Status {
b.mu.Lock()
defer b.mu.Unlock()
out := make([]Status, 0, len(b.states))
for name, e := range b.states {
s := Status{
Provider: name,
State: e.state.String(),
Failures: e.failures,
}
if e.state == Open || e.state == HalfOpen {
s.OpenedAt = e.openedAt.Format(time.RFC3339)
}
out = append(out, s)
}
return out
}

105
internal/circuitbreaker/breaker_test.go Normal file
View File

@ -0,0 +1,105 @@
package circuitbreaker_test
import (
"sync"
"testing"
"time"
"github.com/veylant/ia-gateway/internal/circuitbreaker"
)
func TestAllowWhenClosed(t *testing.T) {
b := circuitbreaker.New(5, 60*time.Second)
if !b.Allow("openai") {
t.Fatal("expected Allow=true for a fresh Closed circuit")
}
}
func TestRejectWhenOpen(t *testing.T) {
b := circuitbreaker.New(3, 60*time.Second)
// Trip the circuit.
for i := 0; i < 3; i++ {
b.Failure("openai")
}
if b.Allow("openai") {
t.Fatal("expected Allow=false when circuit is Open")
}
s := b.Status("openai")
if s.State != "open" {
t.Fatalf("expected state=open, got %s", s.State)
}
}
func TestOpenAfterThreshold(t *testing.T) {
b := circuitbreaker.New(5, 60*time.Second)
// 4 failures: still closed.
for i := 0; i < 4; i++ {
b.Failure("anthropic")
}
if !b.Allow("anthropic") {
t.Fatal("expected Allow=true before threshold reached")
}
// 5th failure: opens.
b.Failure("anthropic")
if b.Allow("anthropic") {
t.Fatal("expected Allow=false after threshold reached")
}
}
func TestHalfOpenAfterTTL(t *testing.T) {
b := circuitbreaker.New(3, 10*time.Millisecond)
// Trip the circuit.
for i := 0; i < 3; i++ {
b.Failure("mistral")
}
if b.Allow("mistral") {
t.Fatal("circuit should be Open immediately after threshold")
}
// Wait for TTL.
time.Sleep(20 * time.Millisecond)
// First Allow should return true (HalfOpen probe).
if !b.Allow("mistral") {
t.Fatal("expected Allow=true in HalfOpen state after TTL")
}
if b.Status("mistral").State != "half_open" {
t.Fatalf("expected state=half_open, got %s", b.Status("mistral").State)
}
}
func TestCloseAfterSuccess(t *testing.T) {
b := circuitbreaker.New(3, 5*time.Millisecond)
for i := 0; i < 3; i++ {
b.Failure("ollama")
}
time.Sleep(10 * time.Millisecond)
b.Allow("ollama") // enter HalfOpen
b.Success("ollama")
if b.Status("ollama").State != "closed" {
t.Fatalf("expected state=closed after success, got %s", b.Status("ollama").State)
}
if b.Status("ollama").Failures != 0 {
t.Fatal("expected failures=0 after success")
}
}
func TestConcurrentSafe(t *testing.T) {
b := circuitbreaker.New(100, 60*time.Second)
var wg sync.WaitGroup
for i := 0; i < 200; i++ {
wg.Add(1)
go func(i int) {
defer wg.Done()
if i%3 == 0 {
b.Failure("azure")
} else if i%3 == 1 {
b.Success("azure")
} else {
b.Allow("azure")
}
}(i)
}
wg.Wait()
// Just check no panic and Status is reachable.
_ = b.Status("azure")
_ = b.Statuses()
}

569
internal/compliance/handler.go Normal file
View File

@ -0,0 +1,569 @@
package compliance
import (
"database/sql"
"encoding/json"
"errors"
"fmt"
"net/http"
"time"
"github.com/go-chi/chi/v5"
"go.uber.org/zap"
"github.com/veylant/ia-gateway/internal/apierror"
"github.com/veylant/ia-gateway/internal/auditlog"
"github.com/veylant/ia-gateway/internal/middleware"
)
// Handler provides HTTP endpoints for the compliance module.
type Handler struct {
store ComplianceStore
auditLog auditlog.Logger // nil → 501 for GDPR and export endpoints
db *sql.DB // nil → 501 for Art. 17 erasure log
tenantName string
logger *zap.Logger
}
// New creates a compliance Handler.
func New(store ComplianceStore, logger *zap.Logger) *Handler {
return &Handler{store: store, logger: logger, tenantName: "Organisation"}
}
// WithAudit attaches an audit logger (required for GDPR access/erase + CSV export).
func (h *Handler) WithAudit(al auditlog.Logger) *Handler {
h.auditLog = al
return h
}
// WithDB attaches a database connection (required for Art. 17 erasure log).
func (h *Handler) WithDB(db *sql.DB) *Handler {
h.db = db
return h
}
// WithTenantName sets the tenant display name used in PDF headers.
func (h *Handler) WithTenantName(name string) *Handler {
if name != "" {
h.tenantName = name
}
return h
}
// Routes registers all compliance endpoints on r.
// Callers must mount r under an authenticated prefix.
func (h *Handler) Routes(r chi.Router) {
// Processing registry CRUD (E9-01)
r.Get("/entries", h.listEntries)
r.Post("/entries", h.createEntry)
r.Get("/entries/{id}", h.getEntry)
r.Put("/entries/{id}", h.updateEntry)
r.Delete("/entries/{id}", h.deleteEntry)
// AI Act classification (E9-02)
r.Post("/entries/{id}/classify", h.classifyEntry)
// PDF reports (E9-03, E9-04, E9-07)
r.Get("/report/article30", h.reportArticle30)
r.Get("/report/aiact", h.reportAiAct)
r.Get("/dpia/{id}", h.reportDPIA)
// GDPR rights (E9-05, E9-06)
r.Get("/gdpr/access/{user_id}", h.gdprAccess)
r.Delete("/gdpr/erase/{user_id}", h.gdprErase)
// CSV export (E7-10)
r.Get("/export/logs", h.exportLogsCSV)
}
// ─── helpers ──────────────────────────────────────────────────────────────────
func tenantFrom(w http.ResponseWriter, r *http.Request) (string, bool) {
claims, ok := middleware.ClaimsFromContext(r.Context())
if !ok || claims.TenantID == "" {
apierror.WriteError(w, apierror.NewAuthError("missing authentication"))
return "", false
}
return claims.TenantID, true
}
func userFrom(r *http.Request) string {
if claims, ok := middleware.ClaimsFromContext(r.Context()); ok {
return claims.UserID
}
return "unknown"
}
func writeJSON(w http.ResponseWriter, status int, v interface{}) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(status)
_ = json.NewEncoder(w).Encode(v)
}
func writeStoreError(w http.ResponseWriter, err error) {
if errors.Is(err, ErrNotFound) {
apierror.WriteError(w, &apierror.APIError{
Type: "not_found_error", Message: "entry not found", HTTPStatus: http.StatusNotFound,
})
return
}
apierror.WriteError(w, apierror.NewUpstreamError(err.Error()))
}
// ─── CRUD ────────────────────────────────────────────────────────────────────
func (h *Handler) listEntries(w http.ResponseWriter, r *http.Request) {
tenantID, ok := tenantFrom(w, r)
if !ok {
return
}
entries, err := h.store.List(r.Context(), tenantID)
if err != nil {
apierror.WriteError(w, apierror.NewUpstreamError("failed to list entries: "+err.Error()))
return
}
if entries == nil {
entries = []ProcessingEntry{}
}
writeJSON(w, http.StatusOK, map[string]interface{}{"data": entries})
}
type entryRequest struct {
UseCaseName string `json:"use_case_name"`
LegalBasis string `json:"legal_basis"`
Purpose string `json:"purpose"`
DataCategories []string `json:"data_categories"`
Recipients []string `json:"recipients"`
Processors []string `json:"processors"`
RetentionPeriod string `json:"retention_period"`
SecurityMeasures string `json:"security_measures"`
ControllerName string `json:"controller_name"`
}
func validateEntry(req entryRequest) error {
if req.UseCaseName == "" {
return fmt.Errorf("use_case_name is required")
}
if req.LegalBasis == "" {
return fmt.Errorf("legal_basis is required")
}
if req.Purpose == "" {
return fmt.Errorf("purpose is required")
}
if req.RetentionPeriod == "" {
return fmt.Errorf("retention_period is required")
}
return nil
}
func (h *Handler) createEntry(w http.ResponseWriter, r *http.Request) {
tenantID, ok := tenantFrom(w, r)
if !ok {
return
}
var req entryRequest
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
apierror.WriteError(w, apierror.NewBadRequestError("invalid JSON: "+err.Error()))
return
}
if err := validateEntry(req); err != nil {
apierror.WriteError(w, apierror.NewBadRequestError(err.Error()))
return
}
if req.DataCategories == nil {
req.DataCategories = []string{}
}
if req.Recipients == nil {
req.Recipients = []string{}
}
if req.Processors == nil {
req.Processors = []string{}
}
entry := ProcessingEntry{
TenantID: tenantID,
UseCaseName: req.UseCaseName,
LegalBasis: req.LegalBasis,
Purpose: req.Purpose,
DataCategories: req.DataCategories,
Recipients: req.Recipients,
Processors: req.Processors,
RetentionPeriod: req.RetentionPeriod,
SecurityMeasures: req.SecurityMeasures,
ControllerName: req.ControllerName,
IsActive: true,
}
created, err := h.store.Create(r.Context(), entry)
if err != nil {
apierror.WriteError(w, apierror.NewUpstreamError("failed to create entry: "+err.Error()))
return
}
h.logger.Info("compliance entry created",
zap.String("id", created.ID),
zap.String("tenant_id", tenantID),
)
writeJSON(w, http.StatusCreated, created)
}
func (h *Handler) getEntry(w http.ResponseWriter, r *http.Request) {
tenantID, ok := tenantFrom(w, r)
if !ok {
return
}
id := chi.URLParam(r, "id")
entry, err := h.store.Get(r.Context(), id, tenantID)
if err != nil {
writeStoreError(w, err)
return
}
writeJSON(w, http.StatusOK, entry)
}
func (h *Handler) updateEntry(w http.ResponseWriter, r *http.Request) {
tenantID, ok := tenantFrom(w, r)
if !ok {
return
}
id := chi.URLParam(r, "id")
var req entryRequest
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
apierror.WriteError(w, apierror.NewBadRequestError("invalid JSON: "+err.Error()))
return
}
if err := validateEntry(req); err != nil {
apierror.WriteError(w, apierror.NewBadRequestError(err.Error()))
return
}
if req.DataCategories == nil {
req.DataCategories = []string{}
}
if req.Recipients == nil {
req.Recipients = []string{}
}
if req.Processors == nil {
req.Processors = []string{}
}
entry := ProcessingEntry{
ID: id,
TenantID: tenantID,
UseCaseName: req.UseCaseName,
LegalBasis: req.LegalBasis,
Purpose: req.Purpose,
DataCategories: req.DataCategories,
Recipients: req.Recipients,
Processors: req.Processors,
RetentionPeriod: req.RetentionPeriod,
SecurityMeasures: req.SecurityMeasures,
ControllerName: req.ControllerName,
IsActive: true,
}
updated, err := h.store.Update(r.Context(), entry)
if err != nil {
writeStoreError(w, err)
return
}
h.logger.Info("compliance entry updated",
zap.String("id", id),
zap.String("tenant_id", tenantID),
)
writeJSON(w, http.StatusOK, updated)
}
func (h *Handler) deleteEntry(w http.ResponseWriter, r *http.Request) {
tenantID, ok := tenantFrom(w, r)
if !ok {
return
}
id := chi.URLParam(r, "id")
if err := h.store.Delete(r.Context(), id, tenantID); err != nil {
writeStoreError(w, err)
return
}
h.logger.Info("compliance entry deleted",
zap.String("id", id),
zap.String("tenant_id", tenantID),
)
w.WriteHeader(http.StatusNoContent)
}
// ─── AI Act classification (E9-02) ───────────────────────────────────────────
type classifyRequest struct {
Answers map[string]bool `json:"answers"`
}
func (h *Handler) classifyEntry(w http.ResponseWriter, r *http.Request) {
tenantID, ok := tenantFrom(w, r)
if !ok {
return
}
id := chi.URLParam(r, "id")
var req classifyRequest
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
apierror.WriteError(w, apierror.NewBadRequestError("invalid JSON: "+err.Error()))
return
}
if len(req.Answers) == 0 {
apierror.WriteError(w, apierror.NewBadRequestError("answers is required"))
return
}
// Fetch current entry
entry, err := h.store.Get(r.Context(), id, tenantID)
if err != nil {
writeStoreError(w, err)
return
}
// Compute risk level
entry.RiskLevel = ScoreRisk(req.Answers)
entry.AiActAnswers = req.Answers
updated, err := h.store.Update(r.Context(), entry)
if err != nil {
writeStoreError(w, err)
return
}
h.logger.Info("AI Act classification updated",
zap.String("id", id),
zap.String("risk_level", updated.RiskLevel),
zap.String("tenant_id", tenantID),
)
writeJSON(w, http.StatusOK, updated)
}
// ─── PDF reports ─────────────────────────────────────────────────────────────
func (h *Handler) reportArticle30(w http.ResponseWriter, r *http.Request) {
tenantID, ok := tenantFrom(w, r)
if !ok {
return
}
entries, err := h.store.List(r.Context(), tenantID)
if err != nil {
apierror.WriteError(w, apierror.NewUpstreamError("failed to load entries: "+err.Error()))
return
}
format := r.URL.Query().Get("format")
if format == "json" {
writeJSON(w, http.StatusOK, map[string]interface{}{"data": entries})
return
}
filename := fmt.Sprintf("article30_rgpd_%s.pdf", time.Now().Format("2006-01-02"))
w.Header().Set("Content-Type", "application/pdf")
w.Header().Set("Content-Disposition", "attachment; filename=\""+filename+"\"")
if err := GenerateArticle30(entries, h.tenantName, w); err != nil {
h.logger.Error("Article 30 PDF generation failed", zap.Error(err))
}
}
func (h *Handler) reportAiAct(w http.ResponseWriter, r *http.Request) {
tenantID, ok := tenantFrom(w, r)
if !ok {
return
}
entries, err := h.store.List(r.Context(), tenantID)
if err != nil {
apierror.WriteError(w, apierror.NewUpstreamError("failed to load entries: "+err.Error()))
return
}
format := r.URL.Query().Get("format")
if format == "json" {
writeJSON(w, http.StatusOK, map[string]interface{}{"data": entries})
return
}
filename := fmt.Sprintf("aiact_report_%s.pdf", time.Now().Format("2006-01-02"))
w.Header().Set("Content-Type", "application/pdf")
w.Header().Set("Content-Disposition", "attachment; filename=\""+filename+"\"")
if err := GenerateAiActReport(entries, h.tenantName, w); err != nil {
h.logger.Error("AI Act PDF generation failed", zap.Error(err))
}
}
func (h *Handler) reportDPIA(w http.ResponseWriter, r *http.Request) {
tenantID, ok := tenantFrom(w, r)
if !ok {
return
}
id := chi.URLParam(r, "id")
entry, err := h.store.Get(r.Context(), id, tenantID)
if err != nil {
writeStoreError(w, err)
return
}
filename := fmt.Sprintf("dpia_%s_%s.pdf", id[:8], time.Now().Format("2006-01-02"))
w.Header().Set("Content-Type", "application/pdf")
w.Header().Set("Content-Disposition", "attachment; filename=\""+filename+"\"")
if err := GenerateDPIA(entry, h.tenantName, w); err != nil {
h.logger.Error("DPIA PDF generation failed", zap.Error(err))
}
}
// ─── GDPR Art. 15 — right of access ──────────────────────────────────────────
func (h *Handler) gdprAccess(w http.ResponseWriter, r *http.Request) {
if h.auditLog == nil {
apierror.WriteError(w, &apierror.APIError{
Type: "not_implemented", Message: "audit logging not enabled", HTTPStatus: http.StatusNotImplemented,
})
return
}
tenantID, ok := tenantFrom(w, r)
if !ok {
return
}
targetUser := chi.URLParam(r, "user_id")
q := auditlog.AuditQuery{
TenantID: tenantID,
UserID: targetUser,
Limit: 1000,
}
result, err := h.auditLog.Query(r.Context(), q)
if err != nil {
apierror.WriteError(w, apierror.NewUpstreamError("failed to query logs: "+err.Error()))
return
}
h.logger.Info("GDPR Art. 15 access request",
zap.String("target_user", targetUser),
zap.String("requested_by", userFrom(r)),
zap.Int("records", result.Total),
)
writeJSON(w, http.StatusOK, map[string]interface{}{
"user_id": targetUser,
"generated_at": time.Now().Format(time.RFC3339),
"total": result.Total,
"records": result.Data,
})
}
// ─── GDPR Art. 17 — right to erasure ─────────────────────────────────────────
func (h *Handler) gdprErase(w http.ResponseWriter, r *http.Request) {
tenantID, ok := tenantFrom(w, r)
if !ok {
return
}
targetUser := chi.URLParam(r, "user_id")
reason := r.URL.Query().Get("reason")
requestedBy := userFrom(r)
// Soft-delete user in users table
recordsDeleted := 0
if h.db != nil {
res, err := h.db.ExecContext(r.Context(),
`UPDATE users SET is_active=FALSE, updated_at=NOW() WHERE email=$1 AND tenant_id=$2`,
targetUser, tenantID,
)
if err != nil {
h.logger.Warn("GDPR erase: users table update failed", zap.Error(err))
} else {
n, _ := res.RowsAffected()
recordsDeleted = int(n)
}
// Log erasure (immutable)
_, logErr := h.db.ExecContext(r.Context(),
`INSERT INTO gdpr_erasure_log (tenant_id, target_user, requested_by, reason, records_deleted)
VALUES ($1, $2, $3, $4, $5)`,
tenantID, targetUser, requestedBy, reason, recordsDeleted,
)
if logErr != nil {
h.logger.Error("GDPR erase: failed to write erasure log", zap.Error(logErr))
}
}
h.logger.Info("GDPR Art. 17 erasure",
zap.String("target_user", targetUser),
zap.String("requested_by", requestedBy),
zap.Int("records_deleted", recordsDeleted),
)
writeJSON(w, http.StatusOK, ErasureRecord{
TenantID: tenantID,
TargetUser: targetUser,
RequestedBy: requestedBy,
Reason: reason,
RecordsDeleted: recordsDeleted,
Status: "completed",
CreatedAt: time.Now(),
})
}
// ─── CSV export (E7-10) ───────────────────────────────────────────────────────
func (h *Handler) exportLogsCSV(w http.ResponseWriter, r *http.Request) {
if h.auditLog == nil {
apierror.WriteError(w, &apierror.APIError{
Type: "not_implemented", Message: "audit logging not enabled", HTTPStatus: http.StatusNotImplemented,
})
return
}
tenantID, ok := tenantFrom(w, r)
if !ok {
return
}
q := auditlog.AuditQuery{
TenantID: tenantID,
Provider: r.URL.Query().Get("provider"),
Limit: 10000,
}
if s := r.URL.Query().Get("start"); s != "" {
if t, err := time.Parse(time.RFC3339, s); err == nil {
q.StartTime = t
}
}
if s := r.URL.Query().Get("end"); s != "" {
if t, err := time.Parse(time.RFC3339, s); err == nil {
q.EndTime = t
}
}
result, err := h.auditLog.Query(r.Context(), q)
if err != nil {
apierror.WriteError(w, apierror.NewUpstreamError("failed to query logs: "+err.Error()))
return
}
filename := fmt.Sprintf("audit_logs_%s_%s.csv", tenantID[:8], time.Now().Format("2006-01-02"))
w.Header().Set("Content-Type", "text/csv; charset=utf-8")
w.Header().Set("Content-Disposition", "attachment; filename=\""+filename+"\"")
// Write CSV header
fmt.Fprintln(w, "request_id,timestamp,user_id,tenant_id,provider,model_requested,model_used,department,user_role,sensitivity_level,token_input,token_output,token_total,cost_usd,latency_ms,status,error_type,pii_entity_count,stream")
for _, e := range result.Data {
fmt.Fprintf(w, "%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%d,%d,%d,%.6f,%d,%s,%s,%d,%t\n",
e.RequestID,
e.Timestamp.Format(time.RFC3339),
e.UserID,
e.TenantID,
e.Provider,
e.ModelRequested,
e.ModelUsed,
e.Department,
e.UserRole,
e.SensitivityLevel,
e.TokenInput,
e.TokenOutput,
e.TokenTotal,
e.CostUSD,
e.LatencyMs,
e.Status,
e.ErrorType,
e.PIIEntityCount,
e.Stream,
)
}
}

529
internal/compliance/pdf.go Normal file
View File

@ -0,0 +1,529 @@
package compliance
import (
"bytes"
"fmt"
"io"
"strings"
"time"
"github.com/go-pdf/fpdf"
)
// ─── colour palette ───────────────────────────────────────────────────────────
var (
colNavy = [3]int{30, 58, 95}
colBlack = [3]int{30, 30, 30}
colGray = [3]int{100, 100, 100}
colLightBg = [3]int{245, 247, 250}
colRed = [3]int{220, 38, 38}
colOrange = [3]int{234, 88, 12}
colAmber = [3]int{180, 110, 10}
colGreen = [3]int{21, 128, 61}
)
func riskColor(risk string) [3]int {
switch risk {
case "forbidden":
return colRed
case "high":
return colOrange
case "limited":
return colAmber
case "minimal":
return colGreen
default:
return colGray
}
}
// ─── helpers ─────────────────────────────────────────────────────────────────
func newPDF() *fpdf.Fpdf {
pdf := fpdf.New("P", "mm", "A4", "")
pdf.SetMargins(20, 20, 20)
pdf.SetAutoPageBreak(true, 20)
return pdf
}
func setFont(pdf *fpdf.Fpdf, style string, size float64, col [3]int) {
pdf.SetFont("Helvetica", style, size)
pdf.SetTextColor(col[0], col[1], col[2])
}
func sectionHeader(pdf *fpdf.Fpdf, title string) {
pdf.Ln(6)
pdf.SetFillColor(colNavy[0], colNavy[1], colNavy[2])
pdf.SetTextColor(255, 255, 255)
pdf.SetFont("Helvetica", "B", 10)
pdf.CellFormat(0, 8, " "+title, "", 1, "L", true, 0, "")
pdf.SetTextColor(colBlack[0], colBlack[1], colBlack[2])
pdf.Ln(2)
}
func labelValue(pdf *fpdf.Fpdf, label, value string) {
if value == "" {
value = "—"
}
setFont(pdf, "B", 9, colGray)
pdf.CellFormat(55, 6, label+":", "", 0, "L", false, 0, "")
setFont(pdf, "", 9, colBlack)
pdf.MultiCell(0, 6, value, "", "L", false)
}
func tableRow(pdf *fpdf.Fpdf, cols []string, widths []float64, fill bool) {
if fill {
pdf.SetFillColor(colLightBg[0], colLightBg[1], colLightBg[2])
} else {
pdf.SetFillColor(255, 255, 255)
}
for i, col := range cols {
pdf.CellFormat(widths[i], 6, col, "1", 0, "L", fill, 0, "")
}
pdf.Ln(-1)
}
func footer(pdf *fpdf.Fpdf) {
pdf.SetFooterFunc(func() {
pdf.SetY(-15)
setFont(pdf, "I", 8, colGray)
pdf.CellFormat(0, 10,
fmt.Sprintf("Généré par Veylant IA · %s · Page %d/{nb}",
time.Now().Format("02/01/2006"),
pdf.PageNo(),
),
"", 0, "C", false, 0, "")
})
pdf.AliasNbPages("{nb}")
}
func covePage(pdf *fpdf.Fpdf, title, subtitle, tenantName string) {
pdf.AddPage()
pdf.Ln(30)
// Title block
pdf.SetFillColor(colNavy[0], colNavy[1], colNavy[2])
pdf.SetTextColor(255, 255, 255)
pdf.SetFont("Helvetica", "B", 22)
pdf.CellFormat(0, 18, title, "", 1, "C", true, 0, "")
pdf.SetFont("Helvetica", "", 13)
pdf.CellFormat(0, 10, subtitle, "", 1, "C", true, 0, "")
pdf.Ln(6)
// Tenant + date
pdf.SetTextColor(colBlack[0], colBlack[1], colBlack[2])
pdf.SetFont("Helvetica", "", 11)
pdf.CellFormat(0, 8, "Organisation : "+tenantName, "", 1, "C", false, 0, "")
pdf.CellFormat(0, 8, "Date de génération : "+time.Now().Format("02 janvier 2006 à 15:04"), "", 1, "C", false, 0, "")
pdf.Ln(10)
// Confidential stamp
pdf.SetFont("Helvetica", "B", 14)
pdf.SetTextColor(colRed[0], colRed[1], colRed[2])
pdf.CellFormat(0, 10, "⚠ DOCUMENT CONFIDENTIEL", "", 1, "C", false, 0, "")
}
// ─── GenerateArticle30 ────────────────────────────────────────────────────────
// GenerateArticle30 generates a GDPR Article 30 processing registry PDF.
func GenerateArticle30(entries []ProcessingEntry, tenantName string, w io.Writer) error {
if tenantName == "" {
tenantName = "Organisation"
}
pdf := newPDF()
footer(pdf)
covePage(pdf, "Registre des Activités de Traitement",
"Conformément à l'Article 30 du Règlement (UE) 2016/679 (RGPD)", tenantName)
// Section 1 — Responsable de traitement
pdf.AddPage()
sectionHeader(pdf, "1. Identification du Responsable de Traitement")
pdf.Ln(2)
labelValue(pdf, "Organisation", tenantName)
labelValue(pdf, "Plateforme IA", "Veylant IA — Proxy IA multi-fournisseurs")
labelValue(pdf, "DPO / Contact", "dpo@"+strings.ToLower(strings.ReplaceAll(tenantName, " ", ""))+".fr")
labelValue(pdf, "Cadre réglementaire", "RGPD (UE) 2016/679, Loi Informatique et Libertés")
// Section 2 — Tableau des traitements
sectionHeader(pdf, "2. Activités de Traitement")
pdf.Ln(2)
if len(entries) == 0 {
setFont(pdf, "I", 9, colGray)
pdf.CellFormat(0, 8, "Aucun traitement enregistré.", "", 1, "L", false, 0, "")
} else {
widths := []float64{55, 40, 30, 40}
headers := []string{"Cas d'usage", "Finalité", "Base légale", "Catégories de données"}
setFont(pdf, "B", 9, colBlack)
tableRow(pdf, headers, widths, true)
for i, e := range entries {
cats := strings.Join(e.DataCategories, ", ")
if len(cats) > 35 {
cats = cats[:32] + "..."
}
purpose := e.Purpose
if len(purpose) > 38 {
purpose = purpose[:35] + "..."
}
legalLabel := LegalBasisLabels[e.LegalBasis]
if legalLabel == "" {
legalLabel = e.LegalBasis
}
setFont(pdf, "", 8, colBlack)
tableRow(pdf, []string{e.UseCaseName, purpose, legalLabel, cats}, widths, i%2 == 0)
}
}
// Section 3 — Sous-traitants
sectionHeader(pdf, "3. Destinataires et Sous-Traitants (Fournisseurs LLM)")
pdf.Ln(2)
allProcessors := map[string]bool{}
for _, e := range entries {
for _, p := range e.Processors {
allProcessors[p] = true
}
for _, r := range e.Recipients {
allProcessors[r] = true
}
}
if len(allProcessors) == 0 {
allProcessors["OpenAI (GPT-4o)"] = true
allProcessors["Anthropic (Claude)"] = true
}
for proc := range allProcessors {
setFont(pdf, "", 9, colBlack)
pdf.CellFormat(5, 6, "•", "", 0, "L", false, 0, "")
pdf.CellFormat(0, 6, proc+" — fournisseur LLM (sous-traitant au sens de l'Art. 28 RGPD)", "", 1, "L", false, 0, "")
}
// Section 4 — Durées de conservation
sectionHeader(pdf, "4. Durées de Conservation")
pdf.Ln(2)
if len(entries) > 0 {
widths := []float64{85, 80}
headers := []string{"Cas d'usage", "Durée de conservation"}
setFont(pdf, "B", 9, colBlack)
tableRow(pdf, headers, widths, true)
for i, e := range entries {
setFont(pdf, "", 8, colBlack)
tableRow(pdf, []string{e.UseCaseName, e.RetentionPeriod}, widths, i%2 == 0)
}
}
pdf.Ln(3)
setFont(pdf, "I", 8, colGray)
pdf.MultiCell(0, 5,
"Architecture Veylant IA : journaux chauds 90 jours (ClickHouse), archives tièdes 1 an, archives froides 5 ans (TTL automatique).",
"", "L", false)
// Section 5 — Mesures de sécurité
sectionHeader(pdf, "5. Mesures de Sécurité Techniques et Organisationnelles")
pdf.Ln(2)
measures := []string{
"Chiffrement AES-256-GCM des prompts avant stockage",
"Pseudonymisation automatique des données personnelles (PII) avant transmission aux LLM",
"Contrôle d'accès RBAC (Admin, Manager, Utilisateur, Auditeur)",
"Authentification forte via Keycloak (OIDC/SAML 2.0 / MFA)",
"Journaux d'audit immuables (ClickHouse append-only, TTL uniquement)",
"TLS 1.3 pour toutes les communications externes",
"Circuit breaker pour la résilience des fournisseurs",
"Séparation logique multi-locataires (Row-Level Security PostgreSQL)",
}
for _, m := range measures {
setFont(pdf, "", 9, colBlack)
pdf.CellFormat(5, 6, "✓", "", 0, "L", false, 0, "")
pdf.MultiCell(0, 6, m, "", "L", false)
}
// Section 6 — Droits des personnes
sectionHeader(pdf, "6. Droits des Personnes Concernées")
pdf.Ln(2)
rights := []struct{ art, desc string }{
{"Art. 15", "Droit d'accès — Endpoint GET /v1/admin/compliance/gdpr/access/{user_id}"},
{"Art. 16", "Droit de rectification — via l'interface d'administration"},
{"Art. 17", "Droit à l'effacement — Endpoint DELETE /v1/admin/compliance/gdpr/erase/{user_id}"},
{"Art. 18", "Droit à la limitation — contact DPO"},
{"Art. 20", "Droit à la portabilité — export JSON/CSV disponible"},
{"Art. 21", "Droit d'opposition — contact DPO"},
{"Art. 22", "Droit à ne pas faire l'objet d'une décision automatisée — supervision humaine obligatoire"},
}
widths := []float64{20, 145}
setFont(pdf, "B", 9, colBlack)
tableRow(pdf, []string{"Article", "Description"}, widths, true)
for i, r := range rights {
setFont(pdf, "", 8, colBlack)
tableRow(pdf, []string{r.art, r.desc}, widths, i%2 == 0)
}
var buf bytes.Buffer
if err := pdf.Output(&buf); err != nil {
return fmt.Errorf("pdf output: %w", err)
}
_, err := w.Write(buf.Bytes())
return err
}
// ─── GenerateAiActReport ──────────────────────────────────────────────────────
// GenerateAiActReport generates an EU AI Act risk classification report PDF.
func GenerateAiActReport(entries []ProcessingEntry, tenantName string, w io.Writer) error {
if tenantName == "" {
tenantName = "Organisation"
}
pdf := newPDF()
footer(pdf)
covePage(pdf, "Rapport de Classification AI Act",
"Conformément au Règlement (UE) 2024/1689 sur l'Intelligence Artificielle", tenantName)
pdf.AddPage()
// Summary
sectionHeader(pdf, "Synthèse de la Classification")
pdf.Ln(2)
counts := map[string]int{"forbidden": 0, "high": 0, "limited": 0, "minimal": 0, "": 0}
for _, e := range entries {
counts[e.RiskLevel]++
}
widths := []float64{50, 30, 85}
setFont(pdf, "B", 9, colBlack)
tableRow(pdf, []string{"Niveau de risque", "Nb systèmes", "Obligations réglementaires"}, widths, true)
obligations := map[string]string{
"forbidden": "INTERDIT — blocage automatique requis",
"high": "DPIA obligatoire · supervision humaine · journalisation renforcée",
"limited": "Obligation de transparence (Art. 50) · mention IA requise",
"minimal": "Journalisation standard uniquement",
"": "Non classifié — questionnaire à compléter",
}
riskOrder := []string{"forbidden", "high", "limited", "minimal", ""}
for i, risk := range riskOrder {
label := RiskLabels[risk]
if label == "" {
label = "Non classifié"
}
col := riskColor(risk)
pdf.SetTextColor(col[0], col[1], col[2])
pdf.SetFont("Helvetica", "B", 8)
fill := i%2 == 0
if fill {
pdf.SetFillColor(colLightBg[0], colLightBg[1], colLightBg[2])
} else {
pdf.SetFillColor(255, 255, 255)
}
pdf.CellFormat(widths[0], 6, label, "1", 0, "L", fill, 0, "")
setFont(pdf, "", 8, colBlack)
pdf.CellFormat(widths[1], 6, fmt.Sprintf("%d", counts[risk]), "1", 0, "C", fill, 0, "")
pdf.CellFormat(widths[2], 6, obligations[risk], "1", 1, "L", fill, 0, "")
}
// Per-system detail
if len(entries) > 0 {
sectionHeader(pdf, "Détail par Système IA")
pdf.Ln(2)
for _, e := range entries {
col := riskColor(e.RiskLevel)
riskLabel := RiskLabels[e.RiskLevel]
if riskLabel == "" {
riskLabel = "Non classifié"
}
// System header
pdf.SetFillColor(colLightBg[0], colLightBg[1], colLightBg[2])
pdf.SetFont("Helvetica", "B", 10)
pdf.SetTextColor(colNavy[0], colNavy[1], colNavy[2])
pdf.CellFormat(0, 8, " "+e.UseCaseName, "LRT", 1, "L", true, 0, "")
// Risk badge
pdf.SetFont("Helvetica", "B", 9)
pdf.SetTextColor(col[0], col[1], col[2])
pdf.CellFormat(40, 6, " Niveau : "+riskLabel, "LB", 0, "L", true, 0, "")
setFont(pdf, "", 9, colBlack)
pdf.CellFormat(0, 6, " Base légale : "+LegalBasisLabels[e.LegalBasis], "RB", 1, "L", true, 0, "")
// Details
pdf.Ln(1)
labelValue(pdf, "Finalité", e.Purpose)
labelValue(pdf, "Données traitées", strings.Join(e.DataCategories, ", "))
labelValue(pdf, "Durée conservation", e.RetentionPeriod)
if len(e.AiActAnswers) > 0 {
yesItems := []string{}
for _, q := range AiActQuestions {
if e.AiActAnswers[q.Key] {
yesItems = append(yesItems, "• "+q.Label)
}
}
if len(yesItems) > 0 {
setFont(pdf, "B", 9, colGray)
pdf.CellFormat(55, 6, "Critères AI Act :", "", 1, "L", false, 0, "")
setFont(pdf, "", 8, colBlack)
for _, yi := range yesItems {
pdf.MultiCell(0, 5, " "+yi, "", "L", false)
}
}
}
pdf.Ln(4)
}
}
// Regulatory note
sectionHeader(pdf, "Note Réglementaire")
pdf.Ln(2)
setFont(pdf, "", 9, colBlack)
pdf.MultiCell(0, 6,
"Ce rapport est généré conformément au Règlement (UE) 2024/1689 sur l'Intelligence Artificielle (AI Act), "+
"entré en vigueur le 1er août 2024. Les systèmes classifiés \"Haut risque\" sont soumis à une évaluation "+
"de conformité avant déploiement. Les systèmes \"Interdits\" ne peuvent être mis en service sur le territoire "+
"de l'Union Européenne. Ce document doit être mis à jour à chaque modification substantielle d'un système IA.",
"", "L", false)
var buf bytes.Buffer
if err := pdf.Output(&buf); err != nil {
return fmt.Errorf("pdf output: %w", err)
}
_, err := w.Write(buf.Bytes())
return err
}
// ─── GenerateDPIA ─────────────────────────────────────────────────────────────
// GenerateDPIA generates a pre-filled DPIA template for a processing entry (Art. 35 GDPR).
func GenerateDPIA(entry ProcessingEntry, tenantName string, w io.Writer) error {
if tenantName == "" {
tenantName = "Organisation"
}
pdf := newPDF()
footer(pdf)
covePage(pdf, "Analyse d'Impact relative à la Protection des Données",
"Data Protection Impact Assessment (DPIA) — Article 35 RGPD", tenantName)
pdf.AddPage()
// Section 1 — Description
sectionHeader(pdf, "1. Description du Traitement")
pdf.Ln(2)
labelValue(pdf, "Cas d'usage", entry.UseCaseName)
labelValue(pdf, "Finalité", entry.Purpose)
labelValue(pdf, "Base légale", LegalBasisLabels[entry.LegalBasis])
labelValue(pdf, "Catégories de données", strings.Join(entry.DataCategories, ", "))
labelValue(pdf, "Destinataires", strings.Join(entry.Recipients, ", "))
labelValue(pdf, "Sous-traitants LLM", strings.Join(entry.Processors, ", "))
labelValue(pdf, "Durée de conservation", entry.RetentionPeriod)
labelValue(pdf, "Classification AI Act", RiskLabels[entry.RiskLevel])
// Section 2 — Nécessité et proportionnalité
sectionHeader(pdf, "2. Nécessité et Proportionnalité")
pdf.Ln(2)
setFont(pdf, "", 9, colBlack)
pdf.MultiCell(0, 6,
"Le traitement est nécessaire pour atteindre la finalité identifiée. "+
"La pseudonymisation automatique des données personnelles par Veylant IA "+
"(avant transmission aux fournisseurs LLM) constitue une mesure de minimisation des données "+
"conforme à l'Art. 5(1)(c) RGPD. "+
"Seules les catégories de données strictement nécessaires sont traitées.",
"", "L", false)
// Section 3 — Risques
sectionHeader(pdf, "3. Évaluation des Risques")
pdf.Ln(2)
risks := []struct{ risk, proba, impact, mitigation string }{
{
"Accès non autorisé aux données",
"Faible",
"Élevé",
"RBAC strict, MFA, TLS 1.3, chiffrement AES-256-GCM",
},
{
"Fuite de données vers fournisseur LLM",
"Très faible",
"Élevé",
"Pseudonymisation PII avant envoi, contrats DPA avec fournisseurs (Art. 28)",
},
{
"Rétention excessive des données",
"Faible",
"Moyen",
"TTL automatique ClickHouse, politique de rétention définie (" + entry.RetentionPeriod + ")",
},
{
"Décision automatisée non supervisée",
"Moyen",
"Élevé",
"Supervision humaine obligatoire pour décisions à impact légal",
},
{
"Indisponibilité du service",
"Faible",
"Moyen",
"Circuit breaker, failover multi-fournisseurs, monitoring Prometheus",
},
}
widths := []float64{60, 22, 22, 61}
setFont(pdf, "B", 9, colBlack)
tableRow(pdf, []string{"Risque", "Probabilité", "Impact", "Mesure d'atténuation"}, widths, true)
for i, r := range risks {
setFont(pdf, "", 8, colBlack)
tableRow(pdf, []string{r.risk, r.proba, r.impact, r.mitigation}, widths, i%2 == 0)
}
// Section 4 — Mesures d'atténuation
sectionHeader(pdf, "4. Mesures d'Atténuation Implémentées")
pdf.Ln(2)
if entry.SecurityMeasures != "" {
labelValue(pdf, "Mesures spécifiques", entry.SecurityMeasures)
}
genericMeasures := []string{
"Pseudonymisation automatique des PII (regex + NER + validation LLM)",
"Chiffrement AES-256-GCM au repos et TLS 1.3 en transit",
"RBAC avec 4 niveaux (Admin, Manager, Utilisateur, Auditeur)",
"Journaux d'audit immuables avec conservation " + entry.RetentionPeriod,
"Tests de sécurité SAST/DAST en pipeline CI/CD",
"Contrats de sous-traitance (DPA) avec chaque fournisseur LLM",
}
for _, m := range genericMeasures {
setFont(pdf, "", 9, colBlack)
pdf.CellFormat(5, 6, "✓", "", 0, "L", false, 0, "")
pdf.MultiCell(0, 6, m, "", "L", false)
}
// Section 5 — Risque résiduel
sectionHeader(pdf, "5. Risque Résiduel et Conclusion")
pdf.Ln(2)
setFont(pdf, "", 9, colBlack)
pdf.MultiCell(0, 6,
"Après application des mesures d'atténuation identifiées, le risque résiduel est évalué comme "+
"ACCEPTABLE. Ce traitement peut être mis en œuvre sous réserve du respect continu des mesures "+
"de sécurité décrites. Une réévaluation annuelle ou lors de toute modification substantielle "+
"du traitement est recommandée.",
"", "L", false)
// Section 6 — Signatures
sectionHeader(pdf, "6. Approbation")
pdf.Ln(4)
col1 := 85.0
col2 := 85.0
setFont(pdf, "B", 9, colBlack)
pdf.CellFormat(col1, 6, "Responsable de traitement", "", 0, "C", false, 0, "")
pdf.CellFormat(col2, 6, "Délégué à la Protection des Données", "", 1, "C", false, 0, "")
pdf.Ln(10)
setFont(pdf, "", 9, colGray)
pdf.CellFormat(col1, 6, "Signature : ________________________", "", 0, "C", false, 0, "")
pdf.CellFormat(col2, 6, "Signature : ________________________", "", 1, "C", false, 0, "")
pdf.Ln(3)
pdf.CellFormat(col1, 6, "Date : ____/____/________", "", 0, "C", false, 0, "")
pdf.CellFormat(col2, 6, "Date : ____/____/________", "", 1, "C", false, 0, "")
var buf bytes.Buffer
if err := pdf.Output(&buf); err != nil {
return fmt.Errorf("pdf output: %w", err)
}
_, err := w.Write(buf.Bytes())
return err
}

241
internal/compliance/pg_store.go Normal file
View File

@ -0,0 +1,241 @@
package compliance
import (
"context"
"database/sql"
"encoding/json"
"errors"
"fmt"
"time"
"go.uber.org/zap"
)
// PgStore implements ComplianceStore using PostgreSQL.
type PgStore struct {
db *sql.DB
logger *zap.Logger
}
// NewPgStore creates a PgStore backed by the given database connection.
func NewPgStore(db *sql.DB, logger *zap.Logger) *PgStore {
return &PgStore{db: db, logger: logger}
}
func (p *PgStore) List(ctx context.Context, tenantID string) ([]ProcessingEntry, error) {
const q = `
SELECT id, tenant_id, use_case_name, legal_basis, purpose,
data_categories, recipients, processors,
retention_period,
COALESCE(security_measures,''), COALESCE(controller_name,''),
COALESCE(risk_level,''), ai_act_answers,
is_active, created_at, updated_at
FROM processing_registry
WHERE tenant_id = $1 AND is_active = TRUE
ORDER BY created_at DESC`
rows, err := p.db.QueryContext(ctx, q, tenantID)
if err != nil {
return nil, fmt.Errorf("processing_registry list: %w", err)
}
defer rows.Close() //nolint:errcheck
var entries []ProcessingEntry
for rows.Next() {
e, err := scanEntry(rows)
if err != nil {
return nil, err
}
entries = append(entries, e)
}
return entries, rows.Err()
}
func (p *PgStore) Get(ctx context.Context, id, tenantID string) (ProcessingEntry, error) {
const q = `
SELECT id, tenant_id, use_case_name, legal_basis, purpose,
data_categories, recipients, processors,
retention_period,
COALESCE(security_measures,''), COALESCE(controller_name,''),
COALESCE(risk_level,''), ai_act_answers,
is_active, created_at, updated_at
FROM processing_registry
WHERE id = $1 AND tenant_id = $2`
row := p.db.QueryRowContext(ctx, q, id, tenantID)
e, err := scanEntry(row)
if errors.Is(err, sql.ErrNoRows) {
return ProcessingEntry{}, ErrNotFound
}
return e, err
}
func (p *PgStore) Create(ctx context.Context, entry ProcessingEntry) (ProcessingEntry, error) {
catJSON, err := json.Marshal(entry.DataCategories)
if err != nil {
return ProcessingEntry{}, fmt.Errorf("marshal data_categories: %w", err)
}
recJSON, err := json.Marshal(entry.Recipients)
if err != nil {
return ProcessingEntry{}, fmt.Errorf("marshal recipients: %w", err)
}
procJSON, err := json.Marshal(entry.Processors)
if err != nil {
return ProcessingEntry{}, fmt.Errorf("marshal processors: %w", err)
}
var answersJSON []byte
if entry.AiActAnswers != nil {
answersJSON, err = json.Marshal(entry.AiActAnswers)
if err != nil {
return ProcessingEntry{}, fmt.Errorf("marshal ai_act_answers: %w", err)
}
}
const q = `
INSERT INTO processing_registry
(tenant_id, use_case_name, legal_basis, purpose,
data_categories, recipients, processors,
retention_period, security_measures, controller_name,
risk_level, ai_act_answers)
VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12)
RETURNING id, tenant_id, use_case_name, legal_basis, purpose,
data_categories, recipients, processors,
retention_period,
COALESCE(security_measures,''), COALESCE(controller_name,''),
COALESCE(risk_level,''), ai_act_answers,
is_active, created_at, updated_at`
nilIfEmpty := func(s string) interface{} {
if s == "" {
return nil
}
return s
}
row := p.db.QueryRowContext(ctx, q,
entry.TenantID, entry.UseCaseName, entry.LegalBasis, entry.Purpose,
catJSON, recJSON, procJSON,
entry.RetentionPeriod,
nilIfEmpty(entry.SecurityMeasures), nilIfEmpty(entry.ControllerName),
nilIfEmpty(entry.RiskLevel), answersJSON,
)
return scanEntry(row)
}
func (p *PgStore) Update(ctx context.Context, entry ProcessingEntry) (ProcessingEntry, error) {
catJSON, err := json.Marshal(entry.DataCategories)
if err != nil {
return ProcessingEntry{}, fmt.Errorf("marshal data_categories: %w", err)
}
recJSON, err := json.Marshal(entry.Recipients)
if err != nil {
return ProcessingEntry{}, fmt.Errorf("marshal recipients: %w", err)
}
procJSON, err := json.Marshal(entry.Processors)
if err != nil {
return ProcessingEntry{}, fmt.Errorf("marshal processors: %w", err)
}
var answersJSON []byte
if entry.AiActAnswers != nil {
answersJSON, err = json.Marshal(entry.AiActAnswers)
if err != nil {
return ProcessingEntry{}, fmt.Errorf("marshal ai_act_answers: %w", err)
}
}
nilIfEmpty := func(s string) interface{} {
if s == "" {
return nil
}
return s
}
const q = `
UPDATE processing_registry
SET use_case_name=$3, legal_basis=$4, purpose=$5,
data_categories=$6, recipients=$7, processors=$8,
retention_period=$9, security_measures=$10, controller_name=$11,
risk_level=$12, ai_act_answers=$13, updated_at=NOW()
WHERE id=$1 AND tenant_id=$2
RETURNING id, tenant_id, use_case_name, legal_basis, purpose,
data_categories, recipients, processors,
retention_period,
COALESCE(security_measures,''), COALESCE(controller_name,''),
COALESCE(risk_level,''), ai_act_answers,
is_active, created_at, updated_at`
row := p.db.QueryRowContext(ctx, q,
entry.ID, entry.TenantID,
entry.UseCaseName, entry.LegalBasis, entry.Purpose,
catJSON, recJSON, procJSON,
entry.RetentionPeriod,
nilIfEmpty(entry.SecurityMeasures), nilIfEmpty(entry.ControllerName),
nilIfEmpty(entry.RiskLevel), answersJSON,
)
e, err := scanEntry(row)
if errors.Is(err, sql.ErrNoRows) {
return ProcessingEntry{}, ErrNotFound
}
return e, err
}
func (p *PgStore) Delete(ctx context.Context, id, tenantID string) error {
const q = `UPDATE processing_registry SET is_active=FALSE, updated_at=NOW() WHERE id=$1 AND tenant_id=$2`
res, err := p.db.ExecContext(ctx, q, id, tenantID)
if err != nil {
return fmt.Errorf("processing_registry delete: %w", err)
}
n, _ := res.RowsAffected()
if n == 0 {
return ErrNotFound
}
return nil
}
// ─── scanner ─────────────────────────────────────────────────────────────────
type scanner interface {
Scan(dest ...interface{}) error
}
func scanEntry(s scanner) (ProcessingEntry, error) {
var (
e ProcessingEntry
catJSON []byte
recJSON []byte
procJSON []byte
answersJSON []byte
createdAt time.Time
updatedAt time.Time
)
err := s.Scan(
&e.ID, &e.TenantID, &e.UseCaseName, &e.LegalBasis, &e.Purpose,
&catJSON, &recJSON, &procJSON,
&e.RetentionPeriod, &e.SecurityMeasures, &e.ControllerName,
&e.RiskLevel, &answersJSON,
&e.IsActive, &createdAt, &updatedAt,
)
if err != nil {
return ProcessingEntry{}, fmt.Errorf("scanning processing_registry row: %w", err)
}
e.CreatedAt = createdAt
e.UpdatedAt = updatedAt
if err := json.Unmarshal(catJSON, &e.DataCategories); err != nil {
return ProcessingEntry{}, fmt.Errorf("parsing data_categories JSON: %w", err)
}
if err := json.Unmarshal(recJSON, &e.Recipients); err != nil {
return ProcessingEntry{}, fmt.Errorf("parsing recipients JSON: %w", err)
}
if err := json.Unmarshal(procJSON, &e.Processors); err != nil {
return ProcessingEntry{}, fmt.Errorf("parsing processors JSON: %w", err)
}
if len(answersJSON) > 0 && string(answersJSON) != "null" {
if err := json.Unmarshal(answersJSON, &e.AiActAnswers); err != nil {
return ProcessingEntry{}, fmt.Errorf("parsing ai_act_answers JSON: %w", err)
}
}
return e, nil
}

12
internal/compliance/store.go Normal file
View File

@ -0,0 +1,12 @@
package compliance
import "context"
// ComplianceStore defines persistence operations for the processing registry.
type ComplianceStore interface {
List(ctx context.Context, tenantID string) ([]ProcessingEntry, error)
Get(ctx context.Context, id, tenantID string) (ProcessingEntry, error)
Create(ctx context.Context, entry ProcessingEntry) (ProcessingEntry, error)
Update(ctx context.Context, entry ProcessingEntry) (ProcessingEntry, error)
Delete(ctx context.Context, id, tenantID string) error
}

101
internal/compliance/types.go Normal file
View File

@ -0,0 +1,101 @@
// Package compliance implements the GDPR Article 30 processing registry,
// EU AI Act risk classification, PDF report generation, and GDPR rights APIs.
package compliance
import (
"errors"
"time"
)
// ErrNotFound is returned when a processing entry is not found.
var ErrNotFound = errors.New("compliance entry not found")
// ProcessingEntry represents one record in the GDPR Article 30 processing registry.
type ProcessingEntry struct {
ID string `json:"id"`
TenantID string `json:"tenant_id"`
UseCaseName string `json:"use_case_name"`
LegalBasis string `json:"legal_basis"`
Purpose string `json:"purpose"`
DataCategories []string `json:"data_categories"`
Recipients []string `json:"recipients"`
Processors []string `json:"processors"`
RetentionPeriod string `json:"retention_period"`
SecurityMeasures string `json:"security_measures"`
ControllerName string `json:"controller_name"`
// AI Act fields (E9-02)
RiskLevel string `json:"risk_level"` // minimal|limited|high|forbidden|""
AiActAnswers map[string]bool `json:"ai_act_answers,omitempty"` // q1..q5
IsActive bool `json:"is_active"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
// ErasureRecord is an immutable audit record for GDPR Art. 17 erasure requests.
type ErasureRecord struct {
ID string `json:"erasure_id"`
TenantID string `json:"tenant_id"`
TargetUser string `json:"user_id"`
RequestedBy string `json:"requested_by"`
Reason string `json:"reason"`
RecordsDeleted int `json:"records_deleted"`
Status string `json:"status"`
CreatedAt time.Time `json:"timestamp"`
}
// LegalBasisLabels maps legal_basis values to human-readable French labels.
var LegalBasisLabels = map[string]string{
"consent": "Consentement (Art. 6.1.a)",
"contract": "Exécution d'un contrat (Art. 6.1.b)",
"legal_obligation": "Obligation légale (Art. 6.1.c)",
"vital_interests": "Intérêts vitaux (Art. 6.1.d)",
"public_task": "Mission d'intérêt public (Art. 6.1.e)",
"legitimate_interest": "Intérêt légitime (Art. 6.1.f)",
}
// RiskLabels maps risk_level values to human-readable labels.
var RiskLabels = map[string]string{
"minimal": "Risque minimal",
"limited": "Risque limité",
"high": "Haut risque",
"forbidden": "Interdit",
}
// AiActQuestions defines the 5 EU AI Act classification questions.
// Keys q1..q5 correspond to the ai_act_answers JSONB field.
var AiActQuestions = []struct {
Key string
Label string
}{
{"q1", "Le système prend-il des décisions autonomes affectant des droits légaux ou des situations similaires des personnes ?"},
{"q2", "Implique-t-il une identification biométrique ou une reconnaissance des émotions ?"},
{"q3", "Est-il utilisé dans des décisions critiques (médical, justice, emploi, crédit) ?"},
{"q4", "Traite-t-il des catégories spéciales de données (santé, biométrie, origine raciale) ?"},
{"q5", "La transparence sur l'utilisation de l'IA est-elle indispensable au consentement éclairé ?"},
}
// ScoreRisk computes the EU AI Act risk level from questionnaire answers.
//
// Scoring rules:
// - 0 "yes" → minimal
// - 1–2 "yes" → limited
// - 3–4 "yes" → high
// - 5 "yes" → forbidden
func ScoreRisk(answers map[string]bool) string {
yes := 0
for _, v := range answers {
if v {
yes++
}
}
switch {
case yes == 5:
return "forbidden"
case yes >= 3:
return "high"
case yes >= 1:
return "limited"
default:
return "minimal"
}
}

236
internal/config/config.go Normal file
View File

@ -0,0 +1,236 @@
package config
import (
"fmt"
"strings"
"github.com/spf13/viper"
)
// Config holds all application configuration.
// Values are loaded from config.yaml then overridden by env vars prefixed with VEYLANT_.
// Example: VEYLANT_SERVER_PORT=9090 overrides server.port.
type Config struct {
Server ServerConfig `mapstructure:"server"`
Database DatabaseConfig `mapstructure:"database"`
Redis RedisConfig `mapstructure:"redis"`
Keycloak KeycloakConfig `mapstructure:"keycloak"`
PII PIIConfig `mapstructure:"pii"`
Log LogConfig `mapstructure:"log"`
Providers ProvidersConfig `mapstructure:"providers"`
RBAC RBACConfig `mapstructure:"rbac"`
Metrics MetricsConfig `mapstructure:"metrics"`
Routing RoutingConfig `mapstructure:"routing"`
ClickHouse ClickHouseConfig `mapstructure:"clickhouse"`
Crypto CryptoConfig `mapstructure:"crypto"`
RateLimit RateLimitConfig `mapstructure:"rate_limit"`
}
// RateLimitConfig holds default rate limiting parameters applied to all tenants
// that have no explicit per-tenant override in the rate_limit_configs table.
type RateLimitConfig struct {
// DefaultTenantRPM is the default tenant-wide requests per minute limit.
DefaultTenantRPM int `mapstructure:"default_tenant_rpm"`
// DefaultTenantBurst is the maximum burst size for a tenant bucket.
DefaultTenantBurst int `mapstructure:"default_tenant_burst"`
// DefaultUserRPM is the default per-user requests per minute limit within a tenant.
DefaultUserRPM int `mapstructure:"default_user_rpm"`
// DefaultUserBurst is the maximum burst size for a per-user bucket.
DefaultUserBurst int `mapstructure:"default_user_burst"`
}
// ClickHouseConfig holds ClickHouse connection settings for the audit log.
type ClickHouseConfig struct {
DSN string `mapstructure:"dsn"` // clickhouse://user:pass@host:9000/db
MaxConns int `mapstructure:"max_conns"`
DialTimeoutSec int `mapstructure:"dial_timeout_seconds"`
}
// CryptoConfig holds cryptographic settings.
type CryptoConfig struct {
// AESKeyBase64 is a base64-encoded 32-byte key for AES-256-GCM prompt encryption.
// Set via env var VEYLANT_CRYPTO_AES_KEY_BASE64 — never hardcode.
AESKeyBase64 string `mapstructure:"aes_key_base64"`
}
// RoutingConfig controls the intelligent routing engine behaviour.
type RoutingConfig struct {
// CacheTTLSeconds is how long routing rules are cached per tenant before
// a background refresh. 0 means use the default (30s).
CacheTTLSeconds int `mapstructure:"cache_ttl_seconds"`
}
// ProvidersConfig holds configuration for all LLM provider adapters.
type ProvidersConfig struct {
OpenAI OpenAIConfig `mapstructure:"openai"`
Anthropic AnthropicConfig `mapstructure:"anthropic"`
Azure AzureConfig `mapstructure:"azure"`
Mistral MistralConfig `mapstructure:"mistral"`
Ollama OllamaConfig `mapstructure:"ollama"`
}
// OpenAIConfig holds OpenAI adapter configuration.
type OpenAIConfig struct {
APIKey string `mapstructure:"api_key"`
BaseURL string `mapstructure:"base_url"`
TimeoutSeconds int `mapstructure:"timeout_seconds"`
MaxConns int `mapstructure:"max_conns"`
}
// AnthropicConfig holds Anthropic adapter configuration.
type AnthropicConfig struct {
APIKey string `mapstructure:"api_key"`
BaseURL string `mapstructure:"base_url"`
Version string `mapstructure:"version"` // Anthropic API version header, e.g. "2023-06-01"
TimeoutSeconds int `mapstructure:"timeout_seconds"`
MaxConns int `mapstructure:"max_conns"`
}
// AzureConfig holds Azure OpenAI adapter configuration.
type AzureConfig struct {
APIKey string `mapstructure:"api_key"`
ResourceName string `mapstructure:"resource_name"` // e.g. "my-azure-resource"
DeploymentID string `mapstructure:"deployment_id"` // e.g. "gpt-4o"
APIVersion string `mapstructure:"api_version"` // e.g. "2024-02-01"
TimeoutSeconds int `mapstructure:"timeout_seconds"`
MaxConns int `mapstructure:"max_conns"`
}
// MistralConfig holds Mistral AI adapter configuration (OpenAI-compatible).
type MistralConfig struct {
APIKey string `mapstructure:"api_key"`
BaseURL string `mapstructure:"base_url"`
TimeoutSeconds int `mapstructure:"timeout_seconds"`
MaxConns int `mapstructure:"max_conns"`
}
// OllamaConfig holds Ollama adapter configuration (OpenAI-compatible, local).
type OllamaConfig struct {
BaseURL string `mapstructure:"base_url"`
TimeoutSeconds int `mapstructure:"timeout_seconds"`
MaxConns int `mapstructure:"max_conns"`
}
// RBACConfig holds role-based access control settings for the provider router.
type RBACConfig struct {
// UserAllowedModels lists models accessible to the "user" role (exact or prefix match).
UserAllowedModels []string `mapstructure:"user_allowed_models"`
// AuditorCanComplete controls whether auditors can make chat completions.
// Defaults to false — auditors receive 403 on POST /v1/chat/completions.
AuditorCanComplete bool `mapstructure:"auditor_can_complete"`
}
// MetricsConfig holds Prometheus metrics configuration.
type MetricsConfig struct {
Enabled bool `mapstructure:"enabled"`
Path string `mapstructure:"path"`
}
type ServerConfig struct {
Port int `mapstructure:"port"`
ShutdownTimeout int `mapstructure:"shutdown_timeout_seconds"`
Env string `mapstructure:"env"` // development, staging, production
TenantName string `mapstructure:"tenant_name"` // display name used in PDF reports
AllowedOrigins []string `mapstructure:"allowed_origins"` // CORS allowed origins for the React dashboard
}
type DatabaseConfig struct {
URL string `mapstructure:"url"`
MaxOpenConns int `mapstructure:"max_open_conns"`
MaxIdleConns int `mapstructure:"max_idle_conns"`
MigrationsPath string `mapstructure:"migrations_path"`
}
type RedisConfig struct {
URL string `mapstructure:"url"`
}
type KeycloakConfig struct {
BaseURL string `mapstructure:"base_url"`
Realm string `mapstructure:"realm"`
ClientID string `mapstructure:"client_id"`
}
type PIIConfig struct {
Enabled bool `mapstructure:"enabled"`
ServiceAddr string `mapstructure:"service_addr"` // gRPC address, e.g. localhost:50051
TimeoutMs int `mapstructure:"timeout_ms"`
FailOpen bool `mapstructure:"fail_open"` // if true, pass request through on PII service error
}
type LogConfig struct {
Level string `mapstructure:"level"` // debug, info, warn, error
Format string `mapstructure:"format"` // json, console
}
// Load reads configuration from config.yaml (searched in . and ./config)
// and overrides with environment variables prefixed VEYLANT_.
func Load() (*Config, error) {
v := viper.New()
v.SetConfigName("config")
v.SetConfigType("yaml")
v.AddConfigPath(".")
v.AddConfigPath("./config")
// Env var overrides: VEYLANT_SERVER_PORT → server.port
v.SetEnvPrefix("VEYLANT")
v.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))
v.AutomaticEnv()
// Defaults
v.SetDefault("server.port", 8090)
v.SetDefault("server.shutdown_timeout_seconds", 30)
v.SetDefault("server.env", "development")
v.SetDefault("server.allowed_origins", []string{"http://localhost:3000"})
v.SetDefault("database.max_open_conns", 25)
v.SetDefault("database.max_idle_conns", 5)
v.SetDefault("database.migrations_path", "migrations")
v.SetDefault("pii.enabled", false)
v.SetDefault("pii.service_addr", "localhost:50051")
v.SetDefault("pii.timeout_ms", 100)
v.SetDefault("pii.fail_open", true)
v.SetDefault("log.level", "info")
v.SetDefault("log.format", "json")
v.SetDefault("providers.openai.base_url", "https://api.openai.com/v1")
v.SetDefault("providers.openai.timeout_seconds", 30)
v.SetDefault("providers.openai.max_conns", 100)
v.SetDefault("providers.anthropic.base_url", "https://api.anthropic.com/v1")
v.SetDefault("providers.anthropic.version", "2023-06-01")
v.SetDefault("providers.anthropic.timeout_seconds", 30)
v.SetDefault("providers.anthropic.max_conns", 100)
v.SetDefault("providers.azure.api_version", "2024-02-01")
v.SetDefault("providers.azure.timeout_seconds", 30)
v.SetDefault("providers.azure.max_conns", 100)
v.SetDefault("providers.mistral.base_url", "https://api.mistral.ai/v1")
v.SetDefault("providers.mistral.timeout_seconds", 30)
v.SetDefault("providers.mistral.max_conns", 100)
v.SetDefault("providers.ollama.base_url", "http://localhost:11434/v1")
v.SetDefault("providers.ollama.timeout_seconds", 120)
v.SetDefault("providers.ollama.max_conns", 10)
v.SetDefault("rbac.user_allowed_models", []string{"gpt-4o-mini", "gpt-3.5-turbo", "mistral-small"})
v.SetDefault("rbac.auditor_can_complete", false)
v.SetDefault("metrics.enabled", true)
v.SetDefault("metrics.path", "/metrics")
v.SetDefault("routing.cache_ttl_seconds", 30)
v.SetDefault("clickhouse.max_conns", 10)
v.SetDefault("clickhouse.dial_timeout_seconds", 5)
v.SetDefault("rate_limit.default_tenant_rpm", 1000)
v.SetDefault("rate_limit.default_tenant_burst", 200)
v.SetDefault("rate_limit.default_user_rpm", 100)
v.SetDefault("rate_limit.default_user_burst", 20)
if err := v.ReadInConfig(); err != nil {
if _, ok := err.(viper.ConfigFileNotFoundError); !ok {
return nil, fmt.Errorf("reading config: %w", err)
}
// Config file not found — rely on defaults and env vars only
}
var cfg Config
if err := v.Unmarshal(&cfg); err != nil {
return nil, fmt.Errorf("unmarshaling config: %w", err)
}
return &cfg, nil
}

53
internal/config/config_test.go Normal file
View File

@ -0,0 +1,53 @@
package config_test
import (
"os"
"testing"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
"github.com/veylant/ia-gateway/internal/config"
)
func TestLoad_Defaults(t *testing.T) {
// No config.yaml in the test working directory — relies on defaults.
cfg, err := config.Load()
require.NoError(t, err)
assert.Equal(t, 8090, cfg.Server.Port)
assert.Equal(t, 30, cfg.Server.ShutdownTimeout)
assert.Equal(t, "development", cfg.Server.Env)
assert.Equal(t, "info", cfg.Log.Level)
assert.Equal(t, "json", cfg.Log.Format)
assert.Equal(t, "https://api.openai.com/v1", cfg.Providers.OpenAI.BaseURL)
assert.Equal(t, 30, cfg.Providers.OpenAI.TimeoutSeconds)
assert.Equal(t, 100, cfg.Providers.OpenAI.MaxConns)
assert.True(t, cfg.Metrics.Enabled)
assert.Equal(t, "/metrics", cfg.Metrics.Path)
}
func TestLoad_EnvVarOverride(t *testing.T) {
t.Setenv("VEYLANT_SERVER_PORT", "9999")
t.Setenv("VEYLANT_LOG_LEVEL", "debug")
t.Setenv("VEYLANT_SERVER_ENV", "production")
cfg, err := config.Load()
require.NoError(t, err)
assert.Equal(t, 9999, cfg.Server.Port)
assert.Equal(t, "debug", cfg.Log.Level)
assert.Equal(t, "production", cfg.Server.Env)
}
func TestLoad_NoConfigFileIsNotAnError(t *testing.T) {
// Change to a temp directory with no config.yaml to confirm graceful fallback.
dir := t.TempDir()
origDir, _ := os.Getwd()
require.NoError(t, os.Chdir(dir))
t.Cleanup(func() { _ = os.Chdir(origDir) })
cfg, err := config.Load()
require.NoError(t, err)
assert.NotNil(t, cfg)
}

82
internal/crypto/aes.go Normal file
View File

@ -0,0 +1,82 @@
// Package crypto provides AES-256-GCM encryption utilities for storing
// sensitive prompt data in the audit log without exposing plaintext.
package crypto
import (
"crypto/aes"
"crypto/cipher"
"crypto/rand"
"encoding/base64"
"errors"
"fmt"
"io"
)
// Encryptor encrypts and decrypts strings using AES-256-GCM.
// A random 12-byte nonce is prepended to each ciphertext; output is base64 URL-safe.
type Encryptor struct {
key []byte
}
// NewEncryptor creates an Encryptor from a standard base64-encoded 32-byte key.
// Returns an error if the key is not exactly 32 bytes after decoding.
func NewEncryptor(keyBase64 string) (*Encryptor, error) {
key, err := base64.StdEncoding.DecodeString(keyBase64)
if err != nil {
return nil, fmt.Errorf("crypto: invalid base64 key: %w", err)
}
if len(key) != 32 {
return nil, fmt.Errorf("crypto: key must be 32 bytes, got %d", len(key))
}
return &Encryptor{key: key}, nil
}
// Encrypt encrypts plaintext and returns a base64 URL-safe string.
// Format: base64(nonce[12] || ciphertext).
func (e *Encryptor) Encrypt(plaintext string) (string, error) {
block, err := aes.NewCipher(e.key)
if err != nil {
return "", fmt.Errorf("crypto: new cipher: %w", err)
}
gcm, err := cipher.NewGCM(block)
if err != nil {
return "", fmt.Errorf("crypto: new gcm: %w", err)
}
nonce := make([]byte, gcm.NonceSize())
if _, err := io.ReadFull(rand.Reader, nonce); err != nil {
return "", fmt.Errorf("crypto: generate nonce: %w", err)
}
ciphertext := gcm.Seal(nonce, nonce, []byte(plaintext), nil)
return base64.URLEncoding.EncodeToString(ciphertext), nil
}
// Decrypt decrypts a base64 URL-safe string produced by Encrypt.
func (e *Encryptor) Decrypt(ciphertext string) (string, error) {
data, err := base64.URLEncoding.DecodeString(ciphertext)
if err != nil {
return "", fmt.Errorf("crypto: invalid base64 ciphertext: %w", err)
}
block, err := aes.NewCipher(e.key)
if err != nil {
return "", fmt.Errorf("crypto: new cipher: %w", err)
}
gcm, err := cipher.NewGCM(block)
if err != nil {
return "", fmt.Errorf("crypto: new gcm: %w", err)
}
nonceSize := gcm.NonceSize()
if len(data) < nonceSize {
return "", errors.New("crypto: ciphertext too short")
}
nonce, data := data[:nonceSize], data[nonceSize:]
plaintext, err := gcm.Open(nil, nonce, data, nil)
if err != nil {
return "", fmt.Errorf("crypto: decrypt failed: %w", err)
}
return string(plaintext), nil
}

89
internal/crypto/aes_test.go Normal file
View File

@ -0,0 +1,89 @@
package crypto_test
import (
"encoding/base64"
"strings"
"testing"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
"github.com/veylant/ia-gateway/internal/crypto"
)
// validKey returns a base64-encoded 32-byte key for tests.
func validKey() string {
return base64.StdEncoding.EncodeToString([]byte("01234567890123456789012345678901"))
}
func newEncryptor(t *testing.T) *crypto.Encryptor {
t.Helper()
enc, err := crypto.NewEncryptor(validKey())
require.NoError(t, err)
return enc
}
func TestAES_Roundtrip(t *testing.T) {
enc := newEncryptor(t)
plaintext := "Mon numéro de sécu est 1 85 06 75 116 097 42"
ciphertext, err := enc.Encrypt(plaintext)
require.NoError(t, err)
assert.NotEmpty(t, ciphertext)
assert.NotEqual(t, plaintext, ciphertext)
decrypted, err := enc.Decrypt(ciphertext)
require.NoError(t, err)
assert.Equal(t, plaintext, decrypted)
}
func TestAES_NonceUnique(t *testing.T) {
enc := newEncryptor(t)
plaintext := "same plaintext"
ct1, err := enc.Encrypt(plaintext)
require.NoError(t, err)
ct2, err := enc.Encrypt(plaintext)
require.NoError(t, err)
// Two encryptions of the same plaintext must produce different ciphertexts
// because nonces are random.
assert.NotEqual(t, ct1, ct2)
}
func TestAES_EmptyPlaintext(t *testing.T) {
enc := newEncryptor(t)
ciphertext, err := enc.Encrypt("")
require.NoError(t, err)
decrypted, err := enc.Decrypt(ciphertext)
require.NoError(t, err)
assert.Equal(t, "", decrypted)
}
func TestAES_InvalidKey(t *testing.T) {
// 16-byte key (too short for AES-256)
shortKey := base64.StdEncoding.EncodeToString([]byte("0123456789abcdef"))
_, err := crypto.NewEncryptor(shortKey)
assert.Error(t, err)
assert.True(t, strings.Contains(err.Error(), "32 bytes"))
}
func TestAES_DecryptTampered(t *testing.T) {
enc := newEncryptor(t)
ct, err := enc.Encrypt("some sensitive data")
require.NoError(t, err)
// Corrupt the last character of the base64 ciphertext.
runes := []rune(ct)
runes[len(runes)-1] = 'X'
if runes[len(runes)-1] == []rune(ct)[len(runes)-1] {
runes[len(runes)-1] = 'Y'
}
tampered := string(runes)
_, err = enc.Decrypt(tampered)
assert.Error(t, err, "decrypting tampered ciphertext should fail")
}

Some files were not shown because too many files have changed in this diff Show More