@flink-app/oidc-plugin 1.0.0

package/spec/utils/claims-mapper.spec.ts

@@ -0,0 +1,257 @@
+/**
+ * Tests for claims mapping utilities
+ */
+
+import { mapClaimsToProfile, extractCustomClaims } from "../../src/utils/claims-mapper";
+
+describe("claims-mapper", () => {
+    describe("mapClaimsToProfile", () => {
+        it("should map standard OIDC claims to profile", () => {
+            const claims = {
+                sub: "user-123",
+                email: "test@example.com",
+                email_verified: true,
+                name: "Test User",
+                given_name: "Test",
+                family_name: "User",
+                preferred_username: "testuser",
+                picture: "https://example.com/photo.jpg",
+                phone_number: "+1234567890",
+            };
+
+            const profile = mapClaimsToProfile(claims);
+
+            expect(profile.id).toBe("user-123");
+            expect(profile.email).toBe("test@example.com");
+            expect(profile.emailVerified).toBe(true);
+            expect(profile.name).toBe("Test User");
+            expect(profile.givenName).toBe("Test");
+            expect(profile.familyName).toBe("User");
+            expect(profile.username).toBe("testuser");
+            expect(profile.picture).toBe("https://example.com/photo.jpg");
+            expect(profile.phoneNumber).toBe("+1234567890");
+        });
+
+        it("should handle minimal claims (only sub and email)", () => {
+            const claims = {
+                sub: "user-456",
+                email: "minimal@example.com",
+            };
+
+            const profile = mapClaimsToProfile(claims);
+
+            expect(profile.id).toBe("user-456");
+            expect(profile.email).toBe("minimal@example.com");
+            expect(profile.emailVerified).toBeUndefined();
+            expect(profile.name).toBeUndefined();
+            expect(profile.givenName).toBeUndefined();
+            expect(profile.familyName).toBeUndefined();
+        });
+
+        it("should include all raw claims", () => {
+            const claims = {
+                sub: "user-789",
+                email: "test@example.com",
+                custom_field: "custom_value",
+                another_field: 123,
+            };
+
+            const profile = mapClaimsToProfile(claims);
+
+            expect(profile.raw).toEqual(claims);
+            expect(profile.raw.custom_field).toBe("custom_value");
+            expect(profile.raw.another_field).toBe(123);
+        });
+
+        it("should handle missing email", () => {
+            const claims = {
+                sub: "user-000",
+            };
+
+            const profile = mapClaimsToProfile(claims);
+
+            expect(profile.id).toBe("user-000");
+            expect(profile.email).toBeUndefined();
+        });
+
+        it("should pass through email_verified as-is", () => {
+            const claims1 = {
+                sub: "user-111",
+                email: "test@example.com",
+                email_verified: "true" as any,
+            };
+
+            const profile1 = mapClaimsToProfile(claims1);
+            expect(profile1.emailVerified).toBe("true" as any);
+
+            const claims2 = {
+                sub: "user-222",
+                email: "test@example.com",
+                email_verified: true,
+            };
+
+            const profile2 = mapClaimsToProfile(claims2);
+            expect(profile2.emailVerified).toBe(true);
+        });
+
+        it("should use email as fallback for missing preferred_username", () => {
+            const claims = {
+                sub: "user-333",
+                email: "username@example.com",
+            };
+
+            const profile = mapClaimsToProfile(claims);
+
+            // Should not set username if preferred_username is missing
+            expect(profile.username).toBeUndefined();
+        });
+    });
+
+    describe("extractCustomClaims", () => {
+        it("should extract custom claims using mapping", () => {
+            const claims = {
+                sub: "user-123",
+                email: "test@example.com",
+                organization_id: "org-456",
+                department: "Engineering",
+                employee_id: "EMP-789",
+            };
+
+            const claimMapping = {
+                organizationId: "organization_id",
+                department: "department",
+                employeeId: "employee_id",
+            };
+
+            const customClaims = extractCustomClaims(claims, claimMapping);
+
+            expect(customClaims.organizationId).toBe("org-456");
+            expect(customClaims.department).toBe("Engineering");
+            expect(customClaims.employeeId).toBe("EMP-789");
+        });
+
+        it("should handle nested claim paths with dot notation", () => {
+            const claims = {
+                sub: "user-123",
+                email: "test@example.com",
+                "custom:org": {
+                    id: "org-456",
+                    name: "ACME Corp",
+                },
+                roles: ["admin", "user"],
+            };
+
+            const claimMapping = {
+                organizationId: "custom:org.id",
+                organizationName: "custom:org.name",
+                roles: "roles",
+            };
+
+            const customClaims = extractCustomClaims(claims, claimMapping);
+
+            expect(customClaims.organizationId).toBe("org-456");
+            expect(customClaims.organizationName).toBe("ACME Corp");
+            expect(customClaims.roles).toEqual(["admin", "user"]);
+        });
+
+        it("should return undefined for missing claims", () => {
+            const claims = {
+                sub: "user-123",
+                email: "test@example.com",
+            };
+
+            const claimMapping = {
+                organizationId: "organization_id",
+                missingField: "does_not_exist",
+            };
+
+            const customClaims = extractCustomClaims(claims, claimMapping);
+
+            expect(customClaims.organizationId).toBeUndefined();
+            expect(customClaims.missingField).toBeUndefined();
+        });
+
+        it("should handle empty claim mapping", () => {
+            const claims = {
+                sub: "user-123",
+                email: "test@example.com",
+            };
+
+            const customClaims = extractCustomClaims(claims, {});
+
+            expect(customClaims).toEqual({});
+        });
+
+        it("should preserve data types", () => {
+            const claims = {
+                sub: "user-123",
+                email: "test@example.com",
+                age: 30,
+                active: true,
+                roles: ["admin", "user"],
+                metadata: { key: "value" },
+            };
+
+            const claimMapping = {
+                age: "age",
+                active: "active",
+                roles: "roles",
+                metadata: "metadata",
+            };
+
+            const customClaims = extractCustomClaims(claims, claimMapping);
+
+            expect(customClaims.age).toBe(30);
+            expect(typeof customClaims.age).toBe("number");
+            expect(customClaims.active).toBe(true);
+            expect(typeof customClaims.active).toBe("boolean");
+            expect(Array.isArray(customClaims.roles)).toBe(true);
+            expect(typeof customClaims.metadata).toBe("object");
+        });
+
+        it("should handle array access in paths", () => {
+            const claims = {
+                sub: "user-123",
+                email: "test@example.com",
+                groups: [{ id: "group-1", name: "Admins" }, { id: "group-2", name: "Users" }],
+            };
+
+            const claimMapping = {
+                firstGroupId: "groups.0.id",
+                firstGroupName: "groups.0.name",
+            };
+
+            const customClaims = extractCustomClaims(claims, claimMapping);
+
+            expect(customClaims.firstGroupId).toBe("group-1");
+            expect(customClaims.firstGroupName).toBe("Admins");
+        });
+    });
+
+    describe("integration: mapClaimsToProfile with extractCustomClaims", () => {
+        it("should work together to create enriched profile", () => {
+            const claims = {
+                sub: "user-123",
+                email: "test@example.com",
+                name: "Test User",
+                organization_id: "org-456",
+                department: "Engineering",
+            };
+
+            const claimMapping = {
+                organizationId: "organization_id",
+                department: "department",
+            };
+
+            const customClaims = extractCustomClaims(claims, claimMapping);
+            const enrichedClaims = { ...claims, ...customClaims };
+            const profile = mapClaimsToProfile(enrichedClaims);
+
+            expect(profile.id).toBe("user-123");
+            expect(profile.email).toBe("test@example.com");
+            expect(profile.name).toBe("Test User");
+            expect(profile.raw.organizationId).toBe("org-456");
+            expect(profile.raw.department).toBe("Engineering");
+        });
+    });
+});

package/spec/utils/encryption-utils.spec.ts

@@ -0,0 +1,126 @@
+/**
+ * Tests for encryption utility functions
+ */
+
+import { encryptToken, decryptToken, validateEncryptionSecret } from "../../src/utils/encryption-utils";
+
+describe("encryption-utils", () => {
+    const validSecret = "this-is-a-very-secure-secret-key-at-least-32-chars-long";
+    const testToken = "test-access-token-value";
+
+    describe("validateEncryptionSecret", () => {
+        it("should accept valid secrets (32+ chars)", () => {
+            expect(() => validateEncryptionSecret(validSecret)).not.toThrow();
+        });
+
+        it("should reject short secrets", () => {
+            expect(() => validateEncryptionSecret("short")).toThrowError(/at least 32 characters/);
+        });
+
+        it("should reject empty secrets", () => {
+            expect(() => validateEncryptionSecret("")).toThrow();
+        });
+
+        it("should accept exactly 32 character secrets", () => {
+            const exactSecret = "a".repeat(32);
+            expect(() => validateEncryptionSecret(exactSecret)).not.toThrow();
+        });
+    });
+
+    describe("encryptToken", () => {
+        it("should encrypt a token", () => {
+            const encrypted = encryptToken(testToken, validSecret);
+            expect(encrypted).toBeDefined();
+            expect(typeof encrypted).toBe("string");
+            expect(encrypted).not.toBe(testToken);
+        });
+
+        it("should produce different ciphertext each time (unique IV)", () => {
+            const encrypted1 = encryptToken(testToken, validSecret);
+            const encrypted2 = encryptToken(testToken, validSecret);
+            expect(encrypted1).not.toBe(encrypted2);
+        });
+
+        it("should produce valid hex output with colons", () => {
+            const encrypted = encryptToken(testToken, validSecret);
+            // Format: iv:authTag:encryptedData (all hex-encoded)
+            expect(encrypted).toMatch(/^[a-f0-9]+:[a-f0-9]+:[a-f0-9]+$/);
+        });
+
+        it("should handle empty tokens", () => {
+            const encrypted = encryptToken("", validSecret);
+            expect(encrypted).toBeDefined();
+            expect(typeof encrypted).toBe("string");
+        });
+    });
+
+    describe("decryptToken", () => {
+        it("should decrypt an encrypted token", () => {
+            const encrypted = encryptToken(testToken, validSecret);
+            const decrypted = decryptToken(encrypted, validSecret);
+            expect(decrypted).toBe(testToken);
+        });
+
+        it("should handle empty tokens", () => {
+            const encrypted = encryptToken("", validSecret);
+            const decrypted = decryptToken(encrypted, validSecret);
+            expect(decrypted).toBe("");
+        });
+
+        it("should handle long tokens", () => {
+            const longToken = "a".repeat(1000);
+            const encrypted = encryptToken(longToken, validSecret);
+            const decrypted = decryptToken(encrypted, validSecret);
+            expect(decrypted).toBe(longToken);
+        });
+
+        it("should throw error for invalid ciphertext", () => {
+            expect(() => decryptToken("invalid-base64", validSecret)).toThrow();
+        });
+
+        it("should throw error for tampered ciphertext", () => {
+            const encrypted = encryptToken(testToken, validSecret);
+            const tampered = encrypted.substring(0, encrypted.length - 5) + "xxxxx";
+            expect(() => decryptToken(tampered, validSecret)).toThrow();
+        });
+
+        it("should throw error for wrong secret", () => {
+            const encrypted = encryptToken(testToken, validSecret);
+            const wrongSecret = "different-secret-key-at-least-32-chars-long-enough";
+            expect(() => decryptToken(encrypted, wrongSecret)).toThrow();
+        });
+    });
+
+    describe("encrypt/decrypt round-trip", () => {
+        it("should successfully round-trip various token formats", () => {
+            const testCases = [
+                "simple-token",
+                "token.with.dots",
+                "token-with-dashes",
+                "token_with_underscores",
+                "VeryLongTokenWithMixedCaseAndNumbers123456789",
+                "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.sig",
+            ];
+
+            testCases.forEach((token) => {
+                const encrypted = encryptToken(token, validSecret);
+                const decrypted = decryptToken(encrypted, validSecret);
+                expect(decrypted).toBe(token);
+            });
+        });
+
+        it("should handle special characters", () => {
+            const specialToken = "token!@#$%^&*()+=[]{}|;:',.<>?/~`";
+            const encrypted = encryptToken(specialToken, validSecret);
+            const decrypted = decryptToken(encrypted, validSecret);
+            expect(decrypted).toBe(specialToken);
+        });
+
+        it("should handle unicode characters", () => {
+            const unicodeToken = "token-with-emoji-😀-and-unicode-™-©";
+            const encrypted = encryptToken(unicodeToken, validSecret);
+            const decrypted = decryptToken(encrypted, validSecret);
+            expect(decrypted).toBe(unicodeToken);
+        });
+    });
+});

package/spec/utils/error-utils.spec.ts

@@ -0,0 +1,107 @@
+/**
+ * Tests for error utility functions
+ */
+
+import { createOidcError, validateProvider, OidcErrorCodes } from "../../src/utils/error-utils";
+
+describe("error-utils", () => {
+    describe("OidcErrorCodes", () => {
+        it("should define all expected error codes", () => {
+            expect(OidcErrorCodes.INVALID_STATE).toBe("invalid_state");
+            expect(OidcErrorCodes.SESSION_NOT_FOUND).toBe("session_not_found");
+            expect(OidcErrorCodes.SESSION_EXPIRED).toBe("session_expired");
+            expect(OidcErrorCodes.PROVIDER_NOT_CONFIGURED).toBe("provider_not_configured");
+            expect(OidcErrorCodes.DISCOVERY_FAILED).toBe("discovery_failed");
+            expect(OidcErrorCodes.TOKEN_EXCHANGE_FAILED).toBe("token_exchange_failed");
+            expect(OidcErrorCodes.USERINFO_FAILED).toBe("userinfo_failed");
+            expect(OidcErrorCodes.INVALID_PROVIDER).toBe("invalid_provider");
+            expect(OidcErrorCodes.MISSING_CODE).toBe("missing_code");
+            expect(OidcErrorCodes.MISSING_STATE).toBe("missing_state");
+        });
+    });
+
+    describe("createOidcError", () => {
+        it("should create an error with code and message", () => {
+            const error = createOidcError(OidcErrorCodes.INVALID_STATE, "State mismatch");
+            expect(error).toBeInstanceOf(Error);
+            expect(error.message).toBe("State mismatch");
+            expect(error.code).toBe("invalid_state");
+        });
+
+        it("should include details if provided", () => {
+            const details = { provider: "test", sessionId: "123" };
+            const error = createOidcError(OidcErrorCodes.SESSION_NOT_FOUND, "Session not found", details);
+            expect(error.details).toEqual(details);
+        });
+
+        it("should work without details", () => {
+            const error = createOidcError(OidcErrorCodes.INVALID_STATE, "State mismatch");
+            expect(error.details).toBeUndefined();
+        });
+
+        it("should be throwable", () => {
+            expect(() => {
+                throw createOidcError(OidcErrorCodes.SESSION_EXPIRED, "Session expired");
+            }).toThrowError("Session expired");
+        });
+    });
+
+
+    describe("validateProvider", () => {
+        it("should accept valid provider names", () => {
+            expect(() => validateProvider("google")).not.toThrow();
+            expect(() => validateProvider("microsoft")).not.toThrow();
+            expect(() => validateProvider("okta")).not.toThrow();
+            expect(() => validateProvider("auth0")).not.toThrow();
+            expect(() => validateProvider("custom-provider")).not.toThrow();
+            expect(() => validateProvider("provider_123")).not.toThrow();
+        });
+
+        it("should reject invalid provider names", () => {
+            expect(() => validateProvider("")).toThrow();
+            expect(() => validateProvider("provider with spaces")).toThrow();
+            expect(() => validateProvider("provider/slash")).toThrow();
+            expect(() => validateProvider("provider\\backslash")).toThrow();
+            expect(() => validateProvider("provider.dot")).toThrow();
+        });
+
+        it("should reject provider names with special characters", () => {
+            const invalidChars = ["@", "#", "$", "%", "^", "&", "*", "(", ")", "+", "=", "[", "]", "{", "}", "|", ";", ":", "'", '"', "<", ">", "?", "/", "\\"];
+            invalidChars.forEach((char) => {
+                expect(() => validateProvider(`provider${char}name`)).toThrow();
+            });
+        });
+
+        it("should accept alphanumeric with dash and underscore", () => {
+            expect(() => validateProvider("provider-name-123")).not.toThrow();
+            expect(() => validateProvider("provider_name_456")).not.toThrow();
+            expect(() => validateProvider("ProviderName789")).not.toThrow();
+        });
+    });
+
+    describe("error handling in try-catch", () => {
+        it("should be catchable and inspectable", () => {
+            try {
+                throw createOidcError(OidcErrorCodes.TOKEN_EXCHANGE_FAILED, "Token exchange failed", {
+                    originalError: "Network timeout",
+                });
+            } catch (error: any) {
+                expect(error.code).toBe("token_exchange_failed");
+                expect(error.message).toBe("Token exchange failed");
+                expect(error.details.originalError).toBe("Network timeout");
+            }
+        });
+
+        it("should allow error code checking", () => {
+            try {
+                throw createOidcError(OidcErrorCodes.PROVIDER_NOT_CONFIGURED, "Provider not found");
+            } catch (error: any) {
+                if (error.code === "provider_not_configured") {
+                    expect(error.message).toBe("Provider not found");
+                } else {
+                    fail("Should have caught provider_not_configured error");
+                }
+            }
+        });
+    });
+});

package/spec/utils/state-utils.spec.ts

@@ -0,0 +1,102 @@
+/**
+ * Tests for state utility functions
+ */
+
+import { generateState, generateSessionId, generateNonce, validateState } from "../../src/utils/state-utils";
+
+describe("state-utils", () => {
+    describe("generateState", () => {
+        it("should generate a random state string", () => {
+            const state = generateState();
+            expect(state).toBeDefined();
+            expect(typeof state).toBe("string");
+            expect(state.length).toBeGreaterThan(0);
+        });
+
+        it("should generate unique state values", () => {
+            const state1 = generateState();
+            const state2 = generateState();
+            expect(state1).not.toBe(state2);
+        });
+
+        it("should generate state with sufficient entropy (64 hex chars = 32 bytes)", () => {
+            const state = generateState();
+            expect(state.length).toBe(64);
+            expect(state).toMatch(/^[a-f0-9]{64}$/);
+        });
+    });
+
+    describe("generateSessionId", () => {
+        it("should generate a random session ID", () => {
+            const sessionId = generateSessionId();
+            expect(sessionId).toBeDefined();
+            expect(typeof sessionId).toBe("string");
+            expect(sessionId.length).toBeGreaterThan(0);
+        });
+
+        it("should generate unique session IDs", () => {
+            const id1 = generateSessionId();
+            const id2 = generateSessionId();
+            expect(id1).not.toBe(id2);
+        });
+
+        it("should generate session ID with sufficient entropy", () => {
+            const sessionId = generateSessionId();
+            expect(sessionId.length).toBe(32);
+            expect(sessionId).toMatch(/^[a-f0-9]{32}$/);
+        });
+    });
+
+    describe("generateNonce", () => {
+        it("should generate a random nonce", () => {
+            const nonce = generateNonce();
+            expect(nonce).toBeDefined();
+            expect(typeof nonce).toBe("string");
+            expect(nonce.length).toBeGreaterThan(0);
+        });
+
+        it("should generate unique nonces", () => {
+            const nonce1 = generateNonce();
+            const nonce2 = generateNonce();
+            expect(nonce1).not.toBe(nonce2);
+        });
+
+        it("should generate nonce with sufficient entropy", () => {
+            const nonce = generateNonce();
+            expect(nonce.length).toBe(32);
+            expect(nonce).toMatch(/^[a-f0-9]{32}$/);
+        });
+    });
+
+    describe("validateState", () => {
+        it("should return true for matching states", () => {
+            const state = generateState();
+            const result = validateState(state, state);
+            expect(result).toBe(true);
+        });
+
+        it("should return false for non-matching states", () => {
+            const state1 = generateState();
+            const state2 = generateState();
+            const result = validateState(state1, state2);
+            expect(result).toBe(false);
+        });
+
+        it("should use constant-time comparison to prevent timing attacks", () => {
+            const state = "a".repeat(64);
+            const wrongState1 = "b".repeat(64);
+            const wrongState2 = "a".repeat(63) + "b";
+
+            // Both should return false
+            expect(validateState(wrongState1, state)).toBe(false);
+            expect(validateState(wrongState2, state)).toBe(false);
+        });
+
+        it("should handle empty strings", () => {
+            expect(validateState("", "")).toBe(false);
+            expect(validateState("abc", "")).toBe(false);
+            expect(validateState("", "abc")).toBe(false);
+        });
+    });
+
+});

package/src/OidcInternalContext.ts

@@ -0,0 +1,15 @@
+import { FlinkContext } from "@flink-app/flink";
+import { OidcPluginContext } from "./OidcPluginContext";
+import OidcSessionRepo from "./repos/OidcSessionRepo";
+import OidcConnectionRepo from "./repos/OidcConnectionRepo";
+
+/**
+ * Internal context type for OIDC plugin
+ * Extends the app's context with OIDC-specific repositories
+ */
+export interface OidcInternalContext extends FlinkContext, OidcPluginContext {
+    repos: FlinkContext["repos"] & {
+        oidcSessionRepo: OidcSessionRepo;
+        oidcConnectionRepo: OidcConnectionRepo;
+    };
+}