cord login ohne kopierte Schlüssel – und ein Assistent, der Cord für Sie integriert

Wie wir den Device Flow der Cord-CLI gebaut haben, warum das Terminal einen eingeschränkten Einmalschlüssel erhält und was der Assistent von npx @flouviahq/cli macht.

ARTIKEL
IN DIESEM ARTIKEL6 ABSCHNITTE

Der erste Kontakt mit einer Zahlungsplattform ist meist der schlimmste: im Dashboard anmelden, den Bereich mit den Schlüsseln finden, eine 50 Zeichen lange Zeichenkette kopieren, sie in eine .env einfügen und hoffen, dass man sie nicht auf GitHub hochgeladen hat. Bei Cord sollte das ein einziger Befehl sein:

npx @flouviahq/cli

Der Device Flow

cord login verwendet dasselbe Muster wie ein Fernseher, der Sie bittet, sich über Ihr Smartphone anzumelden (der Device Flow aus RFC 8628):

  1. Das Terminal fordert über POST /api/cli/login einen Code an. Cord erzeugt zwei Dinge: einen Device Code aus 32 zufälligen Bytes, den nur das Terminal kennt, und einen kurzen User Code wie WXYZ-2346, den Sie zu sehen bekommen.
  2. Das Terminal öffnet Ihren Browser unter /app/cli/autorizar?codigo=WXYZ-2346. Dort bestätigen Sie mit Ihrer normalen Cord-Sitzung, dass der Code mit dem in Ihrem Terminal übereinstimmt, und klicken auf Autorisieren.
  3. In der Zwischenzeit fragt das Terminal alle zwei Sekunden mit seinem Device Code bei POST /api/cli/login/claim an. Sobald Sie zustimmen, erhält es den Schlüssel.

Einige Entscheidungen, die nicht offensichtlich sind:

  • In der Datenbank liegt nur der sha256-Hash des Device Codes. Selbst wer die Tabelle lesen könnte, könnte damit nichts einlösen.
  • Der User Code verwendet keine Zeichen, die sich beim Diktieren verwechseln lassen (0 und O, 1, I und L, 5 und S). Er besteht aus 8 Zeichen aus einem Alphabet mit 25 Zeichen.
  • Die Tabelle hat keine Zugriffsrichtlinien. Sie hat erzwungene Row-Level Security und keine einzige Richtlinie, sodass keine direkte Abfrage sie sieht. Angesprochen wird sie nur über vier eng gefasste security definer-Funktionen: erstellen, suchen, entscheiden und einlösen.
  • Der Schlüssel wird genau einmal übergeben. Er wird verschlüsselt gespeichert, bis das Terminal ihn abholt; in diesem Moment wechselt der Datensatz auf reclamado, und das Secret wird gelöscht. Der Code läuft nach 10 Minuten ab.
  • Das Terminal öffnet im Browser nur eine Adresse mit demselben Origin wie die API. Der Server entscheidet nicht, auf welche Website Sie geleitet werden.

Ein Schlüssel, der keinen Schaden anrichten kann

Das Terminal erhält keinen Administratorschlüssel. Es erhält einen eingeschränkten Testschlüssel (rk_test_) mit drei Berechtigungen: die Simulatoren verwenden, Ereignisse lesen und Konfigurationen vorschlagen. Er läuft nach 90 Tagen ab und erscheint im API-Bereich als CLI · <Ihr Gerät>, wo Sie ihn widerrufen können.

Die eingeschränkten Schlüssel von Cord haben pro Ressource eine eigene Zugriffsstufe, die aus der Route abgeleitet wird. Eine neue API-Route ist für sie von Anfang an gesperrt, bis jemand entscheidet, zu welcher Ressource sie gehört, und ein Test schlägt fehl, wenn eine Route ohne Ressource bleibt.

Da Testschlüssel auf das Limit des Tarifs angerechnet werden, widerruft eine erneute Verbindung desselben Geräts dessen vorherigen Schlüssel. Ein Terminal, ein Schlüssel.

Eine einzige Autorisierung für alles

Auch Ihr Projekt braucht einen Schlüssel, damit sein Server mit Cord kommunizieren kann. Wenn der Assistent ein Projekt integrieren soll, zeigt die Seite zum Autorisieren ein zusätzliches Kontrollkästchen: „Auch einen Schlüssel für dieses Projekt erstellen“. Wenn Sie es aktiviert lassen, erstellt Cord einen Test-Secret-Key, verschlüsselt ihn zusammen mit dem Schlüssel der CLI und übergibt beide gemeinsam genau einmal. Der Assistent schreibt ihn in Ihre .env.local.

Hat Ihr Tarif keinen Platz mehr für einen weiteren Schlüssel, wird die CLI trotzdem verbunden, und die Seite weist Sie darauf hin; nichts bricht auf halbem Weg ab.

Der Assistent

Ohne Befehl öffnet die CLI einen Assistenten mit Menüs, Fortschrittsanzeigen und einer abschließenden Zusammenfassung. Schritt für Schritt:

  1. Verbindet das Terminal über den oben beschriebenen Flow.
  2. Fragt, was zu tun ist: das Konto mit KI einrichten, das Projekt integrieren und Webhooks testen.
  3. Richtet Ihr Konto ein: liest Ihre Website und Ihre Preisliste, zeigt Ihnen den Vorschlag und wartet, bis Sie ihn im Browser freigeben.
  4. Integriert das Projekt: erkennt das Framework (Next.js, Astro, Express, Laravel, Django, Flask oder FastAPI), zeigt Ihnen genau, was er tun wird, und installiert, wenn Sie zustimmen, das SDK mit Ihrem Paketmanager und legt zwei Routen an: eine, die die Signatur jedes Webhooks prüft, und einen Proxy für Cord Elements.
  5. Empfängt Webhooks: öffnet eine Testsitzung, speichert ihr Secret in Ihrer .env.local und leitet jedes Ereignis an Ihren lokalen Server weiter.

Drei Regeln, die der Assistent nie bricht:

  • Er überschreibt keine Dateien. Wenn die Route bereits existiert, lässt er sie unverändert und weist Sie darauf hin.
  • Er schreibt Schlüssel nur in eine Umgebungsdatei, die git ignoriert. Findet er keine, schreibt er nichts und sagt Ihnen, welche Variable Sie hinzufügen müssen.
  • Er ändert die übrigen Zeilen Ihrer .env nicht. Er aktualisiert oder ergänzt nur die Variablen von Cord.
◆  Esto es lo que voy a hacer
│  +  instalar    @flouviahq/node @flouviahq/elements  · con npm
│  +  crear       app/api/webhooks/cord/route.ts       · verifica la firma de cada webhook
│  +  crear       app/api/cord/[...path]/route.ts      · proxy seguro para Cord Elements
│  ~  escribir    .env.local                           · CORD_SECRET_KEY de prueba

Ohne Abhängigkeiten

Die Oberfläche verwendet @clack/prompts, aber das veröffentlichte Paket hängt von nichts ab: esbuild bündelt es beim Build zusammen mit allem anderen in eine einzige Datei. Wer die CLI installiert, holt sich keinen neuen Abhängigkeitsbaum auf den Rechner.

Probieren Sie es aus

npx create-next-app@latest my-store --ts --app
cd my-store
npx @flouviahq/cli

Führen Sie danach in einem Terminal npm run dev und in einem anderen npx @flouviahq/cli trigger quote.approved aus: Das Ereignis erreicht Ihre Route, signiert, und das Terminal zeigt Ihnen den Status 200.