Docs_archive
CDC registry (public)
Source docs/CDC_REGISTRY_PUBLIC.md · All_docs
Type : cahier des charges opérationnel + produit pour l’exposition Internet-facing du service
services/registry.
Statut : normatif pour le déploiement public ; les détails d’API machine restent la source de vérité dansopenapi/registry-v1.yamletschemas/hive-registry-record-v1.schema.json.
Version document : 1.1 — 2026-03-22
Traçabilité :MESH_PLANETARY_TRACE.md, spec courte P1MESH_PLANETARY_P1_GLOBAL_DIRECTORY.md.
Plan Hub + miroir Git + tenants instances :HIVE_GLOBAL_REGISTRY_GIT_PLAN.md.
1. Résumé exécutif
Le registry public Hive est un service HTTP léger qui :
- Publie un annuaire de handles stables → métadonnées de découverte (typiquement une Agent Card HTTPS et optionnellement un descriptor mesh).
- Ne remplace pas l’exécution des agents ni le routage du trafic applicatif : les clients résolvent le handle, puis contactent directement l’origine du nœud (ou passent par les mécanismes mesh / gateway déjà documentés ailleurs).
- Joue le rôle d’amorçage et d’index pour le réseau — comparable à un DNS / annuaire pour l’« Internet des agents », sans être un « master » qui centralise la compute.
Implémentation de référence : services/registry/ (Node.js), image Docker services/registry/Dockerfile.
2. Objectifs produit
3. Périmètre
3.1 Dans le périmètre (cette CDC + service actuel)
- API v1 : health, metrics Prometheus, records CRUD logique (POST upsert, GET by handle, GET liste, DELETE), resolve inverse par
agentCardUrl. - Validation Ajv des corps et réponses selon hive-registry-record-v1.
- Persistance PostgreSQL optionnelle (
REGISTRY_DATABASE_URL) — recommandée en production publique. - Rate limiting lecture / écriture (mémoire ou Redis).
- Revocation :
DELETE; hint temporelvalidUntil+ flagsREGISTRY_ENFORCE_VALID_UNTIL/REGISTRY_REJECT_EXPIRED_WRITES. - Preuve Ed25519 optionnelle sur le record (P5) :
REGISTRY_VERIFY_ED25519_PROOF. - Politiques opérateur : allowlists handle / host
agentCardUrl; PDP HTTP externe optionnel. - Sync fédérée (P4) : tirage périodique depuis d’autres origines registry, preuve de catalogue signée optionnelle.
- Observabilité :
/v1/metricsavec auth optionnelle.
3.2 Hors périmètre (explicitement)
- Paiement, JWT consommateur, marketplace transactionnel : hors de ce service ; un marketplace peut consommer
GET /v1/recordscomme index. Évolution : champs métadonnées ou service annexe — pas requis pour ouvrir un registry public minimal. - Transport applicatif mesh (NATS, passerelles, ingress WAN) : voir P2–P3–P6 dans
MESH_PLANETARY_TRACE.md. - DHT complète / gossip pur P2P : roadmap
MESH_PLANETARY_P4_DHT_ROADMAP.md; le registry HTTP reste la couche bootstrap pragmatique V1. - Moteur DID/VC complet : le schéma prépare
controllerDid,didDocumentUrl,proof; l’émission/validation VC est responsabilité opérateur (cf.MESH_PLANETARY_P5_TRUST_PROOF.md).
4. Parties prenantes et rôles
5. Architecture logique
flowchart LR
subgraph public [Internet]
C[Client]
end
subgraph bootstrap [Registry public]
R[GET /v1/records/handle]
end
subgraph node [Nœud Hive opérateur]
AC[/.well-known/agent-card.json]
MD[/.well-known/hive-mesh.json]
end
C -->|1. Résoudre handle| R
R -->|2. agentCardUrl + meshDescriptorUrl| C
C -->|3. Appels directs HTTPS| AC
C --> MD
- Le registry ne proxy pas le trafic agent dans cette architecture de base.
- Niveau 0 (sans registry) : chaque instance expose déjà
hive-mesh-descriptor-v1— le registry est niveau 1+ agrégation / handles stables.
6. Exigences fonctionnelles
6.1 Endpoints (contrat)
Source normative : openapi/registry-v1.yaml.
6.2 Modèle de données record
- Schéma JSON :
schemas/hive-registry-record-v1.schema.json. - Champs obligatoires :
schema(=hive-registry-record-v1),handle,updatedAt,agentCardUrl. - Champs recommandés pour l’interop Hive :
meshDescriptorUrl,capabilities,ttlSecondsRecommended,publicKeys(si P5). - Marketplace / acheteurs :
buyerInputs(liste structurée :id,label,kind,keyoptionnel,description,required, etc.) ;documentationUrl,sourceUrl,pricing,publishAttestation(voir § 6.2.1). - Normalisation serveur (avant validation Ajv) : alias fusionnés — ex.
hiveBuyerInputs/buyerConfiguration/docsUrl→ champs canoniques du schéma (services/registry/src/registry-record-normalize.mjs). - Exemple minimal valide (sans preuve crypto) :
services/registry/seed-record.example.json.
6.2.1 Publication contrôlée (publish readiness)
Pour que l’éditeur valide la configuration attendue des déployeurs avant mise en catalogue :
POST /v1/records/validate— même corps et auth quePOST /v1/records; réponse 200 avecwouldAcceptWrite,schemaValid,readiness(issues détaillées), sans écriture.- Variables d’environnement (stub Node
services/registry) :REGISTRY_PUBLISH_READINESS=off(défaut) |warn(log warn) |enforce(422 surPOST /v1/recordssi erreurs readiness).REGISTRY_PUBLISH_REQUIRE_ATTESTATION=1— imposepublishAttestation: { confirmedAt, confirmedBuyerConfiguration: true }.REGISTRY_PUBLISH_FETCH_AGENT_CARD=1— GET suragentCardUrlpuis recoupemetadata.hiveAgentManifest/ URL de manifeste avecruntime.envVarsRequiredvs clés documentées dansbuyerInputs.REGISTRY_PUBLISH_AGENT_CARD_TIMEOUT_MS,REGISTRY_PUBLISH_MANIFEST_TIMEOUT_MS— timeouts outbound (défauts 8000 / 6000 ms).REGISTRY_PUBLISH_ATTESTATION_HMAC_SECRET— si défini,publishAttestation.hmacSha256Hexdoit correspondre au HMAC-SHA256 (hex) d’un JSON stable de{ handle, updatedAt, buyerInputs }(évite qu’un attesteur ne signe qu’une config vide).REGISTRY_PUBLISH_FETCH_HOST_ALLOWLIST— liste d’hôtes séparés par des virgules (comparaison en minuscules) ; si non vide, seuls ces hôtes sont autorisés pour les GET readiness (complète le blocage SSRF : IP privées, résolution DNS, pas de redirections illimitées).REGISTRY_PUBLISH_FETCH_MAX_REDIRECTS— plafond de redirections HTTP suivies manuellement (défaut 5).REGISTRY_PUBLISH_FETCH_CACHE_TTL_MS/REGISTRY_PUBLISH_FETCH_CACHE_MAX— cache mémoire des réponses fetch (défauts 60_000 ms / 500 entrées).
Règles métier principales : entrées buyerInputs cohérentes (kind env | secret | url ⇒ key obligatoire) ; si required: true ⇒ description suffisamment explicite ; si manifeste exige FOO en env, un item buyerInputs doit documenter la clé FOO (mode fetch activé).
6.3 Comportements HTTP clés
- ETag faible + 304 sur
GET /v1/records/{handle}siIf-None-Matchcorrespond. - 412 si
REGISTRY_ENFORCE_IF_MATCH=1et mise à jour sans bonIf-Match. - 409 : preuve Ed25519 invalide (si vérification activée) ou
stale_updatedAt(si rejet des mises à jour rétrogrades activé). - 422
publish_readiness_failed:REGISTRY_PUBLISH_READINESS=enforceet contrôles buyer configuration / attestation / manifeste en échec (détails dans le corps JSONreadiness). - 410
record_expiredsivalidUntildépassé et enforcement lecture activé. - 403 : écriture désactivée, politique allowlist, ou PDP externe refusé.
6.4 Flux opérateur nœud (cible)
- L’opérateur déploie Hive avec HTTPS et fichiers well-known valides.
- Il construit un JSON hive-registry-record-v1 (handle stable choisi selon politique du registry, ex. préfixe
urn:hive:agent:…). - Il authentifie un
POST /v1/recordsavec le secret write. - Les clients utilisent
GET /v1/records/{handle}puis appellent l’origine du nœud.
7. Exigences non fonctionnelles
7.1 Sécurité
7.2 Disponibilité et données
- Postgres : table
hive_registry_records— sauvegardes automatiques + procédure de restauration testée (RPO/RTO à définir). - Perte registry : pas de perte des agents déjà configurés côté clients qui cachent les résolutions ; dégradation = pas de nouveaux join / mise à jour globale.
- Timeout socket :
REGISTRY_REQUEST_TIMEOUT_MSrecommandé (ex. 30–120 s) pour limiter les connexions lentes.
7.3 Performance (ordre de grandeur)
- Charge typique : lecture dominante ; viser latence p95 < 200 ms sous charge modeste sur VPS correcte avec Postgres local ou managé.
- Taille corps POST plafonnée :
REGISTRY_MAX_BODY_BYTES(défaut 1 Mo).
7.4 Observabilité
- Scraper
/v1/metricsavec auth si secret défini. - Audit JSON stdout :
REGISTRY_AUDIT_JSON=1pour corrélation SIEM (ligne par POST/DELETE réussi).
7.5 Versioning API et schémas
- Toute évolution du schéma record : bump
$idou stratégie de migration documentée dans P1 +MESH_PLANETARY_CHANGELOG.md. - CI :
npm run docs:validate-planetarydepuisapp/; testsservices/registry(npm test).
7.6 Disponibilité : cibles SLO, RPO et RTO
Le registry est une dépendance de découverte, pas de données métier temps réel : une indisponibilité ne coupe pas les flux déjà établis entre nœuds, mais bloque l’onboarding, les mises à jour d’annuaire et les nouvelles résolutions pour les clients sans cache.
Indicateurs à monitorer (à brancher sur Prometheus / alertes) :
- Ratio 5xx sur
/v1/healthet/v1/records*; taux 429 (abus vs capacité). - Disponibilité Postgres vue depuis le registry (latence requêtes, erreurs connexion).
- Si P4 actif : échecs de sync (logs applicatifs) et dérive du catalogue vs pairs.
Les chiffres du tableau sont des objectifs de cadrage : l’opérateur les adapte au contrat client et les formalise dans son propre document SLA.
7.7 Données traitées, classification et privacy (RGPD / bonnes pratiques)
RGPD (Europe) : si le registry est exploité auprès de résidents UE et traite des données personnelles (ex. annuaire nominatif), prévoir au minimum : base légale et transparence (notice), droits d’accès/suppression sur ce que vous stockez (records + logs), DPIA si volumétrie ou sensibilité élevée, et transferts hors UE documentés si Postgres / hébergeur hors zone.
Principe produit : garder le record comme métadonnée de découverte technique ; éviter d’y stocker identifiants clients finaux, tokens ou PII inutiles.
7.8 Escalade et responsabilités (résumé)
Remplir les noms / canaux (PagerDuty, Slack, email) dans la fiche opérateur interne référencée au § 10.
8. Déploiement public (référence)
8.1 Topologie minimale recommandée
- VPS ou conteneur (1 instance ou N derrière LB).
- PostgreSQL 14+ (16 recommandé) dédié ou managé.
- Reverse proxy (Caddy, Traefik, nginx, cloud LB) : TLS, HTTP/2, limite taille requêtes, option WAF.
- Redis (optionnel mais fortement recommandé si plusieurs réplicas ou LB) pour rate limits cohérents.
8.2 Docker
Depuis la racine du monorepo :
docker build -f services/registry/Dockerfile -t hive-registry:latest .
L’image fixe REGISTRY_RECORD_SCHEMA_PATH=/schemas/hive-registry-record-v1.schema.json et expose le port 4077 par défaut (PORT).
8.3 Variables d’environnement (synthèse prod publique)
Liste détaillée et sémantique : services/registry/README.md.
Fédération (si plusieurs registres) : REGISTRY_SYNC_PEER_BASES, REGISTRY_SYNC_INTERVAL_MS, REGISTRY_SYNC_AUTH_BEARER, options de vérification — voir MESH_PLANETARY_P4_FEDERATED_SYNC.md.
Variables complémentaires (voir README pour la sémantique exacte) :
8.4 Checklist go-live (extraite et complétée depuis MESH_PLANETARY_V1_ADOPTION.md)
- Postgres + backups + restauration testée
-
REGISTRY_WRITE_SECRET/ révocation ; pas d’exposition POST sans contrôle réseau - TLS + LB de confiance si
TRUST_XFF - Rate limits lecture/écriture + Redis si réplicas
-
/v1/metricsprotégé si exposé - Allowlists alignées avec la politique de noms (handles + domaines)
- P4/P5 activés sciemment (sync peers, verify proof, catalog proof)
- Smoke post-déploiement : health + GET record + POST test sur staging
- SLO / RPO / RTO choisis pour le palier d’exploitation (§ 7.6) documentés en interne
- Fiche privacy / rétention logs alignée avec § 7.7 si exposition UE ou PII possible
8.5 Runbook opérationnel (registry)
Procédures autonomes pour l’astreinte ; le détail Postgres générique reste dans RUNBOOK.md.
8.5.1 Symptômes et diagnostic
8.5.2 Sauvegarde et restauration (Postgres registry)
- Backup : inclure la base pointée par
REGISTRY_DATABASE_URL(tablehive_registry_records) dans la politiquepg_dump/ PITR existante — voirRUNBOOK.md§ Postgres Backup and Restore. - Restore : après restore, redémarrer le registry ; vérifier
GET /v1/records/{handle}sur un handle connu et comparerupdatedAtà l’attendu. - Test trimestriel : restauration sur environnement isolé + smoke lecture/écriture staging.
8.5.3 Rotation des secrets (sans downtime prolongé)
Après toute rotation : GET /v1/health (vérifier les drapeaux writeEnabled, catalogAuthEnabled, etc.) + un POST test sur staging.
8.5.4 Dégradation contrôlée
- Maintenance annoncée : basculer DNS ou LB vers une page statique ; ou laisser le registry répondre 503 au LB uniquement sur chemins non-health si la stack le permet.
- Incident Postgres : si lecture seule acceptable, certains déploiements peuvent basculer temporairement en memory (non recommandé en prod : perte de cohérence au restart) — préférer restore ou failover managé.
9. Intégration « Marketplace » (vision — hors implémentation obligatoire registry)
Le registry public est le noyau d’indexation pour :
- Location (AaaS) : le record pointe vers l’agent ; prix, quotas, JWT consommateur peuvent être gérés par Hive app ou un service billing séparé qui n’a pas besoin de modifier le stub registry jour 1.
- Vente (package) : métadonnées « achetable » peuvent être des extensions future du schéma ou des fiches stockées ailleurs référencées par
handle/ URL dans le record — à spécifier dans un CDC Marketplace dédié.
Principe : garder le registry agnostique des transactions monétaires pour maximiser adoption et limiter la surface d’attaque.
10. Critères d’acceptation (Definition of Done — déploiement public)
GET https://registry.example/v1/healthretourneok: trueet reflètepersistence: postgresen prod.- Un record de test validé par Ajv est servi par
GET /v1/records/{handle}. POST /v1/recordsrefusé sans Bearer correct (401/403).- Rate limit déclenché observable (429) sous test de charge léger.
- Après
DELETE /v1/records/{handle}, le GET retourne 404. - Sauvegarde/restauration Postgres : record réapparaît après restore.
- Documentation opérateur interne : URLs, secrets (emplacement), procédure rotation, contact on-call.
- SLO mensuel et RPO/RTO écrits (même si = palier Hobby § 7.6) + chemin des backups Postgres registry.
- Si exposition publique UE ou PII possible : référence à la notice / traitement des données (§ 7.7).