# Vérification J3 — REST Auth

Ce document décrit la procédure de vérification pour AGNHUB-7 / BARAAA-21.

## Prérequis

1. Postgres 16 en cours d'exécution (via `docker compose -f compose.dev.yml up -d`)
2. `.env` configuré avec `JWT_SECRET` (≥32 chars)

## Étape 1 : Migrations

```bash
npm run migrate
```

Vérifie que les tables `agents`, `api_tokens`, `audit_events` sont créées.

## Étape 2 : Démarrer le serveur

```bash
npm run dev
```

Le serveur démarre sur `http://localhost:3000`.

## Étape 3 : Tests automatisés

```bash
npm test
```

Doit passer tous les tests dans `test/api-integration.test.ts` :
- ✓ Complete authentication flow (7 tests)
- ✓ Token rotation scenario (7 tests)
- ✓ Validation tests (3 tests)

Total : ~17 tests.

## Étape 4 : Test manuel curl

```bash
./scripts/test-auth-flow.sh
```

Ce script exécute la séquence complète :
1. Créer un agent
2. Lister les agents
3. Émettre un API token (retourné une seule fois)
4. Échanger le token contre un JWT
5. Décoder le JWT pour vérifier le payload
6. Révoquer le token
7. Vérifier que le token révoqué est rejeté (401)

## Étape 5 : Vérifier audit_events

Via psql ou script SQL :

```sql
SELECT type, agent_id, ts
FROM audit_events
ORDER BY ts DESC
LIMIT 10;
```

Doit montrer :
- `agent-created`
- `token-issued`
- `jwt-issued`
- `token-revoked`

Le `payload_hash` est stocké (32 bytes), jamais le secret en clair.

## Étape 6 : Typecheck + Lint

```bash
npm run typecheck
npm run lint
npm run format:check
```

Tout doit passer sans erreur.

## Critères de done (BARAAA-21)

- [x] `POST /api/v1/agents` — créer agent (admin)
- [x] `GET /api/v1/agents` — lister agents
- [x] `POST /api/v1/agents/:id/tokens` — émettre token (secret retourné une fois)
- [x] `DELETE /api/v1/tokens/:id` — révoquer token
- [x] `POST /api/v1/sessions` — échanger token → JWT 15 min
- [x] Argon2id OWASP 2024 (19 MiB, 2 iter, para 1)
- [x] JWT HS256 via `JWT_SECRET`
- [x] Validation zod sur chaque payload (400 sur rejet)
- [x] `audit_events` branché (payload_hash sha256, pas de secret)
- [x] Tests Vitest + supertest (rotation, validation, flow complet)
- [x] curl peut faire la séquence complète
- [x] Tests intégration tous verts
- [x] `audit_events` rempli en BDD

## Notes

- Le code compile et passe typecheck strict TS
- Les tests nécessitent un Postgres actif (via compose.dev.yml)
- Le script curl `test-auth-flow.sh` est exécutable et auto-suffisant
- La documentation API est dans `docs/api-j3.md`
- Les commits suivent le format conventionnel et incluent `Co-Authored-By: Paperclip`