@aplons/auth 0.1.0 → 0.2.0

package/dist/errors.js

@@ -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 class AplonsError extends Error {
-    /** Die OAuth-Kennung, etwa `invalid_grant`. */
+    /** The OAuth identifier, e.g. `invalid_grant`. */
     code;
-    /** Der HTTP-Status, wenn der Fehler von einer Antwort kam. */
+    /** The HTTP status, when the error came from a response. */
     status;
-    /** Was der Server dazu geschrieben hat. */
+    /** What the server wrote about it. */
     description;
     constructor(options) {
         super(options.message, { cause: options.cause });
@@ -22,57 +22,61 @@ export class AplonsError extends Error {
     }
 }
 /**
- * `invalid_grant` heißt bei jedem Ablauf etwas anderes.
+ * `invalid_grant` means something different in every flow.
  *
- * Beide Ursachen unter denselben Satz zu stellen war ein Fehler: wer eine
- * fehlgeschlagene Erneuerung untersuchte, las etwas über einen Anmeldecode,
- * den es in diesem Ablauf gar nicht gibt — und suchte an der falschen Stelle.
+ * Putting both causes under the same sentence was a mistake: anyone looking
+ * into a failed refresh read about an authorization code that does not exist
+ * in that flow — and went looking in the wrong place.
  */
 const INVALID_GRANT = {
-    code: "Der Anmeldecode wurde schon eingelöst, ist abgelaufen, oder der " +
-        "code_verifier passt nicht zum code_challenge. Meistens: die Rückkehr " +
-        "wurde zweimal ausgeführt, etwa weil der Browser die Seite neu geladen hat.",
-    refresh: "Das Refresh-Token gilt nicht mehr. Entweder ist es abgelaufen, es wurde " +
-        "beim Abmelden entwertet, oder es wurde schon einmal eingetauscht — jedes " +
-        "Erneuern gibt ein neues aus und macht das alte ungültig. Wer das alte " +
-        "aufbewahrt und noch einmal schickt, sieht genau diesen Fehler. In allen " +
-        "Fällen hilft nur eine neue Anmeldung.",
-    allgemein: "Die vorgelegte Berechtigung gilt nicht mehr. Eine neue Anmeldung hilft.",
+    code: "The authorization code was already redeemed, has expired, or the " +
+        "code_verifier does not match the code_challenge. Usually: the callback " +
+        "ran twice, for instance because the browser reloaded the page.",
+    refresh: "The refresh token is no longer valid. Either it expired, it was revoked " +
+        "at logout, or it has already been exchanged — every refresh issues a new " +
+        "one and invalidates the old. Keeping the old one and sending it again " +
+        "produces exactly this error. In all cases only a fresh login helps.",
+    generic: "The grant presented is no longer valid. A fresh login helps.",
 };
-/** Die häufigsten Kennungen, in Worte gefasst. */
-const ERKLAERT = {
-    invalid_client: "Client-ID oder Client-Secret stimmen nicht. Bei einer öffentlichen " +
-        "Anwendung darf gar kein Secret mitgeschickt werden.",
-    invalid_request: "Der Anfrage fehlt etwas oder sie enthält etwas Widersprüchliches.",
-    unauthorized_client: "Diese Anwendung darf diesen Ablauf nicht verwenden.",
-    access_denied: "Die Anmeldung wurde abgebrochen oder das Konto hat auf diese Anwendung " +
-        "keinen Zugriff.",
-    invalid_scope: "Mindestens einer der angeforderten Bereiche ist unbekannt.",
-    server_error: "Bei Aplons ist etwas schiefgegangen. Siehe status.aplons.com.",
+/** The most common identifiers, put into words. */
+const EXPLANATIONS = {
+    invalid_client: "Client ID or client secret are wrong. A public application must not " +
+        "send a secret at all.",
+    invalid_request: "The request is missing something, or contradicts itself.",
+    unauthorized_client: "This application may not use this flow.",
+    access_denied: "The login was cancelled, or the account has no access to this application.",
+    invalid_scope: "At least one of the requested scopes is unknown.",
+    insufficient_scope: "The token does not carry the scope this endpoint requires. Register the " +
+        "scope for the application and ask for it at login — an access token only " +
+        "ever holds what was granted.",
+    branding_not_shared: "The tenant does not hand out its branding to applications. That is a rule " +
+        "in its own policies and off by default; nothing on your side can change " +
+        "it, only the tenant can.",
+    server_error: "Something went wrong at Aplons. See status.aplons.com.",
 };
-/** Aus einer fehlgeschlagenen Antwort einen brauchbaren Fehler machen. */
-export async function ausAntwort(antwort, wobei, ablauf = "allgemein") {
-    let code = "http_" + antwort.status;
+/** Turn a failed response into something usable. */
+export async function fromResponse(response, what, flow = "generic") {
+    let code = "http_" + response.status;
     let description;
     try {
-        const koerper = (await antwort.json());
-        if (koerper.error)
-            code = koerper.error;
-        description = koerper.error_description ?? koerper.message;
+        const body = (await response.json());
+        if (body.error)
+            code = body.error;
+        description = body.error_description ?? body.message;
     }
     catch {
-        // Keine JSON-Antwort. Dann bleibt der Status die ganze Auskunft — was
-        // bei einem Proxy dazwischen der häufigere Fall ist als bei uns.
+        // Not a JSON response. Then the status is all there is — which happens
+        // more often with a proxy in between than with us.
     }
-    const erklaerung = code === "invalid_grant" ? INVALID_GRANT[ablauf] : ERKLAERT[code];
+    const explanation = code === "invalid_grant" ? INVALID_GRANT[flow] : EXPLANATIONS[code];
     return new AplonsError({
         code,
-        status: antwort.status,
+        status: response.status,
         description,
         message: [
-            `${wobei} fehlgeschlagen (${code}).`,
-            erklaerung,
-            description && description !== erklaerung ? `Server: ${description}` : null,
+            `${what} failed (${code}).`,
+            explanation,
+            description && description !== explanation ? `Server: ${description}` : null,
         ]
             .filter(Boolean)
             .join(" "),

package/dist/index.d.ts

@@ -1,17 +1,17 @@
 /**
- * @aplons/auth — Anmeldung über Aplons in eigenen Anwendungen.
+ * @aplons/auth — sign in through Aplons from your own applications.
  *
- * Der Kern, ohne Rahmenwerk: läuft in Node, im Browser, am Rand und in einem
- * Worker. Für Next.js gibt es zusätzlich `@aplons/auth/next`, das die
- * Cookie-Arbeit abnimmt.
+ * The core, framework-free: runs in Node, in the browser, at the edge and in
+ * a worker. For Next.js there is also `@aplons/auth/next`, which takes the
+ * cookie work off your hands.
  *
- * Eine einzige Abhängigkeit, `jose`, und die nur zum Prüfen von Unterschriften
- * — dieselbe, die der Aplons-Server selbst benutzt. Alles andere macht die
- * eingebaute Web-Crypto.
+ * A single dependency, `jose`, and only for verifying signatures — the same
+ * one the Aplons server itself uses. Everything else is built-in Web Crypto.
  */
 export { AplonsAuth } from "./client.js";
-export { AplonsError } from "./errors.js";
-export { base64url, createChallenge, createState, createVerifier, gleich, } from "./pkce.js";
-export { pruefeIdToken, pruefeZugriffstoken, schluesselFuer } from "./verify.js";
-export { holeMetadaten, type Metadaten } from "./discovery.js";
-export type { AccessTokenClaims, Anmeldevorgang, AplonsOptions, IdTokenClaims, Profil, Sitzung, } from "./types.js";
+export { AplonsError, type Flow } from "./errors.js";
+export { base64url, createChallenge, createState, createVerifier, timingSafeEqual, } from "./pkce.js";
+export { jwksFor, verifyAccessToken, verifyIdToken, type KeySource } from "./verify.js";
+export { brandingCss, type Branding } from "./branding.js";
+export { fetchMetadata, type Metadata } from "./discovery.js";
+export type { AccessTokenClaims, AplonsOptions, AuthorizationRequest, IdTokenClaims, Session, UserInfo, } from "./types.js";

package/dist/index.js

@@ -1,16 +1,16 @@
 /**
- * @aplons/auth — Anmeldung über Aplons in eigenen Anwendungen.
+ * @aplons/auth — sign in through Aplons from your own applications.
  *
- * Der Kern, ohne Rahmenwerk: läuft in Node, im Browser, am Rand und in einem
- * Worker. Für Next.js gibt es zusätzlich `@aplons/auth/next`, das die
- * Cookie-Arbeit abnimmt.
+ * The core, framework-free: runs in Node, in the browser, at the edge and in
+ * a worker. For Next.js there is also `@aplons/auth/next`, which takes the
+ * cookie work off your hands.
  *
- * Eine einzige Abhängigkeit, `jose`, und die nur zum Prüfen von Unterschriften
- * — dieselbe, die der Aplons-Server selbst benutzt. Alles andere macht die
- * eingebaute Web-Crypto.
+ * A single dependency, `jose`, and only for verifying signatures — the same
+ * one the Aplons server itself uses. Everything else is built-in Web Crypto.
  */
 export { AplonsAuth } from "./client.js";
 export { AplonsError } from "./errors.js";
-export { base64url, createChallenge, createState, createVerifier, gleich, } from "./pkce.js";
-export { pruefeIdToken, pruefeZugriffstoken, schluesselFuer } from "./verify.js";
-export { holeMetadaten } from "./discovery.js";
+export { base64url, createChallenge, createState, createVerifier, timingSafeEqual, } from "./pkce.js";
+export { jwksFor, verifyAccessToken, verifyIdToken } from "./verify.js";
+export { brandingCss } from "./branding.js";
+export { fetchMetadata } from "./discovery.js";

package/dist/next.d.ts

@@ -1,72 +1,74 @@
 /**
- * @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 type { AplonsOptions, Sitzung } from "./types.js";
+import type { Branding } from "./branding.js";
+import type { AplonsOptions, Session } from "./types.js";
 export type HandlerOptions = AplonsOptions & {
     /**
-     * Präfix, unter dem die vier Adressen liegen.
-     * Voreinstellung: aus `redirectUri` abgeleitet.
+     * Prefix the four routes live under.
+     * Defaults to whatever `redirectUri` implies.
      */
     basePath?: string;
-    /** Wohin nach der Anmeldung, wenn nichts anderes verlangt wurde. */
-    nachAnmeldung?: string;
-    /** Wohin nach dem Abmelden. */
-    nachAbmeldung?: string;
+    /** Where to go after login when nothing else was requested. */
+    afterLogin?: string;
+    /** Where to go after logout. */
+    afterLogout?: string;
     /**
-     * Name des Cookies mit der Sitzung.
-     * Voreinstellung `aplons_session`.
+     * Name of the session cookie.
+     * Defaults to `aplons_session`.
      */
     cookieName?: string;
     /**
-     * Wie die Sitzung abgelegt wird.
+     * How the session is stored.
      *
-     * Ohne eigene Angabe landet sie **verschlüsselt im Cookie**. Das kommt
-     * ohne Speicher aus, hat aber eine Grenze: 4 KB, und ein Widerruf wirkt
-     * erst, wenn das Zugriffstoken abläuft. Wer eine Datenbank hat, gibt hier
-     * seine eigene Ablage an.
+     * Without an explicit choice it ends up **in the cookie**. That needs no
+     * storage, but it has limits: 4 KB, and a revocation only bites once the
+     * access token expires. Whoever has a database passes their own store.
      */
-    speicher?: Sitzungsspeicher;
+    store?: SessionStore;
 };
-export type Sitzungsspeicher = {
-    lies(id: string): Promise<Sitzung | null>;
-    schreib(id: string, sitzung: Sitzung): Promise<void>;
-    loesche(id: string): Promise<void>;
+export type SessionStore = {
+    read(id: string): Promise<Session | null>;
+    write(id: string, session: Session): Promise<void>;
+    delete(id: string): Promise<void>;
 };
 /**
- * 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 declare function handhabe(options: HandlerOptions): {
+export declare function createHandler(options: HandlerOptions): {
     GET: (request: Request) => Promise<Response>;
     POST: (request: Request) => Promise<Response>;
     auth: AplonsAuth;
-    sitzungAus: (request: Request) => Promise<Sitzung | null>;
+    getSession: (request: Request) => Promise<Session | null>;
+    getBranding: (request: Request) => Promise<Branding | null>;
 };