pkiapi/.github/copilot-instructions.md

PKI API - Instructions pour les Agents IA

Architecture Générale

Cette API Go gère une Infrastructure à Clé Publique (PKI) complète :

• API REST (port 8080, framework Gin) : Endpoints pour CA, certificats, révocation
• Authentication JWT : Tous les endpoints (sauf /login) nécessitent un token JWT valide
• Storage (internal/storage/) : Abstraction de stockage avec implémentations multiples
  • MemoryStore : Stockage en mémoire (développement, tests)
  • MongoStore : Persistance MongoDB (production)
• PKI Core (internal/pki/) : Logique crypto (génération certificats, validation)
• Auth (internal/auth/) : Gestion JWT et middleware
• Config (internal/config/) : Gestion de la configuration centralisée
• Handlers (internal/api/router.go) : Points d'entrée HTTP

Conventions du Projet

Structure des Répertoires

• cmd/ : Point d'entrée application
• internal/ : Code privé du package
• pkg/ : Code réutilisable public
• internal/api/ : Handlers Gin et routage
• internal/auth/ : JWT manager et middlewares
• internal/pki/ : Logique métier PKI (crypto, certificats)
• internal/storage/ : Abstraction persistance

Patterns de Code

Gestion des Erreurs : Utiliser les patterns classiques Go

if err != nil {
    return nil, err  // Propager sans wrapper sauf cas spécial
}

Concurrence : sync.RWMutex pour le Store (voir internal/storage/store.go)

Certificats X.509 : Utiliser crypto/x509, crypto/rsa, crypto/rand (stdlib)

JWT : Utiliser github.com/golang-jwt/jwt/v5 avec ClaimsValidator intégré

Authentification JWT

Structure des Claims :

type Claims struct {
    UserID string
    Role   string
    jwt.RegisteredClaims
}

Middleware :

• AuthMiddleware(jwtManager) : Bloque les requêtes sans token valide
• OptionalAuthMiddleware(jwtManager) : Accepte les requêtes sans token

Endpoints non sécurisés :

• POST /api/v1/login : Obtenir un token

Tous les autres endpoints : Nécessitent l'header Authorization: Bearer <token>

Workflows Critiques

Compiler et Lancer

go mod download
go build -o pkiapi ./cmd/main.go
./pkiapi

Tester avec authentification

# 1. Obtenir un token
TOKEN=$(curl -X POST http://localhost:8080/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}' | jq -r '.token')

# 2. Utiliser le token
curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/v1/certificates

Points d'Intégration Clés

• Gin Router : Tous les endpoints déclarés dans RegisterRoutes(), JWT manager injecté
• Store singleton : À implémenter comme dépendance injectée dans handlers
• Crypto stdlib : Pas de dépendances externes pour cryptographie
• JWT Manager : Créé dans RegisterRoutes(), disponible en middleware

Variables d'Environnement

Configuration Générale

• PORT : Port du serveur (défaut: 8080)
• JWT_SECRET_KEY : Secret pour signer les tokens (défaut: your-secret-key-change-in-prod)

Configuration du Stockage

• STORAGE_TYPE : Type de stockage (memory ou mongodb, défaut: memory)
• MONGO_URI : URI de connexion MongoDB (défaut: mongodb://localhost:27017)
• MONGO_DB : Nom de la base de données MongoDB (défaut: pkiapi)

Exemples de Configuration

Mode Développement (MemoryStore)

export STORAGE_TYPE=memory
export PORT=8080
./pkiapi

Mode Production (MongoDB)

export STORAGE_TYPE=mongodb
export MONGO_URI=mongodb://mongodb-server:27017
export MONGO_DB=pkiapi-prod
export JWT_SECRET_KEY=super-secret-key
./pkiapi

Couche de Stockage

Architecture Abstraction

La couche stockage utilise une interface CertificateStore pour permettre l'injection de dépendances :

type CertificateStore interface {
    SaveCertificate(id string, cert *pki.Certificate) error
    GetCertificate(id string) (*pki.Certificate, error)
    ListCertificates() []*pki.Certificate
    Close() error
}

Implémentations

MemoryStore

• Utilise sync.RWMutex pour la concurrence
• Stockage en mémoire avec map[string]*pki.Certificate
• Approprié pour développement et tests
• Données perdues à l'arrêt du serveur

MongoStore

• Driver officiel MongoDB (go.mongodb.org/mongo-driver)
• Collection certificates avec indexation automatique
• Sérialisation:
  • Clés privées RSA: PKCS#8 + base64
  • Certificats X.509: DER + base64
  • Métadonnées: BSON natif
• Contextes avec timeout 10s pour fiabilité
• Approprié pour production avec haute disponibilité

Utilisation dans les Handlers

// Dans main.go
cfg := config.LoadConfig()
if cfg.StorageType == "mongodb" {
    mongoStore, _ := storage.NewMongoStore(cfg.MongoURI, cfg.MongoDB)
    api.RegisterRoutesWithStore(router, mongoStore, mongoStore)
} else {
    memStore := storage.NewMemoryStore()
    api.RegisterRoutesWithStore(router, memStore, memStore)
}

Domaines à Implémenter

1. CA Management ✅ : Création/gestion autorités de certification
2. Certificate Lifecycle ✅ : Génération, validation, révocation (avec authentification)
3. CRL/OCSP ✅ : Listes révocation et vérification d'état
4. Persistence ✅ : Stockage MongoDB avec abstraction pluggable
5. User Management : Stocker users/credentials au lieu de simples identifiants
6. OCSP Server : Répondeur OCSP pour vérification d'état en temps réel
7. HSM Integration : Support matériel de sécurité pour clés privées
8. Audit Logging : Journalisation complète des opérations