pythonbeid-server 1.0.0

Localhost API agent for Belgian eID cards using pythonbeid.

eID Agent (localhost API)

Agent local Python pour lire une carte eID belge via pythonbeid et exposer une API HTTP sur 127.0.0.1 pour un front web distant (HTTPS).

Fonctionnalités

• Bind local strict: 127.0.0.1 uniquement
• API FastAPI JSON UTF-8
• Session token en mémoire (TTL, Bearer token)
• CORS strict configurable par liste d’origines
• Rate limit simple sur /v1/read
• Mapping des données eID vers un contrat stable pour préremplissage formulaire

Installation

Package PyPI: pythonbeid-server
Module Python importable: eid_agent
Commande CLI installée: eid-agent

pip install -e .

Avec dépendances de test:

pip install -e ".[dev]"

Exécution

Mode recommandé:

eid-agent

Alternative:

python -m eid_agent

Configuration (variables d’environnement)

• EID_AGENT_PORT (défaut: 8765)
• EID_AGENT_ALLOWED_ORIGINS (ex: https://school.example,https://dev.school.example)
• EID_AGENT_SESSION_TTL_SECONDS (défaut: 120)
• EID_AGENT_RATE_LIMIT_PER_MINUTE (défaut: 10)
• EID_AGENT_LOG_LEVEL (défaut: INFO)

HTTPS local optionnel:

• EID_AGENT_HTTPS=1
• EID_AGENT_TLS_CERT_PATH
• EID_AGENT_TLS_KEY_PATH

Si HTTPS est activé sans cert/key valides, l’agent échoue au démarrage.

API v1

Toutes les réponses JSON incluent:

• ok (bool)
• timestamp (ISO8601 UTC)
• error en cas d’échec

Health

GET /v1/health

Session

POST /v1/session

Retourne:

{
  "ok": true,
  "timestamp": "2026-03-03T09:00:00Z",
  "token": "<opaque_token>",
  "expires_in": 120
}

Status (auth requise)

GET /v1/status

Header:

Authorization: Bearer <token>

Read eID (auth requise)

POST /v1/read

Body:

{
  "include_photo": true,
  "fields": [
    "first_names",
    "first_name",
    "last_name",
    "national_number",
    "birth_date",
    "birth_place",
    "nationality",
    "sex",
    "card_number",
    "issuing_municipality",
    "validity_start",
    "validity_end",
    "address_street",
    "address_zip",
    "address_city"
  ]
}

Si fields est omis, l’agent renvoie l’ensemble par défaut (incluant les champs eID usuels + adresse).

Logout (auth requise)

POST /v1/logout

Exemple côté front web

const sessionResp = await fetch("http://127.0.0.1:8765/v1/session", {
  method: "POST"
});
const sessionJson = await sessionResp.json();
const token = sessionJson.token;

const readResp = await fetch("http://127.0.0.1:8765/v1/read", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`
  },
  body: JSON.stringify({
    include_photo: true
  })
});
const readJson = await readResp.json();
console.log(readJson.data);

Important:

• Le domaine front doit être explicitement autorisé via EID_AGENT_ALLOWED_ORIGINS.
• Sans origine autorisée, aucun header Access-Control-Allow-Origin n’est envoyé.

Exemple curl

Créer une session:

curl -X POST http://127.0.0.1:8765/v1/session

Lire la carte:

curl -X POST http://127.0.0.1:8765/v1/read ^
  -H "Authorization: Bearer <token>" ^
  -H "Content-Type: application/json" ^
  -d "{\"include_photo\":true}"

Confidentialité et logs

• Aucun token n’est loggé.
• Aucune donnée personnelle eID (nom, adresse, NISS, photo) n’est loggée.
• Logs techniques: démarrage/arrêt, config réseau, erreurs techniques.

Tests

pytest -q

Les tests API n’utilisent pas de matériel eID et injectent un backend simulé.

Publication PyPI (GitHub Actions)

Le workflow CI/CD est fourni ici:

• .github/workflows/publish-pypi.yml

Il publie automatiquement sur PyPI avec Trusted Publishing (OIDC) quand un tag v* est poussé.

Configuration initiale (une seule fois)

1. Sur PyPI, créer un Trusted Publisher pour ce projet avec:
   • Owner GitHub
   • Repo GitHub
   • Workflow: publish-pypi.yml
   • Environment: pypi
2. Sur GitHub, créer l'environnement pypi (Settings > Environments).

Release

1. Mettre à jour la version dans pyproject.toml (ex: 1.0.1).
2. Commit/push.
3. Créer et pousser le tag correspondant:

git tag v1.0.1
git push origin v1.0.1

Le workflow vérifie que le tag correspond à la version (v<version>), build le package, puis publie sur PyPI.

Page web d'exemple

Un exemple de formulaire auto-rempli est disponible ici:

• examples/web/index.html

Servir la page (PowerShell)

1. Démarrer l'agent avec une origine CORS qui correspond au serveur statique:

$env:EID_AGENT_ALLOWED_ORIGINS="http://127.0.0.1:8080"
python -m eid_agent

2. Dans un second terminal, servir la page:

python -m http.server 8080 --bind 127.0.0.1 --directory examples/web

3. Ouvrir:

• http://127.0.0.1:8080

Puis cliquer sur le bouton Lire eID et remplir.