Aller au contenu
local-cert
Parcourir la documentation

Référence de l'API

Tout ce que fait la console passe par une API HTTP que vous pouvez appeler vous-même : depuis un cron, un script de déploiement ou un outil interne. Cette page couvre le modèle d'autorisation, tous les endpoints, l'émission d'un certificat, la métadonnée métier, la vérification d'un sous-domaine et la description OpenAPI.

Modèle d'autorisation

Modèle
api_key ──< grant >── domain
             │
             └── scopes[]
ScopeAutorise
cert:readLire les certificats et leurs événements
cert:issueÉmettre
cert:renewRenouveler
cert:revokeRévoquer / supprimer
cert:exportTélécharger la clé privée (en plus de read)
dns:readLister les enregistrements de la zone
dns:writeUPSERT / DELETE d'enregistrements
admin:*Tout, sur tous les domaines, + console

Une clé sans grant ne peut rien faire. Les droits sont par domaine : la clé du NAS ne peut pas émettre pour le domaine du serveur de build. Les clés se gèrent dans Clés & droits.

Deux mécanismes distincts

Console webAPI
Identifiantemail + mot de passeclé d'API
Stockageargon2idsha256
Transportcookie httpOnly / SameSite=laxen-tête Authorization

Le mot de passe protège un secret à faible entropie choisi par un humain : il lui faut un KDF lent. Une clé d'API porte 256 bits d'entropie CSPRNG — il n'y a rien à brute-forcer, sha256 suffit et reste rapide à chaque requête.

Un compte inexistant et un mauvais mot de passe consomment le même temps de calcul : impossible d'énumérer les comptes par la latence.

Format des clés

Clé d'API
lc_<prefix8hex>_<secret base64url 32 octets>

Le préfixe est indexé et affichable. Une clé fournie par l'opérateur (ADMIN_API_KEY) peut être une chaîne opaque quelconque : son préfixe de recherche dérive de son propre sha256, les deux formes partagent le même index.

Deux façons de s'authentifier

shell
# 1. clé d'API directement (pratique pour cron/curl)
curl -H "Authorization: Bearer lc_..." https://certs.example.com/api/v1/certificates

# 2. échange contre un JWT court (1 h), scopes embarqués dans le token
TOKEN=$(curl -s -X POST https://certs.example.com/api/v1/auth/token \
  -H "Authorization: Bearer lc_..." | jq -r .access_token)
curl -H "Authorization: Bearer $TOKEN" https://certs.example.com/api/v1/certificates

La console d'admin utilise un cookie de session httpOnly + SameSite=lax portant un JWT équivalent, obtenu par email + mot de passe.

Endpoints

Authentification

GET    /api/setup                    { setup_required: bool }
POST   /api/setup                    création du compte admin (une seule fois)
POST   /api/v1/auth/token            clé d'API -> JWT

Certificats

GET    /api/v1/certificates          ?status= &domain= &expires_within_days= &limit= &metadata.<clé>=
POST   /api/v1/certificates          202 + Location
GET    /api/v1/certificates/{id}
PATCH  /api/v1/certificates/{id}     met à jour la métadonnée
DELETE /api/v1/certificates/{id}     ?purge=true pour effacer la ligne
POST   /api/v1/certificates/{id}/renew
GET    /api/v1/certificates/{id}/bundle   ?format=json|pem &include=fullchain,cert,chain,key
GET    /api/v1/certificates/{id}/events   ?stream=1 pour du SSE

Sous-domaines

GET    /api/v1/subdomains/{fqdn}     ce sous-domaine est-il déjà pris ?

DNS

GET    /api/v1/dns/records           ?domain_id=
PUT    /api/v1/dns/records
DELETE /api/v1/dns/records           ?fqdn= &type= &values= &ttl=

Divers

GET    /api/v1/acme/account
GET    /api/openapi.json             description OpenAPI 3.1 (authentifiée)
GET    /api/healthz
POST   /api/mcp                      serveur MCP pour agents IA

Le serveur MCP est décrit dans Serveur MCP.

Administration (session console)

POST|GET|DELETE  /api/admin/session   email+mot de passe / whoami / logout
GET|POST         /api/admin/providers            ?force=true pour enregistrer malgré un test en échec
POST             /api/admin/providers/probe      teste des credentials sans les stocker
PATCH|DELETE     /api/admin/providers/{id}
GET              /api/admin/providers/{id}/zones   zones hébergées visibles
GET              /api/admin/providers/{id}/policy  politique IAM complète (?zone_id= à ajouter)
GET|POST         /api/admin/domains
POST             /api/admin/domains/preflight    les contrôles d'un ajout, sans rien écrire
DELETE           /api/admin/domains/{id}   ?force=true pour supprimer avec ses certificats
GET|POST         /api/admin/keys
PATCH|DELETE     /api/admin/keys/{id}
GET              /api/admin/stats

Émettre un certificat

shell
curl -X POST https://certs.example.com/api/v1/certificates \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'content-type: application/json' \
  -d '{
    "domains": ["nas.home.example.com"],
    "key_type": "ec-256",
    "auto_renew": true,
    "renew_before_days": 30,
    "webhook_url": "https://nas.home.example.com/hooks/cert",
    "dns": { "create_record": true, "target_ip": "192.168.1.50", "ttl": 60 }
  }'

La réponse est un 202 Accepted immédiat. Suivi :

shell
curl -N -H "Authorization: Bearer $TOKEN" \
  "https://certs.example.com/api/v1/certificates/$ID/events?stream=1"

Machine à états :

pending → dns_propagating → validating → issued
                                       ↘ failed (retry exponentiel, 5 essais)
issued → revoked | expired

Métadonnée métier

Chaque sous-domaine porte une map clé/valeur de chaînes, fournie par le système appelant pour le rattacher à son contexte : tenant, environnement, ticket, identifiant interne.

shell
curl -X POST …/api/v1/certificates -H "Authorization: Bearer $TOKEN" \
  -d '{
    "domains": ["nas.home.example.com"],
    "metadata": { "tenant_id": "acme-corp", "env": "prod", "ticket": "OPS-1421" }
  }'

Mise à jour — merge par défaut, replace pour écraser :

shell
curl -X PATCH …/api/v1/certificates/$ID \
  -d '{ "metadata": { "tenant_id": "other-corp" }, "mode": "replace" }'

Filtrage à la liste, une clé à la fois :

shell
curl "…/api/v1/certificates?metadata.tenant_id=acme-corp"

Le filtre est appliqué côté application, pas en SQL : les opérateurs JSON diffèrent entre SQLite et Postgres et la colonne n'est indexée dans aucun des deux, donc il n'y a rien à gagner à le pousser dans la requête.

Limites : 20 entrées, clé de 64 caractères dans [A-Za-z0-9._:-], valeur de 512 caractères, 4096 octets une fois sérialisé. C'est du contexte, pas un magasin de documents.

Vérifier si un sous-domaine est pris

shell
curl …/api/v1/subdomains/nas.home.example.com -H "Authorization: Bearer $TOKEN"
réponse
{
  "fqdn": "nas.home.example.com",
  "available": false,
  "managed_domain": "home.example.com",
  "dns": {
    "exists": true,
    "managed": true,
    "records": [{ "type": "A", "ttl": 60, "values": ["192.168.1.50"] }]
  },
  "certificate": { "id": "cert_…", "status": "issued", "days_remaining": 89, "metadata": {} },
  "metadata": { "tenant_id": "acme-corp" }
}

Les deux sources de vérité sont interrogées séparément parce qu'elles peuvent diverger : un enregistrement peut exister dans la zone sans que local-cert le connaisse (créé à la main, ou par un autre outil), et un certificat peut exister ici sans que rien ne soit publié. available n'est vrai que si aucune des deux ne connaît le nom et que la zone était lisible — une zone illisible remonte dans dns.error plutôt que de faire passer le nom pour libre.

Nécessite cert:read sur le domaine couvrant. La moitié DNS n'est pas protégée davantage : c'est de la donnée publique, résolvable au dig par n'importe qui.

Documentation OpenAPI

La description OpenAPI 3.1 complète est servie sur GET /api/openapi.json (authentifiée — le schéma cartographie toute la surface d'un outil interne).

La console embarque un explorateur sur /admin/api : endpoints groupés par tag, filtre, paramètres et corps pré-remplis depuis le schéma, équivalent curl, et un bouton Envoyer qui exécute réellement la requête depuis le navigateur avec votre cookie de session.

Génération

Le document est généré, jamais écrit à la main :

ÉlémentSource
Corps de requêteles schémas zod que les handlers valident (src/lib/validation.ts)
Réponsessrc/lib/api/schemas.ts, reliées au runtime par z.infer
Opérationssrc/lib/api/routes.ts

Conversion via z.toJSONSchema() de zod 4. Les contraintes viennent donc gratuitement des validateurs — la regex de FQDN, les bornes de TTL, les longueurs de métadonnée apparaissent dans la spec parce qu'elles existent dans le code.

Trois garde-fous, exécutés par npm run openapi:check :

  1. Couverture — chaque handler App Router sur le disque doit figurer au registre, et réciproquement. Une route ajoutée sans documentation fait échouer le check.
  2. Cohérence input/output — aucun schéma de réponse ne doit diverger entre ses projections d'entrée et de sortie ; le générateur fait une passe unique, ce qui n'est correct que tant que c'est vrai (un .default() ou un .transform() sur une réponse casserait l'hypothèse).
  3. Résolution des $ref — toute référence doit pointer sur un composant existant.

Le typage ferme la boucle : serializeCert retourne z.infer<typeof certificateSchema>, donc changer la forme sérialisée sans mettre à jour le schéma publié échoue à la compilation.

npm run openapi:check
openapi:check ok — 30 operations over 19 paths, 36 component schemas, all $refs resolve.