@uniforge/testing 0.1.0-alpha.2

package/dist/auth/index.d.cts

@@ -0,0 +1,177 @@
+import { SessionStorage, Session, Shop, AuthEvent, OnlineAccessInfo, ShopContext, AuthEventType } from '@uniforge/platform-core/auth';
+
+/**
+ * In-memory session storage for testing.
+ */
+
+declare class MemorySessionStorage implements SessionStorage {
+    private sessions;
+    storeSession(session: Session): Promise<boolean>;
+    loadSession(id: string): Promise<Session | undefined>;
+    deleteSession(id: string): Promise<boolean>;
+    deleteSessions(ids: string[]): Promise<boolean>;
+    findSessionsByShop(shop: string): Promise<Session[]>;
+    clear(): void;
+    get size(): number;
+}
+
+/**
+ * Test data factories for authentication types.
+ *
+ * Each factory provides sensible defaults that can be overridden.
+ */
+
+declare function createMockSession(overrides?: Partial<Session>): Session;
+declare function createMockShop(overrides?: Partial<Shop>): Shop;
+declare function createMockAuthEvent(overrides?: Partial<AuthEvent>): AuthEvent;
+
+/**
+ * Mock Shopify API response factories for testing.
+ *
+ * These mocks simulate Shopify API responses for token exchange,
+ * OAuth callback, and token refresh flows.
+ */
+interface MockTokenExchangeResponse {
+    access_token: string;
+    scope: string;
+    expires_in?: number;
+    associated_user_scope?: string;
+    associated_user?: {
+        id: number;
+        first_name: string;
+        last_name: string;
+        email: string;
+        email_verified: boolean;
+        account_owner: boolean;
+        locale: string;
+        collaborator: boolean;
+    };
+}
+interface MockOAuthCallbackResponse {
+    access_token: string;
+    scope: string;
+}
+interface MockRefreshTokenResponse {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+    scope: string;
+}
+declare function mockTokenExchangeResponse(overrides?: Partial<MockTokenExchangeResponse>): MockTokenExchangeResponse;
+declare function mockOnlineTokenExchangeResponse(overrides?: Partial<MockTokenExchangeResponse>): MockTokenExchangeResponse;
+declare function mockOAuthCallbackResponse(overrides?: Partial<MockOAuthCallbackResponse>): MockOAuthCallbackResponse;
+declare function mockRefreshTokenResponse(overrides?: Partial<MockRefreshTokenResponse>): MockRefreshTokenResponse;
+
+/**
+ * Fluent builder for creating session test fixtures in various states.
+ *
+ * Provides a chainable API for constructing Session objects with
+ * controlled expiry, tokens, and online access information.
+ */
+
+declare class SessionFixtureBuilder {
+    private data;
+    private constructor();
+    static offline(shop?: string): SessionFixtureBuilder;
+    static online(shop?: string, userId?: number): SessionFixtureBuilder;
+    withAccessToken(token: string): this;
+    withScopes(scopes: string[] | string): this;
+    expired(minutesAgo?: number): this;
+    expiringSoon(minutesUntil?: number): this;
+    valid(hoursUntil?: number): this;
+    withRefreshToken(token: string, expiresAt?: Date): this;
+    withOnlineAccessInfo(info: Partial<OnlineAccessInfo>): this;
+    withState(state: string): this;
+    withId(id: string): this;
+    build(): Session;
+}
+
+/**
+ * HMAC test utilities for Shopify authentication testing.
+ *
+ * Provides helpers for computing and verifying HMACs used in
+ * OAuth callbacks and webhook validation.
+ */
+/**
+ * Compute Shopify HMAC for query params.
+ * Sorts params alphabetically, joins as key=value pairs with &,
+ * and returns a hex HMAC-SHA256 digest.
+ */
+declare function computeShopifyHmac(params: Record<string, string>, secret: string): string;
+/**
+ * Compute webhook HMAC (base64 digest).
+ * Used for validating Shopify webhook request bodies.
+ */
+declare function computeWebhookHmac(body: string | Buffer, secret: string): string;
+/**
+ * Verify HMAC with timing-safe comparison.
+ * Returns true if computed matches provided.
+ */
+declare function verifyHmac(computed: string, provided: string): boolean;
+/**
+ * Generate a query string with HMAC appended.
+ * Sorts params, computes HMAC, and returns the full query string.
+ */
+declare function createSignedQueryString(params: Record<string, string>, secret: string): string;
+/**
+ * Create a complete signed URL for OAuth callbacks.
+ * Appends signed query params to the base URL.
+ */
+declare function createSignedUrl(baseUrl: string, params: Record<string, string>, secret: string): string;
+
+/**
+ * Auth flow simulator for testing authentication workflows.
+ *
+ * Simulates token exchange, OAuth flows, token refresh, and
+ * generates auth events without requiring a real Shopify API.
+ */
+
+interface AuthFlowSimulatorConfig {
+    apiKey?: string;
+    apiSecretKey?: string;
+    scopes?: string[];
+    hostName?: string;
+}
+interface TokenExchangeResult {
+    session: Session;
+    shopContext: ShopContext;
+}
+interface OAuthFlowResult {
+    authorizeUrl: string;
+    authCode: string;
+    callbackSession: Session;
+    shopContext: ShopContext;
+}
+declare class AuthFlowSimulator {
+    private readonly config;
+    constructor(config?: AuthFlowSimulatorConfig);
+    simulateTokenExchange(shopDomain: string, options?: {
+        isOnline?: boolean;
+        userId?: number;
+        scopes?: string[];
+        accessToken?: string;
+    }): TokenExchangeResult;
+    simulateOAuthFlow(shopDomain: string, options?: {
+        isOnline?: boolean;
+        userId?: number;
+        scopes?: string[];
+    }): OAuthFlowResult;
+    simulateTokenRefresh(session: Session, options?: {
+        newAccessToken?: string;
+        newRefreshToken?: string;
+        newScopes?: string[];
+    }): Session;
+    createExpiredSession(shopDomain: string, options?: {
+        isOnline?: boolean;
+        expiredMinutesAgo?: number;
+    }): Session;
+    generateAuthEvent(type: AuthEventType, shopDomain: string, options?: {
+        sessionId?: string;
+        userId?: number;
+        outcome?: 'success' | 'failure';
+        metadata?: Record<string, string>;
+    }): AuthEvent;
+    get secret(): string;
+}
+
+export { AuthFlowSimulator, type AuthFlowSimulatorConfig, MemorySessionStorage, type MockOAuthCallbackResponse, type MockRefreshTokenResponse, type MockTokenExchangeResponse, type OAuthFlowResult, SessionFixtureBuilder, type TokenExchangeResult, computeShopifyHmac, computeWebhookHmac, createMockAuthEvent, createMockSession, createMockShop, createSignedQueryString, createSignedUrl, mockOAuthCallbackResponse, mockOnlineTokenExchangeResponse, mockRefreshTokenResponse, mockTokenExchangeResponse, verifyHmac };

package/dist/auth/index.d.ts

@@ -0,0 +1,177 @@
+import { SessionStorage, Session, Shop, AuthEvent, OnlineAccessInfo, ShopContext, AuthEventType } from '@uniforge/platform-core/auth';
+
+/**
+ * In-memory session storage for testing.
+ */
+
+declare class MemorySessionStorage implements SessionStorage {
+    private sessions;
+    storeSession(session: Session): Promise<boolean>;
+    loadSession(id: string): Promise<Session | undefined>;
+    deleteSession(id: string): Promise<boolean>;
+    deleteSessions(ids: string[]): Promise<boolean>;
+    findSessionsByShop(shop: string): Promise<Session[]>;
+    clear(): void;
+    get size(): number;
+}
+
+/**
+ * Test data factories for authentication types.
+ *
+ * Each factory provides sensible defaults that can be overridden.
+ */
+
+declare function createMockSession(overrides?: Partial<Session>): Session;
+declare function createMockShop(overrides?: Partial<Shop>): Shop;
+declare function createMockAuthEvent(overrides?: Partial<AuthEvent>): AuthEvent;
+
+/**
+ * Mock Shopify API response factories for testing.
+ *
+ * These mocks simulate Shopify API responses for token exchange,
+ * OAuth callback, and token refresh flows.
+ */
+interface MockTokenExchangeResponse {
+    access_token: string;
+    scope: string;
+    expires_in?: number;
+    associated_user_scope?: string;
+    associated_user?: {
+        id: number;
+        first_name: string;
+        last_name: string;
+        email: string;
+        email_verified: boolean;
+        account_owner: boolean;
+        locale: string;
+        collaborator: boolean;
+    };
+}
+interface MockOAuthCallbackResponse {
+    access_token: string;
+    scope: string;
+}
+interface MockRefreshTokenResponse {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+    scope: string;
+}
+declare function mockTokenExchangeResponse(overrides?: Partial<MockTokenExchangeResponse>): MockTokenExchangeResponse;
+declare function mockOnlineTokenExchangeResponse(overrides?: Partial<MockTokenExchangeResponse>): MockTokenExchangeResponse;
+declare function mockOAuthCallbackResponse(overrides?: Partial<MockOAuthCallbackResponse>): MockOAuthCallbackResponse;
+declare function mockRefreshTokenResponse(overrides?: Partial<MockRefreshTokenResponse>): MockRefreshTokenResponse;
+
+/**
+ * Fluent builder for creating session test fixtures in various states.
+ *
+ * Provides a chainable API for constructing Session objects with
+ * controlled expiry, tokens, and online access information.
+ */
+
+declare class SessionFixtureBuilder {
+    private data;
+    private constructor();
+    static offline(shop?: string): SessionFixtureBuilder;
+    static online(shop?: string, userId?: number): SessionFixtureBuilder;
+    withAccessToken(token: string): this;
+    withScopes(scopes: string[] | string): this;
+    expired(minutesAgo?: number): this;
+    expiringSoon(minutesUntil?: number): this;
+    valid(hoursUntil?: number): this;
+    withRefreshToken(token: string, expiresAt?: Date): this;
+    withOnlineAccessInfo(info: Partial<OnlineAccessInfo>): this;
+    withState(state: string): this;
+    withId(id: string): this;
+    build(): Session;
+}
+
+/**
+ * HMAC test utilities for Shopify authentication testing.
+ *
+ * Provides helpers for computing and verifying HMACs used in
+ * OAuth callbacks and webhook validation.
+ */
+/**
+ * Compute Shopify HMAC for query params.
+ * Sorts params alphabetically, joins as key=value pairs with &,
+ * and returns a hex HMAC-SHA256 digest.
+ */
+declare function computeShopifyHmac(params: Record<string, string>, secret: string): string;
+/**
+ * Compute webhook HMAC (base64 digest).
+ * Used for validating Shopify webhook request bodies.
+ */
+declare function computeWebhookHmac(body: string | Buffer, secret: string): string;
+/**
+ * Verify HMAC with timing-safe comparison.
+ * Returns true if computed matches provided.
+ */
+declare function verifyHmac(computed: string, provided: string): boolean;
+/**
+ * Generate a query string with HMAC appended.
+ * Sorts params, computes HMAC, and returns the full query string.
+ */
+declare function createSignedQueryString(params: Record<string, string>, secret: string): string;
+/**
+ * Create a complete signed URL for OAuth callbacks.
+ * Appends signed query params to the base URL.
+ */
+declare function createSignedUrl(baseUrl: string, params: Record<string, string>, secret: string): string;
+
+/**
+ * Auth flow simulator for testing authentication workflows.
+ *
+ * Simulates token exchange, OAuth flows, token refresh, and
+ * generates auth events without requiring a real Shopify API.
+ */
+
+interface AuthFlowSimulatorConfig {
+    apiKey?: string;
+    apiSecretKey?: string;
+    scopes?: string[];
+    hostName?: string;
+}
+interface TokenExchangeResult {
+    session: Session;
+    shopContext: ShopContext;
+}
+interface OAuthFlowResult {
+    authorizeUrl: string;
+    authCode: string;
+    callbackSession: Session;
+    shopContext: ShopContext;
+}
+declare class AuthFlowSimulator {
+    private readonly config;
+    constructor(config?: AuthFlowSimulatorConfig);
+    simulateTokenExchange(shopDomain: string, options?: {
+        isOnline?: boolean;
+        userId?: number;
+        scopes?: string[];
+        accessToken?: string;
+    }): TokenExchangeResult;
+    simulateOAuthFlow(shopDomain: string, options?: {
+        isOnline?: boolean;
+        userId?: number;
+        scopes?: string[];
+    }): OAuthFlowResult;
+    simulateTokenRefresh(session: Session, options?: {
+        newAccessToken?: string;
+        newRefreshToken?: string;
+        newScopes?: string[];
+    }): Session;
+    createExpiredSession(shopDomain: string, options?: {
+        isOnline?: boolean;
+        expiredMinutesAgo?: number;
+    }): Session;
+    generateAuthEvent(type: AuthEventType, shopDomain: string, options?: {
+        sessionId?: string;
+        userId?: number;
+        outcome?: 'success' | 'failure';
+        metadata?: Record<string, string>;
+    }): AuthEvent;
+    get secret(): string;
+}
+
+export { AuthFlowSimulator, type AuthFlowSimulatorConfig, MemorySessionStorage, type MockOAuthCallbackResponse, type MockRefreshTokenResponse, type MockTokenExchangeResponse, type OAuthFlowResult, SessionFixtureBuilder, type TokenExchangeResult, computeShopifyHmac, computeWebhookHmac, createMockAuthEvent, createMockSession, createMockShop, createSignedQueryString, createSignedUrl, mockOAuthCallbackResponse, mockOnlineTokenExchangeResponse, mockRefreshTokenResponse, mockTokenExchangeResponse, verifyHmac };