@frak-labs/core-sdk 0.0.19 → 0.1.0-beta.00226d62

package/src/utils/sso.test.ts

@@ -0,0 +1,361 @@
+/**
+ * Tests for SSO URL generation utility
+ * Tests generateSsoUrl and compressed parameter formatting
+ */
+
+import { vi } from "vitest";
+
+// Mock compression functions
+vi.mock("./compression/compress", () => ({
+    compressJsonToB64: vi.fn((data: unknown) => {
+        // Return base64url-like string for testing
+        return `compressed_${JSON.stringify(data)}`;
+    }),
+}));
+
+import type { Hex } from "viem";
+import { describe, expect, it } from "../../tests/vitest-fixtures";
+import type { PrepareSsoParamsType } from "../types";
+import { compressJsonToB64 } from "./compression/compress";
+import { generateSsoUrl } from "./sso";
+
+describe("generateSsoUrl", () => {
+    const mockProductId =
+        "0x1234567890123456789012345678901234567890123456789012345678901234" as Hex;
+    const walletUrl = "https://wallet.frak.id";
+
+    describe("basic URL generation", () => {
+        it("should generate SSO URL with basic params", () => {
+            const params: PrepareSsoParamsType = {};
+            const name = "Test App";
+
+            const result = generateSsoUrl(
+                walletUrl,
+                params,
+                mockProductId,
+                name
+            );
+
+            expect(result).toContain("https://wallet.frak.id/sso");
+            expect(result).toContain("?p=");
+        });
+
+        it("should include compressed parameters in URL", () => {
+            const params: PrepareSsoParamsType = {
+                directExit: true,
+            };
+            const name = "My App";
+
+            const result = generateSsoUrl(
+                walletUrl,
+                params,
+                mockProductId,
+                name
+            );
+
+            expect(result).toContain("?p=compressed_");
+            expect(compressJsonToB64).toHaveBeenCalled();
+        });
+
+        it("should set /sso pathname", () => {
+            const params: PrepareSsoParamsType = {};
+            const name = "App";
+
+            const result = generateSsoUrl(
+                walletUrl,
+                params,
+                mockProductId,
+                name
+            );
+
+            const url = new URL(result);
+            expect(url.pathname).toBe("/sso");
+        });
+
+        it("should preserve wallet base URL", () => {
+            const customWalletUrl = "https://custom-wallet.com";
+            const params: PrepareSsoParamsType = {};
+            const name = "App";
+
+            const result = generateSsoUrl(
+                customWalletUrl,
+                params,
+                mockProductId,
+                name
+            );
+
+            expect(result).toContain("https://custom-wallet.com/sso");
+        });
+    });
+
+    describe("parameter compression format", () => {
+        it("should compress params with name and productId", () => {
+            const params: PrepareSsoParamsType = {};
+            const name = "Test App";
+
+            generateSsoUrl(walletUrl, params, mockProductId, name);
+
+            expect(compressJsonToB64).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    p: mockProductId,
+                    m: expect.objectContaining({
+                        n: name,
+                    }),
+                })
+            );
+        });
+
+        it("should include redirectUrl in compressed params", () => {
+            const params: PrepareSsoParamsType = {
+                redirectUrl: "https://example.com/callback",
+            };
+            const name = "App";
+
+            generateSsoUrl(walletUrl, params, mockProductId, name);
+
+            expect(compressJsonToB64).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    r: "https://example.com/callback",
+                })
+            );
+        });
+
+        it("should include directExit in compressed params", () => {
+            const params: PrepareSsoParamsType = {
+                directExit: true,
+            };
+            const name = "App";
+
+            generateSsoUrl(walletUrl, params, mockProductId, name);
+
+            expect(compressJsonToB64).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    d: true,
+                })
+            );
+        });
+
+        it("should include lang in compressed params", () => {
+            const params: PrepareSsoParamsType = {
+                lang: "fr",
+            };
+            const name = "App";
+
+            generateSsoUrl(walletUrl, params, mockProductId, name);
+
+            expect(compressJsonToB64).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    l: "fr",
+                })
+            );
+        });
+
+        it("should include custom CSS when provided", () => {
+            const params: PrepareSsoParamsType = {};
+            const name = "App";
+            const css = "body { color: red; }";
+
+            generateSsoUrl(walletUrl, params, mockProductId, name, css);
+
+            expect(compressJsonToB64).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    m: expect.objectContaining({
+                        css: "body { color: red; }",
+                    }),
+                })
+            );
+        });
+
+        it("should include metadata logoUrl", () => {
+            const params: PrepareSsoParamsType = {
+                metadata: {
+                    logoUrl: "https://example.com/logo.png",
+                },
+            };
+            const name = "App";
+
+            generateSsoUrl(walletUrl, params, mockProductId, name);
+
+            expect(compressJsonToB64).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    m: expect.objectContaining({
+                        l: "https://example.com/logo.png",
+                    }),
+                })
+            );
+        });
+
+        it("should include metadata homepageLink", () => {
+            const params: PrepareSsoParamsType = {
+                metadata: {
+                    homepageLink: "https://example.com",
+                },
+            };
+            const name = "App";
+
+            generateSsoUrl(walletUrl, params, mockProductId, name);
+
+            expect(compressJsonToB64).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    m: expect.objectContaining({
+                        h: "https://example.com",
+                    }),
+                })
+            );
+        });
+
+        it("should include all metadata fields together", () => {
+            const params: PrepareSsoParamsType = {
+                metadata: {
+                    logoUrl: "https://example.com/logo.png",
+                    homepageLink: "https://example.com",
+                },
+            };
+            const name = "Full App";
+            const css = "body { background: blue; }";
+
+            generateSsoUrl(walletUrl, params, mockProductId, name, css);
+
+            expect(compressJsonToB64).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    m: {
+                        n: "Full App",
+                        css: "body { background: blue; }",
+                        l: "https://example.com/logo.png",
+                        h: "https://example.com",
+                    },
+                })
+            );
+        });
+    });
+
+    describe("full parameter combinations", () => {
+        it("should handle all parameters together", () => {
+            const params: PrepareSsoParamsType = {
+                redirectUrl: "https://example.com/callback",
+                directExit: false,
+                lang: "fr",
+                metadata: {
+                    logoUrl: "https://example.com/logo.png",
+                    homepageLink: "https://example.com/home",
+                },
+            };
+            const name = "Complete App";
+            const css = "body { margin: 0; }";
+
+            const result = generateSsoUrl(
+                walletUrl,
+                params,
+                mockProductId,
+                name,
+                css
+            );
+
+            expect(result).toContain("https://wallet.frak.id/sso");
+            expect(result).toContain("?p=");
+            expect(compressJsonToB64).toHaveBeenCalledWith({
+                r: "https://example.com/callback",
+                d: false,
+                l: "fr",
+                p: mockProductId,
+                m: {
+                    n: "Complete App",
+                    css: "body { margin: 0; }",
+                    l: "https://example.com/logo.png",
+                    h: "https://example.com/home",
+                },
+            });
+        });
+
+        it("should handle minimal parameters", () => {
+            const params: PrepareSsoParamsType = {};
+            const name = "Minimal App";
+
+            const result = generateSsoUrl(
+                walletUrl,
+                params,
+                mockProductId,
+                name
+            );
+
+            expect(result).toBeDefined();
+            expect(compressJsonToB64).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    p: mockProductId,
+                    m: expect.objectContaining({
+                        n: "Minimal App",
+                    }),
+                })
+            );
+        });
+    });
+
+    describe("edge cases", () => {
+        it("should handle empty name", () => {
+            const params: PrepareSsoParamsType = {};
+            const name = "";
+
+            const result = generateSsoUrl(
+                walletUrl,
+                params,
+                mockProductId,
+                name
+            );
+
+            expect(result).toBeDefined();
+            expect(compressJsonToB64).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    m: expect.objectContaining({
+                        n: "",
+                    }),
+                })
+            );
+        });
+
+        it("should handle undefined optional parameters", () => {
+            const params: PrepareSsoParamsType = {};
+            const name = "App";
+
+            generateSsoUrl(walletUrl, params, mockProductId, name, undefined);
+
+            expect(compressJsonToB64).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    m: expect.objectContaining({
+                        n: "App",
+                        css: undefined,
+                    }),
+                })
+            );
+        });
+
+        it("should handle wallet URL with trailing slash", () => {
+            const walletUrlWithSlash = "https://wallet.frak.id/";
+            const params: PrepareSsoParamsType = {};
+            const name = "App";
+
+            const result = generateSsoUrl(
+                walletUrlWithSlash,
+                params,
+                mockProductId,
+                name
+            );
+
+            expect(result).toContain("https://wallet.frak.id/sso");
+        });
+
+        it("should handle different product IDs", () => {
+            const differentProductId =
+                "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdabcdefabcdefabcdefabcd" as Hex;
+            const params: PrepareSsoParamsType = {};
+            const name = "App";
+
+            generateSsoUrl(walletUrl, params, differentProductId, name);
+
+            expect(compressJsonToB64).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    p: differentProductId,
+                })
+            );
+        });
+    });
+});

package/src/utils/sso.ts

@@ -0,0 +1,119 @@
+import type { Hex } from "viem";
+import type { PrepareSsoParamsType, SsoMetadata } from "../types";
+import { compressJsonToB64 } from "./compression/compress";
+
+export type AppSpecificSsoMetadata = SsoMetadata & {
+    name: string;
+    css?: string;
+};
+
+/**
+ * The full SSO params that will be used for compression
+ */
+export type FullSsoParams = Omit<PrepareSsoParamsType, "metadata"> & {
+    metadata: AppSpecificSsoMetadata;
+    productId: Hex;
+};
+
+/**
+ * Generate SSO URL with compressed parameters
+ * This mirrors the wallet's getOpenSsoLink() function
+ *
+ * @param walletUrl - Base wallet URL (e.g., "https://wallet.frak.id")
+ * @param params - SSO parameters
+ * @param productId - Product identifier
+ * @param name - Application name
+ * @param css - Optional custom CSS
+ * @returns Complete SSO URL ready to open in popup or redirect
+ *
+ * @example
+ * ```ts
+ * const ssoUrl = generateSsoUrl(
+ *   "https://wallet.frak.id",
+ *   { metadata: { logoUrl: "..." }, directExit: true },
+ *   "0x123...",
+ *   "My App"
+ * );
+ * // Returns: https://wallet.frak.id/sso?p=<compressed_base64>
+ * ```
+ */
+export function generateSsoUrl(
+    walletUrl: string,
+    params: PrepareSsoParamsType,
+    productId: Hex,
+    name: string,
+    css?: string
+): string {
+    // Build full params with app-specific metadata
+    const fullParams: FullSsoParams = {
+        redirectUrl: params.redirectUrl,
+        directExit: params.directExit,
+        lang: params.lang,
+        productId,
+        metadata: {
+            name,
+            css,
+            logoUrl: params.metadata?.logoUrl,
+            homepageLink: params.metadata?.homepageLink,
+        },
+    };
+
+    // Compress params to minimal format
+    const compressedParam = ssoParamsToCompressed(fullParams);
+
+    // Encode to base64url
+    const compressedString = compressJsonToB64(compressedParam);
+
+    // Build URL matching wallet's expected format: /sso?p=<compressed>
+    const ssoUrl = new URL(walletUrl);
+    ssoUrl.pathname = "/sso";
+    ssoUrl.searchParams.set("p", compressedString);
+
+    return ssoUrl.toString();
+}
+
+/**
+ * Map full sso params to compressed sso params
+ * @param params
+ */
+function ssoParamsToCompressed(params: FullSsoParams) {
+    return {
+        r: params.redirectUrl,
+        d: params.directExit,
+        l: params.lang,
+        p: params.productId,
+        m: {
+            n: params.metadata?.name,
+            css: params.metadata?.css,
+            l: params.metadata?.logoUrl,
+            h: params.metadata?.homepageLink,
+        },
+    };
+}
+
+/**
+ * Type of compressed the sso data
+ */
+export type CompressedSsoData = {
+    // Potential id from backend
+    id?: Hex;
+    // redirect url
+    r?: string;
+    // direct exit
+    d?: boolean;
+    // language
+    l?: "en" | "fr";
+    // product id
+    p: Hex;
+    // metadata
+    m: {
+        // product name
+        n: string;
+        // custom css
+        css?: string;
+        // logo
+        l?: string;
+        // home page link
+        h?: string;
+    };
+};