@flink-app/oidc-plugin 2.0.0-alpha.116 → 2.0.0-alpha.118

package/spec/handlers/CallbackOidc.spec.ts

@@ -0,0 +1,330 @@
+/**
+ * Tests for CallbackOidc handler
+ *
+ * Note: These are unit tests for handler logic with a mocked provider.
+ * For full integration tests, use the test-utils package in a demo app.
+ */
+
+import CallbackOidc from "../../src/handlers/CallbackOidc";
+import { OidcErrorCodes } from "../../src/utils/error-utils";
+import { createMockCtx, createMockReq, createMockProfile, createMockTokenSet, createTestProviderConfig } from "../helpers/test-helpers";
+
+const CALLBACK_URL = "https://api.example.com/oidc/test/callback";
+const SESSION_REDIRECT_URI = "https://app.example.com/auth-callback";
+const STATE = "a".repeat(64);
+
+/**
+ * Run the callback handler with a mocked context, session and provider.
+ */
+async function callback(pluginOptions: any, query: Record<string, any> = {}, sessionRedirectUri: string = SESSION_REDIRECT_URI) {
+    return (await callbackWithCtx(pluginOptions, query, sessionRedirectUri)).res;
+}
+
+/**
+ * Same as `callback`, but also returns the mocked context so repo writes can be asserted.
+ */
+async function callbackWithCtx(pluginOptions: any, query: Record<string, any> = {}, sessionRedirectUri: string = SESSION_REDIRECT_URI) {
+    const providerConfig = createTestProviderConfig({ callbackUrl: CALLBACK_URL });
+
+    const ctx = createMockCtx(
+        {
+            providers: { test: providerConfig },
+            onAuthSuccess: async () => ({ user: { _id: "user-1" }, token: "jwt-token" }),
+            ...pluginOptions,
+        },
+        {
+            config: providerConfig,
+            exchangeCodeForToken: async () => createMockTokenSet(),
+            buildProfile: async () => createMockProfile(),
+        }
+    );
+
+    await ctx.repos.oidcSessionRepo.create({
+        sessionId: "session-1",
+        state: STATE,
+        codeVerifier: "verifier",
+        nonce: "nonce",
+        provider: "test",
+        redirectUri: sessionRedirectUri,
+        metadata: {},
+        createdAt: new Date(),
+    });
+
+    const res: any = await (CallbackOidc as any)({
+        ctx,
+        req: createMockReq({ provider: "test" }, { code: "auth-code", state: STATE, ...query }),
+    });
+
+    return { res, ctx };
+}
+
+describe("CallbackOidc handler", () => {
+    describe("Route configuration", () => {
+        it("should export correct route configuration", () => {
+            const { Route } = require("../../src/handlers/CallbackOidc");
+            expect(Route.path).toBe("/oidc/:provider/callback");
+            expect(Route.method).toBe("get");
+        });
+    });
+
+    describe("redirectUri allow-list", () => {
+        it("should redirect to the session redirectUri when the host returns no redirectUrl", async () => {
+            const res = await callback({ allowedRedirectUris: ["https://app.example.com"] });
+
+            expect(res.status).toBe(302);
+            expect(res.headers.Location).toContain(`${SESSION_REDIRECT_URI}#token=`);
+        });
+
+        it("should allow a host-returned redirectUrl inside the allow-list", async () => {
+            const res = await callback({
+                allowedRedirectUris: ["https://app.example.com"],
+                onAuthSuccess: async () => ({ user: { _id: "user-1" }, token: "jwt-token", redirectUrl: "https://app.example.com/welcome" }),
+            });
+
+            expect(res.status).toBe(302);
+            expect(res.headers.Location).toContain("https://app.example.com/welcome#token=");
+        });
+
+        it("should reject a host-returned redirectUrl outside the allow-list", async () => {
+            const res = await callback({
+                allowedRedirectUris: ["https://app.example.com"],
+                onAuthSuccess: async () => ({ user: { _id: "user-1" }, token: "jwt-token", redirectUrl: "https://evil.example/cb" }),
+            });
+
+            expect(res.status).toBe(400);
+            expect(res.error.code).toBe(OidcErrorCodes.INVALID_REDIRECT_URI);
+        });
+
+        it("should allow a relative host-returned redirectUrl", async () => {
+            const res = await callback({
+                allowedRedirectUris: ["https://app.example.com"],
+                onAuthSuccess: async () => ({ user: { _id: "user-1" }, token: "jwt-token", redirectUrl: "/dashboard" }),
+            });
+
+            expect(res.status).toBe(302);
+            expect(res.headers.Location).toContain("/dashboard#token=");
+        });
+
+        it("should allow any host-returned redirectUrl when no allow-list is configured", async () => {
+            const res = await callback({
+                onAuthSuccess: async () => ({ user: { _id: "user-1" }, token: "jwt-token", redirectUrl: "https://anywhere.example/cb" }),
+            });
+
+            expect(res.status).toBe(302);
+            expect(res.headers.Location).toContain("https://anywhere.example/cb#token=");
+        });
+
+        it("should not apply the allow-list to JSON responses", async () => {
+            const res = await callback(
+                {
+                    allowedRedirectUris: ["https://app.example.com"],
+                    onAuthSuccess: async () => ({ user: { _id: "user-1" }, token: "jwt-token", redirectUrl: "https://evil.example/cb" }),
+                },
+                { response_type: "json" }
+            );
+
+            expect(res.data.token).toBe("jwt-token");
+        });
+
+        it("should ignore an onAuthError redirectUrl outside the allow-list", async () => {
+            const res = await callback(
+                {
+                    allowedRedirectUris: ["https://app.example.com"],
+                    onAuthError: async () => ({ redirectUrl: "https://evil.example/cb" }),
+                },
+                { error: "access_denied" }
+            );
+
+            expect(res.status).toBe(400);
+            expect(res.error.code).toBe(OidcErrorCodes.ACCESS_DENIED);
+        });
+
+        it("should follow an onAuthError redirectUrl inside the allow-list", async () => {
+            const res = await callback(
+                {
+                    allowedRedirectUris: ["https://app.example.com"],
+                    onAuthError: async () => ({ redirectUrl: "https://app.example.com/login?error=denied" }),
+                },
+                { error: "access_denied" }
+            );
+
+            expect(res.status).toBe(302);
+            expect(res.headers.Location).toBe("https://app.example.com/login?error=denied");
+        });
+    });
+
+    describe("completion shapes", () => {
+        const user = { _id: "user-1" };
+
+        describe("token (default)", () => {
+            it("should attach the token as a fragment", async () => {
+                const res = await callback({ onAuthSuccess: async () => ({ user, token: "jwt-token", redirectUrl: SESSION_REDIRECT_URI }) });
+
+                expect(res.status).toBe(302);
+                expect(res.headers.Location).toBe(`${SESSION_REDIRECT_URI}#token=jwt-token`);
+            });
+
+            it("should attach the token as a query param when tokenDelivery is query", async () => {
+                const res = await callback({
+                    tokenDelivery: "query",
+                    onAuthSuccess: async () => ({ user, token: "jwt-token", redirectUrl: SESSION_REDIRECT_URI }),
+                });
+
+                expect(res.status).toBe(302);
+                expect(res.headers.Location).toBe(`${SESSION_REDIRECT_URI}?token=jwt-token`);
+            });
+
+            it("should return JSON for response_type=json", async () => {
+                const res = await callback({ onAuthSuccess: async () => ({ user, token: "jwt-token" }) }, { response_type: "json" });
+
+                expect(res.data.token).toBe("jwt-token");
+                expect(res.data.user).toEqual(user);
+            });
+        });
+
+        describe("verbatim redirect (no token)", () => {
+            it("should redirect verbatim without attaching a token", async () => {
+                const doneUrl = "https://app.example.com/done?code=one-time-code";
+                const res = await callback({ onAuthSuccess: async () => ({ user, redirectUrl: doneUrl }) });
+
+                expect(res.status).toBe(302);
+                expect(res.headers.Location).toBe(doneUrl);
+                expect(res.headers.Location).not.toContain("token=");
+            });
+
+            it("should apply the redirectUri allow-list", async () => {
+                const res = await callback({
+                    allowedRedirectUris: ["https://app.example.com"],
+                    onAuthSuccess: async () => ({ user, redirectUrl: "https://evil.example/cb?code=x" }),
+                });
+
+                expect(res.status).toBe(400);
+                expect(res.error.code).toBe(OidcErrorCodes.INVALID_REDIRECT_URI);
+            });
+
+            it("should allow a relative redirect", async () => {
+                const res = await callback({
+                    allowedRedirectUris: ["https://app.example.com"],
+                    onAuthSuccess: async () => ({ user, redirectUrl: "/done?code=one-time-code" }),
+                });
+
+                expect(res.status).toBe(302);
+                expect(res.headers.Location).toBe("/done?code=one-time-code");
+            });
+
+            it("should reject response_type=json when there is no token", async () => {
+                const res = await callback(
+                    { onAuthSuccess: async () => ({ user, redirectUrl: "https://app.example.com/done?code=x" }) },
+                    { response_type: "json" }
+                );
+
+                expect(res.status).toBe(400);
+                expect(res.error.code).toBe(OidcErrorCodes.INVALID_RESPONSE_TYPE);
+            });
+        });
+
+        describe("host-built response", () => {
+            it("should return the response as-is", async () => {
+                const hostResponse = {
+                    status: 302,
+                    headers: {
+                        "Set-Cookie": "session=abc; HttpOnly; Secure; Path=/",
+                        Location: "https://app.example.com/dashboard",
+                    },
+                    data: {},
+                };
+
+                const res = await callback({ onAuthSuccess: async () => ({ user, response: hostResponse }) });
+
+                expect(res).toBe(hostResponse);
+            });
+
+            it("should allow a JSON envelope of the host's own shape", async () => {
+                const res = await callback({
+                    onAuthSuccess: async () => ({
+                        user,
+                        response: { data: { accessToken: "at", refreshToken: "rt", profile: { id: "user-1" } } },
+                    }),
+                });
+
+                expect(res.data.accessToken).toBe("at");
+                expect(res.data.refreshToken).toBe("rt");
+            });
+
+            it("should take precedence over response_type=json", async () => {
+                const res = await callback(
+                    { onAuthSuccess: async () => ({ user, response: { status: 204 } }) },
+                    { response_type: "json" }
+                );
+
+                expect(res.status).toBe(204);
+            });
+        });
+
+        it("should fail when the callback returns no completion at all", async () => {
+            const res = await callback({ onAuthSuccess: async () => ({ user }) });
+
+            expect(res.status).toBe(400);
+            expect(res.error.code).toBe(OidcErrorCodes.JWT_GENERATION_FAILED);
+        });
+
+        describe("storeTokens", () => {
+            const storeTokensOptions = {
+                storeTokens: true,
+                encryptionKey: "test-encryption-key-at-least-32-characters",
+            };
+
+            async function connectionsWrittenFor(onAuthSuccess: any): Promise<any[]> {
+                const { ctx } = await callbackWithCtx({ ...storeTokensOptions, onAuthSuccess });
+
+                return ctx.repos.oidcConnectionRepo.created;
+            }
+
+            it("should write the connection for the token shape", async () => {
+                const connections = await connectionsWrittenFor(async () => ({ user, token: "jwt-token" }));
+
+                expect(connections.length).toBe(1);
+                expect(connections[0].userId).toBe("user-1");
+            });
+
+            it("should write the connection for the verbatim redirect shape", async () => {
+                const connections = await connectionsWrittenFor(async () => ({ user, redirectUrl: "https://app.example.com/done?code=x" }));
+
+                expect(connections.length).toBe(1);
+                expect(connections[0].userId).toBe("user-1");
+            });
+
+            it("should write the connection for the host-built response shape", async () => {
+                const connections = await connectionsWrittenFor(async () => ({ user, response: { status: 204 } }));
+
+                expect(connections.length).toBe(1);
+                expect(connections[0].userId).toBe("user-1");
+            });
+        });
+    });
+
+    describe("onAuthError response escape hatch", () => {
+        it("should return a host-built error response", async () => {
+            const hostResponse = {
+                status: 302,
+                headers: { "Set-Cookie": "session=; Max-Age=0", Location: "https://app.example.com/login?error=denied" },
+                data: {},
+            };
+
+            const res = await callback({ onAuthError: async () => ({ response: hostResponse }) }, { error: "access_denied" });
+
+            expect(res).toBe(hostResponse);
+        });
+
+        it("should take precedence over redirectUrl", async () => {
+            const res = await callback(
+                {
+                    onAuthError: async () => ({ response: { status: 418 }, redirectUrl: "https://app.example.com/login" }),
+                },
+                { error: "access_denied" }
+            );
+
+            expect(res.status).toBe(418);
+        });
+    });
+});

package/spec/handlers/InitiateOidc.spec.ts

@@ -6,8 +6,32 @@
  */
 
 import InitiateOidc from "../../src/handlers/InitiateOidc";
-import { validateProvider } from "../../src/utils/error-utils";
+import { validateProvider, OidcErrorCodes } from "../../src/utils/error-utils";
 import { generateState, generateSessionId, generateNonce } from "../../src/utils/state-utils";
+import { createMockCtx, createMockReq, createTestProviderConfig } from "../helpers/test-helpers";
+
+/**
+ * Run the initiate handler with a mocked context/request.
+ */
+async function initiate(pluginOptions: any, query: Record<string, any>) {
+    const providerConfig = createTestProviderConfig({ callbackUrl: "https://api.example.com/oidc/test/callback" });
+
+    const ctx = createMockCtx(
+        {
+            providers: { test: providerConfig },
+            onAuthSuccess: async () => ({ user: {}, token: "jwt" }),
+            ...pluginOptions,
+        },
+        {
+            config: providerConfig,
+            getAuthorizationUrl: async () => "https://test-idp.example.com/authorize",
+        }
+    );
+
+    const res: any = await (InitiateOidc as any)({ ctx, req: createMockReq({ provider: "test" }, query) });
+
+    return { res, sessions: ctx.repos.oidcSessionRepo.sessions };
+}
 
 describe("InitiateOidc handler", () => {
     describe("Route configuration", () => {
@@ -59,4 +83,74 @@ describe("InitiateOidc handler", () => {
             expect(nonce1.length).toBe(32);
         });
     });
+
+    describe("redirectUri allow-list", () => {
+        it("should accept any redirectUri when allowedRedirectUris is not set", async () => {
+            const { res, sessions } = await initiate({}, { redirectUri: "https://evil.example/cb" });
+
+            expect(res.status).toBe(302);
+            expect(sessions.length).toBe(1);
+            expect(sessions[0].redirectUri).toBe("https://evil.example/cb");
+        });
+
+        it("should accept an exact match", async () => {
+            const { res, sessions } = await initiate(
+                { allowedRedirectUris: ["https://app.example.com/login"] },
+                { redirectUri: "https://app.example.com/login" }
+            );
+
+            expect(res.status).toBe(302);
+            expect(sessions[0].redirectUri).toBe("https://app.example.com/login");
+        });
+
+        it("should accept any path below an origin entry", async () => {
+            const { res } = await initiate({ allowedRedirectUris: ["https://app.example.com"] }, { redirectUri: "https://app.example.com/login?next=/x" });
+
+            expect(res.status).toBe(302);
+        });
+
+        it("should accept a custom app scheme entry", async () => {
+            const { res } = await initiate({ allowedRedirectUris: ["myapp://oidc-callback"] }, { redirectUri: "myapp://oidc-callback" });
+
+            expect(res.status).toBe(302);
+        });
+
+        it("should accept a redirectUri approved by a predicate", async () => {
+            const { res } = await initiate(
+                { allowedRedirectUris: (uri: string, provider: string) => provider === "test" && uri.startsWith("https://app.example.com/") },
+                { redirectUri: "https://app.example.com/welcome" }
+            );
+
+            expect(res.status).toBe(302);
+        });
+
+        it("should always accept the provider callbackUrl", async () => {
+            const { res } = await initiate({ allowedRedirectUris: [] }, { redirectUri: "https://api.example.com/oidc/test/callback" });
+
+            expect(res.status).toBe(302);
+        });
+
+        it("should reject a redirectUri outside the allow-list without creating a session", async () => {
+            const { res, sessions } = await initiate({ allowedRedirectUris: ["https://app.example.com"] }, { redirectUri: "https://evil.example/cb" });
+
+            expect(res.status).toBe(400);
+            expect(res.error.code).toBe(OidcErrorCodes.INVALID_REDIRECT_URI);
+            expect(sessions.length).toBe(0);
+        });
+
+        it("should reject a redirectUri rejected by a predicate", async () => {
+            const { res, sessions } = await initiate({ allowedRedirectUris: () => false }, { redirectUri: "https://evil.example/cb" });
+
+            expect(res.status).toBe(400);
+            expect(res.error.code).toBe(OidcErrorCodes.INVALID_REDIRECT_URI);
+            expect(sessions.length).toBe(0);
+        });
+
+        it("should fall back to the provider callbackUrl when no redirectUri is passed", async () => {
+            const { res, sessions } = await initiate({ allowedRedirectUris: ["https://app.example.com"] }, {});
+
+            expect(res.status).toBe(302);
+            expect(sessions[0].redirectUri).toBe("https://api.example.com/oidc/test/callback");
+        });
+    });
 });

package/spec/helpers/test-helpers.ts

@@ -101,6 +101,74 @@ export function createMockProfile() {
     };
 }
 
+/**
+ * Minimal in-memory OIDC session repo for handler unit tests
+ */
+export function createMockSessionRepo() {
+    const sessions: any[] = [];
+
+    return {
+        sessions,
+        create: async (session: any) => {
+            sessions.push(session);
+            return session;
+        },
+        getByState: async (state: string) => sessions.find((s) => s.state === state) || null,
+        deleteBySessionId: async (sessionId: string) => {
+            const idx = sessions.findIndex((s) => s.sessionId === sessionId);
+            if (idx >= 0) sessions.splice(idx, 1);
+        },
+    };
+}
+
+/**
+ * Create a mock Flink context for OIDC handler unit tests
+ *
+ * @param options - Plugin options as seen by the handlers (via ctx.plugins.oidc.options)
+ * @param provider - Mock OIDC provider instance returned by the provider registry
+ */
+export function createMockCtx(options: any, provider?: any) {
+    const sessionRepo = createMockSessionRepo();
+
+    return {
+        repos: {
+            oidcSessionRepo: sessionRepo,
+            oidcConnectionRepo: {
+                /** Connections written during the test */
+                created: [] as any[],
+                findByUserAndProvider: async () => null,
+                create: async function (connection: any) {
+                    this.created.push(connection);
+                    return connection;
+                },
+                updateById: async () => undefined,
+            },
+        },
+        plugins: {
+            oidc: { options },
+        },
+        oidcProviderRegistry: {
+            getProvider: async () =>
+                provider || {
+                    config: createTestProviderConfig(),
+                    getAuthorizationUrl: async () => "https://test-idp.example.com/authorize?client_id=test-client-id",
+                },
+        },
+    } as any;
+}
+
+/**
+ * Create a mock Express request for OIDC handler unit tests
+ */
+export function createMockReq(params: Record<string, string>, query: Record<string, any> = {}) {
+    return {
+        params,
+        query,
+        protocol: "https",
+        get: (header: string) => (header.toLowerCase() === "host" ? "api.example.com" : undefined),
+    } as any;
+}
+
 /**
  * Wait for a condition to be true
  */