oidc-spa 8.1.9 → 8.1.11

package/src/backend.ts

@@ -1,20 +1,76 @@
-import { fetch } from "./vendor/backend/node-fetch";
-import { assert, isAmong, id, type Equals, is, exclude } from "./vendor/backend/tsafe";
-import { JWK } from "./vendor/backend/node-jose";
-import * as jwt from "./vendor/backend/jsonwebtoken";
+import { assert, isAmong, id, type Equals, is } from "./vendor/backend/tsafe";
+import {
+    decodeProtectedHeader,
+    jwtVerify,
+    createLocalJWKSet,
+    errors,
+    type JWTPayload
+} from "./vendor/backend/jose";
 import { z } from "./vendor/backend/zod";
-import { Evt } from "./vendor/backend/evt";
-import { throttleTime } from "./vendor/backend/evt";
+import { Evt, throttleTime } from "./vendor/backend/evt";
+import type { ZodSchemaLike } from "./tools/ZodSchemaLike";
+
+/**
+ * Claims defined by RFC 9068: "JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens"
+ * https://datatracker.ietf.org/doc/html/rfc9068
+ *
+ * These tokens are intended for consumption by resource servers.
+ */
+export type DecodedAccessToken_RFC9068 = {
+    // --- REQUIRED (MUST) ---
+    iss: string; // Issuer Identifier
+    sub: string; // Subject Identifier
+    aud: string | string[]; // Audience(s)
+    exp: number; // Expiration time (seconds since epoch)
+    iat: number; // Issued-at time (seconds since epoch)
+
+    // --- RECOMMENDED (SHOULD) ---
+    client_id?: string; // OAuth2 Client ID that requested the token
+    scope?: string; // Space-separated list of granted scopes
+    jti?: string; // Unique JWT ID (for replay detection)
+
+    // --- OPTIONAL / EXTENSION CLAIMS ---
+    nbf?: number; // Not-before time (standard JWT claim)
+    auth_time?: number; // Time of user authentication (optional)
+    cnf?: Record<string, unknown>; // Confirmation (e.g. proof-of-possession)
+    [key: string]: unknown; // Allow custom claims (e.g. roles, groups)
+};
 
-export type ParamsOfCreateOidcBackend<DecodedAccessToken extends Record<string, unknown>> = {
+const zDecodedAccessToken_RFC9068 = (() => {
+    type TargetType = DecodedAccessToken_RFC9068;
+
+    const zTargetType = z
+        .object({
+            iss: z.string(),
+            sub: z.string(),
+            aud: z.union([z.string(), z.array(z.string())]),
+            exp: z.number(),
+            iat: z.number(),
+            client_id: z.string().optional(),
+            scope: z.string().optional(),
+            jti: z.string().optional(),
+            nbf: z.number().optional(),
+            auth_time: z.number().optional(),
+            cnf: z.record(z.unknown()).optional()
+        })
+        .catchall(z.unknown());
+
+    type InferredType = z.infer<typeof zTargetType>;
+
+    assert<Equals<TargetType, InferredType>>;
+
+    return id<z.ZodType<TargetType>>(zTargetType);
+})();
+
+export type ParamsOfCreateOidcBackend<DecodedAccessToken> = {
     issuerUri: string;
-    decodedAccessTokenSchema?: { parse: (data: unknown) => DecodedAccessToken };
+    decodedAccessTokenSchema?: ZodSchemaLike<DecodedAccessToken_RFC9068, DecodedAccessToken>;
 };
 
 export type OidcBackend<DecodedAccessToken extends Record<string, unknown>> = {
     verifyAndDecodeAccessToken(params: {
         accessToken: string;
-    }): ResultOfAccessTokenVerify<DecodedAccessToken>;
+    }): Promise<ResultOfAccessTokenVerify<DecodedAccessToken>>;
 };
 
 export type ResultOfAccessTokenVerify<DecodedAccessToken> =
@@ -24,7 +80,9 @@ export type ResultOfAccessTokenVerify<DecodedAccessToken> =
 export namespace ResultOfAccessTokenVerify {
     export type Valid<DecodedAccessToken> = {
         isValid: true;
+
         decodedAccessToken: DecodedAccessToken;
+        decodedAccessToken_original: DecodedAccessToken_RFC9068;
 
         errorCase?: never;
         errorMessage?: never;
@@ -36,13 +94,14 @@ export namespace ResultOfAccessTokenVerify {
         errorMessage: string;
 
         decodedAccessToken?: never;
+        decodedAccessToken_original?: never;
     };
 }
 
-export async function createOidcBackend<DecodedAccessToken extends Record<string, unknown>>(
-    params: ParamsOfCreateOidcBackend<DecodedAccessToken>
-): Promise<OidcBackend<DecodedAccessToken>> {
-    const { issuerUri, decodedAccessTokenSchema = z.record(z.unknown()) } = params;
+export async function createOidcBackend<
+    DecodedAccessToken extends Record<string, unknown> = DecodedAccessToken_RFC9068
+>(params: ParamsOfCreateOidcBackend<DecodedAccessToken>): Promise<OidcBackend<DecodedAccessToken>> {
+    const { issuerUri, decodedAccessTokenSchema } = params;
 
     let publicSigningKeys = await fetchPublicSigningKeys({ issuerUri });
 
@@ -51,8 +110,8 @@ export async function createOidcBackend<DecodedAccessToken extends Record<string
     evtInvalidSignature.pipe(throttleTime(3600_000)).attach(async () => {
         const publicSigningKeys_new = await (async function callee(
             count: number
-        ): Promise<PublicSigningKey[] | undefined> {
-            let wrap;
+        ): Promise<PublicSigningKeys | undefined> {
+            let wrap: PublicSigningKeys | undefined;
 
             try {
                 wrap = await fetchPublicSigningKeys({ issuerUri });
@@ -89,99 +148,66 @@ export async function createOidcBackend<DecodedAccessToken extends Record<string
     });
 
     return {
-        verifyAndDecodeAccessToken: ({ accessToken }) => {
+        verifyAndDecodeAccessToken: async ({ accessToken }) => {
             let kid: string;
-            let alg: jwt.Algorithm;
+            let alg: string;
 
             {
-                const jwtHeader_b64 = accessToken.split(".")[0];
-
-                let jwtHeader: string;
+                let header: ReturnType<typeof decodeProtectedHeader>;
 
                 try {
-                    jwtHeader = Buffer.from(jwtHeader_b64, "base64").toString("utf8");
+                    header = decodeProtectedHeader(accessToken);
                 } catch {
                     return {
                         isValid: false,
                         errorCase: "invalid signature",
-                        errorMessage: "Failed to decode the JWT header as a base64 string"
+                        errorMessage: "Failed to decode the JWT header"
                     };
                 }
 
-                let decodedHeader: unknown;
+                const { kid: kidFromHeader, alg: algFromHeader } = header;
 
-                try {
-                    decodedHeader = JSON.parse(jwtHeader);
-                } catch {
+                if (typeof kidFromHeader !== "string" || kidFromHeader.length === 0) {
                     return {
                         isValid: false,
                         errorCase: "invalid signature",
-                        errorMessage: "Failed to parse the JWT header as a JSON"
+                        errorMessage: "The decoded JWT header does not have a kid property"
                     };
                 }
 
-                type DecodedHeader = {
-                    kid: string;
-                    alg: string;
-                };
-
-                const zDecodedHeader = z.object({
-                    kid: z.string(),
-                    alg: z.string()
-                });
-
-                assert<Equals<DecodedHeader, z.infer<typeof zDecodedHeader>>>();
-
-                try {
-                    zDecodedHeader.parse(decodedHeader);
-                } catch {
+                if (typeof algFromHeader !== "string") {
                     return {
                         isValid: false,
                         errorCase: "invalid signature",
-                        errorMessage: "The decoded JWT header does not have a kid property"
+                        errorMessage: "The decoded JWT header does not specify an algorithm"
                     };
                 }
 
-                assert(is<DecodedHeader>(decodedHeader));
-
-                {
-                    const supportedAlgs = [
-                        "RS256",
-                        "RS384",
-                        "RS512",
-                        "ES256",
-                        "ES384",
-                        "ES512",
-                        "PS256",
-                        "PS384",
-                        "PS512"
-                    ] as const;
-
-                    assert<
-                        Equals<
-                            (typeof supportedAlgs)[number] | "none" | "HS256" | "HS384" | "HS512",
-                            jwt.Algorithm
-                        >
-                    >();
-
-                    if (!isAmong(supportedAlgs, decodedHeader.alg)) {
-                        return {
-                            isValid: false,
-                            errorCase: "invalid signature",
-                            errorMessage: `Unsupported or too week algorithm ${decodedHeader.alg}`
-                        };
-                    }
+                const supportedAlgs = [
+                    "RS256",
+                    "RS384",
+                    "RS512",
+                    "ES256",
+                    "ES384",
+                    "ES512",
+                    "PS256",
+                    "PS384",
+                    "PS512"
+                ] as const;
+
+                if (!isAmong(supportedAlgs, algFromHeader as (typeof supportedAlgs)[number])) {
+                    return {
+                        isValid: false,
+                        errorCase: "invalid signature",
+                        errorMessage: `Unsupported or too weak algorithm ${algFromHeader}`
+                    };
                 }
 
-                kid = decodedHeader.kid;
-                alg = decodedHeader.alg;
+                kid = kidFromHeader;
+                alg = algFromHeader;
             }
 
-            const publicSigningKey = publicSigningKeys.find(
-                publicSigningKey => publicSigningKey.kid === kid
-            );
-
-            if (publicSigningKey === undefined) {
+            if (!publicSigningKeys.kidSet.has(kid)) {
                 return {
                     isValid: false,
                     errorCase: "invalid signature",
@@ -189,74 +215,82 @@ export async function createOidcBackend<DecodedAccessToken extends Record<string
                 };
             }
 
-            let result = id<ResultOfAccessTokenVerify<DecodedAccessToken> | undefined>(undefined);
-
-            jwt.verify(
-                accessToken,
-                publicSigningKey.publicKey,
-                { algorithms: [alg] },
-                (err, decoded) => {
-                    invalid: {
-                        if (!err) {
-                            break invalid;
-                        }
-
-                        if (err.name === "TokenExpiredError") {
-                            result = id<ResultOfAccessTokenVerify.Invalid>({
-                                isValid: false,
-                                errorCase: "expired",
-                                errorMessage: err.message
-                            });
-                            return;
-                        }
-
-                        evtInvalidSignature.post();
-
-                        result = id<ResultOfAccessTokenVerify.Invalid>({
-                            isValid: false,
-                            errorCase: "invalid signature",
-                            errorMessage: err.message
-                        });
-
-                        return;
-                    }
-
-                    let decodedAccessToken: DecodedAccessToken;
-
-                    try {
-                        decodedAccessToken = decodedAccessTokenSchema.parse(
-                            decoded
-                        ) as DecodedAccessToken;
-                    } catch (error) {
-                        result = id<ResultOfAccessTokenVerify.Invalid>({
-                            isValid: false,
-                            errorCase: "does not respect schema",
-                            errorMessage: String(error)
-                        });
-
-                        return;
-                    }
-
-                    result = id<ResultOfAccessTokenVerify.Valid<DecodedAccessToken>>({
-                        isValid: true,
-                        decodedAccessToken: decodedAccessToken
+            let payload: JWTPayload;
+
+            try {
+                const verification = await jwtVerify(accessToken, publicSigningKeys.keyResolver, {
+                    algorithms: [alg]
+                });
+
+                payload = verification.payload;
+            } catch (error) {
+                if (error instanceof errors.JWTExpired) {
+                    return id<ResultOfAccessTokenVerify.Invalid>({
+                        isValid: false,
+                        errorCase: "expired",
+                        errorMessage: error.message
                     });
                 }
-            );
 
-            assert(result !== undefined, "0522e6");
+                evtInvalidSignature.post();
+
+                return id<ResultOfAccessTokenVerify.Invalid>({
+                    isValid: false,
+                    errorCase: "invalid signature",
+                    errorMessage: error instanceof Error ? error.message : String(error)
+                });
+            }
 
-            return result;
+            const decodedAccessToken_unknown = payload as unknown;
+
+            try {
+                zDecodedAccessToken_RFC9068.parse(decodedAccessToken_unknown);
+            } catch (error) {
+                return id<ResultOfAccessTokenVerify.Invalid>({
+                    isValid: false,
+                    errorCase: "does not respect schema",
+                    errorMessage: [
+                        `The decoded access token does not satisfies`,
+                        `the shape mandated by RFC9068: ${String(error)}`
+                    ].join(" ")
+                });
+            }
+
+            assert(is<DecodedAccessToken_RFC9068>(decodedAccessToken_unknown));
+
+            const decodedAccessToken_original = decodedAccessToken_unknown;
+
+            let decodedAccessToken: DecodedAccessToken;
+
+            if (decodedAccessTokenSchema === undefined) {
+                decodedAccessToken = decodedAccessToken_original as unknown as DecodedAccessToken;
+            } else {
+                try {
+                    decodedAccessToken = decodedAccessTokenSchema.parse(decodedAccessToken_original);
+                } catch (error) {
+                    return id<ResultOfAccessTokenVerify.Invalid>({
+                        isValid: false,
+                        errorCase: "does not respect schema",
+                        errorMessage: String(error)
+                    });
+                }
+            }
+
+            return id<ResultOfAccessTokenVerify.Valid<DecodedAccessToken>>({
+                isValid: true,
+                decodedAccessToken,
+                decodedAccessToken_original
+            });
         }
     };
 }
 
-type PublicSigningKey = {
-    kid: string;
-    publicKey: string;
+type PublicSigningKeys = {
+    keyResolver: ReturnType<typeof createLocalJWKSet>;
+    kidSet: Set<string>;
 };
 
-async function fetchPublicSigningKeys(params: { issuerUri: string }): Promise<PublicSigningKey[]> {
+async function fetchPublicSigningKeys(params: { issuerUri: string }): Promise<PublicSigningKeys> {
     const { issuerUri } = params;
 
     const { jwks_uri } = await (async () => {
@@ -325,9 +359,8 @@ async function fetchPublicSigningKeys(params: { issuerUri: string }): Promise<Pu
                 keys: {
                     kid: string;
                     kty: string;
-                    e?: string;
-                    n?: string;
-                    use: string;
+                    use?: string;
+                    alg?: string;
                 }[];
             };
 
@@ -336,9 +369,8 @@ async function fetchPublicSigningKeys(params: { issuerUri: string }): Promise<Pu
                     z.object({
                         kid: z.string(),
                         kty: z.string(),
-                        e: z.string().optional(),
-                        n: z.string().optional(),
-                        use: z.string()
+                        use: z.string().optional(),
+                        alg: z.string().optional()
                     })
                 )
             });
@@ -357,35 +389,38 @@ async function fetchPublicSigningKeys(params: { issuerUri: string }): Promise<Pu
         return { jwks };
     })();
 
-    const publicSigningKeys: PublicSigningKey[] = await Promise.all(
-        jwks.keys
-            .filter(({ use }) => use === "sig")
-            .map(({ kid, kty, e, n }) => {
-                if (kty !== "RSA") {
-                    return undefined;
-                }
+    //const signatureKeys = jwks.keys.filter((key): key is JWKS["keys"][number] & { kid: string } => {
+    const signatureKeys = jwks.keys.filter(key => {
+        if (typeof key.kid !== "string" || key.kid.length === 0) {
+            return false;
+        }
 
-                assert(e !== undefined, "e is undefined");
-                assert(n !== undefined, "n is undefined");
+        if (key.use !== undefined && key.use !== "sig") {
+            return false;
+        }
 
-                return { kid, e, n };
-            })
-            .filter(exclude(undefined))
-            .map(async ({ kid, e, n }) => {
-                const key = await JWK.asKey({ kty: "RSA", e, n });
-                const publicKey = key.toPEM(false);
+        const supportedKty = ["RSA", "EC"] as const;
 
-                return {
-                    kid,
-                    publicKey
-                };
-            })
-    );
+        if (!supportedKty.includes(key.kty as (typeof supportedKty)[number])) {
+            return false;
+        }
+
+        return true;
+    });
 
     assert(
-        publicSigningKeys.length !== 0,
+        signatureKeys.length !== 0,
         `No public signing key found at ${jwks_uri}, ${JSON.stringify(jwks, null, 2)}`
     );
 
-    return publicSigningKeys;
+    const kidSet = new Set(signatureKeys.map(({ kid }) => kid));
+
+    const keyResolver = createLocalJWKSet({
+        keys: signatureKeys
+    });
+
+    return {
+        keyResolver,
+        kidSet
+    };
 }

package/src/core/Oidc.ts

@@ -1,7 +1,7 @@
 import type { OidcInitializationError } from "./OidcInitializationError";
 
 export declare type Oidc<
-    DecodedIdToken extends Record<string, unknown> = Oidc.Tokens.DecodedIdToken_base
+    DecodedIdToken extends Record<string, unknown> = Oidc.Tokens.DecodedIdToken_OidcCoreSpec
 > = Oidc.LoggedIn<DecodedIdToken> | Oidc.NotLoggedIn;
 
 export declare namespace Oidc {
@@ -91,9 +91,9 @@ export declare namespace Oidc {
             isNewBrowserSession: boolean;
         };
 
-    export type Tokens<DecodedIdToken extends Record<string, unknown> = Tokens.DecodedIdToken_base> =
-        | Tokens.WithRefreshToken<DecodedIdToken>
-        | Tokens.WithoutRefreshToken<DecodedIdToken>;
+    export type Tokens<
+        DecodedIdToken extends Record<string, unknown> = Tokens.DecodedIdToken_OidcCoreSpec
+    > = Tokens.WithRefreshToken<DecodedIdToken> | Tokens.WithoutRefreshToken<DecodedIdToken>;
 
     export namespace Tokens {
         export type Common<DecodedIdToken> = {
@@ -112,7 +112,7 @@ export declare namespace Oidc {
              *
              * `decodedIdToken_original` is the actual decoded payload of the  id_token, untransformed.
              * */
-            decodedIdToken_original: DecodedIdToken_base;
+            decodedIdToken_original: DecodedIdToken_OidcCoreSpec;
             /** Millisecond epoch in the server's time, read from id_token's JWT, iat claim value */
             issuedAtTime: number;
 
@@ -132,12 +132,42 @@ export declare namespace Oidc {
             refreshTokenExpirationTime?: never;
         };
 
-        export type DecodedIdToken_base = {
-            iss: string;
-            sub: string;
-            aud: string | string[];
-            exp: number;
-            iat: number;
+        export type DecodedIdToken_OidcCoreSpec = {
+            // REQUIRED
+            iss: string; // Issuer Identifier
+            sub: string; // Subject Identifier
+            aud: string | string[]; // Audience(s)
+            exp: number; // Expiration time (Unix seconds)
+            iat: number; // Issued-at time (Unix seconds)
+
+            // CONDITIONAL
+            auth_time?: number; // Authentication time
+            nonce?: string; // Nonce
+            acr?: string; // Authentication Context Class Reference
+            amr?: string[]; // Authentication Methods References
+            azp?: string; // Authorized party (for multiple audiences)
+
+            // OPTIONAL standard user claims (OpenID §5.1)
+            name?: string;
+            given_name?: string;
+            family_name?: string;
+            middle_name?: string;
+            nickname?: string;
+            preferred_username?: string;
+            profile?: string;
+            picture?: string;
+            website?: string;
+            email?: string;
+            email_verified?: boolean;
+            gender?: string;
+            birthdate?: string;
+            zoneinfo?: string;
+            locale?: string;
+            phone_number?: string;
+            phone_number_verified?: boolean;
+            address?: Record<string, unknown>;
+            updated_at?: number;
+
             [claimName: string]: unknown;
         };
     }

package/src/core/createOidc.ts

@@ -56,7 +56,7 @@ import { getIsValidRemoteJson } from "../tools/getIsValidRemoteJson";
 const VERSION = "{{OIDC_SPA_VERSION}}";
 
 export type ParamsOfCreateOidc<
-    DecodedIdToken extends Record<string, unknown> = Oidc.Tokens.DecodedIdToken_base,
+    DecodedIdToken extends Record<string, unknown> = Oidc.Tokens.DecodedIdToken_OidcCoreSpec,
     AutoLogin extends boolean = false
 > = {
     /**
@@ -67,7 +67,13 @@ export type ParamsOfCreateOidc<
      */
     homeUrl: string;
 
+    /**
+     * See: https://docs.oidc-spa.dev/v/v8/providers-configuration/provider-configuration
+     */
     issuerUri: string;
+    /**
+     * See: https://docs.oidc-spa.dev/v/v8/providers-configuration/provider-configuration
+     */
     clientId: string;
     /**
      * The scopes being requested from the OIDC/OAuth2 provider (default: `["profile"]`
@@ -122,7 +128,7 @@ export type ParamsOfCreateOidc<
     postLoginRedirectUrl?: string;
 
     decodedIdTokenSchema?: {
-        parse: (decodedIdToken_original: Oidc.Tokens.DecodedIdToken_base) => DecodedIdToken;
+        parse: (decodedIdToken_original: Oidc.Tokens.DecodedIdToken_OidcCoreSpec) => DecodedIdToken;
     };
 
     /**
@@ -132,6 +138,9 @@ export type ParamsOfCreateOidc<
      * 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.
+     * Some provider however don't issue a refresh token or do not correctly set the
+     * expiration time. This parameter enable you to hard code the value to compensate
+     * the shortcoming of your auth server.
      * */
     idleSessionLifetimeInSeconds?: number;
 
@@ -209,7 +218,7 @@ globalContext.evtRequestToPersistTokens.subscribe(() => {
 
 /** @see: https://docs.oidc-spa.dev/v/v8/usage */
 export async function createOidc<
-    DecodedIdToken extends Record<string, unknown> = Oidc.Tokens.DecodedIdToken_base,
+    DecodedIdToken extends Record<string, unknown> = Oidc.Tokens.DecodedIdToken_OidcCoreSpec,
     AutoLogin extends boolean = false
 >(
     params: ParamsOfCreateOidc<DecodedIdToken, AutoLogin>

package/src/core/earlyInit.ts

@@ -6,6 +6,7 @@ import {
     postEncryptedAuthResponseToParent,
     preventSessionStorageSetItemOfPublicKeyByThirdParty
 } from "./iframeMessageProtection";
+import { setOidcRequiredPostHydrationReplaceNavigationUrl } from "./requiredPostHydrationReplaceNavigationUrl";
 import { isBrowser } from "../tools/isBrowser";
 
 let hasEarlyInitBeenCalled = false;
@@ -16,6 +17,7 @@ export function oidcEarlyInit(params: {
     // NOTE: Made optional just to avoid breaking change.
     // Will be made mandatory next major.
     freezeWebSocket?: boolean;
+    isPostLoginRedirectManual?: boolean;
 }) {
     if (hasEarlyInitBeenCalled) {
         throw new Error("oidc-spa: oidcEarlyInit() Should be called only once");
@@ -29,9 +31,14 @@ export function oidcEarlyInit(params: {
 
     captureApisForIframeProtection();
 
-    const { freezeFetch, freezeXMLHttpRequest, freezeWebSocket = false } = params ?? {};
+    const {
+        freezeFetch,
+        freezeXMLHttpRequest,
+        freezeWebSocket = false,
+        isPostLoginRedirectManual = false
+    } = params ?? {};
 
-    const { shouldLoadApp } = handleOidcCallback();
+    const { shouldLoadApp } = handleOidcCallback({ isPostLoginRedirectManual });
 
     if (shouldLoadApp) {
         if (freezeXMLHttpRequest) {
@@ -112,7 +119,11 @@ export function getRootRelativeOriginalLocationHref() {
     return rootRelativeOriginalLocationHref;
 }
 
-function handleOidcCallback(): { shouldLoadApp: boolean } {
+function handleOidcCallback(params: { isPostLoginRedirectManual?: boolean }): {
+    shouldLoadApp: boolean;
+} {
+    const { isPostLoginRedirectManual } = params;
+
     const location_urlObj = new URL(window.location.href);
 
     const locationHrefAssessment = (() => {
@@ -209,7 +220,11 @@ function handleOidcCallback(): { shouldLoadApp: boolean } {
                 return stateData.rootRelativeRedirectUrl;
             })();
 
-            history.replaceState({}, "", rootRelativeRedirectUrl);
+            if (isPostLoginRedirectManual) {
+                setOidcRequiredPostHydrationReplaceNavigationUrl({ rootRelativeRedirectUrl });
+            } else {
+                history.replaceState({}, "", rootRelativeRedirectUrl);
+            }
 
             return { shouldLoadApp: true };
         }