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
```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** :
```go
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
```bash
go mod download
go build -o pkiapi ./cmd/main.go
./pkiapi
```

### Tester avec authentification
```bash
# 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)**
```bash
export STORAGE_TYPE=memory
export PORT=8080
./pkiapi
```

**Mode Production (MongoDB)**
```bash
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 :

```go
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
```go
// 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