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

package/dist/lixa.d.ts

@@ -1,6 +1,5 @@
 import { type LixaConfig, type ProviderConfig } from "./types";
 import { IProvider } from "./providers";
-import { ResourceHandler } from "./dao/types";
 import { type Session, type ConnectedResource } from "./models/session";
 /**
  * Type representing the keys of configured providers
@@ -61,8 +60,11 @@ type ConfiguredProviderKey<T extends LixaConfig<Record<string, ProviderConfig>>>
 declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConfig>> = LixaConfig> {
     private static DEFAULT_PROVIDERS;
     private static CONFIGURED_PROVIDERS;
-    private static LOCAL_STATE_HANDLER;
-    private static LOCAL_SESSION_HANDLER;
+    private localStateHandler;
+    private localSessionHandler;
+    private localResourceHandler;
+    private userResourceStore;
+    private refreshMutexes;
     private config;
     private stateHandler;
     private sessionHandler;
@@ -87,7 +89,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;
     /**
@@ -95,20 +97,16 @@ 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;
     /**
-     * Structured debug logging with standardized format.
+     * Structured logging with standardized format and custom logger support.
      *
-     * @param level - Log level (INFO, WARN, ERROR)
-     * @param context - Context of the log (Init, Auth, Token, Session, State)
+     * @param level - Log level (INFO, WARN, ERROR, DEBUG)
+     * @param context - Context of the log (Init, Auth, Token, Session, State, AccountLinking, Resource)
      * @param message - Log message
      * @param data - Optional data to log
-     *
-     * @remarks
-     * Format: [Lixa] [timestamp] [level] [context] message
-     * Only logs when debug mode is enabled.
      */
     private log;
     /**
@@ -307,7 +305,7 @@ declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConfig>> =
      */
     getAuthUrl(provider: ConfiguredProviderKey<TConfig> | string, state?: string): Promise<string>;
     /**
-     * Restricts primary authentication scopes strictly to AuthN identity scopes.
+     * Restricts primary authentication scopes strictly to AuthN identity scopes unless allowNonAuthScopes is true.
      */
     private resolveAuthNScopes;
     /**
@@ -373,14 +371,6 @@ declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConfig>> =
         prompt?: string;
         extraConfig?: Record<string, string>;
     }): Promise<string>;
-    /**
-     * Handles the OAuth callback for a connected resource provider and stores resource tokens on the session.
-     *
-     * @param params - Object containing sessionId, provider, code, state, and requested scopes
-     * @returns Updated Session containing stored resource tokens under session.resources[provider]
-     */
-    private static userResourceStore;
-    static LOCAL_RESOURCE_HANDLER: ResourceHandler;
     private getUserKeyFromSession;
     /**
      * Handles the OAuth callback for a connected resource provider and stores resource tokens bound to user account.
@@ -413,11 +403,16 @@ declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConfig>> =
     getConnectedResource(sessionId: string, provider: string): Promise<ConnectedResource | null>;
     /**
      * Refreshes a user's resource access token using its refresh token.
+     * Deduplicates concurrent refresh requests via an in-flight promise mutex.
      *
      * @param userIdOrEmail - User identifier or email
      * @param provider - Provider identifier (e.g. 'google', 'github')
      */
     refreshUserResourceToken(userIdOrEmail: string, provider: string, existingResource?: ConnectedResource): Promise<ConnectedResource>;
+    /**
+     * Internal execution of refresh token exchange.
+     */
+    private executeRefreshUserResourceToken;
     /**
      * Refreshes a connected resource access token for an active session.
      */
@@ -430,7 +425,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;
 }

package/dist/lixa.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lixa.d.ts","sourceRoot":"","sources":["../src/lixa.ts"],"names":[],"mappings":"AACA,OAAO,EAA0B,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AACvF,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,OAAO,EAAgC,eAAe,EAAmB,MAAM,aAAa,CAAC;AAG7F,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,iBAAiB,EAAkD,MAAM,kBAAkB,CAAC;AAGxH;;GAEG;AACH,KAAK,qBAAqB,CAAC,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,WAAW,CAAC,CAAC;AAExG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,cAAM,IAAI,CAAC,OAAO,SAAS,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,GAAG,UAAU;IAChF,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAqC;IACrE,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAqC;IACxE,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAA2B;IAC7D,OAAO,CAAC,MAAM,CAAC,qBAAqB,CAA6B;IACjE,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,KAAK,CAAU;IAEvB;;;;;;;;;;;;OAYG;gBACS,MAAM,EAAE,OAAO;IA0C3B;;;;;;OAMG;IACH,OAAO,CAAC,sBAAsB;IA2B9B;;;;;;OAMG;IACH,OAAO,CAAC,8BAA8B;IAetC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,GAAG;IAaX;;;;;;;;;;;;;;OAcG;IACI,oBAAoB,CAAC,CAAC,SAAS,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,QAAQ,IAAI,CAAC,GAAG,qBAAqB,CAAC,OAAO,CAAC;IAK1G;;;;;;;;OAQG;IACH,OAAO,CAAC,WAAW;IA0BnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;WACW,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,WAAW,EAAE,CAAC,GAAG,IAAI;IAMzF;;;;OAIG;WACW,sBAAsB,IAAI,MAAM,EAAE;IAIhD;;;;;;;;;;;;;;;;;;;;;;OAsBG;WACW,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,EACjE,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG;QAAE,SAAS,EAAE,CAAC,CAAA;KAAE,GACvC,UAAU,CAAC,CAAC,CAAC;IAIhB;;;;;;;OAOG;WACW,mBAAmB,IAAI,MAAM;IAI3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAInC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0CG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAUjC;;;;;;;;;;;;;;;OAeG;IACU,UAAU,CAAC,QAAQ,EAAE,qBAAqB,CAAC,OAAO,CAAC,GAAG,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAuE3G;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAgD1B;;;;;;;;;;;;;;;;;;OAkBG;IACU,cAAc,CAAC,EAC1B,QAAQ,EACR,IAAI,EACJ,KAAK,GACN,EAAE;QACD,QAAQ,EAAE,qBAAqB,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC;QAClD,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,MAAM,CAAC;IAoJnB;;;;;OAKG;IACU,WAAW,CAAC,MAAM,EAAE;QAC/B,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,qBAAqB,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC;QAClD,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,MAAM,CAAC;IAgEnB;;;;;;OAMG;IACU,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAkBzF;;;;;;;;;;OAUG;IACU,kBAAkB,CAAC,MAAM,EAAE;QACtC,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,qBAAqB,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC;QAClD,MAAM,EAAE,MAAM,EAAE,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACtC,GAAG,OAAO,CAAC,MAAM,CAAC;IAgDnB;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAqD;IAErF,OAAc,sBAAsB,EAAE,eAAe,CA+BnD;IAEF,OAAO,CAAC,qBAAqB;IAI7B;;OAEG;IACU,sBAAsB,CAAC,MAAM,EAAE;QAC1C,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,qBAAqB,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC;QAClD,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;KACnB,GAAG,OAAO,CAAC,OAAO,CAAC;IAoDpB;;;;;;OAMG;IACU,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAmBxG;;OAEG;IACU,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAKhG;;;;;OAKG;IACU,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAkCzG;;;;;OAKG;IACU,wBAAwB,CACnC,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,EAChB,gBAAgB,CAAC,EAAE,iBAAiB,GACnC,OAAO,CAAC,iBAAiB,CAAC;IAqD7B;;OAEG;IACU,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAiBlG;;OAEG;IACU,sBAAsB,CAAC,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAM9F;;OAEG;IACU,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAezE,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;YAK3D,oBAAoB;IAiDlC,OAAO,CAAC,kBAAkB;CAS3B;AAED,OAAO,EAAE,IAAI,EAAE,CAAC"}
+{"version":3,"file":"lixa.d.ts","sourceRoot":"","sources":["../src/lixa.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -57,6 +57,12 @@ export type ProviderConfig = {
     redirectUri: string;
     /** Array of OAuth scopes to request */
     scopes: string[];
+    /**
+     * Set to true to allow non-identity (resource) scopes during primary authentication flow.
+     * By default (false), Lixa restricts primary AuthN scopes to identity scopes to maintain
+     * clean AuthN vs AuthZ separation.
+     */
+    allowNonAuthScopes?: boolean;
     /** Additional provider-specific configuration parameters */
     extraConfig?: Record<string, string>;
 } & ({
@@ -222,6 +228,28 @@ export interface LixaConfig<TProviders extends Record<string, ProviderConfig> =
      * Format: [Lixa] [timestamp] [level] [context] message
      */
     debug?: boolean;
+    /**
+     * Optional custom structured logger implementation.
+     * If provided, all Lixa logs will be routed through this logger.
+     */
+    logger?: LixaLogger;
+}
+/**
+ * Log level for Lixa structured logging.
+ * @public
+ */
+export type LogLevel = "INFO" | "WARN" | "ERROR" | "DEBUG";
+/**
+ * Log context for Lixa structured logging.
+ * @public
+ */
+export type LogContext = "Init" | "Auth" | "Token" | "Session" | "State" | "AccountLinking" | "Resource";
+/**
+ * Custom logger interface for Lixa.
+ * @public
+ */
+export interface LixaLogger {
+    log(level: LogLevel, context: LogContext, message: string, data?: Record<string, unknown>): void;
 }
 /**
  * Helper type to create a configuration with only registered providers.

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,eAAe,EAAE,eAAe,EAAE,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACtI,OAAO,EAAW,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGlD,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,CAAC;AAC1B,OAAO,EAAE,cAAc,EAAE,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,CAAC;AAC3B,OAAO,EAAE,eAAe,EAAE,CAAC;AAC3B,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IAEjB,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;IAErB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IAEpB,uCAAuC;IACvC,MAAM,EAAE,MAAM,EAAE,CAAC;IAEjB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC,GAAG,CACA;IAAE,QAAQ,CAAC,EAAE,KAAK,CAAA;CAAE,GACpB;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,CAC1B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,oBAAY,sBAAsB;IAChC,sFAAsF;IACtF,2BAA2B,gCAAgC;IAE3D,kFAAkF;IAClF,QAAQ,aAAa;CACtB;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAC1B,sBAAsB,GACtB,6BAA6B,GAC7B,UAAU,GACV,aAAa,GACb,UAAU,CAAC;AAEf;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAE1B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU,CAAC,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC;IAC5G;;;OAGG;IACH,SAAS,EAAE,UAAU,CAAC;IAEtB;;OAEG;IACH,cAAc,CAAC,EAAE,oBAAoB,CAAC;IACtC;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAE5B;;;;;;;;;;OAUG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,OAAO,aAAa,EAAE,eAAe,CAAC;IAExD;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,CAAC,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,IAAI,UAAU,CAAC,UAAU,CAAC,GAAG;IACvG,SAAS,EAAE,UAAU,CAAC;CACvB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/utils/cookies.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Sensible default cookie configuration options.
+ * Follows RFC 6265bis and OAuth 2.0 security best practices.
+ *
+ * @public
+ */
+export 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 interface CookiePayload {
+    name: string;
+    value: string;
+    options: CookieOptions;
+    /**
+     * Formatted `Set-Cookie` header value string.
+     */
+    header: string;
+}
+/**
+ * Default session cookie name.
+ * @public
+ */
+export declare const DEFAULT_SESSION_COOKIE_NAME = "lixa_session";
+/**
+ * Default OAuth state cookie name.
+ * @public
+ */
+export declare const DEFAULT_STATE_COOKIE_NAME = "lixa_oauth_state";
+/**
+ * Default session max age in seconds (24 hours).
+ * @public
+ */
+export declare const DEFAULT_SESSION_MAX_AGE_SECONDS: number;
+/**
+ * Default OAuth state max age in seconds (5 minutes / 300 seconds).
+ * @public
+ */
+export declare const DEFAULT_STATE_MAX_AGE_SECONDS: number;
+/**
+ * Checks if the runtime environment is production.
+ * @public
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export declare function clearStateCookie(options?: CookieOptions): CookiePayload;
+//# sourceMappingURL=cookies.d.ts.map

package/dist/utils/cookies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookies.d.ts","sourceRoot":"","sources":["../../src/utils/cookies.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE1B;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE1B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE5B;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAE/B;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAE7B;;;OAGG;IACH,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;IAEjD;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,aAAa,CAAC;IACvB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,eAAO,MAAM,2BAA2B,iBAAiB,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,yBAAyB,qBAAqB,CAAC;AAE5D;;;GAGG;AACH,eAAO,MAAM,+BAA+B,QAAe,CAAC;AAE5D;;;GAGG;AACH,eAAO,MAAM,6BAA6B,QAAS,CAAC;AAEpD;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAEjD;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAsC5F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,aAAa,CAqB7F;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,aAAa,CAqBzE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,aAAa,CAqBvF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,aAAa,CAqBvE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vunexa/lixa",
-  "version": "0.1.6-alpha.7",
+  "version": "0.1.6-alpha.9",
   "description": "Lixa is a flexible, provider-agnostic OAuth and OpenID Connect (OIDC) client library that simplifies multi-provider authentication flows. It supports seamless integration with providers like Google and GitHub, offers extensible session management, and enables dynamic provider resolution based on callback URLs.",
   "keywords": [
     "oauth",