oidc-spa 6.15.1 → 7.0.0

package/README.md

@@ -5,9 +5,6 @@
     <a href="https://github.com/keycloakify/oidc-spa/actions">
       <img src="https://github.com/keycloakify/oidc-spa/actions/workflows/ci.yaml/badge.svg?branch=main">
     </a>
-    <a href="https://bundlephobia.com/package/oidc-spa">
-      <img src="https://img.shields.io/bundlephobia/minzip/oidc-spa">
-    </a>
     <a href="https://www.npmjs.com/package/oidc-spa">
       <img src="https://img.shields.io/npm/dw/oidc-spa">
     </a>
@@ -27,9 +24,11 @@
   <a href="https://docs.oidc-spa.dev">Documentation</a>
 </p>
 
+> 🗣️ oidc-spa will be introduced at [KeyConf 2025](https://keyconf.dev/) on the 28 of August.
+
 A full-featured OpenID Connect / OAuth2 client for single-page applications (SPAs).
 
-With `oidc-spa`, you can seamlessly integrate authentication providers like [Keycloak](https://www.keycloak.org/), [Auth0](https://auth0.com/), or [Microsoft Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id) into your application, purely on the client side—
+With `oidc-spa`, you can seamlessly integrate authentication providers like [Keycloak](https://www.keycloak.org/), [Auth0](https://auth0.com/), or [Microsoft Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id) into your application, purely on the client side,
 [without involving your backend in the token exchange](https://docs.oidc-spa.dev/resources/why-no-client-secret).
 
 In **simple terms**, `oidc-spa` is a library that makes it easy to **add authentication** to your Vite or Create-React-App project.  
@@ -60,12 +59,12 @@ These libraries are **tied to a specific provider**. But what if you need to:
 
 And besides, not all SDKs are equal in terms of setup simplicity, performance, and API quality.
 
-We wanted a **universal solution**—one that is as good or better than all existing SDKs in every aspect.
+We wanted a **universal solution**, one that is as good or better than all existing SDKs in every aspect.
 
 ## Features
 
 -   🎓 **No OIDC/OAuth2 expertise required**: Easy to setup and use. We're here to help [on Discord](https://discord.gg/mJdYJSdcm4)!
--   🛠️ **Simple setup**: No need to define `/login` or `/logout` routes—token refreshing is automatic, it just works.
+-   🛠️ **Simple setup**: No need to define `/login` or `/logout` routes, token refreshing is automatic, it just works.
 -   ✨ **React integration**: Expose a framework agnostic API but also a React adapter `oidc-spa/react`.
 -   🔥 **No limitation**- For example, everything you could do with `keycloak-js`, you can do with `oidc-spa`.
 -   💬 **Detailed debug messages**: If your OIDC server is not properly configured, it tells you precisely what’s wrong and what you need to do to fix it.
@@ -73,23 +72,23 @@ We wanted a **universal solution**—one that is as good or better than all exis
 -   🚪 **Logout propagation**: Logging out in one tab logs out all others.
 -   📖 **Comprehensive documentation**: Guides and examples for common scenarios.
 -   ✅ **Type safety**: Strong TypeScript support with optional [Zod](https://zod.dev/) integration validating the expected shape of the ID token.
--   🔒 **Security-first**: Uses [**Authorization Code Flow + PKCE**](https://docs.oidc-spa.dev/resources/why-no-client-secret#id-2.-authorization-code-flow--pkce-used-by-oidc-spa)—No token persistence in `localStorage` or `sessionStorage`.
+-   🔒 **Security-first**: Uses [**Authorization Code Flow + PKCE**](https://docs.oidc-spa.dev/resources/why-no-client-secret#id-2.-authorization-code-flow--pkce-used-by-oidc-spa), No token persistence in `localStorage` or `sessionStorage`.
 -   🖥️ **Optional backend utilities**: Provides tools for token validation in JavaScript backends (Node.js, Deno, Web Workers).
--   🔗 **Multi-instance support**: Run multiple `oidc-spa` instances—for example, to offer **Login with Google OR Microsoft** in the same app.
--   🍪 **No third-party cookie issues**: Third-party cookies blocked? No problem—`oidc-spa` works around it automatically with no special measures needed on your side.
+-   🍪 **No third-party cookie issues**: Third-party cookies blocked? No problem, `oidc-spa` works around it automatically with no special measures needed on your side.
+-   🔗 **Multi-instance support**: Run multiple `oidc-spa` instances in the same app without conflict.
 
 ## Comparison with Existing Libraries
 
 ### [oidc-client-ts](https://github.com/authts/oidc-client-ts)
 
 While `oidc-client-ts` is a comprehensive toolkit designed for various applications, `oidc-spa` is specifically built for SPAs with an easy-to-set-up API.  
-But **ease of use** isn't the only difference—`oidc-spa` also provides **out-of-the-box** solutions for features that `oidc-client-ts` leaves up to you to implement, such as:
+But **ease of use** isn't the only difference, `oidc-spa` also provides **out-of-the-box** solutions for features that `oidc-client-ts` leaves up to you to implement, such as:
 
 -   **Login/logout propagation** across tabs
 -   **Graceful fallback when third-party cookies are blocked**
 -   **Seamless browser back/forward cache (bfcache) management**
 -   **Auto logout countdown** so users can be automatically logged out after a set period of inactivity.
--   **Ensuring you never get an expired access token error**—even after the computer wakes up from sleep.
+-   **Ensuring you never get an expired access token error**, even after the computer wakes up from sleep.
 -   **Gracefully handles scenarios where the provider does not issue a refresh token or lacks a logout endpoint** (e.g., Google OAuth)
 
 ### [react-oidc-context](https://github.com/authts/react-oidc-context)
@@ -100,7 +99,7 @@ But **ease of use** isn't the only difference—`oidc-spa` also provides **out-o
 ### [keycloak-js](https://www.npmjs.com/package/keycloak-js)
 
 The official OIDC Client for Keycloak. It only works with Keycloak and [will eventually be deprecated](https://www.keycloak.org/2023/03/adapter-deprecation-update).  
-Beyond that, achieving the same seamless user experience as `oidc-spa` with `keycloak-js` requires writing a lot of custom code—code that really **shouldn’t** be handled at the application level.
+Beyond that, achieving the same seamless user experience as `oidc-spa` with `keycloak-js` requires writing a lot of custom code, code that really **shouldn’t** be handled at the application level.
 
 ### [NextAuth.js](https://next-auth.js.org/)
 
@@ -164,7 +163,7 @@ Project backers, we trust and recommend their services.
 
 This library isn't a theoretical exercise or a tool for hobby projects.  
 We developed it to solve real-world problems we faced ourselves.  
-Today, it powers authentication for [Onyxia](https://onyxia.sh)—  
+Today, it powers authentication for [Onyxia](https://onyxia.sh),  
 a data science platform deployed across multiple large organizations.
 
 ### Onyxia

package/core/Oidc.d.ts

@@ -1,5 +1,5 @@
 import type { OidcInitializationError } from "./OidcInitializationError";
-export declare type Oidc<DecodedIdToken extends Record<string, unknown> = Record<string, unknown>> = Oidc.LoggedIn<DecodedIdToken> | Oidc.NotLoggedIn;
+export declare type Oidc<DecodedIdToken extends Record<string, unknown> = Oidc.Tokens.DecodedIdToken_base> = Oidc.LoggedIn<DecodedIdToken> | Oidc.NotLoggedIn;
 export declare namespace Oidc {
     type Common = {
         params: {
@@ -35,16 +35,7 @@ export declare namespace Oidc {
         renewTokens(params?: {
             extraTokenParams?: Record<string, string | undefined>;
         }): Promise<void>;
-        /**
-         * Prefer using getTokens_next(), in the next major getTokens() will be be async.
-         *
-         * The problem is that When the computer wakes up from sleep, the tokens might have expired so
-         * there is a window of time where the tokens are not valid.
-         *
-         * This potential issue do not affect you if you are using "oidc-spa/react" as in the documentation.
-         * */
-        getTokens: () => Tokens<DecodedIdToken>;
-        getTokens_next: () => Promise<Tokens<DecodedIdToken>>;
+        getTokens: () => Promise<Tokens<DecodedIdToken>>;
         subscribeToTokensChange: (onTokenChange: (tokens: Tokens<DecodedIdToken>) => void) => {
             unsubscribe: () => void;
         };
@@ -93,13 +84,26 @@ export declare namespace Oidc {
          */
         isNewBrowserSession: boolean;
     };
-    type Tokens<DecodedIdToken extends Record<string, unknown> = Record<string, unknown>> = Tokens.WithRefreshToken<DecodedIdToken> | Tokens.WithoutRefreshToken<DecodedIdToken>;
+    type Tokens<DecodedIdToken extends Record<string, unknown> = Tokens.DecodedIdToken_base> = Tokens.WithRefreshToken<DecodedIdToken> | Tokens.WithoutRefreshToken<DecodedIdToken>;
     namespace Tokens {
         type Common<DecodedIdToken> = {
             accessToken: string;
             accessTokenExpirationTime: number;
             idToken: string;
             decodedIdToken: DecodedIdToken;
+            /**
+             * decodedIdToken_original = decodeJwt(idToken);
+             * decodedIdToken = decodedIdTokenSchema.parse(decodedIdToken_original)
+             *
+             * The idea here is that if you have provided a zod schema as `decodedIdTokenSchema`
+             * it will strip out every claim that you haven't specified.
+             * You might even be applying some transformation.
+             *
+             * `decodedIdToken_original` is the actual decoded payload of the  id_token, untransformed.
+             * */
+            decodedIdToken_original: DecodedIdToken_base;
+            /** Read from id_token's JWT, iat claim value, it's a JavaScript timestamp (millisecond epoch) */
+            issuedAtTime: number;
         };
         type WithRefreshToken<DecodedIdToken> = Common<DecodedIdToken> & {
             hasRefreshToken: true;
@@ -111,5 +115,13 @@ export declare namespace Oidc {
             refreshToken?: never;
             refreshTokenExpirationTime?: never;
         };
+        type DecodedIdToken_base = {
+            iss: string;
+            sub: string;
+            aud: string | string[];
+            exp: number;
+            iat: number;
+            [claimName: string]: unknown;
+        };
     }
 }

package/core/createOidc.d.ts

@@ -9,18 +9,12 @@ export type ParamsOfCreateOidc<DecodedIdToken extends Record<string, unknown> =
      **/
     scopes?: string[];
     /**
-     * Transform the url of the authorization endpoint before redirecting to the login pages.
-     */
-    transformUrlBeforeRedirect?: (url: string) => string;
-    /**
-     * NOTE: Will replace transformUrlBeforeRedirect in the next major version.
-     *
      * Transform the url (authorization endpoint) before redirecting to the login pages.
      *
      * The isSilent parameter is true when the redirect is initiated in the background iframe for silent signin.
      * This can be used to omit ui related query parameters (like `ui_locales`).
      */
-    transformUrlBeforeRedirect_next?: (params: {
+    transformUrlBeforeRedirect?: (params: {
         authorizationUrl: string;
         isSilent: boolean;
     }) => string;
@@ -65,31 +59,9 @@ export type ParamsOfCreateOidc<DecodedIdToken extends Record<string, unknown> =
      *   - Other:                    `BASE_URL: "/"` (Usually, or `/dashboard` if your app is not at the root of the domain)
      */
     homeUrl: string;
-    /**
-     * WARNING: If you are deploying on the web, you should not set this parameter.
-     * The callbackUrl is the homeURl.
-     *
-     * This is only useful for when you also shipping your app as a Desktop App with Electron.
-     * NOTE that even in this case, it's not automatic, you still need to handle the response
-     * in the electron node process.
-     *
-     * Example: __callbackUri: "myapp://oidc-callback/"
-     */
-    __callbackUri?: string;
     decodedIdTokenSchema?: {
-        parse: (data: unknown) => DecodedIdToken;
+        parse: (decodedIdToken_original: Oidc.Tokens.DecodedIdToken_base) => DecodedIdToken;
     };
-    /**
-     * @deprecated: Use idleSessionLifetimeInSeconds instead
-     *
-     * This parameter defines after how many seconds of inactivity the user should be
-     * logged out automatically.
-     *
-     * WARNING: It should be configured on the identity server side
-     * as it's the authoritative source for security policies and not the client.
-     * If you don't provide this parameter it will be inferred from the refresh token expiration time.
-     * */
-    __unsafe_ssoSessionIdleSeconds?: number;
     /**
      * This parameter defines after how many seconds of inactivity the user should be
      * logged out automatically.
@@ -99,6 +71,9 @@ export type ParamsOfCreateOidc<DecodedIdToken extends Record<string, unknown> =
      * If you don't provide this parameter it will be inferred from the refresh token expiration time.
      * */
     idleSessionLifetimeInSeconds?: number;
+    /**
+     * Default: { redirectTo: "current page" }
+     */
     autoLogoutParams?: Parameters<Oidc.LoggedIn<any>["logout"]>[0];
     autoLogin?: AutoLogin;
     /**
@@ -108,6 +83,16 @@ export type ParamsOfCreateOidc<DecodedIdToken extends Record<string, unknown> =
      */
     noIframe?: boolean;
     debugLogs?: boolean;
+    /**
+     * WARNING: This option exists solely as a workaround
+     * for limitations in the Google OAuth API.
+     * See: https://docs.oidc-spa.dev/providers-configuration/google-oauth
+     *
+     * Do not use this for other providers.
+     * If you think you need a client secret in a SPA, you are likely
+     * trying to use a confidential (private) client in the browser,
+     * which is insecure and not supported.
+     */
     __unsafe_clientSecret?: string;
     /**
      *  WARNING: Setting this to true is a workaround for provider