@aplons/auth 0.1.0

package/README.md

@@ -0,0 +1,164 @@
+# @aplons/auth
+
+Anmeldung über [Aplons](https://auth.aplons.com) in eigenen Anwendungen.
+
+OAuth 2.1 mit PKCE, ohne den Ablauf selbst zu schreiben. Eine einzige
+Abhängigkeit (`jose`, zum Prüfen von Unterschriften) — alles andere macht die
+eingebaute Web-Crypto. Läuft in Node ab 18, im Browser, am Rand und in einem
+Worker.
+
+```bash
+npm i @aplons/auth
+```
+
+## Mit Next.js
+
+Eine Datei, vier Adressen:
+
+```ts
+// app/api/auth/[...aplons]/route.ts
+import { handhabe } from "@aplons/auth/next";
+
+export const { GET, POST } = handhabe({
+  issuer: process.env.APLONS_ISSUER!,          // https://auth.aplons.com
+  clientId: process.env.APLONS_CLIENT_ID!,
+  clientSecret: process.env.APLONS_CLIENT_SECRET,
+  redirectUri: process.env.APLONS_REDIRECT_URI!,
+  nachAnmeldung: "/",
+});
+```
+
+Das ergibt:
+
+| Adresse | wozu |
+|---|---|
+| `/api/auth/login` | Anmeldung starten. `?weiter=/pfad` merkt sich, wohin danach. |
+| `/api/auth/callback` | Rückkehr von Aplons. Hier ist nichts zu tun. |
+| `/api/auth/logout` | Abmelden — hier **und** bei Aplons. |
+| `/api/auth/me` | Wer angemeldet ist; erneuert das Token still, wenn nötig. |
+
+Ein Anmeldeknopf ist dann ein Link:
+
+```tsx
+<a href="/api/auth/login?weiter=/rechnungen">Anmelden</a>
+```
+
+Die Sitzung in einer eigenen Route lesen:
+
+```ts
+const { sitzungAus, auth } = handhabe({ /* … */ });
+
+export async function GET(request: Request) {
+  const sitzung = await sitzungAus(request);
+  if (!sitzung) return new Response("nicht angemeldet", { status: 401 });
+
+  const profil = await auth.profil(sitzung.accessToken);
+  return Response.json(profil);
+}
+```
+
+## Ohne Rahmenwerk
+
+```ts
+import { AplonsAuth } from "@aplons/auth";
+
+const auth = new AplonsAuth({
+  issuer: "https://auth.aplons.com",
+  clientId: "cli_…",
+  clientSecret: "cs_…",        // nur wenn die Anwendung einen Server hat
+  redirectUri: "https://app.example.de/callback",
+});
+
+// 1. Hinschicken
+const { url, verifier, state, nonce } = await auth.start();
+// verifier, state und nonce bis zur Rückkehr aufbewahren
+
+// 2. Zurückkommen
+const sitzung = await auth.rueckkehr({ url: anfrageUrl, verifier, state, nonce });
+sitzung.accessToken;
+sitzung.claims?.email;
+
+// 3. Erneuern
+const frisch = await auth.erneuern(sitzung.refreshToken!);
+
+// 4. Abmelden
+const abmelden = await auth.abmeldeUrl({ danach: "https://app.example.de/" });
+```
+
+**`verifier`, `state` und `nonce` gehören in ein kurzlebiges, `httpOnly`
+gesetztes Cookie — nicht in den `localStorage`.** Was dort liegt, liest jedes
+Skript auf der Seite, und mit dem Verifier lässt sich ein abgefangener
+Anmeldecode einlösen. Der Next-Teil oben macht das schon richtig.
+
+## Eine API dahinter absichern
+
+```ts
+const claims = await auth.pruefeToken(token);
+claims.sub;   // das Konto
+claims.tid;   // der Mandant
+claims.rls;   // Rollen im Mandanten
+```
+
+Geprüft werden Unterschrift, Aussteller und Ablauf — gegen die öffentlichen
+Schlüssel von Aplons, ohne Rückfrage bei jedem Aufruf. Das ist der Unterschied
+zwischen „das Token sieht echt aus" und „das Token ist echt": ein JWT lässt
+sich mit `atob` lesen, ohne dass irgendetwas geprüft wurde.
+
+Die Schlüssel werden zwischengespeichert und bei einem unbekannten `kid` neu
+geholt, damit ein Schlüsselwechsel bei Aplons keinen Ausfall verursacht.
+
+## Öffentlich oder vertraulich
+
+Eine Anwendung mit Server behält ihr `clientSecret`. Eine, 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. Genau dafür gibt es PKCE.
+
+## Fehler
+
+Jeder Fehler ist ein `AplonsError` mit `code` für den Programmablauf und einer
+Meldung für den Menschen:
+
+```ts
+import { AplonsError } from "@aplons/auth";
+
+try {
+  await auth.rueckkehr({ /* … */ });
+} catch (fehler) {
+  if (fehler instanceof AplonsError && fehler.code === "invalid_grant") {
+    // meistens: die Rückkehr wurde zweimal ausgeführt
+  }
+}
+```
+
+Häufig:
+
+| `code` | heißt |
+|---|---|
+| `state_mismatch` | Der Vorgang ist zu alt, oder der Aufruf gehört nicht zu dieser Anmeldung. |
+| `invalid_grant` | Beim Anmeldecode: schon eingelöst. Beim Refresh-Token: abgelaufen oder schon getauscht. |
+| `invalid_client` | Client-ID oder -Secret stimmen nicht. |
+| `issuer_mismatch` | Unter `issuer` meldet sich ein Server, der sich anders nennt. Wird nicht fortgesetzt. |
+
+## Bereiche
+
+`openid`, `profile`, `email`, `phone`, `roles`, `app_profile`. Voreinstellung
+sind die ersten drei. `roles` liefert die Rollen des Kontos **in dieser
+Anwendung**, `app_profile` deren eigene Felder — beide über `auth.profil()`.
+
+## Sitzungen ablegen
+
+Ohne eigene Angabe legt der Next-Teil die Sitzung im Cookie ab. Das kommt ohne
+Speicher aus, hat aber zwei Grenzen: 4 KB, und ein Widerruf wirkt erst, wenn
+das Zugriffstoken abläuft. Wer eine Datenbank hat, gibt seine eigene Ablage an:
+
+```ts
+handhabe({
+  /* … */
+  speicher: {
+    async lies(id) { /* … */ },
+    async schreib(id, sitzung) { /* … */ },
+    async loesche(id) { /* … */ },
+  },
+});
+```

package/dist/client.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Die Anbindung an Aplons.
+ *
+ * Vier Schritte, mehr ist es nicht: Anmeldung starten, Rückkehr entgegen-
+ * nehmen, Token erneuern, abmelden. Dazu das Prüfen eines Tokens für den,
+ * der eine API dahinter absichert.
+ *
+ * Alles, was der Ablauf sonst noch braucht — welcher Endpunkt wo liegt,
+ * welche Schlüssel gerade gültig sind —, holt sich das Paket selbst. Wer nur
+ * `issuer` und `clientId` kennt, ist fertig.
+ */
+import { type Metadaten } from "./discovery.js";
+import type { AccessTokenClaims, Anmeldevorgang, AplonsOptions, Profil, Sitzung } from "./types.js";
+export declare class AplonsAuth {
+    #private;
+    readonly issuer: string;
+    readonly clientId: string;
+    readonly redirectUri: string;
+    readonly scope: string[];
+    constructor(options: AplonsOptions);
+    /**
+     * Die Endpunkte, einmal geholt und dann behalten.
+     *
+     * Als Versprechen zwischengespeichert, nicht als Ergebnis: sonst holen
+     * zehn gleichzeitige Anfragen beim Start zehnmal dieselbe Datei.
+     */
+    metadaten(): Promise<Metadaten>;
+    /**
+     * Schritt 1: Wohin der Browser geschickt wird.
+     *
+     * `verifier` und `state` müssen bis zur Rückkehr aufbewahrt werden — in
+     * einem kurzlebigen, `httpOnly`-Cookie, nicht im localStorage: was dort
+     * liegt, liest jedes Skript auf der Seite.
+     */
+    start(options?: {
+        /** Überschreibt die Bereiche aus dem Konstruktor. */
+        scope?: string[];
+        /** Wird unverändert zurückgegeben — etwa die Seite, die aufgerufen war. */
+        zusatz?: Record<string, string>;
+        /** Erzwingt die Anmeldemaske, auch wenn schon eine Sitzung besteht. */
+        erneutAnmelden?: boolean;
+        /** Setzt die Anmeldeseite auf diesen Mandanten. */
+        tenant?: string;
+    }): Promise<Anmeldevorgang>;
+    /**
+     * Schritt 2: Die Rückkehr.
+     *
+     * Nimmt den vollständigen URL entgegen, mit dem der Browser zurückkam, und
+     * die beiden Werte aus Schritt 1.
+     */
+    rueckkehr(options: {
+        /** Der Aufruf-URL, komplett. */
+        url: string | URL;
+        verifier: string;
+        /** Der State aus Schritt 1 — wird gegen den im URL geprüft. */
+        state: string;
+        /** Der Nonce aus Schritt 1, wenn ein ID-Token erwartet wird. */
+        nonce?: string;
+    }): Promise<Sitzung>;
+    /** Schritt 3: Ein abgelaufenes Zugriffstoken gegen ein frisches tauschen. */
+    erneuern(refreshToken: string): Promise<Sitzung>;
+    /**
+     * Schritt 4: Abmelden — bei Aplons, nicht nur hier.
+     *
+     * Nur die eigene Sitzung zu löschen genügt nicht: die Sitzung bei Aplons
+     * bliebe bestehen, und die nächste Anmeldung liefe ohne Passwort durch.
+     * Auf einem geteilten Rechner ist das der Unterschied zwischen abgemeldet
+     * und scheinbar abgemeldet.
+     */
+    abmeldeUrl(options?: {
+        /** Wohin Aplons nach dem Abmelden zurückschickt. Muss hinterlegt sein. */
+        danach?: string;
+        /** Das ID-Token der Sitzung; damit weiß Aplons, wen es abmeldet. */
+        idToken?: string;
+    }): Promise<string>;
+    /**
+     * Ein Zugriffstoken prüfen — für den, der eine eigene API dahinter hat.
+     *
+     * Geprüft wird gegen die öffentlichen Schlüssel von Aplons, ohne Rückfrage
+     * bei jedem Aufruf: Unterschrift, Aussteller und Ablauf. Das ist der
+     * Unterschied zwischen „das Token sieht echt aus" und „das Token ist echt".
+     */
+    pruefeToken(token: string): Promise<AccessTokenClaims>;
+    /** Die Angaben zum angemeldeten Konto, so weit die Bereiche es hergeben. */
+    profil(accessToken: string): Promise<Profil>;
+    /**
+     * Ein Refresh-Token entwerten.
+     *
+     * Gehört zum Abmelden dazu: ein Token, das noch dreißig Tage gilt, wird
+     * vom Löschen des Cookies nicht ungültig.
+     */
+    widerrufen(refreshToken: string): Promise<void>;
+}

package/dist/client.js

@@ -0,0 +1,248 @@
+/**
+ * Die Anbindung an Aplons.
+ *
+ * Vier Schritte, mehr ist es nicht: Anmeldung starten, Rückkehr entgegen-
+ * nehmen, Token erneuern, abmelden. Dazu das Prüfen eines Tokens für den,
+ * der eine API dahinter absichert.
+ *
+ * Alles, was der Ablauf sonst noch braucht — welcher Endpunkt wo liegt,
+ * welche Schlüssel gerade gültig sind —, holt sich das Paket selbst. Wer nur
+ * `issuer` und `clientId` kennt, ist fertig.
+ */
+import { AplonsError, ausAntwort } from "./errors.js";
+import { createChallenge, createState, createVerifier, gleich } from "./pkce.js";
+import { holeMetadaten } from "./discovery.js";
+import { pruefeIdToken, pruefeZugriffstoken, schluesselFuer } from "./verify.js";
+const STANDARD_SCOPE = ["openid", "profile", "email"];
+export class AplonsAuth {
+    issuer;
+    clientId;
+    redirectUri;
+    scope;
+    #clientSecret;
+    #fetch;
+    #metadaten;
+    constructor(options) {
+        if (!options.issuer)
+            throw new AplonsError({ code: "config", message: "issuer fehlt." });
+        if (!options.clientId)
+            throw new AplonsError({ code: "config", message: "clientId fehlt." });
+        if (!options.redirectUri) {
+            throw new AplonsError({ code: "config", message: "redirectUri fehlt." });
+        }
+        // Ein Schrägstrich am Ende erzeugt sonst `https://auth.example.com//oauth/…`.
+        this.issuer = options.issuer.replace(/\/+$/, "");
+        this.clientId = options.clientId;
+        this.redirectUri = options.redirectUri;
+        this.scope = options.scope ?? STANDARD_SCOPE;
+        this.#clientSecret = options.clientSecret;
+        this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    /**
+     * Die Endpunkte, einmal geholt und dann behalten.
+     *
+     * Als Versprechen zwischengespeichert, nicht als Ergebnis: sonst holen
+     * zehn gleichzeitige Anfragen beim Start zehnmal dieselbe Datei.
+     */
+    metadaten() {
+        this.#metadaten ??= holeMetadaten(this.issuer, this.#fetch);
+        return this.#metadaten;
+    }
+    /**
+     * Schritt 1: Wohin der Browser geschickt wird.
+     *
+     * `verifier` und `state` müssen bis zur Rückkehr aufbewahrt werden — in
+     * einem kurzlebigen, `httpOnly`-Cookie, nicht im localStorage: was dort
+     * liegt, liest jedes Skript auf der Seite.
+     */
+    async start(options) {
+        const metadaten = await this.metadaten();
+        const verifier = createVerifier();
+        const state = createState();
+        const nonce = createState();
+        const url = new URL(metadaten.authorization_endpoint);
+        url.searchParams.set("response_type", "code");
+        url.searchParams.set("client_id", this.clientId);
+        url.searchParams.set("redirect_uri", this.redirectUri);
+        url.searchParams.set("scope", (options?.scope ?? this.scope).join(" "));
+        url.searchParams.set("state", state);
+        url.searchParams.set("nonce", nonce);
+        url.searchParams.set("code_challenge", await createChallenge(verifier));
+        // S256 oder gar nicht: „plain" legt den Verifier in denselben URL wie den
+        // Code und schützt damit vor nichts.
+        url.searchParams.set("code_challenge_method", "S256");
+        if (options?.erneutAnmelden)
+            url.searchParams.set("prompt", "login");
+        if (options?.tenant)
+            url.searchParams.set("tenant", options.tenant);
+        for (const [name, wert] of Object.entries(options?.zusatz ?? {})) {
+            url.searchParams.set(name, wert);
+        }
+        return { url: url.toString(), verifier, state, nonce };
+    }
+    /**
+     * Schritt 2: Die Rückkehr.
+     *
+     * Nimmt den vollständigen URL entgegen, mit dem der Browser zurückkam, und
+     * die beiden Werte aus Schritt 1.
+     */
+    async rueckkehr(options) {
+        const url = typeof options.url === "string" ? new URL(options.url) : options.url;
+        const fehler = url.searchParams.get("error");
+        if (fehler) {
+            throw new AplonsError({
+                code: fehler,
+                message: `Die Anmeldung wurde abgebrochen (${fehler}).` +
+                    (url.searchParams.get("error_description")
+                        ? ` ${url.searchParams.get("error_description")}`
+                        : ""),
+            });
+        }
+        const state = url.searchParams.get("state");
+        const code = url.searchParams.get("code");
+        /*
+          Der State wird geprüft, bevor irgendetwas mit dem Code geschieht.
+    
+          Ohne diese Prüfung könnte jemand einen Anmeldevorgang mit seinem eigenen
+          Konto beginnen und dem Opfer den fertigen Rückkehr-URL unterschieben —
+          das Opfer wäre danach im fremden Konto angemeldet und legte dort seine
+          Daten ab.
+        */
+        if (!state || !gleich(state, options.state)) {
+            throw new AplonsError({
+                code: "state_mismatch",
+                message: "Der state stimmt nicht. Entweder ist der Anmeldevorgang zu alt, " +
+                    "oder der Aufruf kam nicht von der Anmeldung, die diese Anwendung " +
+                    "gestartet hat.",
+            });
+        }
+        if (!code) {
+            throw new AplonsError({
+                code: "missing_code",
+                message: "Im Rückkehr-URL steht kein code.",
+            });
+        }
+        const antwort = await this.#token({
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: this.redirectUri,
+            code_verifier: options.verifier,
+        });
+        return this.#alsSitzung(antwort, options.nonce);
+    }
+    /** Schritt 3: Ein abgelaufenes Zugriffstoken gegen ein frisches tauschen. */
+    async erneuern(refreshToken) {
+        const antwort = await this.#token({
+            grant_type: "refresh_token",
+            refresh_token: refreshToken,
+        });
+        return this.#alsSitzung(antwort);
+    }
+    /**
+     * Schritt 4: Abmelden — bei Aplons, nicht nur hier.
+     *
+     * Nur die eigene Sitzung zu löschen genügt nicht: die Sitzung bei Aplons
+     * bliebe bestehen, und die nächste Anmeldung liefe ohne Passwort durch.
+     * Auf einem geteilten Rechner ist das der Unterschied zwischen abgemeldet
+     * und scheinbar abgemeldet.
+     */
+    async abmeldeUrl(options) {
+        const metadaten = await this.metadaten();
+        const url = new URL(metadaten.end_session_endpoint);
+        url.searchParams.set("client_id", this.clientId);
+        if (options?.danach)
+            url.searchParams.set("post_logout_redirect_uri", options.danach);
+        if (options?.idToken)
+            url.searchParams.set("id_token_hint", options.idToken);
+        return url.toString();
+    }
+    /**
+     * Ein Zugriffstoken prüfen — für den, der eine eigene API dahinter hat.
+     *
+     * Geprüft wird gegen die öffentlichen Schlüssel von Aplons, ohne Rückfrage
+     * bei jedem Aufruf: Unterschrift, Aussteller und Ablauf. Das ist der
+     * Unterschied zwischen „das Token sieht echt aus" und „das Token ist echt".
+     */
+    async pruefeToken(token) {
+        const metadaten = await this.metadaten();
+        return pruefeZugriffstoken(token, {
+            issuer: metadaten.issuer,
+            schluessel: schluesselFuer(metadaten.jwks_uri),
+        });
+    }
+    /** Die Angaben zum angemeldeten Konto, so weit die Bereiche es hergeben. */
+    async profil(accessToken) {
+        const metadaten = await this.metadaten();
+        const antwort = await this.#fetch(metadaten.userinfo_endpoint, {
+            headers: { authorization: `Bearer ${accessToken}` },
+        });
+        if (!antwort.ok)
+            throw await ausAntwort(antwort, "Das Profil zu laden");
+        return (await antwort.json());
+    }
+    /**
+     * Ein Refresh-Token entwerten.
+     *
+     * Gehört zum Abmelden dazu: ein Token, das noch dreißig Tage gilt, wird
+     * vom Löschen des Cookies nicht ungültig.
+     */
+    async widerrufen(refreshToken) {
+        const metadaten = await this.metadaten();
+        const koerper = new URLSearchParams({
+            token: refreshToken,
+            token_type_hint: "refresh_token",
+            client_id: this.clientId,
+        });
+        if (this.#clientSecret)
+            koerper.set("client_secret", this.#clientSecret);
+        const antwort = await this.#fetch(metadaten.revocation_endpoint, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded" },
+            body: koerper,
+        });
+        // RFC 7009 verlangt 200 auch für ein Token, das es nie gab — damit
+        // niemand über den Statuscode herausfindet, welche Token gültig sind.
+        if (!antwort.ok)
+            throw await ausAntwort(antwort, "Das Token zu widerrufen");
+    }
+    async #token(felder) {
+        const metadaten = await this.metadaten();
+        const koerper = new URLSearchParams({ ...felder, client_id: this.clientId });
+        if (this.#clientSecret)
+            koerper.set("client_secret", this.#clientSecret);
+        const antwort = await this.#fetch(metadaten.token_endpoint, {
+            method: "POST",
+            headers: {
+                "content-type": "application/x-www-form-urlencoded",
+                accept: "application/json",
+            },
+            body: koerper,
+        });
+        if (!antwort.ok) {
+            const istErneuerung = felder.grant_type === "refresh_token";
+            throw await ausAntwort(antwort, istErneuerung ? "Das Erneuern der Anmeldung" : "Der Tausch des Anmeldecodes", istErneuerung ? "refresh" : "code");
+        }
+        return (await antwort.json());
+    }
+    async #alsSitzung(antwort, nonce) {
+        const metadaten = await this.metadaten();
+        const claims = antwort.id_token
+            ? await pruefeIdToken(antwort.id_token, {
+                issuer: metadaten.issuer,
+                audience: this.clientId,
+                nonce,
+                schluessel: schluesselFuer(metadaten.jwks_uri),
+            })
+            : undefined;
+        return {
+            accessToken: antwort.access_token,
+            refreshToken: antwort.refresh_token,
+            // Aus der Dauer sofort einen Zeitpunkt: eine Dauer ist ab dem Moment
+            // falsch, in dem man sie irgendwo ablegt.
+            accessTokenExpiresAt: new Date(Date.now() + antwort.expires_in * 1000),
+            idToken: antwort.id_token,
+            scope: antwort.scope ? antwort.scope.split(" ").filter(Boolean) : [],
+            claims,
+        };
+    }
+}

package/dist/discovery.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Wo bei Aplons was liegt — gefragt, nicht geraten.
+ *
+ * Die Endpunkte ließen sich auch fest eintragen; genau das ist in diesem
+ * Projekt schon schiefgegangen, als eine handgeschriebene Liste von Bereichen
+ * neben der echten herlief und Anwendungen die falschen anforderten. Wer
+ * fragt, bekommt immer die Antwort von heute.
+ */
+export type Metadaten = {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    userinfo_endpoint: string;
+    jwks_uri: string;
+    revocation_endpoint: string;
+    end_session_endpoint: string;
+    scopes_supported?: string[];
+    code_challenge_methods_supported?: string[];
+};
+export declare function holeMetadaten(issuer: string, fetchImpl: typeof globalThis.fetch): Promise<Metadaten>;

package/dist/discovery.js

@@ -0,0 +1,57 @@
+/**
+ * Wo bei Aplons was liegt — gefragt, nicht geraten.
+ *
+ * Die Endpunkte ließen sich auch fest eintragen; genau das ist in diesem
+ * Projekt schon schiefgegangen, als eine handgeschriebene Liste von Bereichen
+ * neben der echten herlief und Anwendungen die falschen anforderten. Wer
+ * fragt, bekommt immer die Antwort von heute.
+ */
+import { AplonsError, ausAntwort } from "./errors.js";
+const PFLICHT = [
+    "issuer",
+    "authorization_endpoint",
+    "token_endpoint",
+    "userinfo_endpoint",
+    "jwks_uri",
+];
+export async function holeMetadaten(issuer, fetchImpl) {
+    const url = `${issuer}/.well-known/openid-configuration`;
+    let antwort;
+    try {
+        antwort = await fetchImpl(url, { headers: { accept: "application/json" } });
+    }
+    catch (cause) {
+        throw new AplonsError({
+            code: "unreachable",
+            cause,
+            message: `${issuer} ist nicht erreichbar. Stimmt die Adresse, und kommt dieser ` +
+                "Server überhaupt ins Netz?",
+        });
+    }
+    if (!antwort.ok)
+        throw await ausAntwort(antwort, `${url} zu laden`);
+    const metadaten = (await antwort.json());
+    for (const feld of PFLICHT) {
+        if (!metadaten[feld]) {
+            throw new AplonsError({
+                code: "invalid_metadata",
+                message: `${url} enthält kein ${feld}. Ist das wirklich ein Aplons-Server?`,
+            });
+        }
+    }
+    /*
+      Der Aussteller muss zu der Adresse passen, unter der wir gefragt haben.
+  
+      Ohne diese Prüfung könnte ein untergeschobener Discovery-URL auf fremde
+      Endpunkte zeigen, und die Anwendung schickte ihre Anmeldungen dorthin.
+      RFC 8414 verlangt die Prüfung aus genau diesem Grund.
+    */
+    if (metadaten.issuer.replace(/\/+$/, "") !== issuer) {
+        throw new AplonsError({
+            code: "issuer_mismatch",
+            message: `Unter ${issuer} meldet sich ein Server, der sich „${metadaten.issuer}" ` +
+                "nennt. Das darf nicht sein — die Anmeldung wird nicht fortgesetzt.",
+        });
+    }
+    return metadaten;
+}

package/dist/errors.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Ein Fehler, der sagt, was zu tun ist.
+ *
+ * OAuth antwortet mit Kennungen wie `invalid_grant` — richtig für eine
+ * Maschine, nutzlos für den, der um drei Uhr nachts in ein Log sieht. Jeder
+ * Fehler hier trägt deshalb beides: die Kennung für den Code und einen Satz
+ * für den Menschen.
+ */
+export declare class AplonsError extends Error {
+    /** Die OAuth-Kennung, etwa `invalid_grant`. */
+    readonly code: string;
+    /** Der HTTP-Status, wenn der Fehler von einer Antwort kam. */
+    readonly status?: number;
+    /** Was der Server dazu geschrieben hat. */
+    readonly description?: string;
+    constructor(options: {
+        code: string;
+        message: string;
+        status?: number;
+        description?: string;
+        cause?: unknown;
+    });
+}
+/** Welcher Ablauf gerade fehlgeschlagen ist. */
+export type Ablauf = "code" | "refresh" | "allgemein";
+/** Aus einer fehlgeschlagenen Antwort einen brauchbaren Fehler machen. */
+export declare function ausAntwort(antwort: Response, wobei: string, ablauf?: Ablauf): Promise<AplonsError>;