oidc-spa 8.6.18 → 8.7.0

package/src/server/index.ts

@@ -0,0 +1,4 @@
+export type * from "./types";
+import { oidcSpaUtilsBuilder } from "./utilsBuilder";
+
+export const oidcSpa = oidcSpaUtilsBuilder;

package/src/server/types.tsx

@@ -0,0 +1,99 @@
+/**
+ * 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 ValidateAndDecodeAccessToken<DecodedAccessToken> = (params: {
+    request: {
+        method: string;
+        url: string;
+        headers: Record<"Authorization" | "DPoP", string | null | undefined>;
+    };
+}) => Promise<ValidateAndDecodeAccessToken.ReturnType<DecodedAccessToken>>;
+
+export namespace ValidateAndDecodeAccessToken {
+    export type ReturnType<DecodedAccessToken> =
+        | (ReturnType.Success<DecodedAccessToken> & { errorCause?: never; debugErrorMessage?: never })
+        | (ReturnType.Errored & {
+              decodedAccessToken?: never;
+              decodedAccessToken_original?: never;
+              accessToken?: never;
+          });
+
+    export namespace ReturnType {
+        export type Success<DecodedAccessToken> = {
+            isSuccess: true;
+            decodedAccessToken: DecodedAccessToken;
+            decodedAccessToken_original: DecodedAccessToken_RFC9068;
+            accessToken: string;
+        };
+
+        export type Errored = {
+            isSuccess: false;
+            errorCause:
+                | "missing Authorization header"
+                | "validation error"
+                | "validation error - access token expired"
+                | "validation error - invalid signature";
+            debugErrorMessage: string;
+        };
+    }
+}
+
+export type ParamsOfBootstrap<DecodedAccessToken> =
+    | ParamsOfBootstrap.Real
+    | ParamsOfBootstrap.Mock<DecodedAccessToken>;
+
+export namespace ParamsOfBootstrap {
+    export type Real = {
+        implementation: "real";
+        issuerUri: string;
+        expectedAudience: string | undefined;
+    };
+
+    export type Mock<DecodedAccessToken> = Mock.DecodeOnly | Mock.UseStaticIdentity<DecodedAccessToken>;
+
+    export namespace Mock {
+        type Common = {
+            implementation: "mock";
+        };
+
+        export type DecodeOnly = Common & {
+            behavior: "decode only";
+        };
+
+        export type UseStaticIdentity<DecodedAccessToken> = Common & {
+            behavior: "use static identity";
+            decodedAccessToken_mock: DecodedAccessToken;
+            decodedAccessToken_original_mock?: DecodedAccessToken_RFC9068;
+            accessToken_mock?: string;
+        };
+    }
+}
+
+export type OidcSpaUtils<DecodedAccessToken> = {
+    bootstrapAuth: (params: ParamsOfBootstrap<DecodedAccessToken>) => Promise<void>;
+    validateAndDecodeAccessToken: ValidateAndDecodeAccessToken<DecodedAccessToken>;
+    ofTypeDecodedAccessToken: DecodedAccessToken;
+};

package/src/server/utilsBuilder.ts

@@ -0,0 +1,41 @@
+import type { OidcSpaUtils } from "./types";
+import type { ZodSchemaLike } from "../tools/ZodSchemaLike";
+import { createOidcSpaUtils } from "./createOidcSpaUtils";
+import type { DecodedAccessToken_RFC9068 } from "./types";
+
+export type OidcSpaUtilsBuilder<
+    DecodedAccessToken extends Record<string, unknown> = DecodedAccessToken_RFC9068,
+    ExcludedMethod extends "withExpectedDecodedAccessTokenShape" | "createUtils" = never
+> = Omit<
+    {
+        withExpectedDecodedAccessTokenShape: <
+            DecodedAccessToken extends Record<string, unknown>
+        >(params: {
+            decodedAccessTokenSchema: ZodSchemaLike<DecodedAccessToken_RFC9068, DecodedAccessToken>;
+        }) => OidcSpaUtilsBuilder<
+            DecodedAccessToken,
+            ExcludedMethod | "withExpectedDecodedAccessTokenShape"
+        >;
+        createUtils: () => OidcSpaUtils<DecodedAccessToken>;
+    },
+    ExcludedMethod
+>;
+
+function createOidcSpaUtilsBuilder<
+    DecodedAccessToken extends Record<string, unknown> = DecodedAccessToken_RFC9068
+>(params: {
+    decodedAccessTokenSchema: ZodSchemaLike<DecodedAccessToken_RFC9068, DecodedAccessToken> | undefined;
+}): OidcSpaUtilsBuilder<DecodedAccessToken> {
+    return {
+        withExpectedDecodedAccessTokenShape: ({ decodedAccessTokenSchema }) =>
+            createOidcSpaUtilsBuilder({ decodedAccessTokenSchema }),
+        createUtils: () =>
+            createOidcSpaUtils<DecodedAccessToken>({
+                decodedAccessTokenSchema: params.decodedAccessTokenSchema
+            })
+    };
+}
+
+export const oidcSpaUtilsBuilder = createOidcSpaUtilsBuilder({
+    decodedAccessTokenSchema: undefined
+});

package/src/tanstack-start/react/accessTokenValidation_rfc9068.ts

@@ -1,8 +1,12 @@
-import type { CreateValidateAndGetAccessTokenClaims, ParamsOfBootstrap } from "./types";
-import type { DecodedAccessToken_RFC9068 as AccessTokenClaims_RFC9068 } from "../../backend";
+import type {
+    CreateValidateAndGetAccessTokenClaims,
+    ParamsOfBootstrap,
+    ValidateAndGetAccessTokenClaims
+} from "./types";
+import type { DecodedAccessToken_RFC9068 as AccessTokenClaims_RFC9068 } from "../../server/types";
 import type { ZodSchemaLike } from "../../tools/ZodSchemaLike";
 import { createObjectThatThrowsIfAccessed } from "../../tools/createObjectThatThrowsIfAccessed";
-import { assert, type Equals, is } from "../../tools/tsafe/assert";
+import { assert, type Equals, is, id } from "../../vendor/server/tsafe";
 
 export function createCreateValidateAndGetAccessTokenClaims_rfc9068<
     AccessTokenClaims extends Record<string, unknown>
@@ -23,12 +27,84 @@ export function createCreateValidateAndGetAccessTokenClaims_rfc9068<
     const createValidateAndGetAccessTokenClaims: CreateValidateAndGetAccessTokenClaims<
         AccessTokenClaims
     > = ({ paramsOfBootstrap }) => {
-        if (paramsOfBootstrap.implementation === "mock") {
-            return {
-                validateAndGetAccessTokenClaims: async () => {
-                    return {
-                        isValid: true,
-                        accessTokenClaims: (() => {
+        const prValidateAndDecodeAccessToken = (async () => {
+            const { oidcSpa: oidcSpa_server } = await import("../../server");
+
+            const { bootstrapAuth, validateAndDecodeAccessToken } =
+                accessTokenClaimsSchema === undefined
+                    ? (oidcSpa_server.createUtils() as never)
+                    : oidcSpa_server
+                          .withExpectedDecodedAccessTokenShape({
+                              decodedAccessTokenSchema: accessTokenClaimsSchema
+                          })
+                          .createUtils();
+
+            switch (paramsOfBootstrap.implementation) {
+                case "real":
+                    {
+                        const expectedAudience = (() => {
+                            if (expectedAudienceGetter === undefined) {
+                                return undefined;
+                            }
+
+                            const missingEnvNames = new Set<string>();
+
+                            const env_proxy = new Proxy<Record<string, string>>(
+                                {},
+                                {
+                                    get: (...[, envName]) => {
+                                        assert(typeof envName === "string");
+
+                                        const value = process.env[envName];
+
+                                        if (value === undefined) {
+                                            missingEnvNames.add(envName);
+                                            return "";
+                                        }
+
+                                        return value;
+                                    },
+                                    has: (...[, envName]) => {
+                                        assert(typeof envName === "string");
+                                        return true;
+                                    }
+                                }
+                            );
+
+                            const expectedAudience = expectedAudienceGetter?.({
+                                paramsOfBootstrap,
+                                process: { env: env_proxy }
+                            });
+
+                            if (!expectedAudience) {
+                                throw new Error(
+                                    [
+                                        "oidc-spa: The expectedAudience() you provided returned empty.",
+                                        "If you specified the expectedAudience in withAccessTokenValidation",
+                                        "it's probably an error.",
+                                        missingEnvNames.size !== 0 &&
+                                            `Did you forget to set the env var: ${Array.from(
+                                                missingEnvNames
+                                            ).join(", ")} ?`
+                                    ]
+                                        .filter(line => typeof line === "string")
+                                        .join(" ")
+                                );
+                            }
+
+                            return expectedAudience;
+                        })();
+
+                        await bootstrapAuth({
+                            implementation: "real",
+                            issuerUri: paramsOfBootstrap.issuerUri,
+                            expectedAudience
+                        });
+                    }
+                    break;
+                case "mock":
+                    {
+                        const decodedAccessToken_mock = (() => {
                             if (paramsOfBootstrap.accessTokenClaims_mock !== undefined) {
                                 assert(is<AccessTokenClaims>(paramsOfBootstrap.accessTokenClaims_mock));
                                 return paramsOfBootstrap.accessTokenClaims_mock;
@@ -46,131 +122,65 @@ export function createCreateValidateAndGetAccessTokenClaims_rfc9068<
                                     "specify accessTokenClaims_mock when calling bootstrapOidc()"
                                 ].join(" ")
                             });
-                        })()
-                    };
-                }
-            };
-        }
-        assert<Equals<(typeof paramsOfBootstrap)["implementation"], "real">>;
-
-        const prVerifyAndDecodeAccessToken = (async () => {
-            const { createOidcBackend } = await import("../../backend");
-
-            const { verifyAndDecodeAccessToken } = await createOidcBackend({
-                issuerUri: paramsOfBootstrap.issuerUri,
-                decodedAccessTokenSchema: accessTokenClaimsSchema
-            });
-
-            return verifyAndDecodeAccessToken;
-        })();
-
-        const expectedAudience = (() => {
-            if (expectedAudienceGetter === undefined) {
-                return undefined;
-            }
-
-            const missingEnvNames = new Set<string>();
+                        })();
 
-            const env_proxy = new Proxy<Record<string, string>>(
-                {},
-                {
-                    get: (...[, envName]) => {
-                        assert(typeof envName === "string");
-
-                        const value = process.env[envName];
-
-                        if (value === undefined) {
-                            missingEnvNames.add(envName);
-                            return "";
-                        }
-
-                        return value;
-                    },
-                    has: (...[, envName]) => {
-                        assert(typeof envName === "string");
-                        return true;
+                        await bootstrapAuth({
+                            implementation: "mock",
+                            behavior: "use static identity",
+                            decodedAccessToken_mock
+                        });
                     }
-                }
-            );
-
-            const expectedAudience = expectedAudienceGetter?.({
-                paramsOfBootstrap,
-                process: { env: env_proxy }
-            });
-
-            if (!expectedAudience) {
-                throw new Error(
-                    [
-                        "oidc-spa: The expectedAudience() you provided returned empty.",
-                        "If you specified the expectedAudience in withAccessTokenValidation",
-                        "it's probably and error.",
-                        missingEnvNames.size !== 0 &&
-                            `Did you forget to set the env var: ${Array.from(missingEnvNames).join(
-                                ", "
-                            )} ?`
-                    ]
-                        .filter(line => typeof line === "string")
-                        .join(" ")
-                );
+                    break;
+                default:
+                    assert<Equals<typeof paramsOfBootstrap, never>>(false);
             }
 
-            return expectedAudience;
+            return validateAndDecodeAccessToken;
         })();
 
-        return {
-            validateAndGetAccessTokenClaims: async ({ accessToken }) => {
-                const verifyAndDecodeAccessToken = await prVerifyAndDecodeAccessToken;
-
-                const {
-                    isValid,
-                    errorCase,
-                    errorMessage,
-                    decodedAccessToken,
-                    decodedAccessToken_original
-                } = await verifyAndDecodeAccessToken({ accessToken });
-
-                if (!isValid) {
-                    return {
-                        isValid: false,
-                        errorMessage: `${errorCase}: ${errorMessage}`,
-                        wwwAuthenticateHeaderErrorDescription: (() => {
-                            switch (errorCase) {
-                                case "does not respect schema":
-                                    return "The access token is malformed or missing required claims";
-                                case "expired":
-                                    return "The access token expired";
-                                case "invalid signature":
-                                    return "The access token signature is invalid";
-                            }
-                        })()
-                    };
-                }
-
-                if (expectedAudience !== undefined) {
-                    const aud_array =
-                        typeof decodedAccessToken_original.aud === "string"
-                            ? [decodedAccessToken_original.aud]
-                            : decodedAccessToken_original.aud;
-
-                    if (!aud_array.includes(expectedAudience)) {
-                        return {
-                            isValid: false,
-                            errorMessage: [
-                                "Access token is not for the expected audience.",
-                                `Got aud claim: ${JSON.stringify(decodedAccessToken_original.aud)}`,
-                                `Expected: ${expectedAudience}`
-                            ].join(" "),
-                            wwwAuthenticateHeaderErrorDescription: "The access token audience is invalid"
-                        };
-                    }
+        const validateAndGetAccessTokenClaims: ValidateAndGetAccessTokenClaims<
+            AccessTokenClaims
+        > = async ({ request }) => {
+            const validateAndDecodeAccessToken = await prValidateAndDecodeAccessToken;
+
+            const { isSuccess, errorCause, debugErrorMessage, decodedAccessToken, accessToken } =
+                await validateAndDecodeAccessToken({
+                    request
+                });
+
+            if (!isSuccess) {
+                if (errorCause === "missing Authorization header") {
+                    return id<ValidateAndGetAccessTokenClaims.ReturnType.Errored.AnonymousRequest>({
+                        isSuccess: false,
+                        isAnonymousRequest: true
+                    });
                 }
 
-                return {
-                    isValid: true,
-                    accessTokenClaims: decodedAccessToken
-                };
+                return id<ValidateAndGetAccessTokenClaims.ReturnType.Errored.ValidationFailed>({
+                    isSuccess: false,
+                    isAnonymousRequest: false,
+                    debugErrorMessage: `${errorCause}: ${debugErrorMessage}`,
+                    wwwAuthenticateResponseHeaderValue: `Bearer error="invalid_token", error_description="${(() => {
+                        switch (errorCause) {
+                            case "validation error":
+                            case "validation error - invalid signature":
+                            case "validation error - access token expired":
+                                return "Validation Failed";
+                            default:
+                                assert<Equals<typeof errorCause, never>>(false);
+                        }
+                    })()}"`
+                });
             }
+
+            return id<ValidateAndGetAccessTokenClaims.ReturnType.Success<AccessTokenClaims>>({
+                isSuccess: true,
+                accessTokenClaims: decodedAccessToken,
+                accessToken
+            });
         };
+
+        return { validateAndGetAccessTokenClaims };
     };
 
     return { createValidateAndGetAccessTokenClaims };

package/src/tanstack-start/react/createOidcSpaApi.ts

@@ -1,7 +1,7 @@
 import { useState, useEffect, useReducer } from "react";
 import type {
     CreateValidateAndGetAccessTokenClaims,
-    OidcSpaApi,
+    OidcSpaUtils,
     UseOidc,
     GetOidc,
     ParamsOfBootstrap,
@@ -21,6 +21,7 @@ import type { GetterOrDirectValue } from "../../tools/GetterOrDirectValue";
 import { createServerFn, createMiddleware } from "@tanstack/react-start";
 // @ts-expect-error: Since our module is not labeled as ESM we don't have the types here.
 import { getRequest, setResponseHeader, setResponseStatus } from "@tanstack/react-start/server";
+//import { getRequest, setResponseHeader, setResponseStatus } from "@tanstack/react-start-server";
 import { toFullyQualifiedUrl } from "../../tools/toFullyQualifiedUrl";
 import { BEFORE_LOAD_FN_BRAND_PROPERTY_NAME } from "./disableSsrIfLoginEnforced";
 import { setDesiredPostLoginRedirectUrl } from "../../core/desiredPostLoginRedirectUrl";
@@ -40,7 +41,7 @@ export function createOidcSpaApi<
     createValidateAndGetAccessTokenClaims:
         | CreateValidateAndGetAccessTokenClaims<AccessTokenClaims>
         | undefined;
-}): OidcSpaApi<AutoLogin, DecodedIdToken, AccessTokenClaims> {
+}): OidcSpaUtils<AutoLogin, DecodedIdToken, AccessTokenClaims> {
     const {
         autoLogin,
         decodedIdTokenSchema,
@@ -667,7 +668,8 @@ export function createOidcSpaApi<
                                 __metadata: paramsOfBootstrap.__metadata,
                                 __unsafe_useIdTokenAsAccessToken:
                                     paramsOfBootstrap.__unsafe_useIdTokenAsAccessToken,
-                                autoLogoutParams: paramsOfBootstrap.autoLogoutParams
+                                autoLogoutParams: paramsOfBootstrap.autoLogoutParams,
+                                dpop: paramsOfBootstrap.dpop
                             });
                         } catch (error) {
                             if (!(error instanceof OidcInitializationError)) {
@@ -786,84 +788,86 @@ export function createOidcSpaApi<
             const { next } = options;
 
             const unauthorized = (params: {
-                errorMessage: string;
-                wwwAuthenticateHeaderErrorDescription: string;
+                code: 401 | 403;
+                wwwAuthenticateResponseHeaderValue: string;
+                debugErrorMessage: string;
             }) => {
-                const { errorMessage, wwwAuthenticateHeaderErrorDescription } = params;
-
-                setResponseHeader(
-                    "WWW-Authenticate",
-                    `Bearer error="invalid_token", error_description="${wwwAuthenticateHeaderErrorDescription}"`
+                const { code, wwwAuthenticateResponseHeaderValue, debugErrorMessage } = params;
+
+                setResponseHeader("WWW-Authenticate", wwwAuthenticateResponseHeaderValue);
+                setResponseStatus(
+                    code,
+                    (() => {
+                        switch (code) {
+                            case 401:
+                                return "Unauthorized";
+                            case 403:
+                                return "Forbidden";
+                            default:
+                                assert<Equals<typeof code, never>>(false);
+                        }
+                    })()
                 );
-                setResponseStatus(401, "Unauthorized");
 
-                return new Error(`oidc-spa: ${errorMessage}`);
+                if (process.env.NODE_ENV === "development") {
+                    console.error(`oidc-spa: ${debugErrorMessage}`);
+                }
+
+                return new Error(`oidc-spa: ${wwwAuthenticateResponseHeaderValue}`);
             };
 
-            const { headers } = getRequest();
+            assert(prValidateAndGetAccessTokenClaims !== undefined);
 
-            const authorizationHeaderValue = headers.get("Authorization");
+            const { validateAndGetAccessTokenClaims } = await prValidateAndGetAccessTokenClaims;
 
-            if (authorizationHeaderValue === null) {
-                if (params?.assert === "user logged in") {
-                    const errorMessage = [
-                        "Asserted user logged in for that serverFn request",
-                        "but no access token was attached to the request"
-                    ].join(" ");
+            const { headers, url, method } = getRequest();
 
-                    throw unauthorized({
-                        errorMessage,
-                        wwwAuthenticateHeaderErrorDescription: errorMessage
-                    });
+            const resultOfValidate = await validateAndGetAccessTokenClaims({
+                request: {
+                    url,
+                    method,
+                    headers: {
+                        Authorization: headers.get("Authorization"),
+                        DPoP: headers.get("DPoP")
+                    }
                 }
+            });
 
-                return next({
-                    context: {
-                        oidc: id<OidcServerContext<AccessTokenClaims>>(
-                            id<OidcServerContext.NotLoggedIn>({
-                                isUserLoggedIn: false
-                            })
-                        )
+            if (!resultOfValidate.isSuccess) {
+                if (resultOfValidate.isAnonymousRequest) {
+                    if (params?.assert === "user logged in") {
+                        throw unauthorized({
+                            code: 401,
+                            wwwAuthenticateResponseHeaderValue:
+                                'Bearer error="invalid_request", error_description="Missing access token"',
+                            debugErrorMessage: [
+                                "Asserted user logged in for that serverFn request",
+                                "but no access token was attached to the request"
+                            ].join(" ")
+                        });
                     }
-                });
-            }
 
-            const accessToken = (() => {
-                const prefix = "Bearer ";
-
-                if (!authorizationHeaderValue.startsWith(prefix)) {
-                    return undefined;
+                    return next({
+                        context: {
+                            oidc: id<OidcServerContext<AccessTokenClaims>>(
+                                id<OidcServerContext.NotLoggedIn>({
+                                    isUserLoggedIn: false
+                                })
+                            )
+                        }
+                    });
                 }
 
-                return authorizationHeaderValue.slice(prefix.length);
-            })();
-
-            if (accessToken === undefined) {
-                const errorMessage =
-                    "Missing well formed Authorization header with Bearer <access_token>";
-
-                throw unauthorized({
-                    errorMessage,
-                    wwwAuthenticateHeaderErrorDescription: errorMessage
-                });
-            }
-
-            assert(prValidateAndGetAccessTokenClaims !== undefined);
-
-            const { validateAndGetAccessTokenClaims } = await prValidateAndGetAccessTokenClaims;
-
-            const resultOfValidate = await validateAndGetAccessTokenClaims({ accessToken });
-
-            if (!resultOfValidate.isValid) {
-                const { errorMessage, wwwAuthenticateHeaderErrorDescription } = resultOfValidate;
+                const { debugErrorMessage, wwwAuthenticateResponseHeaderValue } = resultOfValidate;
 
                 throw unauthorized({
-                    errorMessage,
-                    wwwAuthenticateHeaderErrorDescription
+                    code: 401,
+                    wwwAuthenticateResponseHeaderValue,
+                    debugErrorMessage
                 });
             }
 
-            const { accessTokenClaims } = resultOfValidate;
+            const { accessTokenClaims, accessToken } = resultOfValidate;
 
             assert(is<Exclude<AccessTokenClaims, undefined>>(accessTokenClaims));
 
@@ -900,14 +904,14 @@ export function createOidcSpaApi<
                     break check_required_claims;
                 }
 
-                const errorMessage = [
-                    "Missing or invalid required access token claim.",
-                    `Related to claims: ${Array.from(accessedClaimNames).join(" and/or ")}`
-                ].join(" ");
-
                 throw unauthorized({
-                    errorMessage,
-                    wwwAuthenticateHeaderErrorDescription: errorMessage
+                    code: 403,
+                    wwwAuthenticateResponseHeaderValue:
+                        'Bearer error="insufficient_scope", error_description="Insufficient privileges"',
+                    debugErrorMessage: [
+                        "Missing or invalid required access token claim.",
+                        `Related to claims: ${Array.from(accessedClaimNames).join(" and/or ")}`
+                    ].join(" ")
                 });
             }
 

package/src/tanstack-start/react/index.ts

@@ -1,6 +1,6 @@
 export { __disableSsrIfLoginEnforced } from "./disableSsrIfLoginEnforced";
 export { __withOidcSpaServerEntry } from "./withOidcSpaServerEntry";
 export type * from "./types";
-import { oidcSpaApiBuilder } from "./apiBuilder";
+import { oidcSpaUtilsBuilder } from "./utilsBuilder";
 
-export const oidcSpa = oidcSpaApiBuilder;
+export const oidcSpa = oidcSpaUtilsBuilder;