@uniforge/platform-shopify 0.1.0-alpha.2

package/dist/auth/index.d.cts

@@ -0,0 +1,246 @@
+import { AuthRequest, AuthConfig, Session } from '@uniforge/platform-core/auth';
+
+/**
+ * Session token extraction and Shopify token exchange.
+ *
+ * Extracts session tokens from embedded app requests and exchanges
+ * them for access tokens via the Shopify API.
+ */
+
+/**
+ * Extract the session token from the Authorization header.
+ * Returns null if the header is missing or malformed.
+ */
+declare function extractSessionToken(request: AuthRequest): string | null;
+/**
+ * Extract the shop domain from the request.
+ * Checks query parameter first, then x-shopify-shop-domain header.
+ * Validates the domain format before returning.
+ */
+declare function extractShop(request: AuthRequest): string | null;
+/**
+ * Minimal interface for the Shopify token exchange function.
+ * Allows mocking in tests without depending on the full Shopify API.
+ */
+interface ShopifyTokenExchangeFn {
+    (params: {
+        sessionToken: string;
+        shop: string;
+        requestedTokenType: string;
+    }): Promise<{
+        session: {
+            id: string;
+            shop: string;
+            state: string;
+            isOnline: boolean;
+            scope?: string;
+            expires?: Date;
+            accessToken?: string;
+            refreshToken?: string;
+            onlineAccessInfo?: any;
+        };
+    }>;
+}
+/** Input parameters for performing a Shopify token exchange. */
+interface PerformTokenExchangeInput {
+    config: AuthConfig;
+    sessionToken: string;
+    shop: string;
+    tokenType: 'online' | 'offline';
+    /** Optional: provide a custom token exchange function (for testing). */
+    tokenExchangeFn?: ShopifyTokenExchangeFn;
+}
+/**
+ * Create a Shopify API client and return its tokenExchange function.
+ */
+declare function createShopifyTokenExchangeFn(config: AuthConfig): Promise<ShopifyTokenExchangeFn>;
+/**
+ * Exchange a session token for an access token via Shopify API.
+ *
+ * Maps the Shopify Session result to UniForge's Session type.
+ * Emits auth events on success/failure.
+ */
+declare function performTokenExchange(input: PerformTokenExchangeInput): Promise<Session>;
+
+/**
+ * Shopify session manager for embedded app authentication.
+ *
+ * Manages the lifecycle of Shopify sessions: checks storage for
+ * existing valid sessions, performs token exchange when needed,
+ * refreshes expiring tokens, and stores results via encrypted
+ * session storage.
+ */
+
+/**
+ * Injectable function for refreshing a Shopify access token.
+ * In production, wraps `shopify.auth.refreshToken()`.
+ */
+interface ShopifyTokenRefreshFn {
+    (params: {
+        session: {
+            accessToken?: string;
+            refreshToken?: string;
+            shop: string;
+        };
+    }): Promise<{
+        session: {
+            id: string;
+            shop: string;
+            state: string;
+            isOnline: boolean;
+            scope?: string;
+            expires?: Date;
+            accessToken?: string;
+            refreshToken?: string;
+        };
+    }>;
+}
+/** Options for configuring the ShopifySessionManager with test doubles. */
+interface ShopifySessionManagerOptions {
+    /** Optional: provide a custom token exchange function (for testing). */
+    tokenExchangeFn?: ShopifyTokenExchangeFn;
+    /** Optional: provide a custom token refresh function (for testing). */
+    tokenRefreshFn?: ShopifyTokenRefreshFn;
+}
+declare class ShopifySessionManager {
+    private readonly config;
+    private readonly encryptedStorage;
+    private readonly tokenExchangeFn?;
+    private readonly tokenRefreshFn?;
+    constructor(config: AuthConfig, options?: ShopifySessionManagerOptions);
+    /**
+     * Get an existing valid session or create one via token exchange.
+     *
+     * For embedded apps, this:
+     * 1. Extracts the session token and shop from the request
+     * 2. Checks storage for an existing non-expired session
+     * 3. If no valid session, performs token exchange with Shopify
+     * 4. Stores the new session (encrypted) and returns it
+     */
+    getOrCreateSession(request: AuthRequest): Promise<Session>;
+    /**
+     * Get an existing valid online session or create one via token exchange.
+     */
+    getOrCreateOnlineSession(request: AuthRequest): Promise<Session>;
+    /**
+     * Refresh an expiring session token.
+     *
+     * Retries up to `config.tokenRefresh.maxRetries` on failure.
+     * On success, stores the refreshed session (encrypted) and emits
+     * a `token_refreshed` event. On final failure, emits
+     * `token_refresh_failed` and throws.
+     */
+    refreshSessionToken(session: Session): Promise<Session>;
+    /**
+     * Delete all sessions for a shop (e.g., on app uninstall).
+     *
+     * Finds all sessions via `findSessionsByShop`, deletes them,
+     * and emits `session_deleted` events.
+     */
+    cleanupShopSessions(shop: string): Promise<void>;
+    private isExpired;
+    private mapRefreshedSession;
+    private createDefaultRefreshFn;
+}
+
+/**
+ * HMAC validation for Shopify OAuth callbacks.
+ *
+ * Validates the HMAC signature on OAuth callback query parameters
+ * using timing-safe comparison to prevent timing attacks.
+ */
+/**
+ * Validate the HMAC signature on OAuth callback query parameters.
+ *
+ * Per Shopify's spec: remove the `hmac` parameter, sort remaining
+ * params alphabetically, join as `key=value` with `&`, and compute
+ * HMAC-SHA256 with the app's API secret key. Compare using
+ * timing-safe equality.
+ */
+declare function validateOAuthHmac(query: Record<string, string>, secret: string): boolean;
+
+/**
+ * OAuth authorization code flow for non-embedded Shopify apps.
+ *
+ * Implements the begin (redirect to Shopify) and callback
+ * (exchange code for access token) phases of the OAuth flow.
+ */
+
+/**
+ * Injectable function for initiating OAuth.
+ * In production, wraps `shopify.auth.begin()`.
+ */
+interface ShopifyOAuthBeginFn {
+    (params: {
+        shop: string;
+        callbackPath: string;
+        isOnline: boolean;
+    }): Promise<{
+        redirectUrl: string;
+    }>;
+}
+/**
+ * Injectable function for handling the OAuth callback.
+ * In production, wraps `shopify.auth.callback()`.
+ */
+interface ShopifyOAuthCallbackFn {
+    (params: {
+        query: Record<string, string>;
+    }): Promise<{
+        session: {
+            id: string;
+            shop: string;
+            state: string;
+            isOnline: boolean;
+            scope?: string;
+            expires?: Date;
+            accessToken?: string;
+            refreshToken?: string;
+        };
+    }>;
+}
+/** Input parameters for beginning the OAuth authorization flow. */
+interface BeginOAuthInput {
+    config: AuthConfig;
+    request: AuthRequest;
+    callbackPath: string;
+    isOnline?: boolean;
+    beginFn?: ShopifyOAuthBeginFn;
+}
+/** Result from beginning OAuth containing the authorization redirect URL. */
+interface BeginOAuthResult {
+    redirectUrl: string;
+}
+/** Input parameters for handling the OAuth callback from Shopify. */
+interface HandleOAuthCallbackInput {
+    config: AuthConfig;
+    request: AuthRequest;
+    callbackFn?: ShopifyOAuthCallbackFn;
+}
+/** Result from OAuth callback — either success with session or failure with error details. */
+type OAuthCallbackResult = {
+    success: true;
+    session: Session;
+    redirectUrl: string;
+} | {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+        statusCode: number;
+    };
+};
+/**
+ * Initiate OAuth by redirecting the merchant to Shopify's authorization page.
+ */
+declare function beginOAuth(input: BeginOAuthInput): Promise<BeginOAuthResult>;
+/**
+ * Handle the OAuth callback from Shopify.
+ *
+ * Validates HMAC, checks for authorization denial, exchanges the code
+ * for an access token, validates scopes, stores the session encrypted,
+ * and emits events.
+ */
+declare function handleOAuthCallback(input: HandleOAuthCallbackInput): Promise<OAuthCallbackResult>;
+
+export { type BeginOAuthInput, type BeginOAuthResult, type HandleOAuthCallbackInput, type OAuthCallbackResult, type PerformTokenExchangeInput, type ShopifyOAuthBeginFn, type ShopifyOAuthCallbackFn, ShopifySessionManager, type ShopifySessionManagerOptions, type ShopifyTokenExchangeFn, type ShopifyTokenRefreshFn, beginOAuth, createShopifyTokenExchangeFn, extractSessionToken, extractShop, handleOAuthCallback, performTokenExchange, validateOAuthHmac };

package/dist/auth/index.d.ts

@@ -0,0 +1,246 @@
+import { AuthRequest, AuthConfig, Session } from '@uniforge/platform-core/auth';
+
+/**
+ * Session token extraction and Shopify token exchange.
+ *
+ * Extracts session tokens from embedded app requests and exchanges
+ * them for access tokens via the Shopify API.
+ */
+
+/**
+ * Extract the session token from the Authorization header.
+ * Returns null if the header is missing or malformed.
+ */
+declare function extractSessionToken(request: AuthRequest): string | null;
+/**
+ * Extract the shop domain from the request.
+ * Checks query parameter first, then x-shopify-shop-domain header.
+ * Validates the domain format before returning.
+ */
+declare function extractShop(request: AuthRequest): string | null;
+/**
+ * Minimal interface for the Shopify token exchange function.
+ * Allows mocking in tests without depending on the full Shopify API.
+ */
+interface ShopifyTokenExchangeFn {
+    (params: {
+        sessionToken: string;
+        shop: string;
+        requestedTokenType: string;
+    }): Promise<{
+        session: {
+            id: string;
+            shop: string;
+            state: string;
+            isOnline: boolean;
+            scope?: string;
+            expires?: Date;
+            accessToken?: string;
+            refreshToken?: string;
+            onlineAccessInfo?: any;
+        };
+    }>;
+}
+/** Input parameters for performing a Shopify token exchange. */
+interface PerformTokenExchangeInput {
+    config: AuthConfig;
+    sessionToken: string;
+    shop: string;
+    tokenType: 'online' | 'offline';
+    /** Optional: provide a custom token exchange function (for testing). */
+    tokenExchangeFn?: ShopifyTokenExchangeFn;
+}
+/**
+ * Create a Shopify API client and return its tokenExchange function.
+ */
+declare function createShopifyTokenExchangeFn(config: AuthConfig): Promise<ShopifyTokenExchangeFn>;
+/**
+ * Exchange a session token for an access token via Shopify API.
+ *
+ * Maps the Shopify Session result to UniForge's Session type.
+ * Emits auth events on success/failure.
+ */
+declare function performTokenExchange(input: PerformTokenExchangeInput): Promise<Session>;
+
+/**
+ * Shopify session manager for embedded app authentication.
+ *
+ * Manages the lifecycle of Shopify sessions: checks storage for
+ * existing valid sessions, performs token exchange when needed,
+ * refreshes expiring tokens, and stores results via encrypted
+ * session storage.
+ */
+
+/**
+ * Injectable function for refreshing a Shopify access token.
+ * In production, wraps `shopify.auth.refreshToken()`.
+ */
+interface ShopifyTokenRefreshFn {
+    (params: {
+        session: {
+            accessToken?: string;
+            refreshToken?: string;
+            shop: string;
+        };
+    }): Promise<{
+        session: {
+            id: string;
+            shop: string;
+            state: string;
+            isOnline: boolean;
+            scope?: string;
+            expires?: Date;
+            accessToken?: string;
+            refreshToken?: string;
+        };
+    }>;
+}
+/** Options for configuring the ShopifySessionManager with test doubles. */
+interface ShopifySessionManagerOptions {
+    /** Optional: provide a custom token exchange function (for testing). */
+    tokenExchangeFn?: ShopifyTokenExchangeFn;
+    /** Optional: provide a custom token refresh function (for testing). */
+    tokenRefreshFn?: ShopifyTokenRefreshFn;
+}
+declare class ShopifySessionManager {
+    private readonly config;
+    private readonly encryptedStorage;
+    private readonly tokenExchangeFn?;
+    private readonly tokenRefreshFn?;
+    constructor(config: AuthConfig, options?: ShopifySessionManagerOptions);
+    /**
+     * Get an existing valid session or create one via token exchange.
+     *
+     * For embedded apps, this:
+     * 1. Extracts the session token and shop from the request
+     * 2. Checks storage for an existing non-expired session
+     * 3. If no valid session, performs token exchange with Shopify
+     * 4. Stores the new session (encrypted) and returns it
+     */
+    getOrCreateSession(request: AuthRequest): Promise<Session>;
+    /**
+     * Get an existing valid online session or create one via token exchange.
+     */
+    getOrCreateOnlineSession(request: AuthRequest): Promise<Session>;
+    /**
+     * Refresh an expiring session token.
+     *
+     * Retries up to `config.tokenRefresh.maxRetries` on failure.
+     * On success, stores the refreshed session (encrypted) and emits
+     * a `token_refreshed` event. On final failure, emits
+     * `token_refresh_failed` and throws.
+     */
+    refreshSessionToken(session: Session): Promise<Session>;
+    /**
+     * Delete all sessions for a shop (e.g., on app uninstall).
+     *
+     * Finds all sessions via `findSessionsByShop`, deletes them,
+     * and emits `session_deleted` events.
+     */
+    cleanupShopSessions(shop: string): Promise<void>;
+    private isExpired;
+    private mapRefreshedSession;
+    private createDefaultRefreshFn;
+}
+
+/**
+ * HMAC validation for Shopify OAuth callbacks.
+ *
+ * Validates the HMAC signature on OAuth callback query parameters
+ * using timing-safe comparison to prevent timing attacks.
+ */
+/**
+ * Validate the HMAC signature on OAuth callback query parameters.
+ *
+ * Per Shopify's spec: remove the `hmac` parameter, sort remaining
+ * params alphabetically, join as `key=value` with `&`, and compute
+ * HMAC-SHA256 with the app's API secret key. Compare using
+ * timing-safe equality.
+ */
+declare function validateOAuthHmac(query: Record<string, string>, secret: string): boolean;
+
+/**
+ * OAuth authorization code flow for non-embedded Shopify apps.
+ *
+ * Implements the begin (redirect to Shopify) and callback
+ * (exchange code for access token) phases of the OAuth flow.
+ */
+
+/**
+ * Injectable function for initiating OAuth.
+ * In production, wraps `shopify.auth.begin()`.
+ */
+interface ShopifyOAuthBeginFn {
+    (params: {
+        shop: string;
+        callbackPath: string;
+        isOnline: boolean;
+    }): Promise<{
+        redirectUrl: string;
+    }>;
+}
+/**
+ * Injectable function for handling the OAuth callback.
+ * In production, wraps `shopify.auth.callback()`.
+ */
+interface ShopifyOAuthCallbackFn {
+    (params: {
+        query: Record<string, string>;
+    }): Promise<{
+        session: {
+            id: string;
+            shop: string;
+            state: string;
+            isOnline: boolean;
+            scope?: string;
+            expires?: Date;
+            accessToken?: string;
+            refreshToken?: string;
+        };
+    }>;
+}
+/** Input parameters for beginning the OAuth authorization flow. */
+interface BeginOAuthInput {
+    config: AuthConfig;
+    request: AuthRequest;
+    callbackPath: string;
+    isOnline?: boolean;
+    beginFn?: ShopifyOAuthBeginFn;
+}
+/** Result from beginning OAuth containing the authorization redirect URL. */
+interface BeginOAuthResult {
+    redirectUrl: string;
+}
+/** Input parameters for handling the OAuth callback from Shopify. */
+interface HandleOAuthCallbackInput {
+    config: AuthConfig;
+    request: AuthRequest;
+    callbackFn?: ShopifyOAuthCallbackFn;
+}
+/** Result from OAuth callback — either success with session or failure with error details. */
+type OAuthCallbackResult = {
+    success: true;
+    session: Session;
+    redirectUrl: string;
+} | {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+        statusCode: number;
+    };
+};
+/**
+ * Initiate OAuth by redirecting the merchant to Shopify's authorization page.
+ */
+declare function beginOAuth(input: BeginOAuthInput): Promise<BeginOAuthResult>;
+/**
+ * Handle the OAuth callback from Shopify.
+ *
+ * Validates HMAC, checks for authorization denial, exchanges the code
+ * for an access token, validates scopes, stores the session encrypted,
+ * and emits events.
+ */
+declare function handleOAuthCallback(input: HandleOAuthCallbackInput): Promise<OAuthCallbackResult>;
+
+export { type BeginOAuthInput, type BeginOAuthResult, type HandleOAuthCallbackInput, type OAuthCallbackResult, type PerformTokenExchangeInput, type ShopifyOAuthBeginFn, type ShopifyOAuthCallbackFn, ShopifySessionManager, type ShopifySessionManagerOptions, type ShopifyTokenExchangeFn, type ShopifyTokenRefreshFn, beginOAuth, createShopifyTokenExchangeFn, extractSessionToken, extractShop, handleOAuthCallback, performTokenExchange, validateOAuthHmac };