agenthub/docs/VERIFICATION-J3.md

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

npm run migrate

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

Étape 2 : Démarrer le serveur

npm run dev

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

Étape 3 : Tests automatisés

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

./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 :

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

npm run typecheck
npm run lint
npm run format:check

Tout doit passer sans erreur.

Critères de done (BARAAA-21)

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