@sellx/tokens

Sichere Token-Erzeugung mit einheitlichen Präfixen und Prüfsummen. Läuft in Node (>= 18) und im Browser. Keine Abhängigkeiten.

npm install @sellx/tokens

import { createApiKey, parseToken } from '@sellx/tokens';

const key = createApiKey('live');
// → sx_live_0EtrBiGUKcWPyVGbF9h2mpCfrEyK2FQpL9uSZIFUsHR_0JMP3RC

parseToken(key, 'sx_live');
// → { valid: true, prefix: 'sx_live', body: '0EtrBi…' }

Warum nicht einfach crypto.randomBytes()?

Für den reinen Zufall reicht das völlig — dieses Package ruft intern nichts anderes auf. Der Nutzen liegt woanders:

Präfixe. sx_live_… gegenüber sx_test_… macht in Logs, Support-Tickets und Code-Reviews sofort sichtbar, womit man es zu tun hat. Ein Live-Key, der versehentlich in einem Testsystem landet, fällt beim Draufschauen auf. Secret- Scanner (GitHub, GitLab) lassen sich auf das Präfix trainieren und schlagen an, bevor ein Key im öffentlichen Repo landet.

Prüfsummen. Der Klassiker im Support: „Der Key funktioniert nicht." In neun von zehn Fällen wurde beim Kopieren ein Zeichen abgeschnitten. parseToken() erkennt das lokal, ohne Datenbankzugriff — und die Fehlermeldung kann konkret „Token unvollständig kopiert" statt „ungültig" lauten.

Einheitlichkeit. Ohne gemeinsames Package entstehen in jedem Projekt eigene Lösungen: mal Math.random(), mal 8 Byte Entropie, mal ein selbstgebautes Base64 mit Modulo-Bias. Ein Package, das zu wenig Entropie schlicht ablehnt, verhindert diese Fehlerklasse strukturell.

API

createToken(options?)

| Option | Standard | Bedeutung | |---|---|---| | format | 'base62' | 'hex', 'base64url', 'base32', 'base62' | | bytes | 32 | Zufallsbytes. Minimum 16 (= 128 Bit), darunter wird abgelehnt. | | prefix | – | z. B. 'sx_live'. Nur a–z, 0–9, _. | | checksum | true bei Präfix | Prüfsumme anhängen. |

parseToken(token, expectedPrefix?)

Gibt { valid, prefix?, body?, reason? } zurück. reason ist 'malformed', 'checksum_mismatch' oder 'prefix_mismatch'.

Wichtig: valid: true heißt ausschließlich syntaktisch unversehrt. Es sagt nichts darüber aus, ob das Token existiert oder autorisiert ist. Die tatsächliche Prüfung muss immer serverseitig gegen die Datenbank laufen. Die Prüfsumme ist eine Tippfehler-Erkennung, kein Sicherheitsmerkmal — CRC32 kann jeder berechnen.

Convenience-Helfer

createApiKey('live' | 'test')  // sx_live_… mit Prüfsumme, 256 Bit
createWebhookSecret()          // base64url, 256 Bit, ohne Präfix
createIdempotencyKey()         // base32, 128 Bit, vorlesbar
createReference('order')       // order_…, 128 Bit — Kennung, KEIN Geheimnis

Formate — wann welches?

| Format | Zeichen | Wofür | |---|---|---| | base62 | A–Z a–z 0–9 | Standard für API-Keys. Kompakt, URL-sicher. | | base32 | Crockford, ohne I L O U | Wenn Menschen den Wert vorlesen oder abtippen. Keine 1/l- oder 0/O-Verwechslung. | | base64url | A–Z a–z 0–9 - _ | Kompakteste Form, z. B. Webhook-Secrets. | | hex | 0–9 a–f | Wenn ein Fremdsystem Hex erwartet. |

Sicherheitshinweise

• Zufallsquelle: ausschließlich crypto.getRandomValues (Web Crypto). Es gibt bewusst keinen Fallback auf Math.random() — fehlt die sichere Quelle, wirft das Package einen Fehler, statt still unsicher zu werden.
• Kein Modulo-Bias: Base62 nutzt Rejection Sampling, Base32 arbeitet direkt auf dem Bitstrom. Beides ist per Chi-Quadrat-Test abgesichert.
• Speicherung: Token gehören gehasht in die Datenbank (z. B. SHA-256), nicht im Klartext. Dieses Package erzeugt Token, es speichert sie nicht.
• timingSafeEqual ist Best-Effort. In Node ist crypto.timingSafeEqual vorzuziehen; die hier enthaltene Variante existiert für den isomorphen Fall.
• createReference() liefert eine Kennung mit 128 Bit — brauchbar als Auftragsreferenz, ungeeignet als Geheimnis, weil Referenzen typischerweise in E-Mails und Rechnungen auftauchen.

Entwicklung

npm install
npm run build
npm test        # 17 Tests, inkl. Verteilungs- und Grenzfallprüfung

Veröffentlichung im Firmen-Scope

Das Package ist als @sellx/tokens benannt. Für eine private Registry:

npm publish --access restricted

Für GitHub Packages zusätzlich in .npmrc:

@sellx:registry=https://npm.pkg.github.com

Lizenz

MIT