dyegolara/lnurl-auth-agents

lnurl-auth (LUD-04)

Authentifizieren Sie sich bei einem Dienst mittels LNURL-auth (Lightning „Sign in with Lightning“) vollständig clientseitig. Dies dient ausschließlich der Authentifizierung: Der Server sendet eine k1-Challenge, Sie signieren das rohe 32-Byte k1 mit einem secp256k1-Privatschlüssel und senden sig + key per GET an den Callback zurück. Keine Rechnung, keine Zahlung, kein Lightning-Node.

Wann verwenden

• Eine Seite zeigt „Sign in with Lightning“ / LNURL-auth an.
• Ihnen liegt ein lnurl1...-String vor (aus einem QR-Code, einem Link oder einem eingefügten Text).
• Sie dürfen kein Geld ausgeben oder einen Lightning-Node betreiben.

Befehl

Ausführung mit Node (bereits installiert). Das Skript befindet sich unter:

<skill_dir>/lnurl_auth.js

node <skill_dir>/lnurl_auth.js --lnurl <lnurl1...> [optionen]
# oder den lnurl positional übergeben:
node <skill_dir>/lnurl_auth.js <lnurl1...>

Optionen

Option	Beschreibung
--lnurl <str>	Der lnurl1...-String (oder positional übergeben)
--key <hex>	Diesen hexadezimalen Privatschlüssel als Master-Secret verwenden
--keyfile <pfad>	Das Master-Secret (hex) aus einer Datei lesen
--keyout <pfad>	Wo ein generiertes Master-Secret gespeichert werden soll (Standard: ~/.config/lnurl-auth/master.key)
--generate	Erzwingt die Generierung eines neuen Master-Secrets und überschreibt eine vorhandene Schlüsseldatei
--single-key	Einen globalen Linking-Key für alle Dienste verwenden (keine domain-spezifische Ableitung)
--no-t	Kompatibilitätsoption; der Callback fügt keinen t-Parameter hinzu
--action <a>	Aktion setzen/überschreiben: register, login, link oder auth
--callback <url>	Überschreibt die URL, an die die Signatur gesendet wird
--dry-run	Dekodieren, k1 abrufen, signieren – aber keinen Callback senden
--json	Maschinenlesbares JSON ausgeben
-v, --verbose	Ausführliche Protokollierung
-q, --quiet	Fortschrittsprotokolle unterdrücken
-h, --help	Hilfe anzeigen

Schlüsselverwaltung (Standard, datenschutzfreundlich)

• Bei der ersten Nutzung wird ein 32-Byte Master-Secret generiert und in ~/.config/lnurl-auth/master.key (Modus 0600) gespeichert.
• Für jeden Dienst wird ein Linking-Key deterministisch abgeleitet: linkingPriv = HMAC-SHA256(master, serviceDomain).
• Gleicher Dienst → gleicher Schlüssel (wiederkehrender Benutzer). Unterschiedliche Dienste → unterschiedliche Schlüssel (Datenschutz – im Sinne von LUD-05/LUD-13).
• Verwenden Sie --single-key für einen globalen Linking-Key für alle Dienste.

Protokollablauf (LUD-04)

1. lnurl1... ist bech32("lnurl", utf8(serviceURL)). Dekodieren → URL mit k1 (32-Byte hex Challenge) und optional action.
2. Das rohe 32-Byte k1 mit dem Linking-Private-Key mittels ECDSA (secp256k1, prehash: false) signieren, dann die Signatur DER-kodieren.
3. GET an die Service-URL mit &sig=<hex DER sig>&key=<hex komprimierter Pubkey> anhängen, während vorhandene Query-Parameter erhalten bleiben.
4. Der Server überprüft die Signatur und antwortet mit {"status":"OK"} oder {"status":"ERROR","reason":"..."}.

Referenz: https://github.com/lnurl/luds/blob/luds/04.md

Ausgabe

• Fortschrittsmeldungen gehen nach stderr.
• Serverantwort (JSON) geht nach stdout.
• {"status":"OK"} → Exit-Code 0.
• {"status":"ERROR",...} → Exit-Code 3.
• Nicht-JSON oder Nicht-200-Antwort → Exit-Code 4.

Beispiele

Grundlegende Anmeldung

node <skill_dir>/lnurl_auth.js --lnurl "lnurl1dp68gurn8ghj7..."

Zuerst Probelauf (Inspizieren ohne zu senden)

node <skill_dir>/lnurl_auth.js "lnurl1..." --dry-run --json

Bestimmten Schlüssel verwenden

node <skill_dir>/lnurl_auth.js "lnurl1..." --key <64-zeichen-hex-privatschlüssel>

Neue Identität erzwingen

node <skill_dir>/lnurl_auth.js "lnurl1..." --generate

Abhängigkeiten

• Node.js v20.19+ (v22 empfohlen).
• Zwei kleine reine JS npm-Pakete, mitgeliefert in node_modules/:
  • @noble/secp256k1 (Signieren/Verifizieren, klein, ohne Abhängigkeiten)
  • bech32 (lnurl dekodieren/kodieren)
• Kein nativer Build; Netzwerkaufrufe beschränken sich auf das optionale Abrufen der Challenge und den finalen Callback per GET.
• Keine Kosten, kein Lightning-Node.

Mitgelieferte Abhängigkeiten installieren/aktualisieren

cd <skill_dir>
npm install

Selbsttest (keine externen Dienste, keine Kosten)

Ein lokaler Mock-LUD-04-Server validiert den vollständigen Signieren → Senden → Verifizieren-Durchlauf:

cd <skill_dir>
npm test

Abgedeckt: Positivpfad, Zurückweisung von Wiederholungen, Sicherheit des Probelaufs, Zurückweisung manipulierter k1, Domain-Schlüssel-Stabilität, --generate-Überschreiben und Validierung ungerader Hex-Daten.

Praxisnahe Verifizierung

Getestet gegen zwei öffentliche Dienste:

Dienst	Antwort
bitsimp.com	{"status":"OK"}
lightninglogin.live	{"status":"OK"}

Einschränkungen

• Dies führt den kryptografischen Handshake aus; die Erstellung/Anmeldung eines Kontos hängt davon ab, ob der entfernte Dienst den Schlüssel erkennt.
• Der Standard-Linking-Key wird pro Domain aus einem lokalen Master-Secret abgeleitet – es ist nicht dieselbe Identität, die das Wallet eines Benutzers auf dem Telefon erzeugen würde. Ausreichend für die Authentifizierung von Agenten.
• Erfordert Netzwerkzugriff für das optionale Abrufen der Challenge und den finalen Callback (keine Zahlung, kein Lightning-Node).