@harperfast/oauth 1.2.1

package/dist/lib/withOAuthValidation.js

@@ -0,0 +1,188 @@
+/**
+ * OAuth Session Validation Wrapper
+ *
+ * Wraps Harper resources to add automatic OAuth session validation and token refresh
+ * before handling any request. This enables transparent token management for protected endpoints.
+ */
+import { validateAndRefreshSession } from "./sessionValidator.js";
+/**
+ * Wraps a Harper resource to add automatic OAuth session validation
+ *
+ * This wrapper intercepts all resource method calls (get, post, put, patch, delete)
+ * and validates/refreshes OAuth tokens before passing the request to the original resource.
+ *
+ * @example
+ * ```typescript
+ * // In your application component:
+ * import { withOAuthValidation } from '@harperfast/oauth';
+ *
+ * export function handleApplication(scope) {
+ *   // Get OAuth providers from the OAuth plugin
+ *   const oauthPlugin = scope.parent.resources.get('oauth');
+ *
+ *   // Wrap your protected resource
+ *   const myResource = {
+ *     async get(target, request) {
+ *       // This code only runs if OAuth session is valid
+ *       return { user: request.session.oauthUser };
+ *     }
+ *   };
+ *
+ *   scope.resources.set('protected', withOAuthValidation(myResource, {
+ *     providers: oauthPlugin.providers,
+ *     requireAuth: true,
+ *     logger: scope.logger
+ *   }));
+ * }
+ * ```
+ */
+export function withOAuthValidation(resource, options) {
+    const { providers, logger, requireAuth = false, onValidationError } = options;
+    // Create a proxy that wraps all resource methods
+    return new Proxy(resource, {
+        get(target, prop) {
+            const originalMethod = target[prop];
+            // Only wrap HTTP methods
+            if (!['get', 'post', 'put', 'patch', 'delete'].includes(prop)) {
+                return originalMethod;
+            }
+            // Return wrapped method with OAuth validation
+            return async function (...args) {
+                // Extract request from arguments (usually last or second argument)
+                const request = args.find((arg) => arg?.session !== undefined);
+                if (!request) {
+                    // No request object found - just pass through
+                    return originalMethod.apply(this, args);
+                }
+                // Check if session has OAuth data
+                const hasOAuth = request.session?.oauth !== undefined;
+                if (!hasOAuth) {
+                    if (requireAuth) {
+                        // OAuth authentication required but not present
+                        const error = 'OAuth authentication required';
+                        if (onValidationError) {
+                            return onValidationError(request, error);
+                        }
+                        return {
+                            status: 401,
+                            body: {
+                                error: 'Unauthorized',
+                                message: error,
+                            },
+                        };
+                    }
+                    // OAuth not required, pass through
+                    return originalMethod.apply(this, args);
+                }
+                // Get provider for this OAuth session
+                const providerName = request.session?.oauth?.provider;
+                if (!providerName) {
+                    // No provider name in session - invalid OAuth data
+                    if (request.session) {
+                        delete request.session.oauth;
+                        delete request.session.oauthUser;
+                    }
+                    if (requireAuth) {
+                        const error = 'Invalid OAuth session data';
+                        if (onValidationError) {
+                            return onValidationError(request, error);
+                        }
+                        return {
+                            status: 401,
+                            body: {
+                                error: 'Unauthorized',
+                                message: error,
+                            },
+                        };
+                    }
+                    return originalMethod.apply(this, args);
+                }
+                const providerData = providers[providerName];
+                if (!providerData) {
+                    logger?.warn?.(`OAuth provider '${providerName}' not found for session validation`);
+                    // Provider not found - clear OAuth data and continue
+                    if (request.session) {
+                        delete request.session.oauth;
+                        delete request.session.oauthUser;
+                    }
+                    if (requireAuth) {
+                        const error = `OAuth provider '${providerName}' not configured`;
+                        if (onValidationError) {
+                            return onValidationError(request, error);
+                        }
+                        return {
+                            status: 401,
+                            body: {
+                                error: 'Unauthorized',
+                                message: error,
+                            },
+                        };
+                    }
+                    return originalMethod.apply(this, args);
+                }
+                // Validate and refresh session
+                const validation = await validateAndRefreshSession(request, providerData.provider, logger);
+                if (!validation.valid) {
+                    // Session validation failed
+                    logger?.info?.(`OAuth session validation failed: ${validation.error}`);
+                    if (requireAuth) {
+                        const error = validation.error || 'OAuth session expired';
+                        if (onValidationError) {
+                            return onValidationError(request, error);
+                        }
+                        return {
+                            status: 401,
+                            body: {
+                                error: 'Unauthorized',
+                                message: 'OAuth session expired. Please log in again.',
+                                details: validation.error,
+                            },
+                        };
+                    }
+                    // Not requiring auth, but validation failed - continue without OAuth
+                    return originalMethod.apply(this, args);
+                }
+                // Session is valid (and possibly refreshed)
+                if (validation.refreshed) {
+                    logger?.debug?.(`OAuth token refreshed for ${providerName} session`);
+                }
+                // Call original method with validated/refreshed session
+                return originalMethod.apply(this, args);
+            };
+        },
+    });
+}
+/**
+ * Helper to get OAuth providers from the OAuth plugin
+ * Call this from your application to access the provider registry
+ *
+ * @example
+ * ```typescript
+ * import { getOAuthProviders } from '@harperfast/oauth';
+ *
+ * export function handleApplication(scope) {
+ *   const providers = getOAuthProviders(scope);
+ *   // Use providers with withOAuthValidation
+ * }
+ * ```
+ */
+export function getOAuthProviders(scope) {
+    try {
+        // Try to get OAuth plugin from parent scope
+        const oauthResource = scope.parent?.resources?.get?.('oauth');
+        if (oauthResource?.providers) {
+            return oauthResource.providers;
+        }
+        // Try to get from same scope (if plugin is loaded at same level)
+        const localOAuth = scope.resources?.get?.('oauth');
+        if (localOAuth?.providers) {
+            return localOAuth.providers;
+        }
+        return null;
+    }
+    catch {
+        // OAuth module not loaded or accessible
+        return null;
+    }
+}
+//# sourceMappingURL=withOAuthValidation.js.map

package/dist/lib/withOAuthValidation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"withOAuthValidation.js","sourceRoot":"","sources":["../../src/lib/withOAuthValidation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAalE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAa,EAAE,OAA+B;IACjF,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,GAAG,KAAK,EAAE,iBAAiB,EAAE,GAAG,OAAO,CAAC;IAE9E,iDAAiD;IACjD,OAAO,IAAI,KAAK,CAAC,QAAQ,EAAE;QAC1B,GAAG,CAAC,MAAM,EAAE,IAAY;YACvB,MAAM,cAAc,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;YAEpC,yBAAyB;YACzB,IAAI,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC/D,OAAO,cAAc,CAAC;YACvB,CAAC;YAED,8CAA8C;YAC9C,OAAO,KAAK,WAAsB,GAAG,IAAW;gBAC/C,mEAAmE;gBACnE,MAAM,OAAO,GAAwB,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,SAAS,CAAC,CAAC;gBAEpF,IAAI,CAAC,OAAO,EAAE,CAAC;oBACd,8CAA8C;oBAC9C,OAAO,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;gBACzC,CAAC;gBAED,kCAAkC;gBAClC,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,EAAE,KAAK,KAAK,SAAS,CAAC;gBAEtD,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACf,IAAI,WAAW,EAAE,CAAC;wBACjB,gDAAgD;wBAChD,MAAM,KAAK,GAAG,+BAA+B,CAAC;wBAC9C,IAAI,iBAAiB,EAAE,CAAC;4BACvB,OAAO,iBAAiB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;wBAC1C,CAAC;wBACD,OAAO;4BACN,MAAM,EAAE,GAAG;4BACX,IAAI,EAAE;gCACL,KAAK,EAAE,cAAc;gCACrB,OAAO,EAAE,KAAK;6BACd;yBACD,CAAC;oBACH,CAAC;oBACD,mCAAmC;oBACnC,OAAO,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;gBACzC,CAAC;gBAED,sCAAsC;gBACtC,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC;gBACtD,IAAI,CAAC,YAAY,EAAE,CAAC;oBACnB,mDAAmD;oBACnD,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;wBACrB,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC;wBAC7B,OAAO,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC;oBAClC,CAAC;oBACD,IAAI,WAAW,EAAE,CAAC;wBACjB,MAAM,KAAK,GAAG,4BAA4B,CAAC;wBAC3C,IAAI,iBAAiB,EAAE,CAAC;4BACvB,OAAO,iBAAiB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;wBAC1C,CAAC;wBACD,OAAO;4BACN,MAAM,EAAE,GAAG;4BACX,IAAI,EAAE;gCACL,KAAK,EAAE,cAAc;gCACrB,OAAO,EAAE,KAAK;6BACd;yBACD,CAAC;oBACH,CAAC;oBACD,OAAO,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;gBACzC,CAAC;gBAED,MAAM,YAAY,GAAG,SAAS,CAAC,YAAY,CAAC,CAAC;gBAE7C,IAAI,CAAC,YAAY,EAAE,CAAC;oBACnB,MAAM,EAAE,IAAI,EAAE,CAAC,mBAAmB,YAAY,oCAAoC,CAAC,CAAC;oBACpF,qDAAqD;oBACrD,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;wBACrB,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC;wBAC7B,OAAO,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC;oBAClC,CAAC;oBACD,IAAI,WAAW,EAAE,CAAC;wBACjB,MAAM,KAAK,GAAG,mBAAmB,YAAY,kBAAkB,CAAC;wBAChE,IAAI,iBAAiB,EAAE,CAAC;4BACvB,OAAO,iBAAiB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;wBAC1C,CAAC;wBACD,OAAO;4BACN,MAAM,EAAE,GAAG;4BACX,IAAI,EAAE;gCACL,KAAK,EAAE,cAAc;gCACrB,OAAO,EAAE,KAAK;6BACd;yBACD,CAAC;oBACH,CAAC;oBACD,OAAO,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;gBACzC,CAAC;gBAED,+BAA+B;gBAC/B,MAAM,UAAU,GAAG,MAAM,yBAAyB,CAAC,OAAO,EAAE,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;gBAE3F,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;oBACvB,4BAA4B;oBAC5B,MAAM,EAAE,IAAI,EAAE,CAAC,oCAAoC,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC;oBAEvE,IAAI,WAAW,EAAE,CAAC;wBACjB,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,IAAI,uBAAuB,CAAC;wBAC1D,IAAI,iBAAiB,EAAE,CAAC;4BACvB,OAAO,iBAAiB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;wBAC1C,CAAC;wBACD,OAAO;4BACN,MAAM,EAAE,GAAG;4BACX,IAAI,EAAE;gCACL,KAAK,EAAE,cAAc;gCACrB,OAAO,EAAE,6CAA6C;gCACtD,OAAO,EAAE,UAAU,CAAC,KAAK;6BACzB;yBACD,CAAC;oBACH,CAAC;oBAED,qEAAqE;oBACrE,OAAO,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;gBACzC,CAAC;gBAED,4CAA4C;gBAC5C,IAAI,UAAU,CAAC,SAAS,EAAE,CAAC;oBAC1B,MAAM,EAAE,KAAK,EAAE,CAAC,6BAA6B,YAAY,UAAU,CAAC,CAAC;gBACtE,CAAC;gBAED,wDAAwD;gBACxD,OAAO,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YACzC,CAAC,CAAC;QACH,CAAC;KACD,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAU;IAC3C,IAAI,CAAC;QACJ,4CAA4C;QAC5C,MAAM,aAAa,GAAG,KAAK,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC;QAC9D,IAAI,aAAa,EAAE,SAAS,EAAE,CAAC;YAC9B,OAAO,aAAa,CAAC,SAAS,CAAC;QAChC,CAAC;QAED,iEAAiE;QACjE,MAAM,UAAU,GAAG,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC;QACnD,IAAI,UAAU,EAAE,SAAS,EAAE,CAAC;YAC3B,OAAO,UAAU,CAAC,SAAS,CAAC;QAC7B,CAAC;QAED,OAAO,IAAI,CAAC;IACb,CAAC;IAAC,MAAM,CAAC;QACR,wCAAwC;QACxC,OAAO,IAAI,CAAC;IACb,CAAC;AACF,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,326 @@
+/**
+ * OAuth Plugin Type Definitions
+ */
+import type { IncomingMessage } from 'node:http';
+import type { Scope, User, RequestTarget } from 'harperdb';
+/**
+ * OAuth Plugin Configuration
+ * Runtime configuration for the OAuth plugin
+ */
+export interface OAuthPluginConfig {
+    /** Enable debug mode to expose additional endpoints and information (can be boolean or string from env var) */
+    debug?: boolean | string;
+    /** OAuth provider configurations */
+    providers?: Record<string, any>;
+    /** Default redirect URI for all providers */
+    redirectUri?: string;
+    /** Default post-login redirect path */
+    postLoginRedirect?: string;
+    /** Default OAuth scopes */
+    scope?: string;
+    /** Default username claim path */
+    usernameClaim?: string;
+    /** Default role assignment */
+    defaultRole?: string;
+    /** Lifecycle hooks */
+    hooks?: OAuthHooks;
+}
+/**
+ * OAuth Lifecycle Hooks
+ * Callbacks invoked at key points in the OAuth flow
+ */
+export interface OAuthHooks {
+    /**
+     * Resolve OAuth provider configuration dynamically
+     *
+     * Called when a provider is not found in the static registry.
+     * Allows applications to implement multi-tenant OAuth by
+     * returning provider configurations based on naming conventions.
+     *
+     * Example: Provider name "okta-org_abc123" can be parsed to load
+     * organization-specific Okta configuration from database.
+     *
+     * @param providerName - Provider name from URL path (e.g., "okta-org_abc123")
+     * @param logger - Optional logger instance
+     * @returns Provider configuration or null if not found
+     * @throws Error if resolution fails (returns 500 to client)
+     *
+     * Security Requirements:
+     * - MUST validate tenant ID format before database lookup
+     * - MUST validate domain safety (SSRF protection)
+     * - MUST validate provider-specific configuration
+     * - MUST NOT return configurations for disabled/inactive tenants
+     * - SHOULD log all resolution attempts for audit trail
+     *
+     * @example
+     * ```typescript
+     * onResolveProvider: async (providerName, logger) => {
+     *   // Parse provider name: "okta-org_abc123" → ["okta", "org_abc123"]
+     *   const match = providerName.match(/^(okta|azure|auth0)-(.+)$/);
+     *   if (!match) return null;
+     *
+     *   const [, provider, tenantId] = match;
+     *
+     *   // Validate tenant ID format
+     *   validateTenantId(tenantId);
+     *
+     *   // Query database for tenant config
+     *   const org = await Organization.get(tenantId, context);
+     *   if (!org?.oauthConfig?.enabled) return null;
+     *
+     *   // Build and return provider config
+     *   return buildProviderConfig(org.oauthConfig, provider);
+     * }
+     * ```
+     */
+    onResolveProvider?: (providerName: string, logger?: Logger) => Promise<OAuthProviderConfig | null>;
+    /**
+     * Called after successful OAuth login, before session is finalized
+     * Use this to provision users, assign roles, etc.
+     * @param oauthUser - The OAuth user information
+     * @param tokenResponse - The token response from the provider
+     * @param session - The current session object
+     * @param request - The HTTP request object
+     * @param provider - The provider name (e.g., 'github', 'google')
+     * @returns Optional data to merge into the session
+     */
+    onLogin?: (oauthUser: OAuthUser, tokenResponse: TokenResponse, session: any, request: any, provider: string) => Promise<Record<string, any> | void>;
+    /**
+     * Called before logout, before session is cleared
+     * Use this to clean up user-specific data
+     * @param session - The current session object
+     * @param request - The HTTP request object
+     */
+    onLogout?: (session: any, request: any) => Promise<void>;
+    /**
+     * Called after token refresh completes
+     * @param session - The updated session with new tokens
+     * @param refreshed - Whether tokens were actually refreshed
+     * @param request - The HTTP request object (may be undefined for background refresh)
+     */
+    onTokenRefresh?: (session: any, refreshed: boolean, request?: any) => Promise<void>;
+}
+/**
+ * OAuth Provider Configuration
+ * Configuration options for an OAuth 2.0/OIDC provider
+ */
+export interface OAuthProviderConfig {
+    /** Provider identifier (e.g., 'github', 'google', 'azure') */
+    provider: string;
+    clientId: string;
+    clientSecret: string;
+    authorizationUrl: string;
+    tokenUrl: string;
+    userInfoUrl: string;
+    redirectUri?: string;
+    /** OAuth scopes to request (space-separated) */
+    scope?: string;
+    /** JWKS URI for ID token validation (OIDC only) */
+    jwksUri?: string | null;
+    /** Expected token issuer for validation (OIDC only) */
+    issuer?: string | null;
+    /** Claim to use as username (dot notation supported for nested) */
+    usernameClaim?: string;
+    /** Claim containing user's email address */
+    emailClaim?: string;
+    /** Claim containing user's display name */
+    nameClaim?: string;
+    /** Claim containing user's role/group membership */
+    roleClaim?: string;
+    /** Default role if not found in claims */
+    defaultRole?: string;
+    /** URL to redirect after successful login */
+    postLoginRedirect?: string;
+    /** Prefer ID token claims over userinfo endpoint (OIDC) */
+    preferIdToken?: boolean;
+    /** Whether to fetch email from provider's dedicated email endpoint */
+    fetchEmail?: boolean;
+    /** Additional query parameters for authorization URL */
+    additionalParams?: Record<string, string>;
+    /** Custom function to fetch/transform user info */
+    getUserInfo?: (accessToken: string, helpers: GetUserInfoHelpers) => Promise<any>;
+    /** Custom function to validate token (for non-expiring tokens like GitHub) */
+    validateToken?: (accessToken: string, logger?: Logger) => Promise<boolean>;
+    /** Interval for periodic token validation (ms) - only for tokens without expiration */
+    tokenValidationInterval?: number;
+    /** Provider-specific configuration function (e.g., for tenant/domain setup) */
+    configure?: (param: string) => Partial<OAuthProviderConfig>;
+}
+/**
+ * Helpers passed to custom getUserInfo function
+ */
+export interface GetUserInfoHelpers {
+    /** Default getUserInfo implementation to call */
+    getUserInfo: (accessToken: string) => Promise<any>;
+    logger?: Logger;
+}
+/**
+ * OAuth User Object
+ * Represents a user authenticated via OAuth
+ */
+export interface OAuthUser {
+    /** Username extracted from configured claim */
+    username: string;
+    role: string;
+    /** OAuth provider name */
+    provider: string;
+    /** User ID from the OAuth provider */
+    providerUserId?: string;
+    email?: string;
+    name?: string;
+    /** Additional provider-specific data */
+    metadata?: Record<string, any>;
+}
+/**
+ * OAuth Token Response
+ * Standard OAuth 2.0 token endpoint response
+ */
+export interface TokenResponse {
+    access_token: string;
+    /** Usually 'Bearer' */
+    token_type?: string;
+    /** Token lifetime in seconds */
+    expires_in?: number;
+    refresh_token?: string;
+    /** ID token for OIDC providers */
+    id_token?: string;
+    /** Space-separated granted scopes */
+    scope?: string;
+    /** Error code if token request failed (some providers return 200 with error) */
+    error?: string;
+    /** Human-readable error description */
+    error_description?: string;
+    /** URL to documentation about the error */
+    error_uri?: string;
+}
+/**
+ * CSRF Token Data
+ * Metadata stored with CSRF tokens during OAuth flow
+ */
+export interface CSRFTokenData {
+    /** Unix timestamp when token was created */
+    timestamp: number;
+    /** URL to redirect to after successful authentication */
+    originalUrl?: string;
+    /** Session ID to link OAuth flow with existing session */
+    sessionId?: string;
+    [key: string]: any;
+}
+/**
+ * OAuth Provider Interface
+ * Methods that OAuthProvider class implements
+ */
+export interface IOAuthProvider {
+    config: OAuthProviderConfig;
+    logger?: Logger;
+    /** Generate CSRF token for OAuth state parameter */
+    generateCSRFToken(metadata: Record<string, any>): Promise<string>;
+    /** Verify and consume CSRF token (one-time use) */
+    verifyCSRFToken(token: string): Promise<CSRFTokenData | null>;
+    /** Build authorization URL with all required parameters */
+    getAuthorizationUrl(state: string, redirectUri: string): string;
+    /** Exchange authorization code for access/refresh tokens */
+    exchangeCodeForToken(code: string, redirectUri: string): Promise<TokenResponse>;
+    /** Fetch user information from provider */
+    getUserInfo(accessToken: string, idTokenClaims?: any): Promise<any>;
+    /** Map provider user info to Harper user format */
+    mapUserToHarper(userInfo: any): OAuthUser;
+    /** Verify and decode ID token (OIDC only) */
+    verifyIdToken?(idToken: string): Promise<any>;
+    /** Exchange refresh token for new access token */
+    refreshAccessToken?(refreshToken: string): Promise<TokenResponse>;
+}
+/**
+ * Provider Registry Entry
+ * Stores initialized provider instance with its config
+ */
+export interface ProviderRegistryEntry {
+    /** Initialized OAuth provider instance */
+    provider: IOAuthProvider;
+    config: OAuthProviderConfig;
+}
+/**
+ * Provider Registry
+ * Collection of all configured OAuth providers keyed by name
+ */
+export interface ProviderRegistry {
+    [providerName: string]: ProviderRegistryEntry;
+}
+/**
+ * Harper Table Instance
+ * Methods available on a Harper table
+ */
+export interface Table {
+    get(id: string): Promise<any>;
+    put(record: any): Promise<any>;
+    delete(id: string): Promise<void>;
+}
+/**
+ * Logger Interface
+ * Harper's logger interface for component logging
+ */
+export interface Logger {
+    info?: (message: string, ...args: any[]) => void;
+    error?: (message: string, ...args: any[]) => void;
+    warn?: (message: string, ...args: any[]) => void;
+    debug?: (message: string, ...args: any[]) => void;
+}
+/**
+ * Harper HTTP Request
+ * Extended Node.js IncomingMessage with Harper additions
+ */
+export interface Request extends IncomingMessage {
+    /** Authenticated Harper user or username string */
+    user?: User | string;
+    session?: Session;
+    headers: IncomingMessage['headers'];
+    /** Client IP address */
+    ip?: string;
+}
+/**
+ * OAuth Session Metadata
+ * Token and expiration data stored in session for automatic refresh
+ */
+export interface OAuthSessionMetadata {
+    /**
+     * Provider configuration ID/key from config (e.g., 'my-custom-github', 'production-okta').
+     * @deprecated Use `providerConfigId` instead. This field is maintained for backwards compatibility only.
+     */
+    provider: string;
+    /** Provider configuration ID/key from config (e.g., 'my-custom-github', 'production-okta'). */
+    providerConfigId: string;
+    /** OAuth provider type (e.g., 'github', 'google', 'okta') */
+    providerType: string;
+    /** Current access token */
+    accessToken: string;
+    /** Refresh token for obtaining new access tokens */
+    refreshToken?: string;
+    /** Unix timestamp (ms) when the access token expires */
+    expiresAt?: number;
+    /** Unix timestamp (ms) when to proactively refresh (80% of lifetime) */
+    refreshThreshold?: number;
+    /** Space-separated list of granted scopes */
+    scope?: string;
+    /** Token type (usually 'Bearer') */
+    tokenType?: string;
+    /** Unix timestamp (ms) of last successful token refresh */
+    lastRefreshed?: number;
+    /** Unix timestamp (ms) of last token validation (for non-expiring tokens) */
+    lastValidated?: number;
+}
+/**
+ * Harper Session
+ * Session data stored for authenticated users
+ */
+export interface Session {
+    id?: string;
+    /** Harper username (string) */
+    user?: string;
+    /** Full OAuth user object */
+    oauthUser?: OAuthUser;
+    /** OAuth session metadata for automatic token refresh */
+    oauth?: OAuthSessionMetadata;
+    /** Async session update method (when available) */
+    update?: (data: Partial<Session>) => Promise<void>;
+}
+export type { Scope, User, RequestTarget };

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * OAuth Plugin Type Definitions
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/package.json

@@ -0,0 +1,89 @@
+{
+	"name": "@harperfast/oauth",
+	"version": "1.2.1",
+	"description": "OAuth 2.0 authentication plugin for Harper",
+	"license": "Apache-2.0",
+	"author": {
+		"name": "HarperDB, Inc.",
+		"email": "opensource@harperdb.io",
+		"url": "https://harper.fast/"
+	},
+	"contributors": [],
+	"homepage": "https://harper.fast/",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/HarperFast/oauth.git"
+	},
+	"bugs": {
+		"url": "https://github.com/HarperFast/oauth/issues",
+		"email": "opensource@harperdb.io"
+	},
+	"keywords": [
+		"harperdb",
+		"harper",
+		"plugin",
+		"oauth",
+		"oauth2",
+		"authentication",
+		"oidc",
+		"openid"
+	],
+	"type": "module",
+	"main": "dist/index.js",
+	"exports": {
+		".": "./dist/index.js",
+		"./config": "./config.yaml"
+	},
+	"files": [
+		"dist/",
+		"assets/",
+		"schema/",
+		"config.yaml",
+		"LICENSE",
+		"README.md"
+	],
+	"scripts": {
+		"build": "tsc || true",
+		"dev": "tsc --watch",
+		"test": "npm run build && node --test \"test/**/*.test.js\"",
+		"test:watch": "npm run build && node --test --watch \"test/**/*.test.js\"",
+		"test:coverage": "npm run build && node --enable-source-maps --test --experimental-test-coverage --test-coverage-exclude='test/**' --test-coverage-exclude='**/harperdb/**' \"test/**/*.test.js\"",
+		"test:node-twenty": "npm run build && node --test test/",
+		"lint": "eslint . --ignore-pattern 'dist/**'",
+		"format": "prettier .",
+		"format:check": "npm run format -- --check",
+		"format:write": "npm run format -- --write",
+		"prepublishOnly": "npm run build"
+	},
+	"dependencies": {
+		"jsonwebtoken": "^9.0.2",
+		"jwks-rsa": "^3.1.0"
+	},
+	"devDependencies": {
+		"@harperdb/code-guidelines": "^0.0.5",
+		"@types/jsonwebtoken": "^9.0.5",
+		"@types/node": "^20.11.0",
+		"eslint": "^9.35.0",
+		"harperdb": "^4.7.14",
+		"prettier": "^3.6.2",
+		"typescript": "^5.3.3"
+	},
+	"peerDependencies": {
+		"harperdb": ">=4.6.0"
+	},
+	"engines": {
+		"node": ">=20",
+		"bun": ">=1.0"
+	},
+	"devEngines": {
+		"runtime": {
+			"name": "node",
+			"version": ">=20",
+			"onFail": "error"
+		},
+		"packageManager": {
+			"name": "npm",
+			"onFail": "error"
+		}
+	}
+}

package/schema/oauth.graphql

@@ -0,0 +1,21 @@
+## OAuth Plugin Schema
+## This defines the tables needed for OAuth functionality
+
+## CSRF Token storage table in oauth database
+## Stores temporary CSRF tokens for OAuth flows (10 minute expiration)
+type csrf_tokens @table(database: "oauth", expiration: 600) {
+	token_id: ID @primaryKey
+	data: String # JSON stringified CSRFTokenData
+	created_at: Float
+}
+
+## OAuth User Session table (optional, for future use)
+## Could store OAuth-specific user data
+# type oauth_sessions @table(database: "oauth") {
+#     username: ID @primaryKey
+#     provider: String @indexed
+#     provider_id: String
+#     access_token: String
+#     refresh_token: String
+#     expires_at: Float
+# }