Postman · Manuel

Le bureau expose une seule et même API. Trois manières de s'y raccorder, selon vos moyens et vos droits :

• Le site web (cette salle d'écoute) : écouter le trafic et émettre un message public en clair, sans compte. Le son morse est synthétisé dans votre navigateur.
• curl / HTTP : parler à l'API directement, avec une clé d'API.
• Le client postman (ligne de commande), le poste complet : générer ses clés, chiffrer, émettre, écouter, déchiffrer ses messages privés.

Qui peut faire quoi

Se raccorder à l'API

Base : https://postman.oversas.org. Réponses en JSON. La documentation interactive (Swagger, essai en direct) est servie sur /api/v1/docs (schéma brut : /api/v1/openapi.json, version ReDoc : /api/v1/redoc).

Authentification

Les points de lecture (le morse est public) sont ouverts à tous. Émettre par l'API exige une clé d'API, transmise dans l'en-tête X-API-Key. On l'obtient à l'inscription (montrée une seule fois) ou via POST /auth/keys. Chaque clé porte un quota d'envois, une validité et un rate-limit réglés par l'administrateur.

Une clé que vous émettez vous-même est plafonnée à ces réglages : demander plus que le quota ou la validité de l'office vous rend le plafond (demander moins reste possible). Le nombre de clés actives par compte est limité · révoquez-en une avant d'en émettre une nouvelle. Enfin le rate-limit se compte par compte, pas par clé : changer de clé ne rouvre pas la fenêtre.

Principaux points d'accès

Fréquences & limites

Une ligne de diffusion par fréquence : émetteur et auditeur doivent être sur la même fréquence pour se croiser. Bande fixe des invités : 410, 425, 440, 455, 470, 485, 500 kHz (défaut 440). Les inscrits accordent n'importe quel kHz entier de 400 à 500 kHz. La lecture accepte toute la bande ; seul le choix d'émission (et le cadran invité) est un privilège de compte.

La ligne est partagée : le nombre d'envois par minute est borné pour chaque émetteur (plus généreusement pour un inscrit que pour un invité). Au-delà, l'office répond 429 avec un en-tête Retry-After qui dit combien de secondes patienter · un envoi ainsi refusé ne consomme pas le quota de votre clé.

Exemples avec curl

# Découvrir bandes et limites
$ curl https://postman.oversas.org/api/info

# Trafic d'une fréquence : ATTENTION, un curl unique n'est qu'un INSTANTANÉ.
# Le fil est éphémère (un message est répété puis disparaît) : à un instant t,
# la fréquence est souvent vide. Pour capter au vol, il faut écouter DANS LA DURÉE.
$ curl "https://postman.oversas.org/messages?freq=440"

# a) écoute continue en UN appel : flux SSE borné (-N = pas de tampon)
$ curl -N "https://postman.oversas.org/stream/listen?freq=440&seconds=30"
#    ...ou toute la bande d'un coup (chaque événement porte sa fréquence)
$ curl -N "https://postman.oversas.org/stream/listen?all=true&seconds=30"

# b) ou sonder /messages en boucle, en dédupliquant par id
$ while true; do curl -s "https://postman.oversas.org/messages?freq=440"; sleep 2; done

# Émettre un message public en clair (clé d'API requise)
$ curl -X POST https://postman.oversas.org/messages \
       -H "X-API-Key: pk_votre_cle" \
       -H "Content-Type: application/json" \
       -d '{"text":"RENDEZ VOUS A MIDI STOP","frequency":440}'

# Émettre un message PRIVÉ chiffré pour « bob » (sa clé publique vient de l'annuaire)
$ curl -X POST https://postman.oversas.org/messages \
       -H "X-API-Key: pk_votre_cle" \
       -H "Content-Type: application/json" \
       -d '{"text":"message secret","recipient":"bob","is_public":false}'

Le télégraphe en ligne de commande

postman est le troisième poste : il passe par la même API mais garde la crypto en local. Il génère votre paire de clés, chiffre à l'envoi, et déchiffre vos messages privés sur votre machine : votre clé privée (~/.postman/id_rsa.pem) n'est jamais transmise.

1 · Télécharger le client

Un fichier unique auto-suffisant : il embarque le cœur (crypto, morse, pipeline). Réservé aux opérateurs inscrits.

2 · Installer la seule dépendance

Le fichier ne dépend que de la bibliothèque de cryptographie :

$ pip install cryptography
$ python postman.py --help

3 · Générer ses clés & s'inscrire

# Crée ~/.postman/id_rsa.pem (clé privée, chmod 600) + affiche la clé publique
$ python postman.py keygen

# Crée le compte, publie la clé publique, enregistre la clé d'API localement.
# --server est une option globale : elle se place AVANT la commande. L'URL est
# ensuite mémorisée dans config.json, inutile de la répéter par la suite.
$ python postman.py --server https://postman.oversas.org register --name alice

4 · S'accorder, émettre, écouter

# S'accorder sur une fréquence (persistée dans ~/.postman/config.json)
$ python postman.py tune 440

# Émettre un message public en clair
$ python postman.py send "RENDEZ VOUS A MIDI STOP"

# Émettre un privé chiffré pour bob, sur une autre fréquence
$ python postman.py send "message secret" --to bob --freq 400

# Écouter : la fréquence accordée, une précise, ou toute la bande
$ python postman.py listen
$ python postman.py listen --freq 440
$ python postman.py listen --all

# Écoute CONTINUE (flux SSE) : le serveur pousse chaque message qui passe,
# le client se raccorde tout seul. Idéal pour ne rien rater sur une fréquence.
$ python postman.py listen --follow
# ...ou toute la bande multiplexée en un seul flux
$ python postman.py listen --follow --all

À l'écoute, un message public est traduit du morse vers le texte ; un privé qui vous est destiné est déchiffré à la volée avec votre clé privée (🔓), les autres restent chiffrés. Par défaut listen sonde la ligne toutes les quelques secondes ; --follow ouvre plutôt un flux continu (SSE) et affiche chaque message dès qu'il passe.

5 · Ses clés, l'annuaire, son identité

$ python postman.py keys list              # ses clés d'API (quota, validité)
$ python postman.py keys new --quota 50     # émettre une nouvelle clé
$ python postman.py directory               # l'annuaire des correspondants
$ python postman.py directory bob           # la clé publique de bob (PEM)
$ python postman.py whoami                  # l'identité authentifiée

Configuration locale

• ~/.postman/config.json : serveur, nom d'opérateur, clé d'API, fréquence accordée.
• ~/.postman/id_rsa.pem : clé privée RSA (jamais transmise, chmod 600).
• Surchargeable : POSTMAN_HOME, POSTMAN_SERVER, POSTMAN_API_KEY, POSTMAN_PASSPHRASE.