@aplons/auth 0.1.0 → 0.2.0

package/dist/client.js

@@ -1,19 +1,18 @@
 /**
- * Die Anbindung an Aplons.
+ * The connection to 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.
+ * Four steps, no more: start the login, complete it, refresh the tokens, log
+ * out. Plus verifying a token, for whoever has an API behind it.
  *
- * 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.
+ * Everything else the flow needs — which endpoint lives where, which keys are
+ * currently valid — the package fetches itself. If you know `issuer` and
+ * `clientId`, you are done.
  */
-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"];
+import { AplonsError, fromResponse } from "./errors.js";
+import { createChallenge, createState, createVerifier, timingSafeEqual } from "./pkce.js";
+import { fetchMetadata } from "./discovery.js";
+import { jwksFor, verifyAccessToken, verifyIdToken } from "./verify.js";
+const DEFAULT_SCOPE = ["openid", "profile", "email"];
 export class AplonsAuth {
     issuer;
     clientId;
@@ -21,46 +20,48 @@ export class AplonsAuth {
     scope;
     #clientSecret;
     #fetch;
-    #metadaten;
+    #metadata;
     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.issuer) {
+            throw new AplonsError({ code: "config", message: "issuer is missing." });
+        }
+        if (!options.clientId) {
+            throw new AplonsError({ code: "config", message: "clientId is missing." });
+        }
         if (!options.redirectUri) {
-            throw new AplonsError({ code: "config", message: "redirectUri fehlt." });
+            throw new AplonsError({ code: "config", message: "redirectUri is missing." });
         }
-        // Ein Schrägstrich am Ende erzeugt sonst `https://auth.example.com//oauth/…`.
+        // A trailing slash would otherwise produce `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.scope = options.scope ?? DEFAULT_SCOPE;
         this.#clientSecret = options.clientSecret;
         this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
     }
     /**
-     * Die Endpunkte, einmal geholt und dann behalten.
+     * The endpoints, fetched once and then kept.
      *
-     * Als Versprechen zwischengespeichert, nicht als Ergebnis: sonst holen
-     * zehn gleichzeitige Anfragen beim Start zehnmal dieselbe Datei.
+     * Cached as a promise, not as a result: otherwise ten concurrent requests
+     * at startup fetch the same document ten times.
      */
-    metadaten() {
-        this.#metadaten ??= holeMetadaten(this.issuer, this.#fetch);
-        return this.#metadaten;
+    metadata() {
+        this.#metadata ??= fetchMetadata(this.issuer, this.#fetch);
+        return this.#metadata;
     }
     /**
-     * Schritt 1: Wohin der Browser geschickt wird.
+     * Step 1: where to send the browser.
      *
-     * `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.
+     * `verifier`, `state` and `nonce` have to survive until the callback — in a
+     * short-lived, `httpOnly` cookie, not in localStorage: whatever sits there
+     * is readable by every script on the page.
      */
-    async start(options) {
-        const metadaten = await this.metadaten();
+    async startLogin(options) {
+        const metadata = await this.metadata();
         const verifier = createVerifier();
         const state = createState();
         const nonce = createState();
-        const url = new URL(metadaten.authorization_endpoint);
+        const url = new URL(metadata.authorization_endpoint);
         url.searchParams.set("response_type", "code");
         url.searchParams.set("client_id", this.clientId);
         url.searchParams.set("redirect_uri", this.redirectUri);
@@ -68,31 +69,31 @@ export class AplonsAuth {
         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.
+        // S256 or nothing: "plain" puts the verifier in the same URL as the code
+        // and therefore protects against nothing.
         url.searchParams.set("code_challenge_method", "S256");
-        if (options?.erneutAnmelden)
+        if (options?.forceLogin)
             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);
+        for (const [name, value] of Object.entries(options?.extraParams ?? {})) {
+            url.searchParams.set(name, value);
         }
         return { url: url.toString(), verifier, state, nonce };
     }
     /**
-     * Schritt 2: Die Rückkehr.
+     * Step 2: the callback.
      *
-     * Nimmt den vollständigen URL entgegen, mit dem der Browser zurückkam, und
-     * die beiden Werte aus Schritt 1.
+     * Takes the full URL the browser came back with, plus the values from
+     * step 1.
      */
-    async rueckkehr(options) {
+    async completeLogin(options) {
         const url = typeof options.url === "string" ? new URL(options.url) : options.url;
-        const fehler = url.searchParams.get("error");
-        if (fehler) {
+        const error = url.searchParams.get("error");
+        if (error) {
             throw new AplonsError({
-                code: fehler,
-                message: `Die Anmeldung wurde abgebrochen (${fehler}).` +
+                code: error,
+                message: `The login was cancelled (${error}).` +
                     (url.searchParams.get("error_description")
                         ? ` ${url.searchParams.get("error_description")}`
                         : ""),
@@ -101,148 +102,196 @@ export class AplonsAuth {
         const state = url.searchParams.get("state");
         const code = url.searchParams.get("code");
         /*
-          Der State wird geprüft, bevor irgendetwas mit dem Code geschieht.
+          The state is checked before anything happens with the code.
     
-          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.
+          Without this check someone could start a login with their own 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.
         */
-        if (!state || !gleich(state, options.state)) {
+        if (!state || !timingSafeEqual(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.",
+                message: "The state does not match. Either the login is too old, or the " +
+                    "request did not come from the login this application started.",
             });
         }
         if (!code) {
             throw new AplonsError({
                 code: "missing_code",
-                message: "Im Rückkehr-URL steht kein code.",
+                message: "There is no code in the callback URL.",
             });
         }
-        const antwort = await this.#token({
+        const response = await this.#tokenRequest({
             grant_type: "authorization_code",
             code,
             redirect_uri: this.redirectUri,
             code_verifier: options.verifier,
         });
-        return this.#alsSitzung(antwort, options.nonce);
+        return this.#toSession(response, options.nonce);
     }
-    /** Schritt 3: Ein abgelaufenes Zugriffstoken gegen ein frisches tauschen. */
-    async erneuern(refreshToken) {
-        const antwort = await this.#token({
+    /** Step 3: trade an expired access token for a fresh one. */
+    async refresh(refreshToken) {
+        const response = await this.#tokenRequest({
             grant_type: "refresh_token",
             refresh_token: refreshToken,
         });
-        return this.#alsSitzung(antwort);
+        return this.#toSession(response);
     }
     /**
-     * Schritt 4: Abmelden — bei Aplons, nicht nur hier.
+     * Step 4: log out — at Aplons, not just here.
      *
-     * 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.
+     * Clearing your own session is not enough: the session at Aplons would
+     * survive, and the next login would sail through without a password. On a
+     * shared machine that is the difference between signed out and apparently
+     * signed out.
      */
-    async abmeldeUrl(options) {
-        const metadaten = await this.metadaten();
-        const url = new URL(metadaten.end_session_endpoint);
+    async logoutUrl(options) {
+        const metadata = await this.metadata();
+        const url = new URL(required(metadata.end_session_endpoint, "end_session_endpoint", "Logging out"));
         url.searchParams.set("client_id", this.clientId);
-        if (options?.danach)
-            url.searchParams.set("post_logout_redirect_uri", options.danach);
+        if (options?.returnTo) {
+            url.searchParams.set("post_logout_redirect_uri", options.returnTo);
+        }
         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.
+     * Verify an access token — for whoever has their own API behind it.
      *
-     * 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".
+     * Checked against the public keys of Aplons, without a round trip on every
+     * call: signature, issuer and expiry. That is the difference between "the
+     * token looks real" and "the token is real".
      */
-    async pruefeToken(token) {
-        const metadaten = await this.metadaten();
-        return pruefeZugriffstoken(token, {
-            issuer: metadaten.issuer,
-            schluessel: schluesselFuer(metadaten.jwks_uri),
+    async verifyAccessToken(token) {
+        const metadata = await this.metadata();
+        return verifyAccessToken(token, {
+            issuer: metadata.issuer,
+            keys: jwksFor(metadata.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, {
+    /**
+     * Das Erscheinungsbild des Mandanten — Logo, Farben, Eckenradius.
+     *
+     * Ein Aufruf, damit eine eingebundene Oberfläche aussieht wie die Firma,
+     * für die sie gebaut ist, statt deren Logo ein zweites Mal zu pflegen:
+     *
+     *   const branding = await auth.branding(session.accessToken);
+     *
+     * Welcher Mandant, steht im Token — nicht im Aufruf. Ein Konto bekommt
+     * damit immer genau das Erscheinungsbild, das es auf der Anmeldeseite auch
+     * gesehen hat.
+     *
+     * Es lohnt sich, das Ergebnis zwischenzuspeichern: ein Logo wechselt selten,
+     * und eine Seite, die es bei jedem Aufruf neu holt, wartet dafür jedes Mal
+     * auf eine Antwort aus dem Netz.
+     *
+     * Zwei Absagen sind möglich und meinen Verschiedenes: `insufficient_scope`
+     * heißt, das Token trägt den Bereich `branding` nicht — dann fehlt er in den
+     * `scope`s dieser Anwendung. `branding_not_shared` heißt, der Mandant gibt
+     * sein Erscheinungsbild nicht heraus; das steht in seinen Richtlinien und
+     * ist ab Werk aus.
+     */
+    async branding(accessToken) {
+        const metadata = await this.metadata();
+        const response = await this.#fetch(
+        // Ältere Server kennen den Eintrag im Discovery-Dokument noch nicht.
+        // Die Adresse selbst gibt es dort aber schon, deshalb der Rückfall statt
+        // einer Fehlermeldung, die niemandem hilft.
+        metadata.branding_endpoint ?? `${this.issuer}/api/oauth/branding`, { headers: { authorization: `Bearer ${accessToken}` } });
+        if (!response.ok)
+            throw await fromResponse(response, "Loading the branding");
+        return (await response.json());
+    }
+    /** The details of the signed-in account, as far as the scopes allow. */
+    async userInfo(accessToken) {
+        const metadata = await this.metadata();
+        const response = await this.#fetch(metadata.userinfo_endpoint, {
             headers: { authorization: `Bearer ${accessToken}` },
         });
-        if (!antwort.ok)
-            throw await ausAntwort(antwort, "Das Profil zu laden");
-        return (await antwort.json());
+        if (!response.ok)
+            throw await fromResponse(response, "Loading the profile");
+        return (await response.json());
     }
     /**
-     * Ein Refresh-Token entwerten.
+     * Revoke a refresh token.
      *
-     * Gehört zum Abmelden dazu: ein Token, das noch dreißig Tage gilt, wird
-     * vom Löschen des Cookies nicht ungültig.
+     * Part of logging out: a token still valid for thirty days does not become
+     * invalid because a cookie was deleted.
      */
-    async widerrufen(refreshToken) {
-        const metadaten = await this.metadaten();
-        const koerper = new URLSearchParams({
+    async revoke(refreshToken) {
+        const metadata = await this.metadata();
+        const body = 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, {
+            body.set("client_secret", this.#clientSecret);
+        const response = await this.#fetch(required(metadata.revocation_endpoint, "revocation_endpoint", "Revoking the token"), {
             method: "POST",
             headers: { "content-type": "application/x-www-form-urlencoded" },
-            body: koerper,
+            body,
         });
-        // 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");
+        // RFC 7009 demands 200 even for a token that never existed — so nobody
+        // can find out from the status code which tokens are valid.
+        if (!response.ok)
+            throw await fromResponse(response, "Revoking the token");
     }
-    async #token(felder) {
-        const metadaten = await this.metadaten();
-        const koerper = new URLSearchParams({ ...felder, client_id: this.clientId });
+    async #tokenRequest(fields) {
+        const metadata = await this.metadata();
+        const body = new URLSearchParams({ ...fields, client_id: this.clientId });
         if (this.#clientSecret)
-            koerper.set("client_secret", this.#clientSecret);
-        const antwort = await this.#fetch(metadaten.token_endpoint, {
+            body.set("client_secret", this.#clientSecret);
+        const response = await this.#fetch(metadata.token_endpoint, {
             method: "POST",
             headers: {
                 "content-type": "application/x-www-form-urlencoded",
                 accept: "application/json",
             },
-            body: koerper,
+            body,
         });
-        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");
+        if (!response.ok) {
+            const isRefresh = fields.grant_type === "refresh_token";
+            throw await fromResponse(response, isRefresh ? "Refreshing the session" : "Exchanging the authorization code", isRefresh ? "refresh" : "code");
         }
-        return (await antwort.json());
+        return (await response.json());
     }
-    async #alsSitzung(antwort, nonce) {
-        const metadaten = await this.metadaten();
-        const claims = antwort.id_token
-            ? await pruefeIdToken(antwort.id_token, {
-                issuer: metadaten.issuer,
+    async #toSession(response, nonce) {
+        const metadata = await this.metadata();
+        const claims = response.id_token
+            ? await verifyIdToken(response.id_token, {
+                issuer: metadata.issuer,
                 audience: this.clientId,
                 nonce,
-                schluessel: schluesselFuer(metadaten.jwks_uri),
+                keys: jwksFor(metadata.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) : [],
+            accessToken: response.access_token,
+            refreshToken: response.refresh_token,
+            // Turn the duration into a point in time right away: a duration is
+            // wrong the moment you store it somewhere.
+            accessTokenExpiresAt: new Date(Date.now() + response.expires_in * 1000),
+            idToken: response.id_token,
+            scope: response.scope ? response.scope.split(" ").filter(Boolean) : [],
             claims,
         };
     }
 }
+/**
+ * Einen Eintrag aus dem Discovery-Dokument holen, den dieser Aufruf braucht.
+ *
+ * Fehlt er, sagt der Fehler *welcher* und *wofür* — statt eines nackten
+ * „Invalid URL" aus dem URL-Konstruktor, das beides verschweigt.
+ */
+function required(value, field, what) {
+    if (!value) {
+        throw new AplonsError({
+            code: "invalid_metadata",
+            message: `${what} is not possible: the server does not list a ${field} in ` +
+                "its /.well-known/openid-configuration.",
+        });
+    }
+    return value;
+}

package/dist/discovery.d.ts

@@ -1,20 +1,22 @@
 /**
- * Wo bei Aplons was liegt — gefragt, nicht geraten.
+ * Where things live at Aplons — asked for, not guessed.
  *
- * 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.
+ * The endpoints could be hard-coded; that is exactly what went wrong in this
+ * project once already, when a hand-written list of scopes drifted away from
+ * the real one and applications requested the wrong things. Whoever asks
+ * gets today's answer.
  */
-export type Metadaten = {
+export type Metadata = {
     issuer: string;
     authorization_endpoint: string;
     token_endpoint: string;
     userinfo_endpoint: string;
     jwks_uri: string;
-    revocation_endpoint: string;
-    end_session_endpoint: string;
+    revocation_endpoint?: string;
+    end_session_endpoint?: string;
+    /** Das Erscheinungsbild des Mandanten. Eigene Zutat, kein OpenID Connect. */
+    branding_endpoint?: string;
     scopes_supported?: string[];
     code_challenge_methods_supported?: string[];
 };
-export declare function holeMetadaten(issuer: string, fetchImpl: typeof globalThis.fetch): Promise<Metadaten>;
+export declare function fetchMetadata(issuer: string, fetchImpl: typeof globalThis.fetch): Promise<Metadata>;

package/dist/discovery.js

@@ -1,57 +1,57 @@
 /**
- * Wo bei Aplons was liegt — gefragt, nicht geraten.
+ * Where things live at Aplons — asked for, not guessed.
  *
- * 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.
+ * The endpoints could be hard-coded; that is exactly what went wrong in this
+ * project once already, when a hand-written list of scopes drifted away from
+ * the real one and applications requested the wrong things. Whoever asks
+ * gets today's answer.
  */
-import { AplonsError, ausAntwort } from "./errors.js";
-const PFLICHT = [
+import { AplonsError, fromResponse } from "./errors.js";
+const REQUIRED = [
     "issuer",
     "authorization_endpoint",
     "token_endpoint",
     "userinfo_endpoint",
     "jwks_uri",
 ];
-export async function holeMetadaten(issuer, fetchImpl) {
+export async function fetchMetadata(issuer, fetchImpl) {
     const url = `${issuer}/.well-known/openid-configuration`;
-    let antwort;
+    let response;
     try {
-        antwort = await fetchImpl(url, { headers: { accept: "application/json" } });
+        response = 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?",
+            message: `${issuer} is not reachable. Is the address right, and can this ` +
+                "server reach the network at all?",
         });
     }
-    if (!antwort.ok)
-        throw await ausAntwort(antwort, `${url} zu laden`);
-    const metadaten = (await antwort.json());
-    for (const feld of PFLICHT) {
-        if (!metadaten[feld]) {
+    if (!response.ok)
+        throw await fromResponse(response, `Loading ${url}`);
+    const metadata = (await response.json());
+    for (const field of REQUIRED) {
+        if (!metadata[field]) {
             throw new AplonsError({
                 code: "invalid_metadata",
-                message: `${url} enthält kein ${feld}. Ist das wirklich ein Aplons-Server?`,
+                message: `${url} contains no ${field}. Is this really an Aplons server?`,
             });
         }
     }
     /*
-      Der Aussteller muss zu der Adresse passen, unter der wir gefragt haben.
+      The issuer has to match the address we asked at.
   
-      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.
+      Without this check a planted discovery URL could point at foreign
+      endpoints, and the application would send its logins there. RFC 8414
+      requires the check for exactly this reason.
     */
-    if (metadaten.issuer.replace(/\/+$/, "") !== issuer) {
+    if (metadata.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.",
+            message: `The server at ${issuer} calls itself "${metadata.issuer}". That must ` +
+                "not happen — the login will not continue.",
         });
     }
-    return metadaten;
+    return metadata;
 }

package/dist/errors.d.ts

@@ -1,17 +1,17 @@
 /**
- * Ein Fehler, der sagt, was zu tun ist.
+ * An error that says what to do about it.
  *
- * 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.
+ * OAuth answers with identifiers like `invalid_grant` — right for a machine,
+ * useless for the person reading a log at three in the morning. Every error
+ * here carries both: the identifier for the code and a sentence for the
+ * human.
  */
 export declare class AplonsError extends Error {
-    /** Die OAuth-Kennung, etwa `invalid_grant`. */
+    /** The OAuth identifier, e.g. `invalid_grant`. */
     readonly code: string;
-    /** Der HTTP-Status, wenn der Fehler von einer Antwort kam. */
+    /** The HTTP status, when the error came from a response. */
     readonly status?: number;
-    /** Was der Server dazu geschrieben hat. */
+    /** What the server wrote about it. */
     readonly description?: string;
     constructor(options: {
         code: string;
@@ -21,7 +21,7 @@ export declare class AplonsError extends Error {
         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>;
+/** Which flow just failed. */
+export type Flow = "code" | "refresh" | "generic";
+/** Turn a failed response into something usable. */
+export declare function fromResponse(response: Response, what: string, flow?: Flow): Promise<AplonsError>;