@vunexa/lixa 0.1.6-alpha.7 → 0.1.6-alpha.8

package/README.md

@@ -17,8 +17,7 @@ A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library
 - **Multi-SSO Account Linking**: Seamlessly merge accounts sharing the same verified email address under a single unified user session.
 - **Post-Login Resource Connection API**: Connect third-party API providers (GitHub Repositories, Google Drive, Slack) post-authentication and manage resource tokens on the user session.
 - **Multi-provider OAuth/OIDC support** with unified API.
-- **Built-in providers** for Google, GitHub, and more via `@vunexa/lixa-providers`.
-- **Custom provider support** with extensible provider interface.
+- **Pre-built Database Storage Adapters**: Official Prisma and Drizzle ORM adapters via `@vunexa/lixa-adapters` with support for PostgreSQL, MySQL, and SQLite.
 - **Unified session management** via `SessionHandler` (generation + storage).
 - **Unified state management** via `StateHandler` (PKCE + CSRF protection).
 - **Automatic PKCE** (Proof Key for Code Exchange) for all OAuth flows.

package/README.template.md

@@ -17,8 +17,7 @@ A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library
 - **Multi-SSO Account Linking**: Seamlessly merge accounts sharing the same verified email address under a single unified user session.
 - **Post-Login Resource Connection API**: Connect third-party API providers (GitHub Repositories, Google Drive, Slack) post-authentication and manage resource tokens on the user session.
 - **Multi-provider OAuth/OIDC support** with unified API.
-- **Built-in providers** for Google, GitHub, and more via `@vunexa/lixa-providers`.
-- **Custom provider support** with extensible provider interface.
+- **Pre-built Database Storage Adapters**: Official Prisma and Drizzle ORM adapters via `@vunexa/lixa-adapters` with support for PostgreSQL, MySQL, and SQLite.
 - **Unified session management** via `SessionHandler` (generation + storage).
 - **Unified state management** via `StateHandler` (PKCE + CSRF protection).
 - **Automatic PKCE** (Proof Key for Code Exchange) for all OAuth flows.

package/dist/errors.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Base error class for all Lixa authentication and authorization errors.
+ *
+ * @public
+ */
+export declare class LixaError extends Error {
+    /**
+     * Standard error code string.
+     */
+    readonly code: string;
+    /**
+     * Additional error context data.
+     */
+    readonly details: Record<string, unknown> | undefined;
+    constructor(message: string, code?: string, details?: Record<string, unknown>);
+}
+/**
+ * Thrown when an OAuth state parameter is invalid, missing, or has expired.
+ *
+ * @public
+ */
+export declare class InvalidStateError extends LixaError {
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+/**
+ * Thrown when attempting to use a provider that is not configured in the Lixa instance.
+ *
+ * @public
+ */
+export declare class ProviderNotConfiguredError extends LixaError {
+    constructor(provider: string, details?: Record<string, unknown>);
+}
+/**
+ * Thrown when a provider configuration is invalid or missing required credentials.
+ *
+ * @public
+ */
+export declare class InvalidProviderConfigError extends LixaError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Thrown when OAuth callback parameters (e.g. authorization code or state) are missing or malformed.
+ *
+ * @public
+ */
+export declare class InvalidOAuthCallbackError extends LixaError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Thrown when exchanging an authorization code for OAuth tokens fails at the provider endpoint.
+ *
+ * @public
+ */
+export declare class TokenExchangeError extends LixaError {
+    readonly status: number | undefined;
+    constructor(message: string, status?: number, details?: Record<string, unknown>);
+}
+/**
+ * Thrown when a user session is not found or has expired.
+ *
+ * @public
+ */
+export declare class SessionNotFoundError extends LixaError {
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+/**
+ * Thrown when account linking fails, e.g. when unverified email linking is rejected.
+ *
+ * @public
+ */
+export declare class EmailNotVerifiedError extends LixaError {
+    constructor(email?: string, details?: Record<string, unknown>);
+}
+/**
+ * Thrown when unlinking an account violates security constraints (e.g. unlinking the only login provider).
+ *
+ * @public
+ */
+export declare class AccountUnlinkError extends LixaError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Thrown when a refresh token is missing or token refresh fails for a connected resource.
+ *
+ * @public
+ */
+export declare class RefreshTokenError extends LixaError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC;;OAEG;IACH,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,SAAgB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;gBAEjD,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAqB,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAS5F;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,SAAS;gBAClC,OAAO,GAAE,MAAmC,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG5F;AAED;;;;GAIG;AACH,qBAAa,0BAA2B,SAAQ,SAAS;gBAC3C,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAShE;AAED;;;;GAIG;AACH,qBAAa,0BAA2B,SAAQ,SAAS;gBAC3C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG/D;AAED;;;;GAIG;AACH,qBAAa,yBAA0B,SAAQ,SAAS;gBAC1C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG/D;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,SAAS;IAC/C,SAAgB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE/B,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAIhF;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;gBACrC,OAAO,GAAE,MAAkD,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG3G;AAED;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,SAAS;gBACtC,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAO9D;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,SAAS;gBACnC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG/D;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,SAAS;gBAClC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG/D"}

package/dist/export-types/index.d.ts

@@ -123,6 +123,41 @@ export declare enum AccountLinkingStrategy {
     ISOLATED = "ISOLATED"
 }
 
+/**
+ * Thrown when unlinking an account violates security constraints (e.g. unlinking the only login provider).
+ *
+ * @public
+ */
+export declare class AccountUnlinkError extends LixaError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+
+/**
+ * Generates an expired session cookie payload to clear the session on logout.
+ *
+ * @param options - Optional overrides for cookie name or attributes
+ *
+ * @example
+ * ```typescript
+ * const cookie = clearSessionCookie();
+ * res.setHeader("Set-Cookie", cookie.header);
+ * // or with Express:
+ * res.clearCookie(cookie.name, cookie.options);
+ * ```
+ *
+ * @public
+ */
+export declare function clearSessionCookie(options?: CookieOptions): CookiePayload;
+
+/**
+ * Generates an expired OAuth state cookie payload to clean up the state cookie after callback.
+ *
+ * @param options - Optional overrides for cookie attributes
+ *
+ * @public
+ */
+export declare function clearStateCookie(options?: CookieOptions): CookiePayload;
+
 /**
  * Type representing the keys of configured providers
  */
@@ -151,6 +186,91 @@ export declare interface ConnectedResource {
     connectedAt: number;
 }
 
+/**
+ * Sensible default cookie configuration options.
+ * Follows RFC 6265bis and OAuth 2.0 security best practices.
+ *
+ * @public
+ */
+export declare interface CookieOptions {
+    /**
+     * Cookie name.
+     * @default 'lixa_session'
+     */
+    name?: string | undefined;
+    /**
+     * Cookie path.
+     * @default '/'
+     */
+    path?: string | undefined;
+    /**
+     * Maximum age of the cookie in seconds.
+     */
+    maxAge?: number | undefined;
+    /**
+     * Prevents client-side scripts from accessing the cookie (XSS protection).
+     * @default true
+     */
+    httpOnly?: boolean | undefined;
+    /**
+     * Ensures the cookie is only transmitted over secure HTTPS connections.
+     * @default false in development, true in production
+     */
+    secure?: boolean | undefined;
+    /**
+     * Controls whether the cookie is sent with cross-site requests (CSRF protection).
+     * @default 'lax'
+     */
+    sameSite?: "lax" | "strict" | "none" | undefined;
+    /**
+     * Cookie domain.
+     */
+    domain?: string | undefined;
+}
+
+/**
+ * Cookie payload containing name, value, options, and formatted header.
+ *
+ * @public
+ */
+export declare interface CookiePayload {
+    name: string;
+    value: string;
+    options: CookieOptions;
+    /**
+     * Formatted `Set-Cookie` header value string.
+     */
+    header: string;
+}
+
+/**
+ * Generates a session cookie payload with secure default options.
+ *
+ * @param sessionId - The session identifier string
+ * @param options - Optional overrides for cookie attributes
+ *
+ * @example
+ * ```typescript
+ * const cookie = createSessionCookie(sessionId);
+ * res.setHeader("Set-Cookie", cookie.header);
+ * // or with Express:
+ * res.cookie(cookie.name, cookie.value, cookie.options);
+ * ```
+ *
+ * @public
+ */
+export declare function createSessionCookie(sessionId: string, options?: CookieOptions): CookiePayload;
+
+/**
+ * Generates an OAuth CSRF state cookie payload for in-flight authorization flows.
+ *
+ * @param state - The random state string
+ * @param options - Optional overrides for cookie attributes
+ *
+ * @public
+ */
+export declare function createStateCookie(state: string, options?: CookieOptions): CookiePayload;
+
 /**
  * Decode JWT ID token to extract user information
  *
@@ -158,6 +278,30 @@ export declare interface ConnectedResource {
  */
 export declare function decodeIdToken(idToken: string): UserInfo;
 
+/**
+ * Default session cookie name.
+ * @public
+ */
+export declare const DEFAULT_SESSION_COOKIE_NAME = "lixa_session";
+
+/**
+ * Default session max age in seconds (24 hours).
+ * @public
+ */
+export declare const DEFAULT_SESSION_MAX_AGE_SECONDS: number;
+
+/**
+ * Default OAuth state cookie name.
+ * @public
+ */
+export declare const DEFAULT_STATE_COOKIE_NAME = "lixa_oauth_state";
+
+/**
+ * Default OAuth state max age in seconds (10 minutes).
+ * @public
+ */
+export declare const DEFAULT_STATE_MAX_AGE_SECONDS: number;
+
 /**
  * Determine OAuth provider from ID token issuer
  *
@@ -165,6 +309,15 @@ export declare function decodeIdToken(idToken: string): UserInfo;
  */
 export declare function determineProviderFromIssuer(userInfo: UserInfo): string | null;
 
+/**
+ * Thrown when account linking fails, e.g. when unverified email linking is rejected.
+ *
+ * @public
+ */
+export declare class EmailNotVerifiedError extends LixaError {
+    constructor(email?: string, details?: Record<string, unknown>);
+}
+
 /**
  * Extract user info from OAuth token data
  *
@@ -219,6 +372,33 @@ export declare function extractUserInfo(tokenData: OAuthTokenResponse, providerM
  */
 export declare function fetchUserInfo(accessToken: string, userInfoEndpoint: string): Promise<UserInfo>;
 
+/**
+ * Thrown when OAuth callback parameters (e.g. authorization code or state) are missing or malformed.
+ *
+ * @public
+ */
+export declare class InvalidOAuthCallbackError extends LixaError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+
+/**
+ * Thrown when a provider configuration is invalid or missing required credentials.
+ *
+ * @public
+ */
+export declare class InvalidProviderConfigError extends LixaError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+
+/**
+ * Thrown when an OAuth state parameter is invalid, missing, or has expired.
+ *
+ * @public
+ */
+export declare class InvalidStateError extends LixaError {
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+
 /**
  * Interface for OAuth 2.0 and OpenID Connect provider implementations.
  *
@@ -359,6 +539,12 @@ export declare interface IProvider {
     authScopes?: string[];
 }
 
+/**
+ * Checks if the runtime environment is production.
+ * @public
+ */
+export declare function isProductionEnvironment(): boolean;
+
 /**
  * Represents a linked provider account within a user's session.
  *
@@ -460,7 +646,7 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      *
      * @param name - The provider name
      * @param config - The provider configuration
-     * @throws Error when required fields are missing or invalid
+     * @throws InvalidProviderConfigError when required fields are missing or invalid
      */
     private validateProviderConfig;
     /**
@@ -468,7 +654,7 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      *
      * @param name - The provider name
      * @param provider - The provider implementation
-     * @throws Error when required properties are missing
+     * @throws InvalidProviderConfigError when required properties are missing
      */
     private validateProviderImplementation;
     /**
@@ -803,7 +989,16 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      * Disconnects a resource provider from an active session and user account.
      */
     disconnectResource(sessionId: string, provider: string): Promise<boolean>;
+    /**
+     * Retrieves active session details from session storage.
+     */
     fetchSessionInfo(sessionId: string): Promise<Session | null>;
+    /**
+     * Deletes a session from session storage (e.g. on logout).
+     *
+     * @param sessionId - Active session identifier
+     */
+    deleteSession(sessionId: string): Promise<void>;
     private exchangeCodeForToken;
     private findProviderByType;
 }
@@ -864,6 +1059,23 @@ export declare interface LixaConfig<TProviders extends Record<string, ProviderCo
     debug?: boolean;
 }
 
+/**
+ * Base error class for all Lixa authentication and authorization errors.
+ *
+ * @public
+ */
+export declare class LixaError extends Error {
+    /**
+     * Standard error code string.
+     */
+    readonly code: string;
+    /**
+     * Additional error context data.
+     */
+    readonly details: Record<string, unknown> | undefined;
+    constructor(message: string, code?: string, details?: Record<string, unknown>);
+}
+
 /**
  * OAuth 2.0 token response structure.
  * Based on RFC 6749 Section 5.1 and OpenID Connect Core 1.0 Section 3.1.3.3
@@ -986,6 +1198,24 @@ export declare interface ProviderMetadata {
     };
 }
 
+/**
+ * Thrown when attempting to use a provider that is not configured in the Lixa instance.
+ *
+ * @public
+ */
+export declare class ProviderNotConfiguredError extends LixaError {
+    constructor(provider: string, details?: Record<string, unknown>);
+}
+
+/**
+ * Thrown when a refresh token is missing or token refresh fails for a connected resource.
+ *
+ * @public
+ */
+export declare class RefreshTokenError extends LixaError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+
 /**
  * Resource handler configuration.
  *
@@ -1048,6 +1278,18 @@ export declare type SafeLixaConfig<TProviders extends Record<string, ProviderCon
     providers: TProviders;
 };
 
+/**
+ * Serializes a cookie name, value, and options into a standard `Set-Cookie` header string.
+ *
+ * @param name - Cookie name
+ * @param value - Cookie value
+ * @param options - Cookie attributes
+ * @returns Formatted `Set-Cookie` string
+ *
+ * @public
+ */
+export declare function serializeCookie(name: string, value: string, options?: CookieOptions): string;
+
 /**
  * Represents a user session after successful OAuth authentication.
  *
@@ -1248,6 +1490,15 @@ export declare interface SessionHandler {
     generateSession?<T extends Session>(tokenData: OAuthTokenResponse, providerMetadata: ProviderMetadata): Promise<T>;
 }
 
+/**
+ * Thrown when a user session is not found or has expired.
+ *
+ * @public
+ */
+export declare class SessionNotFoundError extends LixaError {
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+
 /**
  * Session storage operations interface.
  *
@@ -1473,6 +1724,16 @@ export declare interface StateStorage {
     deleteState(state: string): Promise<void>;
 }
 
+/**
+ * Thrown when exchanging an authorization code for OAuth tokens fails at the provider endpoint.
+ *
+ * @public
+ */
+export declare class TokenExchangeError extends LixaError {
+    readonly status: number | undefined;
+    constructor(message: string, status?: number, details?: Record<string, unknown>);
+}
+
 /**
  * User information extracted from OAuth provider
  *