@multiplatform.one/keycloak 6.7.0 → 7.1.0

package/src/oauth/loopbackFlow.spec.ts

@@ -0,0 +1,226 @@
+import { createHash, randomBytes } from "node:crypto";
+import { describe, expect, it, vi } from "vitest";
+import { keycloakEndpoints } from "./endpoints";
+import { type LoopbackListener, type LoopbackTransport, runLoopbackLogin } from "./loopbackFlow";
+import type { FetchLike } from "./tokenExchange";
+
+const crypto = {
+  randomBytes: (length: number) => new Uint8Array(randomBytes(length)),
+  sha256: (input: Uint8Array) => new Uint8Array(createHash("sha256").update(input).digest()),
+};
+
+const config = { url: "https://kc.example.com", realm: "myrealm", clientId: "app-public" };
+const issuer = keycloakEndpoints(config).issuer;
+
+/** A structurally real ID token, minted per login so the nonce matches. */
+function mintIdToken(nonce: string, claims: Record<string, unknown> = {}): string {
+  const segment = (value: unknown) => Buffer.from(JSON.stringify(value)).toString("base64url");
+  const now = Math.floor(Date.now() / 1000);
+  return [
+    segment({ alg: "RS256", typ: "JWT", kid: "kid-1" }),
+    segment({
+      iss: issuer,
+      aud: "app-public",
+      azp: "app-public",
+      sub: "3f6c1e2a-user",
+      exp: now + 300,
+      iat: now,
+      nonce,
+      ...claims,
+    }),
+    "signature-we-do-not-verify",
+  ].join(".");
+}
+
+/**
+ * A stand-in Keycloak: it reads the authorization request the flow opened in
+ * the "browser", redirects back with a code, and verifies the PKCE verifier at
+ * the token endpoint the way a real server would. It mints its ID token from
+ * the nonce it was sent, exactly as Keycloak does.
+ */
+function fakeIdp({
+  echoState,
+  tokenPayload,
+  idTokenClaims,
+  omitIdToken,
+}: {
+  echoState?: string;
+  tokenPayload?: unknown;
+  idTokenClaims?: Record<string, unknown>;
+  omitIdToken?: boolean;
+} = {}) {
+  const seen: {
+    authorizationUrl?: URL;
+    challenge?: string;
+    verifier?: string;
+    nonce?: string;
+    listenedFor?: string;
+  } = {};
+  let resolveCallback: (query: Record<string, string>) => void;
+  const callback = new Promise<Record<string, string>>((resolve) => {
+    resolveCallback = resolve;
+  });
+  const listener: LoopbackListener = {
+    redirectUri: "http://127.0.0.1:41234/callback",
+    waitForCallback: () => callback,
+    close: vi.fn(),
+  };
+  const transport: LoopbackTransport = {
+    crypto,
+    listen: async (expectedState: string) => {
+      seen.listenedFor = expectedState;
+      return listener;
+    },
+    openBrowser: (url: string) => {
+      const parsed = new URL(url);
+      seen.authorizationUrl = parsed;
+      seen.challenge = parsed.searchParams.get("code_challenge") ?? undefined;
+      seen.nonce = parsed.searchParams.get("nonce") ?? undefined;
+      resolveCallback({
+        code: "authz-code",
+        state: echoState ?? (parsed.searchParams.get("state") as string),
+      });
+    },
+    fetch: (async (_url, init) => {
+      const form = new URLSearchParams(init.body);
+      seen.verifier = form.get("code_verifier") ?? undefined;
+      return {
+        ok: true,
+        status: 200,
+        json: async () =>
+          tokenPayload ?? {
+            access_token: "at",
+            refresh_token: "rt",
+            ...(omitIdToken ? {} : { id_token: mintIdToken(seen.nonce as string, idTokenClaims) }),
+          },
+        text: async () => "",
+      };
+    }) as FetchLike,
+  };
+  return { transport, listener, seen };
+}
+
+describe("runLoopbackLogin", () => {
+  it("completes the code-for-token round trip", async () => {
+    const { transport } = fakeIdp();
+    const tokens = await runLoopbackLogin(transport, config);
+    expect(tokens).toMatchObject({ accessToken: "at", refreshToken: "rt" });
+    expect(tokens.idTokenClaims?.sub).toBe("3f6c1e2a-user");
+  });
+
+  it("sends a challenge that is the SHA-256 of the verifier it later redeems", async () => {
+    const { transport, seen } = fakeIdp();
+    await runLoopbackLogin(transport, config);
+    const expected = Buffer.from(
+      createHash("sha256")
+        .update(seen.verifier as string)
+        .digest(),
+    )
+      .toString("base64")
+      .replace(/\+/g, "-")
+      .replace(/\//g, "_")
+      .replace(/=+$/, "");
+    expect(seen.challenge).toBe(expected);
+  });
+
+  it("uses the listener's bound redirect uri in both legs of the flow", async () => {
+    const { transport, seen } = fakeIdp();
+    await runLoopbackLogin(transport, config);
+    expect(seen.authorizationUrl?.searchParams.get("redirect_uri")).toBe(
+      "http://127.0.0.1:41234/callback",
+    );
+  });
+
+  it("aborts when the callback echoes a different state", async () => {
+    const { transport } = fakeIdp({ echoState: "attacker-supplied" });
+    await expect(runLoopbackLogin(transport, config)).rejects.toMatchObject({
+      code: "invalid_state",
+    });
+  });
+
+  it("closes the listener even when the exchange fails", async () => {
+    const { transport, listener } = fakeIdp({ echoState: "mismatch" });
+    await expect(runLoopbackLogin(transport, config)).rejects.toThrow();
+    expect(listener.close).toHaveBeenCalledTimes(1);
+  });
+
+  it("closes the listener on success", async () => {
+    const { transport, listener } = fakeIdp();
+    await runLoopbackLogin(transport, config);
+    expect(listener.close).toHaveBeenCalledTimes(1);
+  });
+
+  it("generates a distinct verifier and state per login", async () => {
+    const first = fakeIdp();
+    const second = fakeIdp();
+    await runLoopbackLogin(first.transport, config);
+    await runLoopbackLogin(second.transport, config);
+    expect(first.seen.verifier).not.toBe(second.seen.verifier);
+    expect(first.seen.authorizationUrl?.searchParams.get("state")).not.toBe(
+      second.seen.authorizationUrl?.searchParams.get("state"),
+    );
+  });
+
+  it("hands the listener the state to filter on, before the browser opens", async () => {
+    const { transport, seen } = fakeIdp();
+    await runLoopbackLogin(transport, config);
+    expect(seen.listenedFor).toBe(seen.authorizationUrl?.searchParams.get("state"));
+  });
+
+  it("sends a nonce distinct from the state, and a fresh one per login", async () => {
+    const first = fakeIdp();
+    const second = fakeIdp();
+    await runLoopbackLogin(first.transport, config);
+    await runLoopbackLogin(second.transport, config);
+    expect(first.seen.nonce).toBeTruthy();
+    expect(first.seen.nonce).not.toBe(first.seen.authorizationUrl?.searchParams.get("state"));
+    expect(first.seen.nonce).not.toBe(second.seen.nonce);
+  });
+
+  it("rejects an id token bound to a different login's nonce", async () => {
+    const { transport } = fakeIdp({ idTokenClaims: { nonce: "someone-elses-nonce" } });
+    await expect(runLoopbackLogin(transport, config)).rejects.toMatchObject({
+      code: "invalid_id_token",
+    });
+  });
+
+  it("rejects an id token minted for another client in the realm", async () => {
+    const { transport } = fakeIdp({ idTokenClaims: { aud: "other", azp: "other" } });
+    await expect(runLoopbackLogin(transport, config)).rejects.toMatchObject({
+      code: "invalid_id_token",
+    });
+  });
+
+  it("rejects an openid login that came back with no id token", async () => {
+    const { transport } = fakeIdp({ omitIdToken: true });
+    await expect(runLoopbackLogin(transport, config)).rejects.toThrow(/no id_token came back/);
+  });
+
+  it("allows a non-openid login to come back without an id token", async () => {
+    const { transport } = fakeIdp({ omitIdToken: true });
+    await expect(
+      runLoopbackLogin(transport, { ...config, scopes: ["profile"] }),
+    ).resolves.toMatchObject({ accessToken: "at" });
+  });
+
+  it("refuses to start against a plaintext issuer", async () => {
+    const { transport } = fakeIdp();
+    await expect(
+      runLoopbackLogin(transport, { ...config, url: "http://kc.example.com" }),
+    ).rejects.toMatchObject({ code: "insecure_issuer" });
+  });
+
+  it("runs against a loopback dev realm when the caller opts in", async () => {
+    const localConfig = {
+      url: "http://127.0.0.1:8080",
+      realm: "myrealm",
+      clientId: "app-public",
+      allowInsecureLoopbackHttp: true,
+    };
+    const localIssuer = keycloakEndpoints(localConfig).issuer;
+    const { transport } = fakeIdp({ idTokenClaims: { iss: localIssuer } });
+    await expect(runLoopbackLogin(transport, localConfig)).resolves.toMatchObject({
+      accessToken: "at",
+    });
+  });
+});

package/src/oauth/loopbackFlow.ts

@@ -0,0 +1,114 @@
+/**
+ * File: /src/oauth/loopbackFlow.ts
+ * Project: @multiplatform.one/keycloak
+ *
+ * Authorization Code + PKCE with a loopback redirect — the flow RFC 8252
+ * ("OAuth 2.0 for Native Apps", §7.3) prescribes for desktop applications.
+ *
+ * The app binds an ephemeral port on 127.0.0.1, hands Keycloak that port as
+ * the redirect URI, and opens the system browser. The user authenticates in a
+ * real browser — with their password manager, their existing SSO cookie and a
+ * verifiable address bar — and Keycloak redirects back to the listener, which
+ * closes as soon as the code arrives.
+ *
+ * Why not the alternatives:
+ *
+ *   - A custom URI scheme (`myapp://callback`) needs an installed .desktop
+ *     file registering `x-scheme-handler/myapp` plus a desktop-database
+ *     refresh. That cannot work from a dev tree run with `gjs -m dist/...`,
+ *     and on a multi-app desktop any other app can register the same scheme.
+ *   - The device authorization grant avoids the redirect entirely, but it has
+ *     to be enabled per-client on the realm, and it downgrades the UX to
+ *     retyping a code for a GUI app that can perfectly well open a browser.
+ *   - An embedded webview would put the app between the user and their
+ *     credentials, which RFC 8252 §8.12 explicitly rules out.
+ *
+ * Everything the flow touches is injected, so the whole orchestration is
+ * exercised in unit tests with no browser, no sockets and no GJS.
+ */
+
+import { buildAuthorizationUrl, defaultScopes } from "./authorizationUrl";
+import { type CallbackQuery, parseAuthorizationCallback } from "./callback";
+import { keycloakEndpoints } from "./endpoints";
+import { OAuthError } from "./errors";
+import { createNonce, createPkcePair, createStateToken, type PkceCrypto } from "./pkce";
+import { exchangeAuthorizationCode, type FetchLike, type TokenSet } from "./tokenExchange";
+
+/** A bound loopback socket waiting for exactly one redirect. */
+export interface LoopbackListener {
+  /** The `http://127.0.0.1:<port>/…` URI the socket is bound to. */
+  redirectUri: string;
+  waitForCallback(): Promise<CallbackQuery>;
+  close(): void;
+}
+
+export interface LoopbackTransport {
+  crypto: PkceCrypto;
+  fetch: FetchLike;
+  openBrowser(url: string): void | Promise<void>;
+  /**
+   * Bind a loopback socket for one login.
+   *
+   * `expectedState` is handed over at bind time rather than at wait time so
+   * the listener can tell the real redirect from a stray local request from
+   * the very first packet — there is no window in which it does not yet know
+   * what it is waiting for.
+   */
+  listen(expectedState: string): Promise<LoopbackListener>;
+}
+
+export interface LoopbackLoginConfig {
+  url: string;
+  realm: string;
+  clientId: string;
+  /** See `RealmLocation.allowInsecureLoopbackHttp` — development only. */
+  allowInsecureLoopbackHttp?: boolean;
+  scopes?: string[];
+  prompt?: "none" | "login" | "consent" | "select_account";
+  loginHint?: string;
+}
+
+export async function runLoopbackLogin(
+  transport: LoopbackTransport,
+  config: LoopbackLoginConfig,
+): Promise<TokenSet> {
+  const endpoints = keycloakEndpoints(config);
+  const pkce = createPkcePair(transport.crypto);
+  const state = createStateToken(transport.crypto);
+  const nonce = createNonce(transport.crypto);
+  const scopes = config.scopes ?? defaultScopes;
+  const listener = await transport.listen(state);
+  try {
+    await transport.openBrowser(
+      buildAuthorizationUrl({
+        endpoints,
+        clientId: config.clientId,
+        redirectUri: listener.redirectUri,
+        state,
+        codeChallenge: pkce.challenge,
+        nonce,
+        scopes,
+        prompt: config.prompt,
+        loginHint: config.loginHint,
+      }),
+    );
+    const code = parseAuthorizationCallback(await listener.waitForCallback(), state);
+    const tokens = await exchangeAuthorizationCode(transport.fetch, {
+      endpoints,
+      clientId: config.clientId,
+      code,
+      codeVerifier: pkce.verifier,
+      redirectUri: listener.redirectUri,
+      nonce,
+    });
+    // An `openid` request that comes back without an ID token means the
+    // server did not do what was asked; accepting it would quietly turn an
+    // authenticated login into a bare access token nobody validated.
+    if (scopes.includes("openid") && !tokens.idToken) {
+      throw new OAuthError("invalid_response", "openid was requested but no id_token came back");
+    }
+    return tokens;
+  } finally {
+    listener.close();
+  }
+}

package/src/oauth/pkce.spec.ts

@@ -0,0 +1,60 @@
+import { createHash } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import { base64UrlEncode, createPkcePair, createStateToken, type PkceCrypto } from "./pkce";
+
+const sha256 = (input: Uint8Array) => new Uint8Array(createHash("sha256").update(input).digest());
+
+function base64UrlDecode(value: string): Uint8Array {
+  return new Uint8Array(Buffer.from(value.replace(/-/g, "+").replace(/_/g, "/"), "base64"));
+}
+
+function fixedCrypto(bytes: Uint8Array): PkceCrypto {
+  return { randomBytes: () => bytes, sha256 };
+}
+
+describe("base64UrlEncode", () => {
+  it("uses the URL-safe alphabet and strips padding", () => {
+    // 0xfb 0xff 0xbe encodes to "+/++" in standard base64.
+    expect(base64UrlEncode(new Uint8Array([0xfb, 0xff, 0xbe]))).toBe("-_--");
+    expect(base64UrlEncode(new Uint8Array([0x01]))).toBe("AQ");
+    expect(base64UrlEncode(new Uint8Array([]))).toBe("");
+  });
+});
+
+describe("createPkcePair", () => {
+  // RFC 7636 Appendix B publishes this verifier/challenge pair.
+  it("reproduces the RFC 7636 Appendix B test vector", () => {
+    const rfcVerifier = "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk";
+    const rfcChallenge = "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM";
+    const pair = createPkcePair(fixedCrypto(base64UrlDecode(rfcVerifier)));
+    expect(pair.verifier).toBe(rfcVerifier);
+    expect(pair.challenge).toBe(rfcChallenge);
+    expect(pair.method).toBe("S256");
+  });
+
+  it("produces a verifier within the length RFC 7636 §4.1 allows", () => {
+    const pair = createPkcePair(fixedCrypto(new Uint8Array(32).fill(7)));
+    expect(pair.verifier.length).toBeGreaterThanOrEqual(43);
+    expect(pair.verifier.length).toBeLessThanOrEqual(128);
+    expect(pair.verifier).toMatch(/^[A-Za-z0-9\-._~]+$/);
+  });
+
+  it("requests 32 bytes of entropy for the verifier", () => {
+    let requested = -1;
+    createPkcePair({
+      randomBytes: (length) => {
+        requested = length;
+        return new Uint8Array(length);
+      },
+      sha256,
+    });
+    expect(requested).toBe(32);
+  });
+});
+
+describe("createStateToken", () => {
+  it("encodes 16 random bytes", () => {
+    const state = createStateToken({ randomBytes: (length) => new Uint8Array(length).fill(1) });
+    expect(state).toBe(base64UrlEncode(new Uint8Array(16).fill(1)));
+  });
+});

package/src/oauth/pkce.ts

@@ -0,0 +1,80 @@
+/**
+ * File: /src/oauth/pkce.ts
+ * Project: @multiplatform.one/keycloak
+ *
+ * PKCE (RFC 7636) for public clients. A desktop app cannot keep a client
+ * secret, so the code verifier is what proves the app redeeming the
+ * authorization code is the same app that requested it.
+ *
+ * Crypto is injected rather than imported: the browser has WebCrypto, GJS has
+ * GLib.compute_checksum_for_bytes, and neither is reachable from the other.
+ * Keeping the primitive behind an interface is also what makes this file
+ * testable with fixed vectors.
+ */
+
+export interface PkceCrypto {
+  /** Cryptographically secure random bytes. */
+  randomBytes(length: number): Uint8Array;
+  /** Raw (not hex) SHA-256 digest. */
+  sha256(input: Uint8Array): Uint8Array;
+}
+
+export interface PkcePair {
+  verifier: string;
+  challenge: string;
+  method: "S256";
+}
+
+const base64UrlAlphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+/**
+ * base64url per RFC 4648 §5 — no padding, URL-safe alphabet.
+ *
+ * Hand-rolled rather than btoa/Buffer because this runs on all three of
+ * browsers, node (tests) and GJS, and GJS has neither of those globals.
+ */
+export function base64UrlEncode(bytes: Uint8Array): string {
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const remaining = bytes.length - i;
+    const chunk =
+      (bytes[i] << 16) |
+      ((remaining > 1 ? bytes[i + 1] : 0) << 8) |
+      (remaining > 2 ? bytes[i + 2] : 0);
+    out += base64UrlAlphabet[(chunk >> 18) & 63];
+    out += base64UrlAlphabet[(chunk >> 12) & 63];
+    // A 1-byte tail encodes to 2 chars, a 2-byte tail to 3 — the dropped
+    // characters are exactly what the "=" padding would have covered.
+    if (remaining > 1) out += base64UrlAlphabet[(chunk >> 6) & 63];
+    if (remaining > 2) out += base64UrlAlphabet[chunk & 63];
+  }
+  return out;
+}
+
+/**
+ * RFC 7636 §4.1 allows a 43–128 char verifier; 32 random bytes base64url-encode
+ * to 43 chars, the shortest length the spec considers secure.
+ */
+export function createPkcePair(crypto: PkceCrypto): PkcePair {
+  const verifier = base64UrlEncode(crypto.randomBytes(32));
+  const challenge = base64UrlEncode(crypto.sha256(new TextEncoder().encode(verifier)));
+  return { verifier, challenge, method: "S256" };
+}
+
+/** Opaque CSRF token echoed back on the redirect (RFC 6749 §10.12). */
+export function createStateToken(crypto: Pick<PkceCrypto, "randomBytes">): string {
+  return base64UrlEncode(crypto.randomBytes(16));
+}
+
+/**
+ * Replay defence for the ID token (OIDC Core §3.1.2.1). Sent on the
+ * authorization request and echoed in the id_token's `nonce` claim, so a
+ * token captured from one login cannot be presented as the result of another.
+ *
+ * Separate from the state token on purpose: state binds the *redirect* to
+ * this process, nonce binds the *token* to this authorization request, and
+ * reusing one value for both would leak the state into the token.
+ */
+export function createNonce(crypto: Pick<PkceCrypto, "randomBytes">): string {
+  return base64UrlEncode(crypto.randomBytes(16));
+}