CAFE Documentation

This directory contains the official documentation for the CAFE (Crypto-Agility Framework for Ethereum) project. Last updated: August 2026.

Available Documents

Specifications (English)

• functional-specifications.md — CAFE product behavior: Discovery scans, CPM policies, CPM UI user stories (US1–US21), governance rules (W1–W8), workflows, and compliance overview
• technical-specifications.md — CAFE technical architecture: services, APIs, persistence, messaging, deployment (including Cloudflare Tunnel home hosting), and testing

Note: specs-fonctionnelles.md is a deprecated stub. It previously held a legacy Ponybook document; use the English specifications above.

Introduction

• 01-introduction-cafe-crypto-agility.md — Introduction to CAFE and the crypto-agility problem for the Ethereum blockchain

User Guide

• 02-cafe-user-guide.md — Complete user guide for the CAFE frontend: navigation (Discovery, Platform, CPM, Remediation), Crypto Policy Management two-layer workflow (catalogue Crypto Policy → scan-compatible providers → user constraints → persist), account-based access, and all features

Developer Guide

• 03-cafe-developer-guide.md — Canonical API v1 developer guide for Discovery (/api/discovery/v1) and CPM (/api/cpm/v1), including dual local deployments (cafe-deploy Compose + cafe-expresso minikube), edge at http://localhost:8080 on minikube for signup/signin, scan scan_id correlation, CPM-owned policy assessment, catalogue (/crypto-policies, /providers), explore v0.2 (crypto_policy_id + policy_context → scan_compatible_providers), persist v0.2 (user_constraints + accepted_provider_snapshot), and QA sign-off checks.

Admin Guide

• 04-cafe-admin-guide.md — Platform administration for Compose and minikube: environments, Helm/kubectl deploy, ingress edge, Cloudflare Tunnel (home / no inbound ports), deploy and health checks (/api/version, /api/cpm/version), pgweb, CPM catalogue (Crypto Policies + provider manifests), ADR §7.2.1 signals (catalogue and runtime), observability, operator diagnosis, and user-support scenarios.

Architecture

• CPM — Discovery v1 to policy flow — Option A: scan → catalogue CP → explore (couche A, W2) → local composition (NB2) → signed persist; no server drafts; links ADR_20260824 + OpenAPI.
• CAFE MBSE / SysML Modelio project — Step-by-step project plan to build a SysML/MBSE model of CAFE for Modelio (out of scope / not started for the Capability Provider amendement train — see ADR PR plan). From system context and logical architecture to behavior flows, state machines, and traceability.
• CPM UI specifications (cafe-frontend/CPM-specs-ui.md) — Normative CPM page user stories US1–US21 and delivery epics CPM-UI-1…8 (solution profile view, scénario A).
• ADR — Capability Provider abstraction (ADR_20260803) — ADR governing the Capability Provider model: two-layer explore/persist, ProviderManifest, SolutionProfile, posture matching, Nicetry pilote.
• ADR — Remove CP drafts (ADR_20260824) — No /drafts*; signed POST /policies; W2; NB1/NB2; PR plan.
• CPM README — Capability Providers — CPM service README covering the provider model, env vars (CPM_CRYPTO_POLICY_PATHS, CPM_PROVIDER_MANIFEST_PATHS), explore v0.2, persist user_constraints, catalogue/runtime signals.

API QA

• API v1 QA Checklist — Compact reviewer checklist for route names, retired catalog paths, explore v0.2 / assessment ownership, delete semantics, and cross-repository follow-up.

Security and Operations

• CPM Auth contract — Authenticated CPM behavior, scan authorization, owner-scoped policies (no /drafts*), error contract (explore legacy 400, W2 / persist codes, assessment v0.2)
• CP-PERSIST (no drafts) — Signed POST /policies, payload_sha256, W2, NB1/NB2; links ADR + OpenAPI + CP_PERSIST.md
• CPM explore — no scan-compatible provider (observability & admin diagnosis) — REQ9 / IMM-OPS-1…2: runtime signal runtime.no_scan_compatible, structured logs, Prometheus/Grafana, curl admin workflow (complements user-facing REQ8 in the SPA; couche B is a separate signal)

About CAFE

CAFE (Crypto-Agility Framework for Ethereum) is a three-service platform designed to discover, govern, and remediate cryptographic assets on Ethereum—ensuring compliance, resilience, and trust in the post-quantum and zero-knowledge era.

Architecture

CAFE is composed of three main services:

1. Discovery — Identification of on-chain and network quantum exposures
2. Crypto Policy Manager — Definition and enforcement of cryptographic policies
3. Remediation — Secure migration and attested key operations

Additional Resources

• CAFE Whitepaper — May be private while content is prepared for public release
• Discovery Repository — Cryptographic discovery service with PQC (see README Data structure (CPM export contract) for the CPM-facing observation shape)
• Crypto Policy Management (cafe-crypto-policy-mgt) — Policy service; normative contract and vocabulary for Discovery exports
• Frontend Repository — User interface
• cafe-deploy — Docker Compose deployment (VM / local / Cloudflare Tunnel home)
• cafe-deploy — Cloudflare Tunnel (README) — Prod-tunnel compose + cloudflared quick path
• cafe-deploy — Home selfhosted guide — OpenWrt, DNS, tunnel, firewall end-to-end
• cafe-expresso — minikube / Helm / Argo CD (Kubernetes P0)
• Crypto backend Repository — Cryptographic backend; tooling for building and running applications with Post-Quantum Cryptography (PQC) support
• Edge Repository — Reverse-proxy images with PQC
• TLS scanner Repository — TLS scanner service with PQC
• CAFE Website — Public website

Contributing

To contribute to the documentation, please follow Markdown formatting conventions and maintain consistency with existing documents.