@aplons/auth 0.1.0 → 0.2.0

package/dist/pkce.js

@@ -1,75 +1,73 @@
 /**
- * PKCE — der Nachweis, dass der, der den Code einlöst, auch der ist, der ihn
- * angefordert hat.
+ * PKCE — proof that whoever redeems the code is the one who asked for it.
  *
- * Der Code kommt über einen Umleitungs-URL zurück und steht damit im Verlauf
- * des Browsers, im Log jedes Proxys dazwischen und im Referer der nächsten
- * Seite. Wer ihn dort aufliest, kann ihn ohne PKCE einlösen. Mit PKCE braucht
- * er zusätzlich den Verifier, und der hat den Browser nie verlassen.
+ * The code comes back through a redirect URL, which puts it in the browser
+ * history, in the log of every proxy in between, and in the referer of the
+ * next page. Without PKCE, anyone who reads it there can redeem it. With
+ * PKCE they also need the verifier, and that never left the browser.
  *
- * Alles hier läuft über die eingebaute Web-Crypto — kein Paket, keine
- * Abhängigkeit. Verfügbar in Node ab 18, in jedem Browser und am Rand.
+ * Everything here runs on built-in Web Crypto — no package, no dependency.
+ * Available in Node 18+, in every browser, and at the edge.
  */
-/** Der Zufall, aus dem alles Weitere folgt. */
-function zufall(bytes) {
-    const puffer = new Uint8Array(bytes);
-    crypto.getRandomValues(puffer);
-    return puffer;
+/** The randomness everything else follows from. */
+function randomBytes(count) {
+    const buffer = new Uint8Array(count);
+    crypto.getRandomValues(buffer);
+    return buffer;
 }
 /**
- * Base64 ohne die drei Zeichen, die in einem URL etwas anderes bedeuten.
+ * Base64 without the three characters that mean something else in a URL.
  *
- * `+` wird in einer Formularkodierung zum Leerzeichen, `/` trennt Pfade, und
- * `=` trennt Parameter von Werten. Ein Verifier mit diesen Zeichen kommt am
- * anderen Ende verändert an und passt dann nicht mehr zu seinem Challenge —
- * ein Fehler, der sich als „invalid_grant" zeigt und nach allem aussieht
- * außer nach seiner Ursache.
+ * `+` becomes a space in form encoding, `/` separates path segments, and `=`
+ * separates a parameter from its value. A verifier containing them arrives
+ * altered at the other end and no longer matches its challenge — a failure
+ * that surfaces as `invalid_grant` and looks like anything but its cause.
  */
-export function base64url(daten) {
-    const bytes = daten instanceof Uint8Array ? daten : new Uint8Array(daten);
-    let roh = "";
+export function base64url(data) {
+    const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+    let raw = "";
     for (const byte of bytes)
-        roh += String.fromCharCode(byte);
-    return btoa(roh).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+        raw += String.fromCharCode(byte);
+    return btoa(raw).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
 /**
- * Ein Verifier: 32 Byte Zufall, base64url — 43 Zeichen.
+ * A verifier: 32 bytes of randomness, base64url — 43 characters.
  *
- * Das ist die Untergrenze aus RFC 7636 und zugleich genug: 256 Bit Zufall
- * lassen sich nicht raten. Die Obergrenze von 128 Zeichen brächte nichts
- * dazu.
+ * That is the lower bound from RFC 7636 and it is also enough: 256 bits of
+ * randomness cannot be guessed. Going up to the 128-character limit would
+ * add nothing.
  */
 export function createVerifier() {
-    return base64url(zufall(32));
+    return base64url(randomBytes(32));
 }
-/** Was davon in den Anmelde-URL geht: der Hash, nie der Verifier selbst. */
+/** What goes into the authorization URL: the hash, never the verifier. */
 export async function createChallenge(verifier) {
     const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
     return base64url(digest);
 }
 /**
- * Der Wert gegen fremde Anfragen (CSRF).
+ * The value that guards against cross-site request forgery.
  *
- * Ohne ihn könnte jemand einen Anmeldevorgang mit *seinem* Konto beginnen und
- * dem Opfer den Rückkehr-URL unterschieben; das Opfer wäre danach im fremden
- * Konto angemeldet und legte dort Daten ab.
+ * Without it someone could start a login with *their* account and hand the
+ * victim the finished redirect URL; the victim would end up signed into a
+ * stranger's account and file their data there.
  */
 export function createState() {
-    return base64url(zufall(16));
+    return base64url(randomBytes(16));
 }
 /**
- * Zwei Zeichenketten vergleichen, ohne über die Dauer zu verraten, ab welcher
- * Stelle sie sich unterscheiden.
+ * Compare two strings without revealing, through timing, where they start
+ * to differ.
  *
- * Für den State ist das strenggenommen mehr, als nötig wäre — aber die
- * Funktion steht auch für den, der sie auf etwas Empfindlicheres anwendet.
+ * For the state this is strictly more than necessary — but the function is
+ * also here for whoever applies it to something more sensitive.
  */
-export function gleich(a, b) {
+export function timingSafeEqual(a, b) {
     if (a.length !== b.length)
         return false;
-    let unterschied = 0;
+    let difference = 0;
     for (let i = 0; i < a.length; i += 1) {
-        unterschied |= a.charCodeAt(i) ^ b.charCodeAt(i);
+        difference |= a.charCodeAt(i) ^ b.charCodeAt(i);
     }
-    return unterschied === 0;
+    return difference === 0;
 }

package/dist/types.d.ts

@@ -1,36 +1,35 @@
-/** Wie eine Anwendung sich gegenüber Aplons ausweist. */
+/** How an application identifies itself to Aplons. */
 export type AplonsOptions = {
     /**
-     * Wo Aplons steht, ohne Pfad — etwa `https://auth.aplons.com`.
-     * Alles Weitere holt das Paket von dort selbst (`/.well-known/…`).
+     * Where Aplons lives, without a path — e.g. `https://auth.aplons.com`.
+     * Everything else the package fetches from there itself (`/.well-known/…`).
      */
     issuer: string;
     clientId: string;
     /**
-     * Nur für Anwendungen, die ein Geheimnis behalten können — also einen
-     * Server haben. Eine Anwendung, die im Browser oder auf einem Telefon
-     * läuft, lässt es weg: was dort mitgeliefert wird, ist nicht geheim, und
-     * ein „Geheimnis", das jeder auslesen kann, macht die Sache nicht sicherer,
-     * sondern nur unübersichtlich.
+     * Only for applications that can keep a secret — that is, ones with a
+     * server. An application running in a browser or on a phone leaves it out:
+     * whatever ships there is not secret, and a "secret" anyone can read does
+     * not make things safer, only less clear.
      */
     clientSecret?: string;
-    /** Wohin Aplons nach der Anmeldung zurückschickt. Muss hinterlegt sein. */
+    /** Where Aplons sends the browser back to. Must be registered. */
     redirectUri: string;
-    /** Voreinstellung: openid, profile, email. */
+    /** Defaults to openid, profile, email. */
     scope?: string[];
-    /** Eigene fetch-Implementierung, etwa zum Testen. */
+    /** Your own fetch implementation, e.g. for tests. */
     fetch?: typeof globalThis.fetch;
 };
-/** Was nach der Anmeldung vorliegt. */
-export type Sitzung = {
+/** What you hold after a successful login. */
+export type Session = {
     accessToken: string;
     refreshToken?: string;
-    /** Zeitpunkt, nicht Dauer: eine Dauer ist ab dem Moment falsch, in dem
-     *  man sie ablegt. */
+    /** A point in time, not a duration: a duration is wrong the moment you
+     *  store it. */
     accessTokenExpiresAt: Date;
     idToken?: string;
     scope: string[];
-    /** Die geprüften Angaben aus dem ID-Token. */
+    /** The verified claims from the ID token. */
     claims?: IdTokenClaims;
 };
 export type IdTokenClaims = {
@@ -44,29 +43,29 @@ export type IdTokenClaims = {
     name?: string;
     given_name?: string;
     family_name?: string;
-    /** Der Mandant, zu dem das Konto gehört. */
+    /** The tenant the account belongs to. */
     tid?: string;
-    [weitere: string]: unknown;
+    [claim: string]: unknown;
 };
 export type AccessTokenClaims = {
     sub: string;
     iss: string;
     exp: number;
     iat: number;
-    /** Der Mandant. */
+    /** The tenant. */
     tid?: string;
-    /** Rollen im Mandanten. */
+    /** Roles within the tenant. */
     rls?: string[];
-    /** Einzelne Berechtigungen. */
+    /** Individual permissions. */
     prm?: string[];
-    /** Die Sitzung, aus der das Token stammt. */
+    /** The session the token came from. */
     sid?: string;
     email?: string;
     scope?: string;
-    [weitere: string]: unknown;
+    [claim: string]: unknown;
 };
-/** Was UserInfo zurückgibt — je nach Bereich mehr oder weniger. */
-export type Profil = {
+/** What UserInfo returns — more or less, depending on the scopes. */
+export type UserInfo = {
     sub: string;
     email?: string;
     email_verified?: boolean;
@@ -74,17 +73,17 @@ export type Profil = {
     given_name?: string;
     family_name?: string;
     phone_number?: string;
-    /** Rollen in *dieser* Anwendung, mit dem Bereich `roles`. */
+    /** Roles in *this* application, with the `roles` scope. */
     roles?: string[];
-    /** Die eigenen Felder dieser Anwendung, mit dem Bereich `app_profile`. */
+    /** This application's own fields, with the `app_profile` scope. */
     app_profile?: Record<string, unknown>;
-    [weitere: string]: unknown;
+    [claim: string]: unknown;
 };
-/** Das, was zwischen Start und Rückkehr aufbewahrt werden muss. */
-export type Anmeldevorgang = {
-    /** Dorthin schicken. */
+/** What has to survive between starting a login and completing it. */
+export type AuthorizationRequest = {
+    /** Send the browser here. */
     url: string;
-    /** Beides kurzlebig ablegen — und beim Rückkehr-Aufruf wieder mitgeben. */
+    /** Keep all three briefly — and hand them back to `completeLogin`. */
     verifier: string;
     state: string;
     nonce: string;

package/dist/verify.d.ts

@@ -1,26 +1,26 @@
 /**
- * Ein Token prüfen, statt ihm zu glauben.
+ * Verify a token instead of believing it.
  *
- * Ein JWT ist lesbar, ohne dass jemand etwas prüft — `atob` auf den mittleren
- * Teil, fertig. Wer das für eine Prüfung hält, lässt jeden herein, der sich
- * ein Token selbst schreibt. Geprüft wird deshalb die Unterschrift gegen die
- * öffentlichen Schlüssel von Aplons, dazu Aussteller, Empfänger und Ablauf.
+ * A JWT is readable without anyone verifying anything — `atob` on the middle
+ * part and you are done. Whoever mistakes that for verification lets in
+ * everybody who writes themselves a token. So the signature is checked
+ * against the public keys of Aplons, along with issuer, audience and expiry.
  *
- * `jose` erledigt das Kryptografische. Es ist die einzige Abhängigkeit dieses
- * Pakets, und es ist dieselbe, die der Aplons-Server selbst benutzt.
+ * `jose` does the cryptography. It is this package's only dependency, and it
+ * is the same one the Aplons server itself uses.
  */
 import { createRemoteJWKSet } from "jose";
 import type { AccessTokenClaims, IdTokenClaims } from "./types.js";
-type Schluesselquelle = ReturnType<typeof createRemoteJWKSet>;
-export declare function schluesselFuer(jwksUri: string): Schluesselquelle;
-export declare function pruefeZugriffstoken(token: string, options: {
+type KeySource = ReturnType<typeof createRemoteJWKSet>;
+export declare function jwksFor(jwksUri: string): KeySource;
+export declare function verifyAccessToken(token: string, options: {
     issuer: string;
-    schluessel: Schluesselquelle;
+    keys: KeySource;
 }): Promise<AccessTokenClaims>;
-export declare function pruefeIdToken(token: string, options: {
+export declare function verifyIdToken(token: string, options: {
     issuer: string;
     audience: string;
     nonce?: string;
-    schluessel: Schluesselquelle;
+    keys: KeySource;
 }): Promise<IdTokenClaims>;
-export {};
+export type { KeySource };

package/dist/verify.js

@@ -1,94 +1,94 @@
 /**
- * Ein Token prüfen, statt ihm zu glauben.
+ * Verify a token instead of believing it.
  *
- * Ein JWT ist lesbar, ohne dass jemand etwas prüft — `atob` auf den mittleren
- * Teil, fertig. Wer das für eine Prüfung hält, lässt jeden herein, der sich
- * ein Token selbst schreibt. Geprüft wird deshalb die Unterschrift gegen die
- * öffentlichen Schlüssel von Aplons, dazu Aussteller, Empfänger und Ablauf.
+ * A JWT is readable without anyone verifying anything — `atob` on the middle
+ * part and you are done. Whoever mistakes that for verification lets in
+ * everybody who writes themselves a token. So the signature is checked
+ * against the public keys of Aplons, along with issuer, audience and expiry.
  *
- * `jose` erledigt das Kryptografische. Es ist die einzige Abhängigkeit dieses
- * Pakets, und es ist dieselbe, die der Aplons-Server selbst benutzt.
+ * `jose` does the cryptography. It is this package's only dependency, and it
+ * is the same one the Aplons server itself uses.
  */
 import { createRemoteJWKSet, jwtVerify } from "jose";
 import { AplonsError } from "./errors.js";
 /*
-  Eine Schlüsselquelle je Adresse, nicht je Aufruf.
+  One key source per address, not per call.
 
-  `createRemoteJWKSet` bringt einen eigenen Zwischenspeicher mit und holt bei
-  einem unbekannten `kid` neu — das ist genau das Verhalten, das einen
-  Schlüsselwechsel überlebt. Für jeden Aufruf eine neue Quelle anzulegen
-  hieße, den Zwischenspeicher wegzuwerfen und bei jeder Anfrage die
-  Schlüssel erneut zu laden.
+  `createRemoteJWKSet` brings its own cache and refetches on an unknown `kid`
+  — exactly the behaviour that survives a key rotation. Building a new source
+  for every call would throw that cache away and refetch the keys on every
+  single request.
 */
-const quellen = new Map();
-export function schluesselFuer(jwksUri) {
-    let quelle = quellen.get(jwksUri);
-    if (!quelle) {
-        quelle = createRemoteJWKSet(new URL(jwksUri));
-        quellen.set(jwksUri, quelle);
+const keySources = new Map();
+export function jwksFor(jwksUri) {
+    let source = keySources.get(jwksUri);
+    if (!source) {
+        source = createRemoteJWKSet(new URL(jwksUri));
+        keySources.set(jwksUri, source);
     }
-    return quelle;
+    return source;
 }
-export async function pruefeZugriffstoken(token, options) {
+export async function verifyAccessToken(token, options) {
     try {
-        const { payload } = await jwtVerify(token, options.schluessel, {
+        const { payload } = await jwtVerify(token, options.keys, {
             issuer: options.issuer,
-            // Bewusst ohne `audience`: ein Zugriffstoken ist an die Anwendung
-            // gerichtet, die es benutzt, und die kann eine andere sein als die,
-            // die es geholt hat. Wer das enger fassen will, prüft `aud` selbst.
+            // Deliberately without `audience`: an access token is addressed to the
+            // application that uses it, and that can be a different one from the
+            // application that obtained it. Anyone wanting it stricter checks
+            // `aud` themselves.
         });
         return payload;
     }
     catch (cause) {
-        throw alsFehler(cause, "Das Zugriffstoken");
+        throw asError(cause, "The access token");
     }
 }
-export async function pruefeIdToken(token, options) {
+export async function verifyIdToken(token, options) {
     let claims;
     try {
-        const { payload } = await jwtVerify(token, options.schluessel, {
+        const { payload } = await jwtVerify(token, options.keys, {
             issuer: options.issuer,
-            // Hier schon: ein ID-Token ist an genau diese Anwendung gerichtet.
-            // Eines, das für eine andere ausgestellt wurde, darf nicht zählen.
+            // Here it does apply: an ID token is addressed to exactly this
+            // application. One issued for another must not count.
             audience: options.audience,
         });
         claims = payload;
     }
     catch (cause) {
-        throw alsFehler(cause, "Das ID-Token");
+        throw asError(cause, "The ID token");
     }
     /*
-      Der Nonce bindet das ID-Token an genau diesen Anmeldevorgang.
+      The nonce binds the ID token to this one login.
   
-      Ohne ihn ließe sich ein früher abgefangenes, noch gültiges ID-Token in
-      einem neuen Vorgang einreichen. Geprüft wird nur, wenn beim Start einer
-      gesetzt wurde — sonst gäbe es nichts zu vergleichen.
+      Without it, an intercepted ID token that is still valid could be replayed
+      in a new flow. Only checked when one was set at the start — otherwise
+      there would be nothing to compare against.
     */
     if (options.nonce && claims.nonce !== options.nonce) {
         throw new AplonsError({
             code: "nonce_mismatch",
-            message: "Der nonce im ID-Token gehört nicht zu diesem Anmeldevorgang. " +
-                "Die Anmeldung wird nicht fortgesetzt.",
+            message: "The nonce in the ID token does not belong to this login. " +
+                "The login will not continue.",
         });
     }
     return claims;
 }
-function alsFehler(cause, was) {
+function asError(cause, what) {
     const code = cause && typeof cause === "object" && "code" in cause
         ? String(cause.code)
         : "invalid_token";
-    const erklaerung = {
-        ERR_JWT_EXPIRED: "ist abgelaufen. Erneuere es mit dem Refresh-Token.",
-        ERR_JWT_CLAIM_VALIDATION_FAILED: "wurde für einen anderen Aussteller oder Empfänger ausgestellt.",
-        ERR_JWS_SIGNATURE_VERIFICATION_FAILED: "trägt keine gültige Unterschrift von Aplons.",
-        ERR_JOSE_NOT_SUPPORTED: "benutzt ein Verfahren, das hier nicht zugelassen ist — bei " +
-            '`alg: "none"` ist das ein selbst geschriebenes Token ohne Unterschrift.',
-        ERR_JWKS_NO_MATCHING_KEY: "ist mit einem Schlüssel unterschrieben, den Aplons nicht kennt. " +
-            "Bei einem gerade gewechselten Schlüssel hilft ein zweiter Versuch.",
+    const explanations = {
+        ERR_JWT_EXPIRED: "has expired. Renew it with the refresh token.",
+        ERR_JWT_CLAIM_VALIDATION_FAILED: "was issued for a different issuer or audience.",
+        ERR_JWS_SIGNATURE_VERIFICATION_FAILED: "does not carry a valid signature from Aplons.",
+        ERR_JOSE_NOT_SUPPORTED: 'uses an algorithm that is not allowed here — with `alg: "none"` that ' +
+            "is a self-written token with no signature at all.",
+        ERR_JWKS_NO_MATCHING_KEY: "is signed with a key Aplons does not know. If a key was just rotated, " +
+            "a second attempt helps.",
     };
     return new AplonsError({
         code,
         cause,
-        message: `${was} ${erklaerung[code] ?? "ist nicht gültig."}`,
+        message: `${what} ${explanations[code] ?? "is not valid."}`,
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aplons/auth",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Anmeldung über Aplons in eigenen Anwendungen — OAuth 2.1 mit PKCE, ohne den Ablauf selbst zu schreiben.",
   "license": "UNLICENSED",
   "private": false,
@@ -23,9 +23,8 @@
       "default": "./dist/next.js"
     }
   },
-  "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.json",
-    "prepublishOnly": "pnpm build"
+  "publishConfig": {
+    "access": "public"
   },
   "dependencies": {
     "jose": "^6.1.0"
@@ -39,5 +38,8 @@
     "pkce",
     "authentication",
     "aplons"
-  ]
-}
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json"
+  }
+}