@uniforge/core 0.1.0-alpha.2

package/dist/auth/index.d.cts

@@ -0,0 +1,165 @@
+import { AuthEventType, AuthEvent, AuthConfig, TokenEncryptionService, EncryptionConfig, EncryptedPayload, SessionStorage, Session, SessionConfig, TokenRefreshConfig, RouteProtectionConfig, AuthMiddleware } from '@uniforge/platform-core/auth';
+
+/**
+ * Auth event factory.
+ *
+ * Creates structured authentication events with automatic UUID generation,
+ * timestamp setting, and sensitive metadata key rejection.
+ */
+
+/** Input parameters for creating an auth event. */
+interface CreateAuthEventInput {
+    type: AuthEventType;
+    shopDomain: string;
+    outcome: 'success' | 'failure';
+    sessionId?: string | null;
+    userId?: number | null;
+    metadata?: Record<string, string>;
+}
+/** Create a structured auth event with auto-generated ID and timestamp. Rejects sensitive metadata keys. */
+declare function createAuthEvent(input: CreateAuthEventInput): AuthEvent;
+
+/**
+ * Auth config factory with validation and defaults.
+ */
+
+/** Input parameters for creating a validated auth configuration. */
+interface CreateAuthConfigInput {
+    apiKey: string;
+    apiSecretKey: string;
+    scopes: string[];
+    hostName: string;
+    apiVersion: string;
+    isEmbeddedApp?: boolean;
+    sessionStorage: AuthConfig['sessionStorage'];
+    encryption: AuthConfig['encryption'];
+    eventHandler?: AuthConfig['eventHandler'];
+    session?: AuthConfig['session'];
+    tokenRefresh?: AuthConfig['tokenRefresh'];
+}
+/** Create a validated AuthConfig with sensible defaults. Throws on invalid input. */
+declare function createAuthConfig(input: CreateAuthConfigInput): AuthConfig;
+
+/**
+ * AES-256-GCM token encryption with key rotation.
+ *
+ * Implements TokenEncryptionService using Node.js built-in crypto.
+ * Each encrypt call generates a unique 12-byte random IV.
+ * Key rotation is supported via a key registry — decrypt looks up
+ * the key by keyId, while encrypt always uses the active (first) key.
+ */
+
+declare class TokenEncryptionServiceImpl implements TokenEncryptionService {
+    private readonly keys;
+    private readonly activeKeyId;
+    constructor(config: EncryptionConfig);
+    /** Encrypt plaintext using the active (first) key. Generates a unique IV per call. */
+    encrypt(plaintext: string): EncryptedPayload;
+    /** Decrypt an encrypted payload. Looks up the key by keyId from the registry. */
+    decrypt(payload: EncryptedPayload): string;
+    /** Check if a payload was encrypted with the currently active key. */
+    isEncryptedWithActiveKey(payload: EncryptedPayload): boolean;
+    private toBuffer;
+}
+
+/**
+ * Encrypting session storage decorator.
+ *
+ * Wraps any SessionStorage implementation, transparently encrypting
+ * accessToken and refreshToken on store, and decrypting on load/find.
+ * Delete operations pass through unchanged.
+ */
+
+declare class EncryptedSessionStorage implements SessionStorage {
+    private readonly inner;
+    private readonly encryption;
+    constructor(inner: SessionStorage, encryption: TokenEncryptionService);
+    /** Store a session with encrypted tokens. */
+    storeSession(session: Session): Promise<boolean>;
+    /** Load a session and decrypt its tokens. */
+    loadSession(id: string): Promise<Session | undefined>;
+    /** Delete a session by ID (pass-through). */
+    deleteSession(id: string): Promise<boolean>;
+    /** Delete multiple sessions by ID (pass-through). */
+    deleteSessions(ids: string[]): Promise<boolean>;
+    /** Find sessions by shop and decrypt their tokens. */
+    findSessionsByShop(shop: string): Promise<Session[]>;
+    private encryptTokens;
+    private decryptTokens;
+}
+
+/**
+ * Session expiration and token refresh utilities.
+ *
+ * Platform-agnostic helpers for determining session validity
+ * and whether tokens should be proactively refreshed.
+ */
+
+/**
+ * Check if a session has expired.
+ *
+ * Returns true if the session's `expires` date is in the past (or now).
+ * Non-expiring sessions (null expires) are never considered expired.
+ */
+declare function isSessionExpired(session: Session, _config?: SessionConfig): boolean;
+/**
+ * Check if a session's token should be proactively refreshed.
+ *
+ * Returns true if the session will expire within the refresh buffer window.
+ * Non-expiring sessions (null expires) never need refresh.
+ */
+declare function shouldRefreshToken(session: Session, config?: TokenRefreshConfig): boolean;
+/**
+ * Calculate a session expiration date based on config.
+ *
+ * Returns a Date that is `expirationTimeoutSeconds` from now.
+ */
+declare function getSessionExpirationDate(config?: SessionConfig): Date;
+
+/**
+ * Route matcher utility for auth middleware.
+ *
+ * Determines whether a given URL path is public (no auth required)
+ * or protected (auth required) based on glob pattern configuration.
+ */
+
+/**
+ * Check if a URL path is a public route that does not require authentication.
+ *
+ * Public routes take precedence over protected routes.
+ * Auth callback paths (/auth/callback, /auth/STAR/callback) are always public.
+ */
+declare function isPublicRoute(url: string, config: RouteProtectionConfig): boolean;
+/**
+ * Normalize a URL path by stripping query parameters and trailing slashes.
+ */
+declare function normalizePath(url: string): string;
+/**
+ * Simple glob pattern matcher supporting:
+ * - Exact matches: `/health` matches `/health`
+ * - Single segment wildcard `*`: `/admin/*` matches `/admin/foo` but not `/admin/foo/bar`
+ * - Multi-segment wildcard `**`: `/api/**` matches `/api/foo`, `/api/foo/bar`, etc.
+ */
+declare function matchGlob(path: string, pattern: string): boolean;
+
+/**
+ * Authentication middleware factory.
+ *
+ * Creates a framework-agnostic auth middleware that:
+ * - Checks if the route is public (skip auth)
+ * - Extracts shop domain from the request
+ * - Loads and validates the session from storage
+ * - Constructs ShopContext on success
+ * - Returns redirect or error on failure
+ * - Emits middleware auth events
+ */
+
+/**
+ * Create an auth middleware instance.
+ *
+ * @param config - The auth configuration
+ * @param routeConfig - Optional route protection configuration. If not provided, all routes are protected.
+ */
+declare function createAuthMiddleware(config: AuthConfig, routeConfig?: RouteProtectionConfig): AuthMiddleware;
+
+export { type CreateAuthConfigInput, type CreateAuthEventInput, EncryptedSessionStorage, TokenEncryptionServiceImpl, createAuthConfig, createAuthEvent, createAuthMiddleware, getSessionExpirationDate, isPublicRoute, isSessionExpired, matchGlob, normalizePath, shouldRefreshToken };

package/dist/auth/index.d.ts

@@ -0,0 +1,165 @@
+import { AuthEventType, AuthEvent, AuthConfig, TokenEncryptionService, EncryptionConfig, EncryptedPayload, SessionStorage, Session, SessionConfig, TokenRefreshConfig, RouteProtectionConfig, AuthMiddleware } from '@uniforge/platform-core/auth';
+
+/**
+ * Auth event factory.
+ *
+ * Creates structured authentication events with automatic UUID generation,
+ * timestamp setting, and sensitive metadata key rejection.
+ */
+
+/** Input parameters for creating an auth event. */
+interface CreateAuthEventInput {
+    type: AuthEventType;
+    shopDomain: string;
+    outcome: 'success' | 'failure';
+    sessionId?: string | null;
+    userId?: number | null;
+    metadata?: Record<string, string>;
+}
+/** Create a structured auth event with auto-generated ID and timestamp. Rejects sensitive metadata keys. */
+declare function createAuthEvent(input: CreateAuthEventInput): AuthEvent;
+
+/**
+ * Auth config factory with validation and defaults.
+ */
+
+/** Input parameters for creating a validated auth configuration. */
+interface CreateAuthConfigInput {
+    apiKey: string;
+    apiSecretKey: string;
+    scopes: string[];
+    hostName: string;
+    apiVersion: string;
+    isEmbeddedApp?: boolean;
+    sessionStorage: AuthConfig['sessionStorage'];
+    encryption: AuthConfig['encryption'];
+    eventHandler?: AuthConfig['eventHandler'];
+    session?: AuthConfig['session'];
+    tokenRefresh?: AuthConfig['tokenRefresh'];
+}
+/** Create a validated AuthConfig with sensible defaults. Throws on invalid input. */
+declare function createAuthConfig(input: CreateAuthConfigInput): AuthConfig;
+
+/**
+ * AES-256-GCM token encryption with key rotation.
+ *
+ * Implements TokenEncryptionService using Node.js built-in crypto.
+ * Each encrypt call generates a unique 12-byte random IV.
+ * Key rotation is supported via a key registry — decrypt looks up
+ * the key by keyId, while encrypt always uses the active (first) key.
+ */
+
+declare class TokenEncryptionServiceImpl implements TokenEncryptionService {
+    private readonly keys;
+    private readonly activeKeyId;
+    constructor(config: EncryptionConfig);
+    /** Encrypt plaintext using the active (first) key. Generates a unique IV per call. */
+    encrypt(plaintext: string): EncryptedPayload;
+    /** Decrypt an encrypted payload. Looks up the key by keyId from the registry. */
+    decrypt(payload: EncryptedPayload): string;
+    /** Check if a payload was encrypted with the currently active key. */
+    isEncryptedWithActiveKey(payload: EncryptedPayload): boolean;
+    private toBuffer;
+}
+
+/**
+ * Encrypting session storage decorator.
+ *
+ * Wraps any SessionStorage implementation, transparently encrypting
+ * accessToken and refreshToken on store, and decrypting on load/find.
+ * Delete operations pass through unchanged.
+ */
+
+declare class EncryptedSessionStorage implements SessionStorage {
+    private readonly inner;
+    private readonly encryption;
+    constructor(inner: SessionStorage, encryption: TokenEncryptionService);
+    /** Store a session with encrypted tokens. */
+    storeSession(session: Session): Promise<boolean>;
+    /** Load a session and decrypt its tokens. */
+    loadSession(id: string): Promise<Session | undefined>;
+    /** Delete a session by ID (pass-through). */
+    deleteSession(id: string): Promise<boolean>;
+    /** Delete multiple sessions by ID (pass-through). */
+    deleteSessions(ids: string[]): Promise<boolean>;
+    /** Find sessions by shop and decrypt their tokens. */
+    findSessionsByShop(shop: string): Promise<Session[]>;
+    private encryptTokens;
+    private decryptTokens;
+}
+
+/**
+ * Session expiration and token refresh utilities.
+ *
+ * Platform-agnostic helpers for determining session validity
+ * and whether tokens should be proactively refreshed.
+ */
+
+/**
+ * Check if a session has expired.
+ *
+ * Returns true if the session's `expires` date is in the past (or now).
+ * Non-expiring sessions (null expires) are never considered expired.
+ */
+declare function isSessionExpired(session: Session, _config?: SessionConfig): boolean;
+/**
+ * Check if a session's token should be proactively refreshed.
+ *
+ * Returns true if the session will expire within the refresh buffer window.
+ * Non-expiring sessions (null expires) never need refresh.
+ */
+declare function shouldRefreshToken(session: Session, config?: TokenRefreshConfig): boolean;
+/**
+ * Calculate a session expiration date based on config.
+ *
+ * Returns a Date that is `expirationTimeoutSeconds` from now.
+ */
+declare function getSessionExpirationDate(config?: SessionConfig): Date;
+
+/**
+ * Route matcher utility for auth middleware.
+ *
+ * Determines whether a given URL path is public (no auth required)
+ * or protected (auth required) based on glob pattern configuration.
+ */
+
+/**
+ * Check if a URL path is a public route that does not require authentication.
+ *
+ * Public routes take precedence over protected routes.
+ * Auth callback paths (/auth/callback, /auth/STAR/callback) are always public.
+ */
+declare function isPublicRoute(url: string, config: RouteProtectionConfig): boolean;
+/**
+ * Normalize a URL path by stripping query parameters and trailing slashes.
+ */
+declare function normalizePath(url: string): string;
+/**
+ * Simple glob pattern matcher supporting:
+ * - Exact matches: `/health` matches `/health`
+ * - Single segment wildcard `*`: `/admin/*` matches `/admin/foo` but not `/admin/foo/bar`
+ * - Multi-segment wildcard `**`: `/api/**` matches `/api/foo`, `/api/foo/bar`, etc.
+ */
+declare function matchGlob(path: string, pattern: string): boolean;
+
+/**
+ * Authentication middleware factory.
+ *
+ * Creates a framework-agnostic auth middleware that:
+ * - Checks if the route is public (skip auth)
+ * - Extracts shop domain from the request
+ * - Loads and validates the session from storage
+ * - Constructs ShopContext on success
+ * - Returns redirect or error on failure
+ * - Emits middleware auth events
+ */
+
+/**
+ * Create an auth middleware instance.
+ *
+ * @param config - The auth configuration
+ * @param routeConfig - Optional route protection configuration. If not provided, all routes are protected.
+ */
+declare function createAuthMiddleware(config: AuthConfig, routeConfig?: RouteProtectionConfig): AuthMiddleware;
+
+export { type CreateAuthConfigInput, type CreateAuthEventInput, EncryptedSessionStorage, TokenEncryptionServiceImpl, createAuthConfig, createAuthEvent, createAuthMiddleware, getSessionExpirationDate, isPublicRoute, isSessionExpired, matchGlob, normalizePath, shouldRefreshToken };