@multiplatform.one/keycloak 6.7.0 → 7.0.0

package/src/oauth/authorizationUrl.ts

@@ -0,0 +1,74 @@
+/**
+ * File: /src/oauth/authorizationUrl.ts
+ * Project: @multiplatform.one/keycloak
+ */
+
+import type { OidcEndpoints } from "./endpoints";
+import { encodeForm } from "./form";
+
+export interface AuthorizationUrlParams {
+  endpoints: OidcEndpoints;
+  clientId: string;
+  redirectUri: string;
+  state: string;
+  codeChallenge: string;
+  /**
+   * Echoed in the id_token's `nonce` claim (OIDC Core §3.1.2.1). Required
+   * rather than optional: an authorization request built without one yields
+   * an ID token with nothing to bind it to this login.
+   */
+  nonce: string;
+  /** Defaults to the OIDC minimum plus the claims BaseKeycloak reads. */
+  scopes?: string[];
+  prompt?: "none" | "login" | "consent" | "select_account";
+  loginHint?: string;
+}
+
+export const defaultScopes = ["openid", "profile", "email"];
+
+export function buildAuthorizationUrl({
+  endpoints,
+  clientId,
+  redirectUri,
+  state,
+  codeChallenge,
+  nonce,
+  scopes = defaultScopes,
+  prompt,
+  loginHint,
+}: AuthorizationUrlParams): string {
+  return `${endpoints.authorization}?${encodeForm({
+    client_id: clientId,
+    redirect_uri: redirectUri,
+    response_type: "code",
+    scope: scopes.join(" "),
+    state,
+    nonce,
+    code_challenge: codeChallenge,
+    code_challenge_method: "S256",
+    ...(prompt ? { prompt } : {}),
+    ...(loginHint ? { login_hint: loginHint } : {}),
+  })}`;
+}
+
+export interface LogoutUrlParams {
+  endpoints: OidcEndpoints;
+  clientId: string;
+  idToken?: string;
+  postLogoutRedirectUri?: string;
+}
+
+export function buildLogoutUrl({
+  endpoints,
+  clientId,
+  idToken,
+  postLogoutRedirectUri,
+}: LogoutUrlParams): string {
+  // Keycloak only honours post_logout_redirect_uri when it can tie the request
+  // to a session, which id_token_hint is what supplies.
+  return `${endpoints.endSession}?${encodeForm({
+    client_id: clientId,
+    ...(idToken ? { id_token_hint: idToken } : {}),
+    ...(postLogoutRedirectUri ? { post_logout_redirect_uri: postLogoutRedirectUri } : {}),
+  })}`;
+}

package/src/oauth/callback.spec.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from "vitest";
+import { isCallbackForState, parseAuthorizationCallback } from "./callback";
+import { OAuthError } from "./errors";
+
+describe("isCallbackForState", () => {
+  it("accepts the redirect that echoes the state we generated", () => {
+    expect(isCallbackForState({ code: "abc", state: "s1" }, "s1")).toBe(true);
+  });
+
+  it("rejects a local request that carries someone else's state", () => {
+    expect(isCallbackForState({ code: "abc", state: "other" }, "s1")).toBe(false);
+  });
+
+  it("rejects a bare port scan with no query at all", () => {
+    expect(isCallbackForState({}, "s1")).toBe(false);
+  });
+
+  it("rejects an error redirect that does not name this login", () => {
+    expect(isCallbackForState({ error: "access_denied" }, "s1")).toBe(false);
+  });
+
+  it("accepts an error redirect that does name this login, so the flow fails fast", () => {
+    expect(isCallbackForState({ error: "access_denied", state: "s1" }, "s1")).toBe(true);
+  });
+
+  it("never matches on an empty expected state", () => {
+    expect(isCallbackForState({ state: "" }, "")).toBe(false);
+  });
+});
+
+describe("parseAuthorizationCallback", () => {
+  it("returns the code when the state matches", () => {
+    expect(parseAuthorizationCallback({ code: "abc", state: "s1" }, "s1")).toBe("abc");
+  });
+
+  it("rejects a callback whose state does not match the request", () => {
+    expect(() => parseAuthorizationCallback({ code: "abc", state: "other" }, "s1")).toThrow(
+      OAuthError,
+    );
+    expect(() => parseAuthorizationCallback({ code: "abc", state: "other" }, "s1")).toThrow(
+      /state did not match/,
+    );
+  });
+
+  it("rejects a callback with no state at all", () => {
+    expect(() => parseAuthorizationCallback({ code: "abc" }, "s1")).toThrow(/no state parameter/);
+  });
+
+  it("surfaces the server's error code and description", () => {
+    try {
+      parseAuthorizationCallback(
+        { error: "access_denied", error_description: "user said no", state: "s1" },
+        "s1",
+      );
+      expect.unreachable("should have thrown");
+    } catch (err) {
+      expect(err).toBeInstanceOf(OAuthError);
+      expect((err as OAuthError).code).toBe("access_denied");
+      expect((err as OAuthError).description).toBe("user said no");
+    }
+  });
+
+  it("reports an error before a state mismatch, since the flow already failed", () => {
+    expect(() => parseAuthorizationCallback({ error: "server_error" }, "s1")).toThrow(
+      /server_error/,
+    );
+  });
+
+  it("rejects a callback that carries state but no code", () => {
+    expect(() => parseAuthorizationCallback({ state: "s1" }, "s1")).toThrow(/no code parameter/);
+  });
+});

package/src/oauth/callback.ts

@@ -0,0 +1,46 @@
+/**
+ * File: /src/oauth/callback.ts
+ * Project: @multiplatform.one/keycloak
+ */
+
+import { OAuthError } from "./errors";
+
+export type CallbackQuery = Record<string, string | undefined>;
+
+/**
+ * Is this request the redirect for the login that generated `expectedState`?
+ *
+ * Anything on the machine can hit 127.0.0.1, so the listener needs to tell a
+ * stray local request from the real callback *before* it decides it is done
+ * waiting. A request that fails this is noise: it gets a 404 and the listener
+ * keeps listening. Without that distinction, any unprivileged local process
+ * that races the browser to the port can deny sign-in — it cannot get a code
+ * exchanged, because `parseAuthorizationCallback` checks state again, but it
+ * can make the real callback arrive at a closed socket.
+ */
+export function isCallbackForState(query: CallbackQuery, expectedState: string): boolean {
+  return !!expectedState && query.state === expectedState;
+}
+
+/**
+ * Validate the redirect's query and return the authorization code.
+ *
+ * The state check is the CSRF defence for the loopback listener: anything on
+ * the machine can hit 127.0.0.1, so a callback that does not echo the state we
+ * generated is rejected rather than exchanged.
+ */
+export function parseAuthorizationCallback(query: CallbackQuery, expectedState: string): string {
+  if (query.error) {
+    throw new OAuthError(query.error, undefined, query.error_description);
+  }
+  if (!query.state) {
+    throw new OAuthError("invalid_state", "authorization response had no state parameter");
+  }
+  if (query.state !== expectedState) {
+    throw new OAuthError("invalid_state", "authorization response state did not match the request");
+  }
+  if (!query.code) {
+    throw new OAuthError("invalid_request", "authorization response had no code parameter");
+  }
+  return query.code;
+}

package/src/oauth/callbackPage.spec.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+import {
+  callbackPageFailure,
+  callbackPageSuccess,
+  escapeHtml,
+  renderCallbackPage,
+} from "./callbackPage";
+
+/** The exact payload a hostile local client can put in `error_description`. */
+const hostileErrorDescription = "</p><script>alert(1)</script><p>";
+
+describe("escapeHtml", () => {
+  it("neutralises the characters that end a text node or an attribute", () => {
+    expect(escapeHtml(`<>&"'`)).toBe("&lt;&gt;&amp;&quot;&#39;");
+  });
+
+  it("escapes the ampersand first, so no entity is double-decoded", () => {
+    expect(escapeHtml("&lt;script&gt;")).toBe("&amp;lt;script&amp;gt;");
+  });
+
+  it("leaves ordinary text alone", () => {
+    expect(escapeHtml("Signed in")).toBe("Signed in");
+  });
+
+  it("defuses the script payload the loopback listener used to reflect", () => {
+    const escaped = escapeHtml(hostileErrorDescription);
+    expect(escaped).not.toContain("<script>");
+    expect(escaped).not.toContain("</p>");
+    expect(escaped).toContain("&lt;script&gt;");
+  });
+});
+
+describe("renderCallbackPage", () => {
+  it("renders the success copy", () => {
+    const html = renderCallbackPage(callbackPageSuccess);
+    expect(html).toContain("<h1>Signed in</h1>");
+    expect(html).toContain("You can close this tab");
+  });
+
+  it("renders the failure copy without any provider-supplied text", () => {
+    const html = renderCallbackPage(callbackPageFailure);
+    expect(html).toContain("<h1>Sign-in failed</h1>");
+    expect(html).toContain("Return to the app for the reason.");
+  });
+
+  it("escapes anything interpolated, so a future caller cannot inject markup", () => {
+    const html = renderCallbackPage({
+      heading: hostileErrorDescription,
+      detail: hostileErrorDescription,
+    });
+    expect(html).not.toContain("<script>");
+    expect(html).not.toContain("alert(1)</script>");
+    expect(html).toContain("&lt;script&gt;alert(1)&lt;/script&gt;");
+  });
+
+  it("emits exactly one h1 and one p even for markup-shaped input", () => {
+    const html = renderCallbackPage({ heading: "<h1>x</h1>", detail: "<p>y</p>" });
+    expect(html.match(/<h1>/g)).toHaveLength(1);
+    expect(html.match(/<p>/g)).toHaveLength(1);
+  });
+});

package/src/oauth/callbackPage.ts

@@ -0,0 +1,57 @@
+/**
+ * File: /src/oauth/callbackPage.ts
+ * Project: @multiplatform.one/keycloak
+ *
+ * The HTML the loopback listener serves back into the browser tab the
+ * redirect lands in.
+ *
+ * It lives in the OAuth core rather than in the GJS listener for two reasons:
+ * markup assembly is pure, so it can be unit tested in CI where nothing runs
+ * gjs; and putting the only place this flow emits HTML behind one escaped
+ * renderer means there is a single thing to audit.
+ *
+ * Two rules, both load-bearing:
+ *
+ *   1. **Nothing the authorization server sent is rendered.** The failure
+ *      page's copy is fixed. Keycloak's `error_description` arrives on a
+ *      redirect that any local process can forge, so treating it as markup
+ *      turned an error page into a script-injection sink; the app still
+ *      receives the full text through the callback query and surfaces it as
+ *      an `OAuthError` where it is a string, not a document.
+ *   2. **Everything interpolated is escaped anyway.** Belt and braces: the
+ *      inputs are constants today, and this way they can stop being
+ *      constants without that being a vulnerability.
+ */
+
+/** Escape text for an HTML text node or a double-quoted attribute. */
+export function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+export interface CallbackPageContent {
+  heading: string;
+  detail: string;
+}
+
+export const callbackPageSuccess: CallbackPageContent = {
+  heading: "Signed in",
+  detail: "You can close this tab and return to the app.",
+};
+
+export const callbackPageFailure: CallbackPageContent = {
+  heading: "Sign-in failed",
+  detail: "Return to the app for the reason. You can close this tab.",
+};
+
+export function renderCallbackPage({ heading, detail }: CallbackPageContent): string {
+  return (
+    `<!doctype html><meta charset="utf-8"><title>${escapeHtml(heading)}</title>` +
+    '<body style="font-family:system-ui,sans-serif;text-align:center;margin-top:4rem">' +
+    `<h1>${escapeHtml(heading)}</h1><p>${escapeHtml(detail)}</p>`
+  );
+}

package/src/oauth/endpoints.spec.ts

@@ -0,0 +1,193 @@
+import { describe, expect, it } from "vitest";
+import { assertSecureIssuer, keycloakEndpoints, type OidcEndpoints } from "./endpoints";
+
+describe("keycloakEndpoints", () => {
+  it("derives the standard OIDC endpoints for a realm", () => {
+    expect(keycloakEndpoints({ url: "https://kc.example.com", realm: "myrealm" })).toEqual({
+      issuer: "https://kc.example.com/realms/myrealm",
+      authorization: "https://kc.example.com/realms/myrealm/protocol/openid-connect/auth",
+      token: "https://kc.example.com/realms/myrealm/protocol/openid-connect/token",
+      endSession: "https://kc.example.com/realms/myrealm/protocol/openid-connect/logout",
+      userinfo: "https://kc.example.com/realms/myrealm/protocol/openid-connect/userinfo",
+      revocation: "https://kc.example.com/realms/myrealm/protocol/openid-connect/revoke",
+    });
+  });
+
+  it("tolerates a trailing slash on the base url", () => {
+    expect(keycloakEndpoints({ url: "https://kc.example.com///", realm: "r" }).token).toBe(
+      "https://kc.example.com/realms/r/protocol/openid-connect/token",
+    );
+  });
+
+  it("escapes a realm name that needs it", () => {
+    expect(keycloakEndpoints({ url: "https://kc", realm: "my realm" }).authorization).toBe(
+      "https://kc/realms/my%20realm/protocol/openid-connect/auth",
+    );
+  });
+
+  it("derives the issuer the id token must claim", () => {
+    expect(keycloakEndpoints({ url: "https://kc.example.com/", realm: "myrealm" }).issuer).toBe(
+      "https://kc.example.com/realms/myrealm",
+    );
+  });
+
+  it("still derives the docker realm's endpoints under the loopback opt-in", () => {
+    expect(
+      keycloakEndpoints({
+        url: "http://localhost:8080",
+        realm: "myrealm",
+        allowInsecureLoopbackHttp: true,
+      }).token,
+    ).toBe("http://localhost:8080/realms/myrealm/protocol/openid-connect/token");
+  });
+});
+
+describe("assertSecureIssuer", () => {
+  it("accepts https anywhere", () => {
+    expect(() => assertSecureIssuer({ url: "https://kc.example.com", realm: "r" })).not.toThrow();
+  });
+
+  it("is case insensitive about the scheme", () => {
+    expect(() => assertSecureIssuer({ url: "HTTPS://kc.example.com", realm: "r" })).not.toThrow();
+  });
+
+  it("refuses plaintext http to a remote host even with the loopback opt-in set", () => {
+    expect(() =>
+      assertSecureIssuer({
+        url: "http://kc.example.com",
+        realm: "r",
+        allowInsecureLoopbackHttp: true,
+      }),
+    ).toThrow(/refusing plaintext http to kc.example.com/);
+  });
+
+  it("refuses plaintext http to a loopback host without the opt-in", () => {
+    expect(() => assertSecureIssuer({ url: "http://localhost:8080", realm: "r" })).toThrow(
+      /needs an explicit allowInsecureLoopbackHttp/,
+    );
+  });
+
+  it("refuses the shipped dev default until something opts in", () => {
+    expect(() => keycloakEndpoints({ url: "http://localhost:8080", realm: "myrealm" })).toThrow(
+      expect.objectContaining({ code: "insecure_issuer" }),
+    );
+  });
+
+  for (const url of [
+    "http://127.0.0.1:8080",
+    "http://127.1.2.3:8080",
+    "http://localhost",
+    "http://LOCALHOST:8080",
+    "http://[::1]:8080",
+    "http://user:pw@127.0.0.1:8080",
+  ]) {
+    it(`allows ${url} under the opt-in`, () => {
+      expect(() =>
+        assertSecureIssuer({ url, realm: "r", allowInsecureLoopbackHttp: true }),
+      ).not.toThrow();
+    });
+  }
+
+  for (const url of [
+    // Hosts that only look like loopback — the classic SSRF bypass set.
+    "http://127.0.0.1.evil.com",
+    "http://localhost.evil.com",
+    "http://evil.com#127.0.0.1",
+    "http://evil.com/127.0.0.1",
+    "http://evil.com?127.0.0.1",
+    "http://0.0.0.0",
+    "http://10.0.0.1",
+  ]) {
+    it(`still refuses ${url} under the opt-in`, () => {
+      expect(() =>
+        assertSecureIssuer({ url, realm: "r", allowInsecureLoopbackHttp: true }),
+      ).toThrow(/must use https/);
+    });
+  }
+
+  it("rejects a non-http scheme", () => {
+    expect(() => assertSecureIssuer({ url: "ftp://kc.example.com", realm: "r" })).toThrow(
+      /must use https, got ftp/,
+    );
+  });
+
+  it("rejects a url with no scheme at all", () => {
+    expect(() => assertSecureIssuer({ url: "kc.example.com", realm: "r" })).toThrow(
+      /must be an absolute http\(s\) url/,
+    );
+  });
+});
+
+/**
+ * The userinfo boundary inside `hostOf`, which decides what counts as
+ * loopback and therefore what the http opt-in is allowed to reach.
+ *
+ * An authority may contain more than one `@` and only the LAST one ends the
+ * userinfo (RFC 3986 §3.2) — everything before it is a credential, not a
+ * host. Split on the first `@` instead and `x@127.0.0.1:8080@evil.com` reads
+ * as host `127.0.0.1`: loopback, accepted under the opt-in, and every
+ * derived endpoint then points at `evil.com` over plaintext http. The
+ * authorization code and the PKCE verifier get posted there, and OIDC Core
+ * §3.1.3.7's "over TLS" precondition — the whole reason this package skips
+ * signature verification — is silently void.
+ *
+ * That inversion is one character, and nothing else in this file notices it.
+ */
+describe("assertSecureIssuer userinfo boundary", () => {
+  for (const url of [
+    "http://x@127.0.0.1:8080@evil.com",
+    "http://user:pass@127.0.0.1:8080@evil.com",
+    "http://x@[::1]@evil.com",
+  ]) {
+    it(`takes the host after the last @, not the first, in ${url}`, () => {
+      expect(() =>
+        assertSecureIssuer({ url, realm: "r", allowInsecureLoopbackHttp: true }),
+      ).toThrow(/refusing plaintext http to evil\.com/);
+    });
+  }
+
+  it("still allows a genuine loopback host whose userinfo only looks hostile", () => {
+    expect(() =>
+      assertSecureIssuer({
+        url: "http://evil.com@127.0.0.1",
+        realm: "r",
+        allowInsecureLoopbackHttp: true,
+      }),
+    ).not.toThrow();
+  });
+
+  it("derives the endpoints from the real host, not the userinfo", () => {
+    expect(
+      keycloakEndpoints({
+        url: "http://evil.com@127.0.0.1:8080",
+        realm: "r",
+        allowInsecureLoopbackHttp: true,
+      }).token,
+    ).toBe("http://evil.com@127.0.0.1:8080/realms/r/protocol/openid-connect/token");
+  });
+});
+
+/**
+ * The brand is type-only, so this is checked by `tsc --noEmit` — which
+ * includes this file and runs in CI — rather than by the assertion below.
+ * Drop the brand from `OidcEndpoints` and the literal becomes assignable, at
+ * which point tsc fails on an unused `@ts-expect-error`. It is what makes
+ * "every URL derives from here" a property of the type rather than a habit:
+ * a forged endpoint set is how a plaintext token URL would reach the code
+ * exchange without `assertSecureIssuer` ever having run.
+ */
+describe("OidcEndpoints is not constructible outside this module", () => {
+  it("refuses a hand-written object literal", () => {
+    const plaintext = "http://evil.com/realms/r/protocol/openid-connect";
+    // @ts-expect-error OidcEndpoints is branded; keycloakEndpoints is the only source
+    const forged: OidcEndpoints = {
+      issuer: "http://evil.com/realms/r",
+      authorization: `${plaintext}/auth`,
+      token: `${plaintext}/token`,
+      endSession: `${plaintext}/logout`,
+      userinfo: `${plaintext}/userinfo`,
+      revocation: `${plaintext}/revoke`,
+    };
+    expect(forged.token).toBe(`${plaintext}/token`);
+  });
+});

package/src/oauth/endpoints.ts

@@ -0,0 +1,135 @@
+/**
+ * File: /src/oauth/endpoints.ts
+ * Project: @multiplatform.one/keycloak
+ *
+ * Keycloak's OIDC endpoints are positional under /realms/<realm>, so they can
+ * be derived without a discovery round trip. Deriving beats fetching
+ * .well-known here: the GNOME target builds these before it has a working
+ * token, and one less network hop is one less failure mode at startup.
+ *
+ * This is also the transport-security choke point, and `OidcEndpoints` is
+ * branded so that it is one by construction rather than by convention: no
+ * hand-written object satisfies the type, so every code path that talks to
+ * Keycloak — the authorization URL, the token exchange, the refresh, the
+ * back-channel logout — necessarily derives its URLs from `keycloakEndpoints`,
+ * and rejecting a plaintext issuer here rejects it everywhere. That matters
+ * more than usual for this flow:
+ * `validateIdToken` skips signature verification on the strength of OIDC Core
+ * §3.1.3.7, whose precondition is that the token arrived directly from the
+ * token endpoint *over TLS*. Without an enforced https floor that precondition
+ * is an assumption, and an assumption is not a control.
+ */
+
+import { OAuthError } from "./errors";
+
+declare const oidcEndpointsBrand: unique symbol;
+
+export interface OidcEndpoints {
+  /**
+   * Phantom brand — in the type, never on the object. It is what turns the
+   * choke point described above from a convention into something the
+   * compiler holds: an object literal cannot satisfy this interface, so the
+   * only way a caller gets an `OidcEndpoints` is out of `keycloakEndpoints`,
+   * which runs `assertSecureIssuer` first. Without it a consumer could hand
+   * `exchangeAuthorizationCode` a plaintext `token` URL of its own making
+   * and the https floor would never have been consulted.
+   */
+  readonly [oidcEndpointsBrand]: true;
+  /** The `iss` claim an ID token minted by this realm must carry. */
+  issuer: string;
+  authorization: string;
+  token: string;
+  endSession: string;
+  userinfo: string;
+  revocation: string;
+}
+
+export interface RealmLocation {
+  /** Keycloak base URL, e.g. `https://kc.example.com`. */
+  url: string;
+  realm: string;
+  /**
+   * Development-only escape hatch for a Keycloak running on the same machine
+   * — `http://localhost:8080`, the docker realm, a stand-in IdP in a test.
+   *
+   * Deliberately narrow: it permits `http` for **loopback hosts only**
+   * (`localhost`, `127.0.0.0/8`, `::1`). A plaintext URL pointing anywhere
+   * else stays rejected whatever this is set to, because the traffic would
+   * leave the machine. Deliberately explicit: there is no silent fallback and
+   * no environment sniffing, so a build that talks plaintext to a real realm
+   * has to have said so in its own source.
+   */
+  allowInsecureLoopbackHttp?: boolean;
+}
+
+const originPattern = /^([A-Za-z][A-Za-z0-9+.-]*):\/\/([^/?#]*)/;
+const ipv4LoopbackPattern = /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/;
+
+/**
+ * Host of an absolute URL, minus any userinfo and port. Hand-rolled because
+ * GJS has no `URL` any more than it has `URLSearchParams`.
+ */
+function hostOf(authority: string): string {
+  const afterUserinfo = authority.slice(authority.lastIndexOf("@") + 1);
+  // An IPv6 literal is bracketed, so its colons are not a port separator.
+  if (afterUserinfo.startsWith("[")) {
+    return afterUserinfo.slice(1, afterUserinfo.indexOf("]")).toLowerCase();
+  }
+  const colon = afterUserinfo.indexOf(":");
+  return (colon === -1 ? afterUserinfo : afterUserinfo.slice(0, colon)).toLowerCase();
+}
+
+function isLoopbackHost(host: string): boolean {
+  return host === "localhost" || host === "::1" || ipv4LoopbackPattern.test(host);
+}
+
+/**
+ * Reject any issuer the OIDC Core §3.1.3.7 carve-out would not cover.
+ *
+ * Exported so a caller can check a configured URL before it builds anything
+ * from it — the message names the offending host rather than just failing.
+ */
+export function assertSecureIssuer({ url, allowInsecureLoopbackHttp }: RealmLocation): void {
+  const match = originPattern.exec(url);
+  if (!match) {
+    throw new OAuthError(
+      "insecure_issuer",
+      `keycloak url must be an absolute http(s) url, got ${JSON.stringify(url)}`,
+    );
+  }
+  const scheme = match[1].toLowerCase();
+  if (scheme === "https") return;
+  if (scheme !== "http") {
+    throw new OAuthError("insecure_issuer", `keycloak url must use https, got ${scheme}://`);
+  }
+  const host = hostOf(match[2]);
+  if (!isLoopbackHost(host)) {
+    throw new OAuthError(
+      "insecure_issuer",
+      `keycloak url must use https — refusing plaintext http to ${host}`,
+    );
+  }
+  if (!allowInsecureLoopbackHttp) {
+    throw new OAuthError(
+      "insecure_issuer",
+      `keycloak url must use https — plaintext http to the loopback host ${host} needs an explicit allowInsecureLoopbackHttp`,
+    );
+  }
+}
+
+export function keycloakEndpoints(location: RealmLocation): OidcEndpoints {
+  assertSecureIssuer(location);
+  const issuer = `${location.url.replace(/\/+$/, "")}/realms/${encodeURIComponent(location.realm)}`;
+  const base = `${issuer}/protocol/openid-connect`;
+  // The one place the brand is applied, immediately after the only call to
+  // assertSecureIssuer. The brand is type-only, so nothing is added here at
+  // runtime and the returned object is exactly its six URLs.
+  return {
+    issuer,
+    authorization: `${base}/auth`,
+    token: `${base}/token`,
+    endSession: `${base}/logout`,
+    userinfo: `${base}/userinfo`,
+    revocation: `${base}/revoke`,
+  } as OidcEndpoints;
+}

package/src/oauth/errors.ts

@@ -0,0 +1,18 @@
+/**
+ * File: /src/oauth/errors.ts
+ * Project: @multiplatform.one/keycloak
+ */
+
+/** An OAuth 2.0 / OIDC protocol failure, carrying the spec's `error` code. */
+export class OAuthError extends Error {
+  constructor(
+    /** The `error` field from the authorization or token response. */
+    public readonly code: string,
+    message?: string,
+    /** The `error_description` field, when the server sent one. */
+    public readonly description?: string,
+  ) {
+    super(message ?? description ?? code);
+    this.name = "OAuthError";
+  }
+}