@flink-app/oidc-plugin 2.0.0-alpha.122 → 2.0.0-alpha.123

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @flink-app/oidc-plugin
 
+## 2.0.0-alpha.123
+
+### Minor Changes
+
+-   f69d88e: Add a `basePath` option to both plugins, and `allowedRedirectUris` to `oauth-plugin`.
+
+    **`basePath` (oauth-plugin, oidc-plugin):** prefix for the routes the plugin registers, for apps that keep every backend route under e.g. `/api` so an SPA fallback can own the rest. `basePath: "/api"` registers `/api/oauth/:provider/{initiate,callback}` and `/api/oidc/:provider/{initiate,callback}`. `"api"`, `"/api"` and `"/api/"` are equivalent. The OIDC auto-detected callback fallback includes the prefix, and the effective paths are logged at startup. Default `""` keeps the routes at the root.
+
+    **`allowedRedirectUris` (oauth-plugin):** ported from `oidc-plugin` with the same semantics. The `?redirectUri=` on `/oauth/:provider/initiate` is checked against the list (exact URIs, bare origins or a predicate); a mismatch answers `400 invalid_redirect_uri` and no session is created. Relative paths and the provider's `callbackUrl` are always accepted. The `redirectUrl` returned by `onAuthSuccess` / `onAuthError` is checked too when it differs from the session's. `AllowedRedirectUris`, `isRedirectUriAllowed` and `isRelativeRedirect` are exported.
+
+    Non-breaking: both options are optional. Without `allowedRedirectUris` every `redirectUri` is still accepted and the plugin logs a warning at startup. Existing `400` responses keep their `code` (`badRequest`); only the new `invalid_redirect_uri` rejection carries its own code.
+
+### Patch Changes
+
+-   @flink-app/flink@2.0.0-alpha.123
+-   @flink-app/jwt-auth-plugin@2.0.0-alpha.123
+
 ## 2.0.0-alpha.122
 
 ### Patch Changes

package/README.md

@@ -178,6 +178,34 @@ await app.start();
 | `encryptionKey`             | `string`   | No       | (derived)          | Encryption key for tokens (32+ chars recommended)      |
 | `tokenDelivery`             | `"fragment"` \| `"query"` \| `Function` | No | `"fragment"` | How the JWT is attached on the post-callback redirect (see [Token Delivery](#token-delivery-fragment-vs-query)) |
 | `registerRoutes`            | `boolean`  | No       | `true`             | Auto-register OIDC routes                              |
+| `basePath`                  | `string`   | No       | `""`               | Prefix for the registered routes (see [Route Prefix](#route-prefix-basepath)) |
+
+### Route Prefix (`basePath`)
+
+Apps that serve an SPA and the API from the same origin usually keep every backend route under
+a prefix (e.g. `/api`) so the SPA fallback can own everything else. `basePath` moves the
+plugin's routes under that prefix:
+
+```typescript
+oidcPlugin({
+    basePath: "/api", // routes become /api/oidc/:provider/initiate and /api/oidc/:provider/callback
+    providers: {
+        acme: {
+            issuer: "https://idp.acme.com",
+            clientId: process.env.OIDC_CLIENT_ID!,
+            clientSecret: process.env.OIDC_CLIENT_SECRET!,
+            callbackUrl: "https://myapp.com/api/oidc/acme/callback", // include the prefix
+            discoveryUrl: "https://idp.acme.com/.well-known/openid-configuration",
+        },
+    },
+    // ...
+});
+```
+
+- `"api"`, `"/api"` and `"/api/"` are equivalent; the default `""` keeps the routes at the root.
+- The prefix is **not** added to a provider's `callbackUrl` for you — include it there and in the redirect URI registered at the IdP.
+- The auto-detected callback fallback (used when a provider has no `callbackUrl`) includes the prefix.
+- The effective paths are logged at startup, which makes a mismatched callback URL easy to spot.
 
 ### Provider Configuration
 

package/dist/OidcPlugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OidcPlugin.d.ts","sourceRoot":"","sources":["../src/OidcPlugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,WAAW,EAAO,MAAM,kBAAkB,CAAC;AAG9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAWxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH,wBAAgB,UAAU,CAAC,IAAI,GAAG,GAAG,EAAE,OAAO,EAAE,iBAAiB,CAAC,IAAI,CAAC,GAAG,WAAW,CAgRpF"}
+{"version":3,"file":"OidcPlugin.d.ts","sourceRoot":"","sources":["../src/OidcPlugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,WAAW,EAAO,MAAM,kBAAkB,CAAC;AAG9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAYxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH,wBAAgB,UAAU,CAAC,IAAI,GAAG,GAAG,EAAE,OAAO,EAAE,iBAAiB,CAAC,IAAI,CAAC,GAAG,WAAW,CA4RpF"}

package/dist/OidcPlugin.js

@@ -32,6 +32,7 @@ const log_1 = require("./log");
 const OidcSessionRepo_1 = __importDefault(require("./repos/OidcSessionRepo"));
 const OidcConnectionRepo_1 = __importDefault(require("./repos/OidcConnectionRepo"));
 const encryption_utils_1 = require("./utils/encryption-utils");
+const base_path_utils_1 = require("./utils/base-path-utils");
 const ProviderRegistry_1 = require("./providers/ProviderRegistry");
 const InitiateOidc = __importStar(require("./handlers/InitiateOidc"));
 const CallbackOidc = __importStar(require("./handlers/CallbackOidc"));
@@ -155,6 +156,13 @@ function oidcPlugin(options) {
     else {
         log_1.oidcLog.debug("Redirect URI allow-list: predicate function");
     }
+    let basePath;
+    try {
+        basePath = (0, base_path_utils_1.normalizeBasePath)(options.basePath);
+    }
+    catch (error) {
+        throw new Error(`OIDC Plugin: ${error.message}`);
+    }
     // Provider cache TTL (0 = cache for the life of the process, unchanged behaviour)
     const providerCacheTtlSec = options.providerCacheTtlSec ?? 0;
     if (typeof providerCacheTtlSec !== "number" || !Number.isFinite(providerCacheTtlSec) || providerCacheTtlSec < 0) {
@@ -222,8 +230,11 @@ function oidcPlugin(options) {
             // Register OIDC handlers
             // Only register handlers if registerRoutes is enabled (default: true)
             if (options.registerRoutes !== false) {
-                flinkApp.addHandler(InitiateOidc);
-                flinkApp.addHandler(CallbackOidc);
+                const initiatePath = basePath + InitiateOidc.Route.path;
+                const callbackPath = basePath + CallbackOidc.Route.path;
+                flinkApp.addHandler(InitiateOidc, { path: initiatePath });
+                flinkApp.addHandler(CallbackOidc, { path: callbackPath });
+                flink_1.log.info(`OIDC Plugin: registered routes GET ${initiatePath} and GET ${callbackPath}`);
             }
             flink_1.log.info(`OIDC Plugin initialized${configuredProviders.length > 0 ? ` with providers: ${configuredProviders.join(", ")}` : " with dynamic provider loader"}`);
         }

package/dist/OidcPluginOptions.d.ts

@@ -450,5 +450,20 @@ export interface OidcPluginOptions<TCtx = any> {
      * or use a custom URL structure.
      */
     registerRoutes?: boolean;
+    /**
+     * Path prefix for the routes registered by the plugin
+     *
+     * With `basePath: "/api"` the routes become `/api/oidc/:provider/initiate` and
+     * `/api/oidc/:provider/callback`. Useful when the app serves an SPA from the same
+     * origin and keeps every backend route under a prefix.
+     *
+     * Normalised: `"api"`, `"/api"` and `"/api/"` are equivalent. Remember to include the
+     * prefix in each provider's `callbackUrl` and in the redirect URI registered at the IdP.
+     * The auto-detected callback fallback (used when a provider has no `callbackUrl`)
+     * includes the prefix.
+     *
+     * Default: "" (routes at the root)
+     */
+    basePath?: string;
 }
 //# sourceMappingURL=OidcPluginOptions.d.ts.map

package/dist/OidcPluginOptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OidcPluginOptions.d.ts","sourceRoot":"","sources":["../src/OidcPluginOptions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"OidcPluginOptions.d.ts","sourceRoot":"","sources":["../src/OidcPluginOptions.ts"],"names":[],"mappings":"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"}

package/dist/handlers/InitiateOidc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"InitiateOidc.d.ts","sourceRoot":"","sources":["../../src/handlers/InitiateOidc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAc,UAAU,EAAmC,MAAM,kBAAkB,CAAC;AACvG,OAAO,eAAe,MAAM,4BAA4B,CAAC;AAOzD;;GAEG;AACH,UAAU,UAAU;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,eAAO,MAAM,KAAK,EAAE,UAGnB,CAAC;AAEF;;;;;GAKG;AACH,QAAA,MAAM,YAAY,EAAE,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,UAAU,EAAE,eAAe,CA4FnE,CAAC;AAEF,eAAe,YAAY,CAAC"}
+{"version":3,"file":"InitiateOidc.d.ts","sourceRoot":"","sources":["../../src/handlers/InitiateOidc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAc,UAAU,EAAmC,MAAM,kBAAkB,CAAC;AACvG,OAAO,eAAe,MAAM,4BAA4B,CAAC;AAQzD;;GAEG;AACH,UAAU,UAAU;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,eAAO,MAAM,KAAK,EAAE,UAGnB,CAAC;AAEF;;;;;GAKG;AACH,QAAA,MAAM,YAAY,EAAE,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,UAAU,EAAE,eAAe,CA4FnE,CAAC;AAEF,eAAe,YAAY,CAAC"}

package/dist/handlers/InitiateOidc.js

@@ -17,6 +17,7 @@ const flink_1 = require("@flink-app/flink");
 const state_utils_1 = require("../utils/state-utils");
 const error_utils_1 = require("../utils/error-utils");
 const redirect_uri_utils_1 = require("../utils/redirect-uri-utils");
+const base_path_utils_1 = require("../utils/base-path-utils");
 const openid_client_1 = require("openid-client");
 const log_1 = require("../log");
 /**
@@ -59,7 +60,7 @@ const InitiateOidc = async ({ ctx, req }) => {
             log_1.oidcLog.debug(`Initiate: rejected redirectUri="${redirectUri}" (not in allowedRedirectUris)`);
             throw (0, error_utils_1.createOidcError)(error_utils_1.OidcErrorCodes.INVALID_REDIRECT_URI, "The provided redirectUri is not allowed", { redirectUri, provider });
         }
-        const finalRedirectUri = redirectUri || callbackUrl || `${req.protocol}://${req.get("host")}/oidc/${provider}/callback`;
+        const finalRedirectUri = redirectUri || callbackUrl || `${req.protocol}://${req.get("host")}${(0, base_path_utils_1.normalizeBasePath)(options.basePath)}/oidc/${provider}/callback`;
         // Collect meta.* query params as opaque metadata (prefix stripped)
         const metadata = {};
         for (const [key, value] of Object.entries(req.query)) {

package/dist/utils/base-path-utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Normalise the `basePath` plugin option into a route prefix.
+ *
+ * A leading slash is added and trailing slashes are stripped, so `"api"`, `"/api"` and
+ * `"/api/"` all become `"/api"`. An empty value (or `"/"`) yields `""`, i.e. routes stay
+ * at the root.
+ */
+export declare function normalizeBasePath(basePath?: string): string;
+//# sourceMappingURL=base-path-utils.d.ts.map

package/dist/utils/base-path-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-path-utils.d.ts","sourceRoot":"","sources":["../../src/utils/base-path-utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAY3D"}

package/dist/utils/base-path-utils.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeBasePath = normalizeBasePath;
+/**
+ * Normalise the `basePath` plugin option into a route prefix.
+ *
+ * A leading slash is added and trailing slashes are stripped, so `"api"`, `"/api"` and
+ * `"/api/"` all become `"/api"`. An empty value (or `"/"`) yields `""`, i.e. routes stay
+ * at the root.
+ */
+function normalizeBasePath(basePath) {
+    if (basePath === undefined || basePath === null) {
+        return "";
+    }
+    if (typeof basePath !== "string") {
+        throw new Error("basePath must be a string");
+    }
+    const trimmed = basePath.trim().replace(/^\/+/, "").replace(/\/+$/, "");
+    return trimmed ? `/${trimmed}` : "";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flink-app/oidc-plugin",
-  "version": "2.0.0-alpha.122",
+  "version": "2.0.0-alpha.123",
   "description": "Flink plugin for OIDC authentication with generic IdP support",
   "author": "joel@frost.se",
   "license": "MIT",
@@ -11,10 +11,10 @@
   },
   "dependencies": {
     "openid-client": "^5.7.0",
-    "@flink-app/jwt-auth-plugin": "2.0.0-alpha.122"
+    "@flink-app/jwt-auth-plugin": "2.0.0-alpha.123"
   },
   "peerDependencies": {
-    "@flink-app/flink": ">=2.0.0-alpha.122",
+    "@flink-app/flink": ">=2.0.0-alpha.123",
     "mongodb": ">=3.7.0 <7.0.0"
   },
   "peerDependenciesMeta": {
@@ -27,9 +27,9 @@
     "@types/node": "22.13.10",
     "ts-node": "^10.9.2",
     "tsc-watch": "^4.2.9",
-    "@flink-app/test-utils": "2.0.0-alpha.122",
-    "@flink-app/jwt-auth-plugin": "2.0.0-alpha.122",
-    "@flink-app/flink": "2.0.0-alpha.122"
+    "@flink-app/flink": "2.0.0-alpha.123",
+    "@flink-app/test-utils": "2.0.0-alpha.123",
+    "@flink-app/jwt-auth-plugin": "2.0.0-alpha.123"
   },
   "scripts": {
     "test": "jasmine-ts --config=./spec/support/jasmine.json",

package/spec/handlers/InitiateOidc.spec.ts

@@ -153,4 +153,41 @@ describe("InitiateOidc handler", () => {
             expect(sessions[0].redirectUri).toBe("https://api.example.com/oidc/test/callback");
         });
     });
+
+    describe("auto-detected callback fallback", () => {
+        async function initiateWithoutCallbackUrl(pluginOptions: any) {
+            const ctx = createMockCtx(
+                {
+                    providers: {},
+                    providerLoader: async () => null,
+                    onAuthSuccess: async () => ({ user: {}, token: "jwt" }),
+                    ...pluginOptions,
+                },
+                {
+                    config: {},
+                    getAuthorizationUrl: async () => "https://test-idp.example.com/authorize",
+                }
+            );
+
+            const res: any = await (InitiateOidc as any)({ ctx, req: createMockReq({ provider: "test" }, {}) });
+
+            return { res, sessions: ctx.repos.oidcSessionRepo.sessions };
+        }
+
+        it("should build the fallback from the request host", async () => {
+            const { res, sessions } = await initiateWithoutCallbackUrl({});
+            expect(res.status).toBe(302);
+            expect(sessions[0].redirectUri).toBe("https://api.example.com/oidc/test/callback");
+        });
+
+        it("should include basePath in the fallback", async () => {
+            const { sessions } = await initiateWithoutCallbackUrl({ basePath: "/api" });
+            expect(sessions[0].redirectUri).toBe("https://api.example.com/api/oidc/test/callback");
+        });
+
+        it("should normalise basePath in the fallback", async () => {
+            const { sessions } = await initiateWithoutCallbackUrl({ basePath: "api/" });
+            expect(sessions[0].redirectUri).toBe("https://api.example.com/api/oidc/test/callback");
+        });
+    });
 });

package/spec/plugin/OidcPlugin.spec.ts

@@ -389,4 +389,56 @@ describe("OidcPlugin", () => {
             }).toThrowError(/allowedRedirectUris must be an array of non-empty strings or a predicate function/);
         });
     });
+
+    describe("basePath option", () => {
+        const fakeDb = {
+            collection: () => ({ createIndex: async () => undefined }),
+        };
+
+        async function registeredPaths(options: any): Promise<string[]> {
+            const paths: string[] = [];
+            const app = {
+                ctx: {} as any,
+                addRepo: () => undefined,
+                addHandler: (handler: any, routePropsOverride?: any) => {
+                    paths.push({ ...handler.Route, ...routePropsOverride }.path);
+                },
+            };
+
+            const plugin = oidcPlugin({
+                providers: { test: createTestProviderConfig() },
+                onAuthSuccess: async () => ({ user: {}, token: "" }),
+                ...options,
+            });
+            await plugin.init!(app as any, fakeDb as any);
+
+            return paths;
+        }
+
+        it("should register routes at the root by default", async () => {
+            expect(await registeredPaths({})).toEqual(["/oidc/:provider/initiate", "/oidc/:provider/callback"]);
+        });
+
+        it("should register routes at the root for an empty basePath", async () => {
+            expect(await registeredPaths({ basePath: "" })).toEqual(["/oidc/:provider/initiate", "/oidc/:provider/callback"]);
+        });
+
+        it("should prefix routes with basePath", async () => {
+            expect(await registeredPaths({ basePath: "/api" })).toEqual(["/api/oidc/:provider/initiate", "/api/oidc/:provider/callback"]);
+        });
+
+        it("should normalise basePath before prefixing", async () => {
+            expect(await registeredPaths({ basePath: "api/" })).toEqual(["/api/oidc/:provider/initiate", "/api/oidc/:provider/callback"]);
+        });
+
+        it("should throw for a non-string basePath", () => {
+            expect(() =>
+                oidcPlugin({
+                    providers: { test: createTestProviderConfig() },
+                    basePath: 1 as any,
+                    onAuthSuccess: async () => ({ user: {}, token: "" }),
+                })
+            ).toThrowError(/OIDC Plugin: basePath must be a string/);
+        });
+    });
 });

package/src/OidcPlugin.ts

@@ -7,6 +7,7 @@ import { OidcInternalContext } from "./OidcInternalContext";
 import OidcSessionRepo from "./repos/OidcSessionRepo";
 import OidcConnectionRepo from "./repos/OidcConnectionRepo";
 import { decryptToken, validateEncryptionSecret } from "./utils/encryption-utils";
+import { normalizeBasePath } from "./utils/base-path-utils";
 import OidcConnection from "./schemas/OidcConnection";
 import { ProviderRegistry } from "./providers/ProviderRegistry";
 import * as InitiateOidc from "./handlers/InitiateOidc";
@@ -148,6 +149,13 @@ export function oidcPlugin<TCtx = any>(options: OidcPluginOptions<TCtx>): FlinkP
         oidcLog.debug("Redirect URI allow-list: predicate function");
     }
 
+    let basePath: string;
+    try {
+        basePath = normalizeBasePath(options.basePath);
+    } catch (error: any) {
+        throw new Error(`OIDC Plugin: ${error.message}`);
+    }
+
     // Provider cache TTL (0 = cache for the life of the process, unchanged behaviour)
     const providerCacheTtlSec = options.providerCacheTtlSec ?? 0;
 
@@ -242,8 +250,13 @@ export function oidcPlugin<TCtx = any>(options: OidcPluginOptions<TCtx>): FlinkP
             // Register OIDC handlers
             // Only register handlers if registerRoutes is enabled (default: true)
             if (options.registerRoutes !== false) {
-                flinkApp.addHandler(InitiateOidc);
-                flinkApp.addHandler(CallbackOidc);
+                const initiatePath = basePath + InitiateOidc.Route.path;
+                const callbackPath = basePath + CallbackOidc.Route.path;
+
+                flinkApp.addHandler(InitiateOidc, { path: initiatePath });
+                flinkApp.addHandler(CallbackOidc, { path: callbackPath });
+
+                log.info(`OIDC Plugin: registered routes GET ${initiatePath} and GET ${callbackPath}`);
             }
 
             log.info(`OIDC Plugin initialized${configuredProviders.length > 0 ? ` with providers: ${configuredProviders.join(", ")}` : " with dynamic provider loader"}`);

package/src/OidcPluginOptions.ts

@@ -487,4 +487,20 @@ export interface OidcPluginOptions<TCtx = any> {
      * or use a custom URL structure.
      */
     registerRoutes?: boolean;
+
+    /**
+     * Path prefix for the routes registered by the plugin
+     *
+     * With `basePath: "/api"` the routes become `/api/oidc/:provider/initiate` and
+     * `/api/oidc/:provider/callback`. Useful when the app serves an SPA from the same
+     * origin and keeps every backend route under a prefix.
+     *
+     * Normalised: `"api"`, `"/api"` and `"/api/"` are equivalent. Remember to include the
+     * prefix in each provider's `callbackUrl` and in the redirect URI registered at the IdP.
+     * The auto-detected callback fallback (used when a provider has no `callbackUrl`)
+     * includes the prefix.
+     *
+     * Default: "" (routes at the root)
+     */
+    basePath?: string;
 }

package/src/handlers/InitiateOidc.ts

@@ -16,6 +16,7 @@ import InitiateRequest from "../schemas/InitiateRequest";
 import { generateState, generateSessionId, generateNonce } from "../utils/state-utils";
 import { validateProvider, createOidcError, OidcErrorCodes } from "../utils/error-utils";
 import { isRedirectUriAllowed } from "../utils/redirect-uri-utils";
+import { normalizeBasePath } from "../utils/base-path-utils";
 import { generators } from "openid-client";
 import { oidcLog } from "../log";
 
@@ -76,7 +77,7 @@ const InitiateOidc: GetHandler<any, any, PathParams, InitiateRequest> = async ({
             throw createOidcError(OidcErrorCodes.INVALID_REDIRECT_URI, "The provided redirectUri is not allowed", { redirectUri, provider });
         }
 
-        const finalRedirectUri = redirectUri || callbackUrl || `${req.protocol}://${req.get("host")}/oidc/${provider}/callback`;
+        const finalRedirectUri = redirectUri || callbackUrl || `${req.protocol}://${req.get("host")}${normalizeBasePath(options.basePath)}/oidc/${provider}/callback`;
 
         // Collect meta.* query params as opaque metadata (prefix stripped)
         const metadata: Record<string, string> = {};

package/src/utils/base-path-utils.ts

@@ -0,0 +1,20 @@
+/**
+ * Normalise the `basePath` plugin option into a route prefix.
+ *
+ * A leading slash is added and trailing slashes are stripped, so `"api"`, `"/api"` and
+ * `"/api/"` all become `"/api"`. An empty value (or `"/"`) yields `""`, i.e. routes stay
+ * at the root.
+ */
+export function normalizeBasePath(basePath?: string): string {
+    if (basePath === undefined || basePath === null) {
+        return "";
+    }
+
+    if (typeof basePath !== "string") {
+        throw new Error("basePath must be a string");
+    }
+
+    const trimmed = basePath.trim().replace(/^\/+/, "").replace(/\/+$/, "");
+
+    return trimmed ? `/${trimmed}` : "";
+}