Airlock
view release on metacpan or search on metacpan
docs/superpowers/specs/2026-10-02-airlock-design.md view on Meta::CPAN
### Factor (`Airlock::Factor`, Moo::Role)
`name`, `amr` (z. B. `otp`), `available_for($subject)`, `verify($subject, $proof)`.
- `Airlock::Factor::Callback`: Die Host-App prüft selbst. Das ist der Weg für Mothership,
wo TOTP laut Design bei Stalwart liegt und Mothership nichts speichert.
- `Airlock::Factor::TOTP`: RFC 6238 mit `Digest::SHA`, Fenster ±1, Replay-Schutz über
den letzten akzeptierten Zeitschritt, `otpauth://`-URI fürs Einrichten. Geheimnis und
letzter Zeitschritt kommen über zwei Subs der Host-App.
- `Airlock::Factor::Upstream`: gilt als erfüllt, wenn das Subject passende `amr`/`acr`
vom IdP mitbringt und `auth_time` frisch genug ist.
- Später: `Airlock::Factor::WebAuthn` über `Authen::WebAuthn` als optionale Abhängigkeit,
und Recovery-Codes.
### Policy
Bildet Request und Subject auf eine Liste nötiger Faktoren ab. Deklarativ für den
Normalfall (`step_up => { scope => [faktoren] }`, `max_auth_age => 300`), Coderef für
alles andere. Fehlt dem Subject ein verlangter Faktor, wird nicht bestätigt; das Ergebnis
sagt, was fehlt.
### Issuer
Ein Sub `($grant) â Token-Antwort`. Ohne Angabe stellt Airlock ein opakes Zufallstoken
aus, legt es gehasht im Store ab und bietet `verify_token` zum Prüfen. Das reicht, solange
nur die Host-App selbst das Token akzeptiert. Phase 2 bringt einen fertigen JWT-Issuer mit
`amr`, `auth_time`, `scope`, `sub` und JWKS-Export.
### Code (`Airlock::Code`)
`user_code`: 8 Zeichen aus `BCDFGHJKLMNPQRSTVWXZ` (keine Vokale, nichts Verwechselbares),
Anzeige `XXXX-XXXX`, Eingabe wird normalisiert (GroÃ/Klein, Trenner, Leerzeichen).
`device_code`: 32 Byte aus dem System-Zufall (`Crypt::URandom`).
### QR (`Airlock::QR`)
Zwei Stellen brauchen QR-Codes, beide über dieselbe kleine API:
1. `verification_uri_complete`: Der Laptop oder das CLI zeigt den QR, das Handy scannt
und landet mit vorausgefülltem Code auf der Bestätigungsseite.
2. TOTP-Einrichtung: die `otpauth://`-URI für die Authenticator-App.
```perl
Airlock::QR->new(text => $uri)->svg; # fürs Web, keine Bildbibliothek nötig
Airlock::QR->new(text => $uri)->terminal; # Unicode-Halbblöcke fürs CLI
Airlock::QR->new(text => $uri)->data_uri; # direkt ins <img src>
Airlock::QR->new(text => $uri)->matrix; # rohe Module, für eigene Darstellung
```
Kodiert wird mit `GD::Barcode::QRcode` (reines Perl; die Dist verlangt zur Laufzeit kein
GD). Der Encoder sitzt hinter einer kleinen Naht, damit `Text::QRCode` (libqrencode)
benutzt werden kann, wenn es installiert ist. Der Plan beginnt mit einem Nachweis, dass
die erzeugte Matrix sich mit einem unabhängigen Decoder zurücklesen lässt; fällt der
Nachweis durch, wird der Encoder gewechselt, bevor etwas darauf aufbaut.
### `Airlock::Client`
Die Gegenseite, also das, womit dieses Projekt angefangen hat: ein RFC-8628-Client mit
`HTTP::Tiny`. Findet die Endpunkte per `.well-known/openid-configuration`
(`device_authorization_endpoint`) oder bekommt sie direkt, zeigt Code und Terminal-QR,
pollt und beachtet `slow_down`. Spricht mit Airlock, Keycloak und GitHub gleichermaÃen.
## 7. Keycloak: minimal, aber getestet
Zwei Berührungspunkte in v1, beide gegen ein echtes Keycloak geprüft:
**A. Keycloak ist die Login-Quelle der Bestätigungsseite.** Die Host-App loggt per OIDC
ein und reicht Airlock das Subject samt `amr`, `acr` und `auth_time` aus dem ID-Token.
`Airlock::Factor::Upstream` erkennt daran, ob Keycloak schon einen zweiten Faktor geprüft
hat. Fehlt er, liefert Airlock der Host-App die Parameter (`acr_values`, `max_age=0`),
mit denen sie die Person noch einmal zu Keycloak schickt. Wie Keycloak `acr` und `amr`
tatsächlich füllt, wird nicht aus der Doku übernommen, sondern am echten Token
festgestellt und als `Airlock::Upstream::Keycloak` festgehalten.
**B. Der Client spricht direkt mit Keycloak.** Keycloak kann den Device-Grant selbst.
`Airlock::Client` muss gegen dessen Endpunkte durchlaufen.
**Der Live-Test** (`t/90-live-keycloak.t`, nur wenn `TEST_AIRLOCK_KEYCLOAK_URL` gesetzt
ist) braucht ein Keycloak mit einem Realm, einem Client mit eingeschaltetem Device-Flow
und einem Nutzer mit TOTP. Für den Test reicht ein Container mit Realm-Import aus einer
JSON-Datei in `t/keycloak/`; ein Admin-Client ist dafür nicht nötig.
**Nicht in v1:** Zitadel- und Authentik-Abbildungen (dieselbe Naht, kommen bei Bedarf),
Airlock als Fassade vor Keycloaks Device-Endpunkt (unnötig), und von Dritten prüfbare
Airlock-Tokens samt Token Exchange (Phase 2/3; ab dort ist Airlock faktisch ein kleiner
Aussteller, was für Mothership die Zeile âKein Identity Providerâ berührt).
**AuÃerhalb dieser Dist:** Auf CPAN gibt es kein Keycloak-Modul (Stand 2026-10-02; die
Suche findet nur generische OIDC- und SAML-Module, die Keycloak erwähnen). Ein
`WWW::Keycloak` nach dem Muster von `WWW::Zitadel` (OIDC plus Admin-API für Realms,
Clients, Nutzer) ist eine eigene Dist und die Grundlage für ein automatisches
Keycloak-Setup. Airlock hängt nicht davon ab.
## 8. Sicherheit
- `user_code` hat rund 2,5 · 10¹ⰠMöglichkeiten und lebt 10 Minuten. Fehlversuche meldet
der Kern als `code_miss` mit Subject und Herkunft; begrenzen muss die Host-App, weil nur
sie Sessions und IPs kennt. Die Doku sagt das deutlich, das Beispiel macht es vor.
- `inspect` liefert Client-Namen, Scopes, Herkunft (IP, User-Agent) und Alter der Anfrage,
damit die Seite sie zeigen kann. Bestätigt wird nur durch einen `approve`-Aufruf mit
Subject, nie durch bloÃes Ãffnen von `verification_uri_complete`.
- `device_code` nur gehasht im Store; Vergleiche in konstanter Zeit.
- Einlösen ist atomar und einmalig.
- Faktoren: Replay-Schutz bei TOTP, begrenzte Versuche pro Request, danach ist der Request
`denied`.
- Fehlerantworten strikt nach RFC 8628 (HTTP 400 mit `error`).
- Keine Codes, Tokens oder Faktor-Geheimnisse in Logs oder Events.
## 9. Tests und Phasen
Tests: Zustandsautomat mit eingebautem Speicher und gestellter Uhr; `Airlock::Test::Store`
gegen den eingebauten Speicher und gegen das DBI-Beispiel auf SQLite; TOTP gegen die
Testvektoren aus RFC 6238; QR durch Zurücklesen; `to_app` mit rohen PSGI-Envs und
`handle` mit `HTTP::Request`; `Airlock::Client` gegen `to_app` auf einem lokalen Port;
Keycloak live hinter der Umgebungsvariable.
| Phase | Inhalt |
|---|---|
| 1 | Kern, Code, Policy, Store-Subs mit eingebautem Speicher, `Airlock::Test::Store`, Factor::Callback/TOTP/Upstream, Issuer-Sub mit Opaque-Standard, QR, `to_app`, `handle`, Client, Keycloak-Abbildung mit Live-Test, Beispiele (Plack, Mojolicious, DB...
| 2 | JWT-Issuer mit JWKS, Recovery-Codes, Mojolicious-Plugin falls nötig, weitere IdP-Abbildungen |
( run in 1.119 second using v1.01-cache-2.11-cpan-99fa8243a42 )