@multiplatform.one/keycloak 6.7.0 → 7.1.0

package/src/oauth/form.spec.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { encodeForm } from "./form";
+
+describe("encodeForm", () => {
+  it("joins pairs with & and =", () => {
+    expect(encodeForm({ a: "1", b: "2" })).toBe("a=1&b=2");
+  });
+
+  it("encodes byte for byte the way URLSearchParams does", () => {
+    // The point of this file is to be a drop-in for URLSearchParams on
+    // runtimes that lack it, so pin that equivalence rather than the escapes.
+    for (const value of [
+      "hello world",
+      "a+b",
+      "a&b=c",
+      "tok-_.~!*()'",
+      "http://127.0.0.1:8080/cb?x=1",
+      "realm/with space",
+      "öäü",
+      "openid profile email",
+      "",
+    ]) {
+      expect(encodeForm({ k: value })).toBe(new URLSearchParams({ k: value }).toString());
+    }
+  });
+
+  it("encodes keys as well as values", () => {
+    expect(encodeForm({ "a key": "v" })).toBe(new URLSearchParams({ "a key": "v" }).toString());
+  });
+
+  it("round-trips through a URLSearchParams parse", () => {
+    const params = { grant_type: "authorization_code", code_verifier: "aB-_09~x", scope: "a b" };
+    expect(Object.fromEntries(new URLSearchParams(encodeForm(params)))).toEqual(params);
+  });
+});

package/src/oauth/form.ts

@@ -0,0 +1,30 @@
+/**
+ * File: /src/oauth/form.ts
+ * Project: @multiplatform.one/keycloak
+ *
+ * application/x-www-form-urlencoded serialization.
+ *
+ * URLSearchParams would do this in one line, but GJS has no such global —
+ * the GNOME app only gets one from the react-gnome polyfills, and the auth
+ * entries deliberately run without them. Twelve lines here keeps the OAuth
+ * core dependent on nothing but the language.
+ *
+ * Matches URLSearchParams byte for byte, including the space-as-"+" rule that
+ * the form-urlencoded media type requires.
+ */
+
+export function encodeForm(params: Record<string, string>): string {
+  return Object.entries(params)
+    .map(([key, value]) => `${encodeFormComponent(key)}=${encodeFormComponent(value)}`)
+    .join("&");
+}
+
+function encodeFormComponent(value: string): string {
+  return (
+    encodeURIComponent(value)
+      .replace(/%20/g, "+")
+      // encodeURIComponent leaves these unescaped, but they are reserved in a
+      // query component, so URLSearchParams escapes them.
+      .replace(/[!'()~]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`)
+  );
+}

package/src/oauth/idToken.spec.ts

@@ -0,0 +1,191 @@
+import { randomBytes } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import { base64UrlDecode, decodeJwt } from "./jwt";
+import { type IdTokenClaims, validateIdToken } from "./idToken";
+import { base64UrlEncode } from "./pkce";
+
+const issuer = "https://kc.example.com/realms/myrealm";
+const clientId = "app-public";
+const now = 1_700_000_000;
+
+function segment(value: unknown): string {
+  return base64UrlEncode(new TextEncoder().encode(JSON.stringify(value)));
+}
+
+function mintIdToken(claims: Partial<IdTokenClaims>, header: Record<string, unknown> = {}): string {
+  return [
+    segment({ alg: "RS256", typ: "JWT", kid: "abc", ...header }),
+    segment({
+      iss: issuer,
+      aud: clientId,
+      azp: clientId,
+      sub: "3f6c1e2a-user",
+      exp: now + 300,
+      iat: now - 5,
+      ...claims,
+    }),
+    "not-a-real-signature",
+  ].join(".");
+}
+
+const validation = { issuer, clientId, now };
+
+describe("base64UrlDecode", () => {
+  it("round-trips base64UrlEncode over random inputs of every tail length", () => {
+    for (let length = 0; length <= 64; length++) {
+      const bytes = new Uint8Array(randomBytes(length));
+      expect(Array.from(base64UrlDecode(base64UrlEncode(bytes)))).toEqual(Array.from(bytes));
+    }
+  });
+
+  it("matches node's base64url decoder over 2000 random inputs", () => {
+    for (let i = 0; i < 2000; i++) {
+      const bytes = randomBytes(Math.floor(Math.random() * 96));
+      const encoded = bytes.toString("base64url");
+      expect(Array.from(base64UrlDecode(encoded))).toEqual(Array.from(bytes));
+    }
+  });
+
+  it("accepts the padded form node also accepts", () => {
+    expect(new TextDecoder().decode(base64UrlDecode("aGk="))).toBe("hi");
+  });
+
+  it("rejects a character outside the url-safe alphabet", () => {
+    expect(() => base64UrlDecode("ab+c")).toThrow(/outside the alphabet/);
+  });
+
+  it("rejects an impossible length", () => {
+    expect(() => base64UrlDecode("abcde")).toThrow(/impossible length/);
+  });
+});
+
+describe("decodeJwt", () => {
+  it("decodes the header and payload without touching the signature", () => {
+    const decoded = decodeJwt(mintIdToken({}));
+    expect(decoded.header.alg).toBe("RS256");
+    expect(decoded.payload.sub).toBe("3f6c1e2a-user");
+    expect(decoded.signature).toBe("not-a-real-signature");
+  });
+
+  it("rejects a token that is not three segments", () => {
+    expect(() => decodeJwt("only.two")).toThrow(/three base64url segments/);
+  });
+
+  it("rejects a payload that is not a json object", () => {
+    expect(() => decodeJwt(`${segment({ alg: "RS256" })}.${segment([1, 2])}.sig`)).toThrow(
+      /not a json object/,
+    );
+  });
+});
+
+describe("validateIdToken", () => {
+  it("accepts a token from the expected issuer for this client", () => {
+    const claims = validateIdToken(mintIdToken({}), validation);
+    expect(claims.sub).toBe("3f6c1e2a-user");
+  });
+
+  it("rejects a token from a different issuer", () => {
+    const token = mintIdToken({ iss: "https://evil.example.com/realms/myrealm" });
+    expect(() => validateIdToken(token, validation)).toThrow(/iss .* is not/);
+  });
+
+  it("rejects a token minted for a sibling client in the same realm", () => {
+    const token = mintIdToken({ aud: "other-client", azp: "other-client" });
+    expect(() => validateIdToken(token, validation)).toThrow(/does not include app-public/);
+  });
+
+  it("rejects a token whose azp is a different client even when aud fits", () => {
+    const token = mintIdToken({ aud: clientId, azp: "other-client" });
+    expect(() => validateIdToken(token, validation)).toThrow(/azp .* is not app-public/);
+  });
+
+  it("accepts a multi-audience token that names this client in azp", () => {
+    const token = mintIdToken({ aud: [clientId, "account"], azp: clientId });
+    expect(validateIdToken(token, validation).azp).toBe(clientId);
+  });
+
+  it("rejects a multi-audience token with no azp", () => {
+    const token = mintIdToken({ aud: [clientId, "account"], azp: undefined });
+    expect(() => validateIdToken(token, validation)).toThrow(/multiple values but azp is missing/);
+  });
+
+  it("rejects an expired token", () => {
+    expect(() => validateIdToken(mintIdToken({ exp: now - 3600 }), validation)).toThrow(
+      /exp is in the past/,
+    );
+  });
+
+  it("allows a token that expired within the clock tolerance", () => {
+    const token = mintIdToken({ exp: now - 30 });
+    expect(validateIdToken(token, validation).exp).toBe(now - 30);
+  });
+
+  it("rejects a token with no exp", () => {
+    expect(() => validateIdToken(mintIdToken({ exp: undefined }), validation)).toThrow(
+      /exp is missing/,
+    );
+  });
+
+  it("rejects a token issued in the future", () => {
+    expect(() => validateIdToken(mintIdToken({ iat: now + 3600 }), validation)).toThrow(
+      /iat is in the future/,
+    );
+  });
+
+  it("rejects a token that is not yet valid", () => {
+    expect(() => validateIdToken(mintIdToken({ nbf: now + 3600 }), validation)).toThrow(
+      /nbf is in the future/,
+    );
+  });
+
+  it("rejects an unsecured jwt", () => {
+    expect(() => validateIdToken(mintIdToken({}, { alg: "none" }), validation)).toThrow(/alg=none/);
+  });
+
+  it("rejects a header with no alg", () => {
+    expect(() => validateIdToken(mintIdToken({}, { alg: undefined }), validation)).toThrow(
+      /header has no alg/,
+    );
+  });
+
+  it("rejects a token with no sub", () => {
+    expect(() => validateIdToken(mintIdToken({ sub: undefined }), validation)).toThrow(
+      /sub is missing/,
+    );
+  });
+
+  it("rejects a replayed token whose nonce belongs to another login", () => {
+    const token = mintIdToken({ nonce: "nonce-from-an-earlier-login" });
+    expect(() => validateIdToken(token, { ...validation, nonce: "this-logins-nonce" })).toThrow(
+      /nonce does not match/,
+    );
+  });
+
+  it("rejects a token with no nonce when one was requested", () => {
+    expect(() => validateIdToken(mintIdToken({}), { ...validation, nonce: "n" })).toThrow(
+      /nonce does not match/,
+    );
+  });
+
+  it("accepts the matching nonce", () => {
+    const token = mintIdToken({ nonce: "this-logins-nonce" });
+    expect(validateIdToken(token, { ...validation, nonce: "this-logins-nonce" }).nonce).toBe(
+      "this-logins-nonce",
+    );
+  });
+
+  it("skips the nonce check on the refresh grant, where none is supplied", () => {
+    const token = mintIdToken({ nonce: "nonce-from-the-original-login" });
+    expect(validateIdToken(token, validation).sub).toBe("3f6c1e2a-user");
+  });
+
+  it("raises an OAuthError with a stable code so callers can branch on it", () => {
+    expect(() => validateIdToken(mintIdToken({ exp: now - 3600 }), validation)).toThrow(
+      expect.objectContaining({ code: "invalid_id_token" }),
+    );
+  });
+
+  it("rejects a token that is not a jwt at all", () => {
+    expect(() => validateIdToken("fake-id-token", validation)).toThrow(/three base64url segments/);
+  });
+});

package/src/oauth/idToken.ts

@@ -0,0 +1,153 @@
+/**
+ * File: /src/oauth/idToken.ts
+ * Project: @multiplatform.one/keycloak
+ *
+ * ID token validation for the loopback flow (OIDC Core §3.1.3.7).
+ *
+ * ## What is checked, and what is deliberately not
+ *
+ * Checked: `iss`, `aud`, `azp`, `exp`, `iat`, `nbf`, `nonce`, `sub`, and that
+ * the header does not claim `alg: none`.
+ *
+ * **Not checked: the signature.** This is a deliberate decision, not an
+ * oversight, and it rests on a precondition that is enforced rather than
+ * assumed. OIDC Core §3.1.3.7 rule 6 says a client MAY skip signature
+ * validation when the ID token is received "directly from the Token Endpoint"
+ * over a TLS-protected channel, because TLS server authentication already
+ * proves who minted it. Both halves of that are true here and neither is left
+ * to chance:
+ *
+ *   1. *Directly from the token endpoint.* `validateIdToken` is only ever
+ *      called from `tokenExchange.ts`, on the parsed body of a POST this
+ *      process just made to `endpoints.token`. No ID token from a redirect,
+ *      a front channel or a caller reaches it — there is no implicit flow
+ *      here and no `response_type` that returns a token on the redirect.
+ *   2. *Over TLS.* `keycloakEndpoints` refuses to derive a token endpoint for
+ *      a plaintext issuer unless the host is loopback **and** the caller
+ *      passed `allowInsecureLoopbackHttp`. See endpoints.ts.
+ *
+ * The alternative is a JWKS fetch plus RS256 verification, and it is not
+ * available: GJS has no `node:crypto` and no WebCrypto (`globalThis.crypto`
+ * is undefined as of gjs 1.88), so RSA verification would mean hand-rolling
+ * modular exponentiation over bignums in JavaScript. Hand-rolled RSA in an
+ * auth path is a worse risk than the carve-out the spec explicitly grants.
+ *
+ * If this code ever accepts an ID token from anywhere other than a direct
+ * token-endpoint response — a front-channel redirect, a push from a server,
+ * a cached token from another process — the carve-out stops applying and the
+ * signature has to be verified for real.
+ *
+ * ## What the carve-out does not excuse
+ *
+ * Nothing above says anything about the claims. A validly-signed token minted
+ * for a different client in the same realm, or one that expired last week, is
+ * still the wrong token; `azp`/`aud` and `exp` are what catch those, and they
+ * are checked unconditionally.
+ */
+
+import { OAuthError } from "./errors";
+import { decodeJwt } from "./jwt";
+
+export interface IdTokenClaims {
+  iss?: string;
+  aud?: string | string[];
+  azp?: string;
+  exp?: number;
+  iat?: number;
+  nbf?: number;
+  nonce?: string;
+  sub?: string;
+  [claim: string]: unknown;
+}
+
+export interface IdTokenValidation {
+  /** `endpoints.issuer` — the exact string the `iss` claim must equal. */
+  issuer: string;
+  clientId: string;
+  /**
+   * The nonce sent on the authorization request. When supplied the token's
+   * `nonce` must match it exactly, which is what stops a token captured from
+   * one login being replayed into another.
+   *
+   * Omitted only on the refresh grant, where there is no fresh authorization
+   * request to bind to and the token store does not carry the original nonce
+   * across process restarts. The refreshed token is still bound to this
+   * client by `azp`/`aud` and to this realm by `iss`.
+   */
+  nonce?: string;
+  /** Epoch seconds. Injected by tests; defaults to the wall clock. */
+  now?: number;
+  /** Allowance for clock skew between this machine and Keycloak. */
+  clockToleranceSeconds?: number;
+}
+
+const defaultClockToleranceSeconds = 60;
+
+function reject(detail: string): never {
+  throw new OAuthError("invalid_id_token", `id token rejected: ${detail}`);
+}
+
+function numericClaim(claims: IdTokenClaims, name: "exp" | "iat" | "nbf"): number | undefined {
+  const value = claims[name];
+  if (value === undefined) return undefined;
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    reject(`${name} is not a number`);
+  }
+  return value;
+}
+
+/**
+ * Validate an ID token that came straight off a token-endpoint response, and
+ * return its claims. Throws `OAuthError("invalid_id_token")` on any failure.
+ */
+export function validateIdToken(idToken: string, validation: IdTokenValidation): IdTokenClaims {
+  const { header, payload } = decodeJwt(idToken);
+  const claims = payload as IdTokenClaims;
+  const now = validation.now ?? Math.floor(Date.now() / 1000);
+  const tolerance = validation.clockToleranceSeconds ?? defaultClockToleranceSeconds;
+
+  // `alg: none` is an unsecured JWT (RFC 7519 §6). We do not verify the
+  // signature, but a token that announces it does not have one was not
+  // produced by Keycloak's token endpoint and should not be humoured.
+  const alg = header.alg;
+  if (typeof alg !== "string" || !alg) reject("header has no alg");
+  if (alg.toLowerCase() === "none") reject("header declares alg=none");
+
+  if (claims.iss !== validation.issuer) {
+    reject(`iss ${JSON.stringify(claims.iss)} is not ${JSON.stringify(validation.issuer)}`);
+  }
+
+  const audiences =
+    typeof claims.aud === "string" ? [claims.aud] : Array.isArray(claims.aud) ? claims.aud : [];
+  if (!audiences.length) reject("aud is missing");
+  if (!audiences.includes(validation.clientId)) {
+    reject(`aud ${JSON.stringify(claims.aud)} does not include ${validation.clientId}`);
+  }
+  // OIDC Core §2: azp is REQUIRED when the token has more than one audience,
+  // and when present it must be this client. It is the claim that stops a
+  // token minted for a sibling client in the same realm being replayed here.
+  if (claims.azp === undefined) {
+    if (audiences.length > 1) reject("aud has multiple values but azp is missing");
+  } else if (claims.azp !== validation.clientId) {
+    reject(`azp ${JSON.stringify(claims.azp)} is not ${validation.clientId}`);
+  }
+
+  const exp = numericClaim(claims, "exp");
+  if (exp === undefined) reject("exp is missing");
+  if (now >= exp + tolerance) reject("exp is in the past");
+
+  const iat = numericClaim(claims, "iat");
+  if (iat === undefined) reject("iat is missing");
+  if (iat > now + tolerance) reject("iat is in the future");
+
+  const nbf = numericClaim(claims, "nbf");
+  if (nbf !== undefined && now < nbf - tolerance) reject("nbf is in the future");
+
+  if (validation.nonce !== undefined && claims.nonce !== validation.nonce) {
+    reject("nonce does not match the authorization request");
+  }
+
+  if (typeof claims.sub !== "string" || !claims.sub) reject("sub is missing");
+
+  return claims;
+}

package/src/oauth/index.ts

@@ -0,0 +1,10 @@
+export * from "./authorizationUrl";
+export * from "./callback";
+export * from "./callbackPage";
+export * from "./endpoints";
+export * from "./errors";
+export * from "./idToken";
+export * from "./jwt";
+export * from "./loopbackFlow";
+export * from "./pkce";
+export * from "./tokenExchange";

package/src/oauth/jwt.ts

@@ -0,0 +1,90 @@
+/**
+ * File: /src/oauth/jwt.ts
+ * Project: @multiplatform.one/keycloak
+ *
+ * Unverified JWT decoding — the inverse of pkce.ts's base64url encoder, and
+ * hand-rolled for the same reason: GJS has no `atob` and no `Buffer`, and the
+ * OAuth core has to run unchanged on GJS, node and the browser.
+ *
+ * "Unverified" is load-bearing. Nothing in this file looks at the signature.
+ * Decoding a JWT tells you what the bytes claim, not whether the claim is
+ * true; `validateIdToken` in idToken.ts is what turns the former into the
+ * latter, and it is the only thing that should be feeding these results into
+ * a decision.
+ */
+
+import { OAuthError } from "./errors";
+
+const base64UrlAlphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+const base64UrlValues: Record<string, number> = {};
+for (let i = 0; i < base64UrlAlphabet.length; i++) base64UrlValues[base64UrlAlphabet[i]] = i;
+
+/**
+ * base64url per RFC 4648 §5 — URL-safe alphabet, padding optional.
+ *
+ * Strict on input: an unknown character or a 1-character tail (which no
+ * base64 encoding can produce) is a malformed token, not something to
+ * silently round down.
+ */
+export function base64UrlDecode(value: string): Uint8Array {
+  const input = value.replace(/=+$/, "");
+  if (input.length % 4 === 1) {
+    throw new OAuthError("invalid_token", "base64url input has an impossible length");
+  }
+  const bytes = new Uint8Array(Math.floor((input.length * 3) / 4));
+  let out = 0;
+  for (let i = 0; i < input.length; i += 4) {
+    const remaining = input.length - i;
+    let chunk = 0;
+    for (let j = 0; j < 4; j++) {
+      const sextet = j < remaining ? base64UrlValues[input[i + j]] : 0;
+      if (sextet === undefined) {
+        throw new OAuthError(
+          "invalid_token",
+          "base64url input has a character outside the alphabet",
+        );
+      }
+      chunk = (chunk << 6) | sextet;
+    }
+    bytes[out++] = (chunk >> 16) & 255;
+    // A 2-character tail carries 1 byte, a 3-character tail 2 — the rest is
+    // the padding bits, which must be dropped rather than emitted as zeros.
+    if (remaining > 2) bytes[out++] = (chunk >> 8) & 255;
+    if (remaining > 3) bytes[out++] = chunk & 255;
+  }
+  return bytes;
+}
+
+function decodeJsonSegment(segment: string, what: string): Record<string, unknown> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(new TextDecoder().decode(base64UrlDecode(segment)));
+  } catch {
+    throw new OAuthError("invalid_token", `jwt ${what} is not base64url-encoded json`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new OAuthError("invalid_token", `jwt ${what} is not a json object`);
+  }
+  return parsed as Record<string, unknown>;
+}
+
+export interface DecodedJwt {
+  header: Record<string, unknown>;
+  payload: Record<string, unknown>;
+  /** Present so a caller can see there is one; nothing here verifies it. */
+  signature: string;
+}
+
+/** Decode a compact-serialization JWS without verifying anything about it. */
+export function decodeJwt(token: string): DecodedJwt {
+  const parts = token.split(".");
+  if (parts.length !== 3 || !parts[0] || !parts[1]) {
+    throw new OAuthError("invalid_token", "jwt is not three base64url segments");
+  }
+  return {
+    header: decodeJsonSegment(parts[0], "header"),
+    payload: decodeJsonSegment(parts[1], "payload"),
+    signature: parts[2],
+  };
+}