@multiplatform.one/keycloak 6.7.0 → 7.1.0

package/src/provider/authProvider/index.native.tsx

@@ -12,9 +12,14 @@
  */
 
 import { useEffect, useMemo, useState } from "react";
+import { AppState, type AppStateStatus } from "react-native";
 import * as Linking from "expo-linking";
 import { Loading } from "../../Loading";
-import { createExpoAuthFlow } from "../../betterAuth/expoAuthFlow.native";
+import {
+  createExpoAuthFlow,
+  rewriteLoopbackHostForNative,
+} from "../../betterAuth/expoAuthFlow.native";
+import { clearKeycloakBearerToken } from "../../frappeToken.native";
 import { KeycloakConfigContext } from "../../keycloak/config";
 import { Keycloak } from "../../keycloak/index";
 import type { KeycloakLoginOptions, KeycloakLogoutOptions } from "../../keycloak/base";
@@ -35,8 +40,12 @@ export function AuthProvider({
   // Resolve the Better Auth server base URL from keycloak config.
   // On native, the keycloakConfig.url is the Keycloak server — the Better Auth
   // server is the app backend (CreateApp wires BETTER_AUTH_BASE_URL/BASE_URL).
+  // Loopback hosts are rewritten for the device (127.0.0.1 / 10.0.2.2): see
+  // rewriteLoopbackHostForNative.
   const serverBaseUrl = useMemo(() => {
-    return keycloakConfig.betterAuthBaseUrl || "http://localhost:8000";
+    return rewriteLoopbackHostForNative(
+      keycloakConfig.betterAuthBaseUrl || "http://localhost:8000",
+    );
   }, [keycloakConfig]);
 
   const scheme = useMemo(() => keycloakConfig.expoScheme, [keycloakConfig]);
@@ -72,11 +81,24 @@ export function AuthProvider({
           // can only receive exp:// redirects (Linking.createURL derives
           // exp://<host>/--/ there; the bare app scheme in dev builds).
           await flow.signIn("keycloak", options.redirectUri || Linking.createURL("/"));
+          // Drop any signed-out cooldown/stale token so the first Frappe
+          // request after sign-in fetches a fresh Bearer token.
+          clearKeycloakBearerToken();
           await refresh();
           return undefined;
         },
-        async (_options: KeycloakLogoutOptions) => {
-          await flow.signOut();
+        async (options: KeycloakLogoutOptions) => {
+          // Single sign-out: ends the Better Auth session AND rides the
+          // Keycloak end-session endpoint through the system browser (see
+          // expoAuthFlow.signOut). Only custom-scheme URLs make sense as the
+          // post-logout return on native; web-style paths fall back to the
+          // app's own runtime URL.
+          const redirectUri =
+            options.redirectUri && options.redirectUri.includes("://")
+              ? options.redirectUri
+              : Linking.createURL("/");
+          await flow.signOut(redirectUri);
+          clearKeycloakBearerToken();
           await refresh();
           return undefined;
         },
@@ -105,8 +127,19 @@ export function AuthProvider({
     refresh().finally(() => {
       if (alive) setIsLoading(false);
     });
+
+    // Re-probe when the app returns to the foreground: covers a completed
+    // ASWebAuthenticationSession whose Linking event arrived after dismiss,
+    // and a user who abandoned the end-session page (local jar already
+    // empty; this just refreshes the header).
+    const onAppState = (next: AppStateStatus) => {
+      if (next === "active") refresh().catch(() => undefined);
+    };
+    const appSub = AppState.addEventListener("change", onAppState);
+
     return () => {
       alive = false;
+      appSub.remove();
     };
   }, [disabled, flow, keycloakConfig]);
 

package/src/session/index.ts

@@ -6,7 +6,7 @@
  * Replaces the previous next-auth/react useSession.
  */
 
-import { isBrowser, isTauri } from "@multiplatform.one/platform";
+import { isBrowser } from "@multiplatform.one/platform";
 import { getAuthClient } from "../betterAuth/client";
 
 export interface Session {
@@ -37,7 +37,7 @@ let useSession = <R extends boolean = false>(
   return { session: null, status: "unauthenticated" };
 };
 
-if (isBrowser && !isTauri) {
+if (isBrowser) {
   useSession = <R extends boolean = false>(
     _options?: Record<string, unknown>,
   ): SessionContextValue<R> => {

package/src/state.ts

@@ -1,7 +1,10 @@
 import { createStore, useStore } from "@multiplatform.one/store";
-import { isBrowser, isIframe, isServer, isTauri } from "@multiplatform.one/platform";
+import { isBrowser, isIframe, isServer } from "@multiplatform.one/platform";
 
-export const persist = isIframe || isTauri || (!isBrowser && !isServer);
+// Browsers keep the session in a Better Auth cookie, so nothing to persist.
+// Everywhere else (iframes fed tokens by a parent, native, and the GNOME/GJS
+// target) the tokens are the only session there is.
+export const persist = isIframe || (!isBrowser && !isServer);
 
 export interface AuthTokenState {
   idToken: string;

package/types/betterAuth/expoAuthFlow.native.d.ts

@@ -1,6 +1,7 @@
 /**
- * Hand-rolled Better Auth flow for native (Expo) — fetch + expo-web-browser +
- * SecureStore, NO better-auth client packages.
+ * Hand-rolled Better Auth flow for native (Expo) — fetch + expo-web-browser
+ * (ASWebAuthenticationSession / Chrome Custom Tabs) + SecureStore, NO
+ * better-auth client packages.
  *
  * Why not @better-auth/expo/client: its import graph drags better-auth's
  * cookies module -> @better-auth/core db schema -> zod into the Hermes bundle,
@@ -12,7 +13,14 @@
  */
 export interface ExpoAuthFlow {
     signIn(provider: string, callbackURL?: string): Promise<void>;
-    signOut(): Promise<void>;
+    /**
+     * Ends the Better Auth session AND (when the server exposes the
+     * keycloak-sso plugin) the Keycloak SSO session, riding the OIDC
+     * end-session endpoint through the same browser that holds the SSO
+     * cookie. `postLogoutRedirectUri` is where that browser hands control
+     * back (defaults to the app's own runtime URL).
+     */
+    signOut(postLogoutRedirectUri?: string): Promise<void>;
     getSession(): Promise<{
         user?: {
             id: string;
@@ -26,6 +34,45 @@ export interface ExpoAuthFlow {
         accessTokenExpiresAt?: string;
     } | null>;
 }
+/**
+ * Rewrite a loopback host for the device the app actually runs on:
+ * `localhost` inside the iOS simulator can resolve to `::1`, where unrelated
+ * daemons may squat the port (the reason the web env pins 127.0.0.1), and
+ * Android emulators reach the host machine at 10.0.2.2, never loopback.
+ * Non-loopback hosts (LAN IPs, real domains) pass through untouched.
+ *
+ * String-based on purpose: React Native's minimal URL polyfill does not
+ * implement the `hostname` SETTER (reads work, mutation throws), so a
+ * new-URL-and-assign rewrite silently no-ops on device.
+ */
+export declare function rewriteLoopbackHostForNative(configured: string): string;
+/**
+ * Loosen a return URL for prefix matching: drop query/fragment and collapse
+ * the slash run after the scheme. `Linking.createURL("/")` yields
+ * `multiplatform-one:///` (empty authority) but iOS delivers the redirect as
+ * `multiplatform-one://?cookie=…` — a strict startsWith between the two
+ * misses, leaving the sign-in promise pending forever (observed on the
+ * 2026-08-13 simulator run).
+ */
+export declare function normalizeForReturnMatch(url: string): string;
+/**
+ * Give a bare-scheme URL (`multiplatform-one:///` — what Linking.createURL
+ * emits for custom app schemes: empty authority) a host segment. OIDC
+ * post-logout redirects need it: Keycloak's redirect builder (Java
+ * UriBuilder) throws "empty host" appending the `state` param to an
+ * authority-less URI, answering 500 "We are sorry" instead of returning to
+ * the app. URLs that already carry an authority (exp://host:port/…) pass
+ * through untouched.
+ */
+export declare function ensureReturnUrlAuthority(url: string, segment: string): string;
+/**
+ * Pull the Better Auth session cookie out of an OAuth return URL without
+ * `new URL()`. React Native's URL polyfill throws or drops search on
+ * authority-less custom schemes (`multiplatform-one://?cookie=…` — the
+ * shape iOS actually delivers). Mirrors `URLSearchParams.get("cookie")`
+ * including decodeURIComponent.
+ */
+export declare function extractCookieFromReturnUrl(returnUrl: string): string | null;
 export declare function getActiveExpoAuthFlow(): ExpoAuthFlow | null;
 export declare function createExpoAuthFlow(baseURL: string, scheme?: string): ExpoAuthFlow;
 //# sourceMappingURL=expoAuthFlow.native.d.ts.map

package/types/betterAuth/expoAuthFlow.native.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"expoAuthFlow.native.d.ts","sourceRoot":"","sources":["../../src/betterAuth/expoAuthFlow.native.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA6EH,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,UAAU,IAAI,OAAO,CAAC;QAAE,IAAI,CAAC,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IACvF,mEAAmE;IACnE,cAAc,CACZ,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,oBAAoB,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;CAC5E;AAOD,wBAAgB,qBAAqB,IAAI,YAAY,GAAG,IAAI,CAE3D;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAkIjF"}
+{"version":3,"file":"expoAuthFlow.native.d.ts","sourceRoot":"","sources":["../../src/betterAuth/expoAuthFlow.native.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAmFH,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,UAAU,IAAI,OAAO,CAAC;QAAE,IAAI,CAAC,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IACvF,mEAAmE;IACnE,cAAc,CACZ,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,oBAAoB,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;CAC5E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAGvE;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAsB3E;AAqED,wBAAgB,qBAAqB,IAAI,YAAY,GAAG,IAAI,CAE3D;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAgHjF"}

package/types/frappeToken.d.ts

@@ -11,6 +11,12 @@
  * cookie) and sends `Authorization: Bearer <token>` on every REST request
  * and socket handshake — the same transport native uses. The bench's
  * frappe_keycloak auth hook validates the JWT against the realm public key.
+ *
+ * Failures are classified, not collapsed:
+ * - 401/403, or 400 `FAILED_TO_GET_ACCESS_TOKEN` (server already decided
+ *   the refresh token is dead): signed-out cooldown + session notify.
+ * - 5xx `TOKEN_REFRESH_UNAVAILABLE`, other 5xx, network: retry with
+ *   backoff, keep the session. A Keycloak restart must not look like logout.
  */
 /**
  * Returns a valid Keycloak access token, or undefined when signed out.
@@ -19,9 +25,16 @@
  * concurrent data request: parallel callers share the in-flight fetch, and a
  * signed-out answer short-circuits further attempts for a few seconds. A real
  * sign-in arrives via the OAuth redirect (full navigation), which resets this
- * module state anyway.
+ * module state anyway. Transient Keycloak failures retry before giving up,
+ * and never start the signed-out cooldown.
  */
 export declare function getKeycloakBearerToken(): Promise<string | undefined>;
 /** Drop the cached token (sign-out / fresh sign-in). */
 export declare function clearKeycloakBearerToken(): void;
+/**
+ * Bust the client cache and re-fetch when the tab is focused again, so a
+ * front-channel logout (or Keycloak recovery) in another window is noticed
+ * without a full reload. Returns an unsubscribe. No-op on the server.
+ */
+export declare function watchKeycloakBearerTokenRevalidate(): () => void;
 //# sourceMappingURL=frappeToken.d.ts.map

package/types/frappeToken.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frappeToken.d.ts","sourceRoot":"","sources":["../src/frappeToken.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAUH;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAU1E;AAuCD,wDAAwD;AACxD,wBAAgB,wBAAwB,SAIvC"}
+{"version":3,"file":"frappeToken.d.ts","sourceRoot":"","sources":["../src/frappeToken.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAgDH;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAW1E;AA4DD,wDAAwD;AACxD,wBAAgB,wBAAwB,SAKvC;AAED;;;;GAIG;AACH,wBAAgB,kCAAkC,IAAI,MAAM,IAAI,CAiB/D"}

package/types/frappeToken.native.d.ts

@@ -8,8 +8,22 @@
  * from better-auth's /get-access-token endpoint (which refreshes server-side
  * when expired), authenticated with the SecureStore cookie jar.
  */
-/** Returns a valid Keycloak access token, or undefined when signed out. */
+/**
+ * Returns a valid Keycloak access token, or undefined when signed out.
+ *
+ * Signed-out clients get a single 401 per cooldown window instead of one per
+ * concurrent collection sync: parallel callers share the in-flight fetch, and
+ * a signed-out answer short-circuits further attempts for a few seconds. The
+ * AuthProvider clears this module state on sign-in / sign-out.
+ */
 export declare function getKeycloakBearerToken(): Promise<string | undefined>;
-/** Drop the cached token (sign-out). */
+/** Drop the cached token (sign-out / fresh sign-in). */
 export declare function clearKeycloakBearerToken(): void;
+/**
+ * Bust the client cache and re-fetch when the app returns to the
+ * foreground, so a completed ASWebAuthenticationSession (or an SLO in
+ * Safari that the Linking listener missed) is noticed without a reload.
+ * Returns an unsubscribe. AfterAuth mounts this once.
+ */
+export declare function watchKeycloakBearerTokenRevalidate(): () => void;
 //# sourceMappingURL=frappeToken.native.d.ts.map

package/types/frappeToken.native.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frappeToken.native.d.ts","sourceRoot":"","sources":["../src/frappeToken.native.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,2EAA2E;AAC3E,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAuB1E;AAED,wCAAwC;AACxC,wBAAgB,wBAAwB,SAEvC"}
+{"version":3,"file":"frappeToken.native.d.ts","sourceRoot":"","sources":["../src/frappeToken.native.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAaH;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAS1E;AA2BD,wDAAwD;AACxD,wBAAgB,wBAAwB,SAIvC;AAED;;;;;GAKG;AACH,wBAAgB,kCAAkC,IAAI,MAAM,IAAI,CAS/D"}

package/types/index.d.ts

@@ -6,5 +6,5 @@ export * from "./provider/index";
 export * from "./session/index";
 export * from "./token";
 export * from "./types";
-export { getKeycloakBearerToken } from "./frappeToken";
+export { getKeycloakBearerToken, watchKeycloakBearerTokenRevalidate } from "./frappeToken";
 //# sourceMappingURL=index.d.ts.map

package/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,sBAAsB,EAAE,kCAAkC,EAAE,MAAM,eAAe,CAAC"}

package/types/keycloak/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/keycloak/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,cAAc,MAAM,gCAAgC,CAAC;AAKjE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAEhD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,KAAK,oBAAoB,EAAE,KAAK,qBAAqB,EAAE,MAAM,QAAQ,CAAC;AAI7F,qBAAa,QAAS,SAAQ,YAAY;IACxC,SAAS,CAAC,kBAAkB,CAAC,KAAK,EAAE,cAAc,GAAG,YAAY,GAAG,OAAO;IAcrE,KAAK,CAAC,OAAO,GAAE,oBAAyB;IAgBxC,MAAM,CAAC,OAAO,GAAE,qBAA0B;CAqBjD;AAED,wBAAgB,WAAW,gCAwB1B;AAED,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/keycloak/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,cAAc,MAAM,gCAAgC,CAAC;AAMjE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAEhD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,KAAK,oBAAoB,EAAE,KAAK,qBAAqB,EAAE,MAAM,QAAQ,CAAC;AAI7F,qBAAa,QAAS,SAAQ,YAAY;IACxC,SAAS,CAAC,kBAAkB,CAAC,KAAK,EAAE,cAAc,GAAG,YAAY,GAAG,OAAO;IAcrE,KAAK,CAAC,OAAO,GAAE,oBAAyB;IAgBxC,MAAM,CAAC,OAAO,GAAE,qBAA0B;CAqCjD;AAED,wBAAgB,WAAW,gCAwB1B;AAED,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC"}

package/types/keycloak/index.webext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.webext.d.ts","sourceRoot":"","sources":["../../src/keycloak/index.webext.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,cAAc,MAAM,gCAAgC,CAAC;AAKjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,KAAK,oBAAoB,EAAE,KAAK,qBAAqB,EAAE,MAAM,QAAQ,CAAC;AAG7F,qBAAa,QAAS,SAAQ,YAAY;IACxC,SAAS,CAAC,kBAAkB,CAAC,KAAK,EAAE,cAAc,GAAG,YAAY;IAQ3D,KAAK,CAAC,OAAO,GAAE,oBAAyB;IAgBxC,MAAM,CAAC,OAAO,GAAE,qBAA0B;CAiBjD;AAED,wBAAgB,WAAW,4CAK1B;AAED,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.webext.d.ts","sourceRoot":"","sources":["../../src/keycloak/index.webext.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,cAAc,MAAM,gCAAgC,CAAC;AAMjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,KAAK,oBAAoB,EAAE,KAAK,qBAAqB,EAAE,MAAM,QAAQ,CAAC;AAG7F,qBAAa,QAAS,SAAQ,YAAY;IACxC,SAAS,CAAC,kBAAkB,CAAC,KAAK,EAAE,cAAc,GAAG,YAAY;IAQ3D,KAAK,CAAC,OAAO,GAAE,oBAAyB;IAgBxC,MAAM,CAAC,OAAO,GAAE,qBAA0B;CAgCjD;AAED,wBAAgB,WAAW,4CAK1B;AAED,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC"}

package/types/oauth/authorizationUrl.d.ts

@@ -0,0 +1,32 @@
+/**
+ * File: /src/oauth/authorizationUrl.ts
+ * Project: @multiplatform.one/keycloak
+ */
+import type { OidcEndpoints } from "./endpoints";
+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 declare const defaultScopes: string[];
+export declare function buildAuthorizationUrl({ endpoints, clientId, redirectUri, state, codeChallenge, nonce, scopes, prompt, loginHint, }: AuthorizationUrlParams): string;
+export interface LogoutUrlParams {
+    endpoints: OidcEndpoints;
+    clientId: string;
+    idToken?: string;
+    postLogoutRedirectUri?: string;
+}
+export declare function buildLogoutUrl({ endpoints, clientId, idToken, postLogoutRedirectUri, }: LogoutUrlParams): string;
+//# sourceMappingURL=authorizationUrl.d.ts.map

package/types/oauth/authorizationUrl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorizationUrl.d.ts","sourceRoot":"","sources":["../../src/oauth/authorizationUrl.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,aAAa,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,gBAAgB,CAAC;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,aAAa,UAAiC,CAAC;AAE5D,wBAAgB,qBAAqB,CAAC,EACpC,SAAS,EACT,QAAQ,EACR,WAAW,EACX,KAAK,EACL,aAAa,EACb,KAAK,EACL,MAAsB,EACtB,MAAM,EACN,SAAS,GACV,EAAE,sBAAsB,GAAG,MAAM,CAajC;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,aAAa,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,wBAAgB,cAAc,CAAC,EAC7B,SAAS,EACT,QAAQ,EACR,OAAO,EACP,qBAAqB,GACtB,EAAE,eAAe,GAAG,MAAM,CAQ1B"}

package/types/oauth/callback.d.ts

@@ -0,0 +1,26 @@
+/**
+ * File: /src/oauth/callback.ts
+ * Project: @multiplatform.one/keycloak
+ */
+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 declare function isCallbackForState(query: CallbackQuery, expectedState: string): boolean;
+/**
+ * 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 declare function parseAuthorizationCallback(query: CallbackQuery, expectedState: string): string;
+//# sourceMappingURL=callback.d.ts.map

package/types/oauth/callback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"callback.d.ts","sourceRoot":"","sources":["../../src/oauth/callback.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAE/D;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAEvF;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAc9F"}

package/types/oauth/callbackPage.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 declare function escapeHtml(value: string): string;
+export interface CallbackPageContent {
+    heading: string;
+    detail: string;
+}
+export declare const callbackPageSuccess: CallbackPageContent;
+export declare const callbackPageFailure: CallbackPageContent;
+export declare function renderCallbackPage({ heading, detail }: CallbackPageContent): string;
+//# sourceMappingURL=callbackPage.d.ts.map

package/types/oauth/callbackPage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"callbackPage.d.ts","sourceRoot":"","sources":["../../src/oauth/callbackPage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOhD;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,mBAAmB,EAAE,mBAGjC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,mBAGjC,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,mBAAmB,GAAG,MAAM,CAMnF"}

package/types/oauth/endpoints.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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.
+ */
+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;
+}
+/**
+ * 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 declare function assertSecureIssuer({ url, allowInsecureLoopbackHttp }: RealmLocation): void;
+export declare function keycloakEndpoints(location: RealmLocation): OidcEndpoints;
+export {};
+//# sourceMappingURL=endpoints.d.ts.map

package/types/oauth/endpoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoints.d.ts","sourceRoot":"","sources":["../../src/oauth/endpoints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,CAAC,MAAM,kBAAkB,EAAE,OAAO,MAAM,CAAC;AAEhD,MAAM,WAAW,aAAa;IAC5B;;;;;;;;OAQG;IACH,QAAQ,CAAC,CAAC,kBAAkB,CAAC,EAAE,IAAI,CAAC;IACpC,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,wDAAwD;IACxD,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;;;OAUG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAC;CACrC;AAuBD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,GAAG,EAAE,yBAAyB,EAAE,EAAE,aAAa,GAAG,IAAI,CA0B1F;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,aAAa,GAAG,aAAa,CAexE"}

package/types/oauth/errors.d.ts

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

package/types/oauth/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/oauth/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,8EAA8E;AAC9E,qBAAa,UAAW,SAAQ,KAAK;IAEjC,kEAAkE;aAClD,IAAI,EAAE,MAAM;IAE5B,+DAA+D;aAC/C,WAAW,CAAC,EAAE,MAAM;;IAJpC,kEAAkE;IAClD,IAAI,EAAE,MAAM,EAC5B,OAAO,CAAC,EAAE,MAAM;IAChB,+DAA+D;IAC/C,WAAW,CAAC,EAAE,MAAM,YAAA;CAKvC"}

package/types/oauth/form.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 declare function encodeForm(params: Record<string, string>): string;
+//# sourceMappingURL=form.d.ts.map

package/types/oauth/form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form.d.ts","sourceRoot":"","sources":["../../src/oauth/form.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAIjE"}

package/types/oauth/idToken.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 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.
+ */
+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;
+}
+/**
+ * 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 declare function validateIdToken(idToken: string, validation: IdTokenValidation): IdTokenClaims;
+//# sourceMappingURL=idToken.d.ts.map

package/types/oauth/idToken.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idToken.d.ts","sourceRoot":"","sources":["../../src/oauth/idToken.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAKH,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAiBD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,iBAAiB,GAAG,aAAa,CAkD7F"}

package/types/oauth/index.d.ts

@@ -0,0 +1,11 @@
+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";
+//# sourceMappingURL=index.d.ts.map

package/types/oauth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/oauth/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,OAAO,CAAC;AACtB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,QAAQ,CAAC;AACvB,cAAc,iBAAiB,CAAC"}