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

package/dist/index.d.cts

@@ -1023,7 +1023,7 @@ declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConfig>> =
      *
      * @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;
     /**
@@ -1031,7 +1031,7 @@ declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConfig>> =
      *
      * @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;
     /**
@@ -1366,7 +1366,16 @@ declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConfig>> =
      * 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;
 }
@@ -1452,4 +1461,236 @@ declare function extractUserInfo(tokenData: OAuthTokenResponse, providerMetadata
     userInfo: UserInfo;
 }>;
 
-export { type AccountLinkingConfig, type AccountLinkingMode, AccountLinkingStrategy, type ConnectedResource, type IProvider, Lixa, type LixaConfig, type OAuthTokenResponse, type ProviderConfig, type ProviderMetadata, type ResourceHandler, type ResourceStorage, type SafeLixaConfig, type Session, type SessionHandler, type SessionStorage, type StateData, type StateHandler, type StateStorage, type UserInfo, decodeIdToken, determineProviderFromIssuer, extractUserInfo, fetchUserInfo };
+/**
+ * Base error class for all Lixa authentication and authorization errors.
+ *
+ * @public
+ */
+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
+ */
+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
+ */
+declare class ProviderNotConfiguredError extends LixaError {
+    constructor(provider: string, details?: Record<string, unknown>);
+}
+/**
+ * Thrown when a provider configuration is invalid or missing required credentials.
+ *
+ * @public
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+declare class RefreshTokenError extends LixaError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+
+/**
+ * Sensible default cookie configuration options.
+ * Follows RFC 6265bis and OAuth 2.0 security best practices.
+ *
+ * @public
+ */
+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
+ */
+interface CookiePayload {
+    name: string;
+    value: string;
+    options: CookieOptions;
+    /**
+     * Formatted `Set-Cookie` header value string.
+     */
+    header: string;
+}
+/**
+ * Default session cookie name.
+ * @public
+ */
+declare const DEFAULT_SESSION_COOKIE_NAME = "lixa_session";
+/**
+ * Default OAuth state cookie name.
+ * @public
+ */
+declare const DEFAULT_STATE_COOKIE_NAME = "lixa_oauth_state";
+/**
+ * Default session max age in seconds (24 hours).
+ * @public
+ */
+declare const DEFAULT_SESSION_MAX_AGE_SECONDS: number;
+/**
+ * Default OAuth state max age in seconds (10 minutes).
+ * @public
+ */
+declare const DEFAULT_STATE_MAX_AGE_SECONDS: number;
+/**
+ * Checks if the runtime environment is production.
+ * @public
+ */
+declare function isProductionEnvironment(): boolean;
+/**
+ * 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
+ */
+declare function serializeCookie(name: string, value: string, options?: CookieOptions): 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
+ */
+declare function createSessionCookie(sessionId: string, options?: CookieOptions): CookiePayload;
+/**
+ * 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
+ */
+declare function clearSessionCookie(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
+ */
+declare function createStateCookie(state: string, 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
+ */
+declare function clearStateCookie(options?: CookieOptions): CookiePayload;
+
+export { type AccountLinkingConfig, type AccountLinkingMode, AccountLinkingStrategy, AccountUnlinkError, type ConnectedResource, type CookieOptions, type CookiePayload, DEFAULT_SESSION_COOKIE_NAME, DEFAULT_SESSION_MAX_AGE_SECONDS, DEFAULT_STATE_COOKIE_NAME, DEFAULT_STATE_MAX_AGE_SECONDS, EmailNotVerifiedError, type IProvider, InvalidOAuthCallbackError, InvalidProviderConfigError, InvalidStateError, Lixa, type LixaConfig, LixaError, type OAuthTokenResponse, type ProviderConfig, type ProviderMetadata, ProviderNotConfiguredError, RefreshTokenError, type ResourceHandler, type ResourceStorage, type SafeLixaConfig, type Session, type SessionHandler, SessionNotFoundError, type SessionStorage, type StateData, type StateHandler, type StateStorage, TokenExchangeError, type UserInfo, clearSessionCookie, clearStateCookie, createSessionCookie, createStateCookie, decodeIdToken, determineProviderFromIssuer, extractUserInfo, fetchUserInfo, isProductionEnvironment, serializeCookie };

package/dist/index.d.ts

@@ -18,4 +18,6 @@
 export { Lixa } from "./lixa";
 export { type ProviderConfig, type LixaConfig, type SafeLixaConfig, type IProvider, type Session, type ConnectedResource, type ProviderMetadata, type OAuthTokenResponse, type StateHandler, type StateStorage, type SessionHandler, type SessionStorage, type ResourceHandler, type ResourceStorage, type StateData, AccountLinkingStrategy, type AccountLinkingMode, type AccountLinkingConfig, } from "./types";
 export { type UserInfo, extractUserInfo, decodeIdToken, fetchUserInfo, determineProviderFromIssuer, } from "./utils/user-info";
+export { LixaError, InvalidStateError, ProviderNotConfiguredError, InvalidProviderConfigError, InvalidOAuthCallbackError, TokenExchangeError, SessionNotFoundError, EmailNotVerifiedError, AccountUnlinkError, RefreshTokenError, } from "./errors";
+export { type CookieOptions, type CookiePayload, DEFAULT_SESSION_COOKIE_NAME, DEFAULT_STATE_COOKIE_NAME, DEFAULT_SESSION_MAX_AGE_SECONDS, DEFAULT_STATE_MAX_AGE_SECONDS, isProductionEnvironment, serializeCookie, createSessionCookie, clearSessionCookie, createStateCookie, clearStateCookie, } from "./utils/cookies";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,OAAO,EACZ,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,SAAS,EACd,sBAAsB,EACtB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,GAC1B,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,KAAK,QAAQ,EACb,eAAe,EACf,aAAa,EACb,aAAa,EACb,2BAA2B,GAC5B,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,OAAO,EACZ,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,SAAS,EACd,sBAAsB,EACtB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,GAC1B,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,KAAK,QAAQ,EACb,eAAe,EACf,aAAa,EACb,aAAa,EACb,2BAA2B,GAC5B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,0BAA0B,EAC1B,0BAA0B,EAC1B,yBAAyB,EACzB,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,2BAA2B,EAC3B,yBAAyB,EACzB,+BAA+B,EAC/B,6BAA6B,EAC7B,uBAAuB,EACvB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC"}