@aplons/auth 0.1.0 → 0.2.0

package/dist/next.js

@@ -1,262 +1,362 @@
 /**
- * @aplons/auth/next — der Teil, den man sonst jedes Mal neu schreibt.
+ * @aplons/auth/next — the part you would otherwise write from scratch every
+ * time.
  *
- * Der Kern kennt keine Cookies; er weiß nichts davon, wo `verifier` und
- * `state` zwischen zwei Aufrufen liegen. Genau dort steckt aber die Arbeit,
- * und genau dort werden die Fehler gemacht: der Verifier im localStorage
- * (jedes Skript auf der Seite liest ihn), der State ohne `httpOnly`, ein
- * Cookie ohne `secure`, das über einen offenen Hotspot geht.
+ * The core knows nothing about cookies; it has no idea where `verifier` and
+ * `state` live between two requests. But that is exactly where the work is,
+ * and exactly where the mistakes get made: the verifier in localStorage
+ * (every script on the page reads it), the state without `httpOnly`, a
+ * cookie without `secure` travelling over an open hotspot.
  *
- * Hier passiert das einmal richtig:
+ * Here that happens once, correctly:
  *
  *   app/api/auth/[...aplons]/route.ts
  *   ------------------------------------------------------------------
- *   import { handhabe } from "@aplons/auth/next";
+ *   import { createHandler } from "@aplons/auth/next";
  *
- *   export const { GET, POST } = handhabe({
+ *   export const { GET, POST } = createHandler({
  *     issuer: process.env.APLONS_ISSUER!,
  *     clientId: process.env.APLONS_CLIENT_ID!,
  *     clientSecret: process.env.APLONS_CLIENT_SECRET,
  *     redirectUri: process.env.APLONS_REDIRECT_URI!,
  *   });
  *
- * Das ergibt vier Adressen: /api/auth/login, /callback, /logout, /me.
+ * That yields four routes: /api/auth/login, /callback, /logout, /me.
  *
- * Next.js ist eine Peer-Abhängigkeit und wird hier absichtlich nicht
- * importiert — dieses Modul kommt mit `Request` und `Response` aus, und die
- * gibt es überall. So lässt es sich auch woanders verwenden, und wer nur den
- * Kern will, zieht sich Next nicht mit ein.
+ * Next.js is a peer dependency and is deliberately not imported here — this
+ * module gets by with `Request` and `Response`, which exist everywhere. That
+ * makes it usable elsewhere too, and whoever only wants the core does not
+ * pull Next in with it.
  */
 import { AplonsAuth } from "./client.js";
 import { AplonsError } from "./errors.js";
-const VORGANG_COOKIE = "aplons_vorgang";
+const TRANSACTION_COOKIE = "aplons_tx";
 /**
- * Die vier Adressen.
+ * The four routes.
  *
- * Zurückgegeben als `{ GET, POST }`, weil der App Router genau das erwartet.
+ * Returned as `{ GET, POST }`, because that is what the App Router expects.
  */
-export function handhabe(options) {
+export function createHandler(options) {
     const auth = new AplonsAuth(options);
-    const basePath = options.basePath ?? ableitenBasePath(options.redirectUri);
+    const basePath = options.basePath ?? deriveBasePath(options.redirectUri);
     const cookieName = options.cookieName ?? "aplons_session";
     async function GET(request) {
         const url = new URL(request.url);
-        const aktion = url.pathname.slice(basePath.length).replace(/^\/+/, "");
+        const action = url.pathname.slice(basePath.length).replace(/^\/+/, "");
         /*
-          Kein Fehler verlässt diese Funktion.
+          No error leaves this function.
     
-          Ein Wurf hier landet sonst als unbehandelte Ablehnung im Prozess der
-          Kundenanwendung — beim Ausprobieren hat das den Testserver schlicht
-          beendet, ohne dass irgendwo stand, warum. Ein Anmeldeknopf, der die
-          Anwendung abschießt, ist das Gegenteil von dem, was ein Paket abnehmen
-          soll. Die Meldung von AplonsError sagt bereits, was zu tun ist; sie
-          kommt hier heraus statt in einem Stapelabzug.
+          A throw here would otherwise land as an unhandled rejection in the
+          customer's process — while testing, that simply killed the server with
+          nothing anywhere saying why. A login button that takes down the
+          application is the opposite of what a package is supposed to save you.
+          The message on AplonsError already says what to do; it comes out here
+          instead of in a stack trace.
         */
         try {
-            switch (aktion) {
+            switch (action) {
                 case "login":
-                    return await anmelden(request, url);
+                    return await login(request, url);
                 case "callback":
-                    return await rueckkehr(request, url);
+                    return await callback(request, url);
                 case "logout":
-                    return await abmelden(request);
+                    return await logout(request);
                 case "me":
-                    return await wer(request);
+                    return await me(request);
+                case "branding":
+                    return await branding(request);
                 default:
                     return json({ error: "not_found" }, 404);
             }
         }
-        catch (fehler) {
-            if (fehler instanceof AplonsError) {
-                return json({ error: fehler.code, message: fehler.message }, 500);
+        catch (error) {
+            if (error instanceof AplonsError) {
+                return json({ error: error.code, message: error.message }, 500);
             }
-            // Etwas Unerwartetes: die Meldung geht ins Log des Servers, nicht in
-            // die Antwort — dort könnte sie interne Pfade preisgeben.
-            console.error("[@aplons/auth]", fehler);
+            // Something unexpected: the message goes to the server log, not into
+            // the response — there it could give away internal paths.
+            console.error("[@aplons/auth]", error);
             return json({
-                error: "unerwartet",
-                message: "Bei der Anmeldung ist etwas schiefgegangen. Siehe Serverlog.",
+                error: "unexpected",
+                message: "Something went wrong during login. See the server log.",
             }, 500);
         }
     }
-    async function anmelden(request, url) {
-        const vorgang = await auth.start({
+    async function login(request, url) {
+        const authorization = await auth.startLogin({
             tenant: url.searchParams.get("tenant") ?? undefined,
-            erneutAnmelden: url.searchParams.get("prompt") === "login",
+            forceLogin: url.searchParams.get("prompt") === "login",
         });
-        const antwort = weiter(vorgang.url);
+        const response = redirect(authorization.url);
         /*
-          Verifier, State und Nonce zusammen in ein kurzlebiges Cookie.
+          Verifier, state and nonce together in one short-lived cookie.
     
-          httpOnly, damit kein Skript sie liest; sameSite=lax, weil die Rückkehr
-          von Aplons eine Navigation von außen ist und ein `strict`-Cookie dabei
-          nicht mitgeschickt würde — der Vorgang bräche dann ausgerechnet im
-          letzten Schritt ab. Zehn Minuten: so lange braucht niemand für eine
-          Anmeldung, und was länger offen liegt, ist eher vergessen als in Arbeit.
+          httpOnly so no script reads them; sameSite=lax because the return from
+          Aplons is a cross-site navigation and a `strict` cookie would not be
+          sent along with it — the flow would then break at the very last step.
+          Ten minutes: nobody needs longer for a login, and whatever sits open
+          longer is forgotten rather than in progress.
         */
-        setzeCookie(antwort, VORGANG_COOKIE, JSON.stringify({
-            v: vorgang.verifier,
-            s: vorgang.state,
-            n: vorgang.nonce,
-            z: url.searchParams.get("weiter") ?? options.nachAnmeldung ?? "/",
-        }), { maxAge: 600, sicher: istHttps(url) });
-        return antwort;
+        setCookie(response, TRANSACTION_COOKIE, JSON.stringify({
+            v: authorization.verifier,
+            s: authorization.state,
+            n: authorization.nonce,
+            next: url.searchParams.get("next") ?? options.afterLogin ?? "/",
+        }), { maxAge: 600, secure: isHttps(url) });
+        return response;
     }
-    async function rueckkehr(request, url) {
-        const roh = liesCookie(request, VORGANG_COOKIE);
-        if (!roh) {
-            return fehlerSeite("Der Anmeldevorgang ist nicht mehr da. Das passiert, wenn die " +
-                "Anmeldung länger als zehn Minuten offen lag oder in einem anderen " +
-                "Browser begonnen wurde. Fang noch einmal an.");
+    async function callback(request, url) {
+        const raw = readCookie(request, TRANSACTION_COOKIE);
+        if (!raw) {
+            return errorResponse("The login is gone. That happens when it sat open for more than ten " +
+                "minutes, or was started in a different browser. Start again.");
         }
-        let vorgang;
+        let transaction;
         try {
-            vorgang = JSON.parse(roh);
+            transaction = JSON.parse(raw);
         }
         catch {
-            return fehlerSeite("Der Anmeldevorgang ist unlesbar. Fang noch einmal an.");
+            return errorResponse("The login is unreadable. Start again.");
         }
-        let sitzung;
+        let session;
         try {
-            sitzung = await auth.rueckkehr({
+            session = await auth.completeLogin({
                 url,
-                verifier: vorgang.v,
-                state: vorgang.s,
-                nonce: vorgang.n,
+                verifier: transaction.v,
+                state: transaction.s,
+                nonce: transaction.n,
             });
         }
-        catch (fehler) {
-            return fehlerSeite(fehler instanceof AplonsError ? fehler.message : "Die Anmeldung ist fehlgeschlagen.");
+        catch (error) {
+            return errorResponse(error instanceof AplonsError ? error.message : "The login failed.");
         }
-        // Nur relative Ziele: ein „weiter"-Parameter, der auf eine fremde Adresse
-        // zeigt, macht aus der eigenen Anmeldung eine Weiterleitung für andere.
-        const ziel = vorgang.z.startsWith("/") && !vorgang.z.startsWith("//") ? vorgang.z : "/";
-        const antwort = weiter(new URL(ziel, url).toString());
-        // Der Vorgang ist erledigt; sein Cookie hat nichts mehr zu suchen.
-        loescheCookie(antwort, VORGANG_COOKIE, istHttps(url));
-        await legeSitzungAb(antwort, sitzung, istHttps(url));
-        return antwort;
+        // Relative targets only: a `next` parameter pointing at a foreign address
+        // would turn your own login into an open redirect for someone else.
+        const target = transaction.next.startsWith("/") && !transaction.next.startsWith("//")
+            ? transaction.next
+            : "/";
+        const response = redirect(new URL(target, url).toString());
+        // The login is done; its cookie has no business sticking around.
+        clearCookie(response, TRANSACTION_COOKIE, isHttps(url));
+        await write(response, session, null, isHttps(url));
+        return response;
     }
-    async function abmelden(request) {
-        const sitzung = await holeSitzung(request);
+    async function logout(request) {
+        const stored = await readEntry(request);
+        const session = stored?.session ?? null;
         const url = new URL(request.url);
-        if (sitzung?.refreshToken) {
-            // Das Refresh-Token gilt dreißig Tage weiter, wenn es niemand
-            // entwertet — ein gelöschtes Cookie beeindruckt es nicht.
-            await auth.widerrufen(sitzung.refreshToken).catch(() => undefined);
+        if (session?.refreshToken) {
+            // The refresh token stays valid for thirty days unless somebody
+            // revokes it — a deleted cookie does not impress it.
+            await auth.revoke(session.refreshToken).catch(() => undefined);
         }
-        const abmeldeUrl = await auth.abmeldeUrl({
-            danach: options.nachAbmeldung
-                ? new URL(options.nachAbmeldung, url).toString()
+        /*
+          Und aus der eigenen Ablage heraus.
+    
+          Das Cookie zu löschen nahm dem Browser nur den Schlüssel; der Eintrag
+          selbst — mitsamt Refresh-Token — blieb in der Datenbank liegen, für
+          jede Anmeldung eines jeden Kontos einer. `store.delete` stand in der
+          Beschreibung des Typs und wurde nirgends aufgerufen: wer die eigene
+          Ablage einbaute, sammelte abgemeldete Sitzungen, bis jemand nachsah.
+        */
+        if (options.store && stored?.id) {
+            await options.store.delete(stored.id).catch(() => undefined);
+        }
+        const target = await auth.logoutUrl({
+            returnTo: options.afterLogout
+                ? new URL(options.afterLogout, url).toString()
                 : undefined,
-            idToken: sitzung?.idToken,
+            idToken: session?.idToken,
         });
-        const antwort = weiter(abmeldeUrl);
-        loescheCookie(antwort, cookieName, istHttps(url));
-        if (options.speicher)
-            loescheCookie(antwort, cookieName + "_id", istHttps(url));
-        return antwort;
+        const response = redirect(target);
+        clearCookie(response, cookieName, isHttps(url));
+        if (options.store)
+            clearCookie(response, cookieName + "_id", isHttps(url));
+        return response;
     }
-    async function wer(request) {
-        const sitzung = await holeSitzung(request);
-        if (!sitzung)
-            return json({ angemeldet: false }, 401);
-        // Abgelaufen? Dann still erneuern, statt den Aufrufer abzuweisen.
-        if (sitzung.accessTokenExpiresAt.getTime() < Date.now() && sitzung.refreshToken) {
-            try {
-                const frisch = await auth.erneuern(sitzung.refreshToken);
-                const antwort = json({ angemeldet: true, konto: frisch.claims ?? null });
-                await legeSitzungAb(antwort, frisch, istHttps(new URL(request.url)));
-                return antwort;
-            }
-            catch {
-                return json({ angemeldet: false }, 401);
-            }
+    async function me(request) {
+        const state = await current(request);
+        if (!state)
+            return json({ authenticated: false }, 401);
+        return respond(json({ authenticated: true, account: state.session.claims ?? null }), state, request);
+    }
+    /**
+     * Das Erscheinungsbild des Mandanten, für die eigene Oberfläche.
+     *
+     * Braucht den Bereich `branding` in `scope` und einen Mandanten, der das
+     * Weitergeben in seinen Richtlinien erlaubt hat — sonst kommt die Absage von
+     * Aplons hier unverändert wieder heraus, damit die Ursache erkennbar bleibt
+     * statt als „irgendwas mit 500" zu enden.
+     */
+    async function branding(request) {
+        const state = await current(request);
+        if (!state)
+            return json({ error: "not_authenticated" }, 401);
+        let payload;
+        try {
+            payload = json(await auth.branding(state.session.accessToken));
+        }
+        catch (error) {
+            if (!(error instanceof AplonsError))
+                throw error;
+            payload = json({ error: error.code, message: error.message }, error.status ?? 500);
         }
-        return json({ angemeldet: true, konto: sitzung.claims ?? null });
+        return respond(payload, state, request);
     }
-    async function holeSitzung(request) {
-        if (options.speicher) {
-            const id = liesCookie(request, cookieName + "_id");
-            return id ? options.speicher.lies(id) : null;
+    /**
+     * Die Sitzung, wie sie *jetzt* gilt.
+     *
+     * Ist das Zugriffstoken abgelaufen, wird still erneuert. Ob das passiert
+     * ist, steht im Ergebnis: die erneuerte Sitzung muss in die Antwort dieses
+     * einen Aufrufs geschrieben werden, und nur der Aufrufer hält sie in der
+     * Hand.
+     */
+    async function current(request) {
+        const stored = await readEntry(request);
+        if (!stored)
+            return null;
+        const { session, id } = stored;
+        if (session.accessTokenExpiresAt.getTime() >= Date.now() ||
+            !session.refreshToken) {
+            return { session, id, refreshed: false };
         }
-        const roh = liesCookie(request, cookieName);
-        if (!roh)
+        try {
+            return { session: await auth.refresh(session.refreshToken), id, refreshed: true };
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Eine Antwort, die eine unterwegs erneuerte Sitzung mitnimmt. */
+    async function respond(response, state, request) {
+        if (state.refreshed) {
+            await write(response, state.session, state.id, isHttps(new URL(request.url)));
+        }
+        return response;
+    }
+    async function readEntry(request) {
+        if (options.store) {
+            const id = readCookie(request, cookieName + "_id");
+            if (!id)
+                return null;
+            const session = await options.store.read(id);
+            return session ? { id, session: withDate(session) } : null;
+        }
+        const raw = readCookie(request, cookieName);
+        if (!raw)
             return null;
         try {
-            const daten = JSON.parse(roh);
-            return { ...daten, accessTokenExpiresAt: new Date(daten.accessTokenExpiresAt) };
+            return { id: null, session: withDate(JSON.parse(raw)) };
         }
         catch {
             return null;
         }
     }
-    async function legeSitzungAb(antwort, sitzung, sicher) {
-        if (options.speicher) {
-            const id = crypto.randomUUID();
-            await options.speicher.schreib(id, sitzung);
-            setzeCookie(antwort, cookieName + "_id", id, { maxAge: 2592000, sicher });
+    async function readSession(request) {
+        return (await readEntry(request))?.session ?? null;
+    }
+    /**
+     * Die Sitzung in die Antwort schreiben — und in die eigene Ablage.
+     *
+     * `id` ist die Kennung, unter der sie dort schon liegt, oder `null` für eine
+     * neue Anmeldung. Sie wiederzuverwenden ist der Unterschied zwischen einer
+     * Zeile pro Sitzung und einer pro Erneuerung: erneuert wird alle zehn
+     * Minuten, und der alte Eintrag verschwand dabei nicht, sondern wurde nur
+     * unerreichbar.
+     */
+    async function write(response, session, id, secure) {
+        if (options.store) {
+            const key = id ?? crypto.randomUUID();
+            await options.store.write(key, session);
+            setCookie(response, cookieName + "_id", key, { maxAge: 2592000, secure });
             return;
         }
-        setzeCookie(antwort, cookieName, JSON.stringify(sitzung), {
+        setCookie(response, cookieName, JSON.stringify(session), {
             maxAge: 2592000,
-            sicher,
+            secure,
         });
     }
-    /** Die Sitzung aus einer eigenen Route heraus lesen. */
-    async function sitzungAus(request) {
-        return holeSitzung(request);
+    /**
+     * Read the session from one of your own routes.
+     *
+     * Erneuert nicht: eine eigene Route kann kein Cookie mitschicken, das sie
+     * nicht selbst schreibt. Wer sicher ein gültiges Token braucht, ruft `/me`
+     * auf oder erneuert selbst über `auth.refresh`.
+     */
+    async function getSession(request) {
+        return readSession(request);
+    }
+    /** Das Erscheinungsbild, aus einer eigenen Route heraus. */
+    async function getBranding(request) {
+        const session = await readSession(request);
+        return session ? auth.branding(session.accessToken) : null;
     }
-    return { GET, POST: GET, auth, sitzungAus };
+    return { GET, POST: GET, auth, getSession, getBranding };
 }
 // ---------------------------------------------------------------------------
-function ableitenBasePath(redirectUri) {
-    const pfad = new URL(redirectUri).pathname;
+/**
+ * Aus dem Abgelegten wieder eine Sitzung machen.
+ *
+ * `accessTokenExpiresAt` ist ein Datum. Durch JSON — im Cookie ebenso wie in
+ * einer fremden Ablage — kommt es als Zeichenkette zurück, und `.getTime()`
+ * gibt es darauf nicht: die Erneuerung lief dann in einen TypeError statt zu
+ * erneuern. Eine eigene Ablage, die Objekte behält, liefert dagegen ein
+ * richtiges Datum; beides muss hier durchkommen.
+ */
+function withDate(session) {
+    const expires = session.accessTokenExpiresAt;
+    return {
+        ...session,
+        accessTokenExpiresAt: expires instanceof Date ? expires : new Date(expires),
+    };
+}
+function deriveBasePath(redirectUri) {
+    const path = new URL(redirectUri).pathname;
     // .../api/auth/callback → .../api/auth
-    return pfad.replace(/\/callback\/?$/, "");
+    return path.replace(/\/callback\/?$/, "");
 }
-function istHttps(url) {
+function isHttps(url) {
     return url.protocol === "https:";
 }
-function weiter(ziel) {
-    return new Response(null, { status: 302, headers: { location: ziel } });
+function redirect(target) {
+    return new Response(null, { status: 302, headers: { location: target } });
 }
-function json(daten, status = 200) {
-    return new Response(JSON.stringify(daten), {
+function json(data, status = 200) {
+    return new Response(JSON.stringify(data), {
         status,
         headers: { "content-type": "application/json" },
     });
 }
-function fehlerSeite(text) {
-    return json({ error: "anmeldung_fehlgeschlagen", message: text }, 400);
+function errorResponse(message) {
+    return json({ error: "login_failed", message }, 400);
 }
-function setzeCookie(antwort, name, wert, options) {
-    const teile = [
-        `${name}=${encodeURIComponent(wert)}`,
+function setCookie(response, name, value, options) {
+    const parts = [
+        `${name}=${encodeURIComponent(value)}`,
         "Path=/",
         "HttpOnly",
         "SameSite=Lax",
         `Max-Age=${options.maxAge}`,
     ];
-    // Ohne HTTPS kein Secure — sonst käme das Cookie in der Entwicklung unter
-    // http://localhost gar nicht erst an, und niemand fände den Grund.
-    if (options.sicher)
-        teile.push("Secure");
-    antwort.headers.append("set-cookie", teile.join("; "));
+    // No Secure without HTTPS — otherwise the cookie would never arrive during
+    // development on http://localhost, and nobody would find the reason.
+    if (options.secure)
+        parts.push("Secure");
+    response.headers.append("set-cookie", parts.join("; "));
 }
-function loescheCookie(antwort, name, sicher) {
-    setzeCookie(antwort, name, "", { maxAge: 0, sicher });
+function clearCookie(response, name, secure) {
+    setCookie(response, name, "", { maxAge: 0, secure });
 }
-function liesCookie(request, name) {
-    const kopf = request.headers.get("cookie");
-    if (!kopf)
+function readCookie(request, name) {
+    const header = request.headers.get("cookie");
+    if (!header)
         return null;
-    for (const teil of kopf.split(";")) {
-        const trenn = teil.indexOf("=");
-        if (trenn < 0)
+    for (const part of header.split(";")) {
+        const separator = part.indexOf("=");
+        if (separator < 0)
             continue;
-        if (teil.slice(0, trenn).trim() === name) {
-            return decodeURIComponent(teil.slice(trenn + 1));
+        if (part.slice(0, separator).trim() === name) {
+            return decodeURIComponent(part.slice(separator + 1));
         }
     }
     return null;

package/dist/pkce.d.ts

@@ -1,48 +1,46 @@
 /**
- * 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.
  */
 /**
- * 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 declare function base64url(daten: ArrayBuffer | Uint8Array): string;
+export declare function base64url(data: ArrayBuffer | Uint8Array): string;
 /**
- * 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 declare function createVerifier(): string;
-/** 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 declare function createChallenge(verifier: string): Promise<string>;
 /**
- * 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 declare function createState(): string;
 /**
- * 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 declare function gleich(a: string, b: string): boolean;
+export declare function timingSafeEqual(a: string, b: string): boolean;