next-token-auth 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,283 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+
+type ExpiryInput = number | string;
+type ExpiryStrategy = "backend" | "config" | "hybrid";
+interface AuthTokens {
+    accessToken: string;
+    refreshToken: string;
+    /** Unix timestamp (ms) */
+    accessTokenExpiresAt: number;
+    /** Unix timestamp (ms) */
+    refreshTokenExpiresAt?: number;
+}
+interface AuthSession<User = unknown> {
+    user: User | null;
+    tokens: AuthTokens | null;
+    isAuthenticated: boolean;
+}
+interface LoginInput {
+    [key: string]: unknown;
+}
+interface LoginResponse<User = unknown> {
+    user: User;
+    accessToken: string;
+    refreshToken: string;
+    /** Seconds until access token expires (legacy field) */
+    expiresIn?: number;
+    accessTokenExpiresIn?: number | string;
+    refreshTokenExpiresIn?: number | string;
+}
+interface AuthConfig<User = unknown> {
+    /** Base URL of your backend API */
+    baseUrl: string;
+    endpoints: {
+        login: string;
+        register?: string;
+        refresh: string;
+        logout?: string;
+        /** Endpoint to fetch the current user profile */
+        me?: string;
+    };
+    routes?: {
+        /** Paths that are always accessible without auth */
+        public: string[];
+        /** Paths that require authentication */
+        protected: string[];
+    };
+    token: {
+        storage: "cookie" | "memory";
+        cookieName?: string;
+        secure?: boolean;
+        sameSite?: "strict" | "lax" | "none";
+    };
+    /** Secret used for encrypting stored tokens */
+    secret: string;
+    /** Automatically refresh access token before expiry */
+    autoRefresh?: boolean;
+    /**
+     * Seconds before expiry to trigger a proactive refresh.
+     * @default 60
+     */
+    refreshThreshold?: number;
+    expiry?: {
+        accessTokenExpiresIn?: ExpiryInput;
+        refreshTokenExpiresIn?: ExpiryInput;
+        /**
+         * - "backend"  → trust expiresIn from API response
+         * - "config"   → use config values only
+         * - "hybrid"   → backend first, fallback to config
+         * @default "hybrid"
+         */
+        strategy?: ExpiryStrategy;
+    };
+    /** Optional custom fetch implementation */
+    fetchFn?: typeof fetch;
+    /** Called after a successful login */
+    onLogin?: (session: AuthSession<User>) => void;
+    /** Called after logout */
+    onLogout?: () => void;
+    /** Called when token refresh fails */
+    onRefreshError?: (error: unknown) => void;
+}
+
+/**
+ * Manages storage, retrieval, and expiry checks for auth tokens.
+ * Supports "cookie" and "memory" storage strategies.
+ */
+declare class TokenManager {
+    private memoryStore;
+    private readonly config;
+    constructor(config: AuthConfig);
+    getTokens(): AuthTokens | null;
+    setTokens(tokens: AuthTokens): Promise<void>;
+    clearTokens(): void;
+    isAccessExpired(tokens: AuthTokens): boolean;
+    isRefreshExpired(tokens: AuthTokens): boolean;
+    private cookieName;
+    private readFromCookie;
+    private writeToCookie;
+    private deleteCookie;
+    /**
+     * Encrypts tokens for secure server-side cookie storage.
+     */
+    encryptTokens(tokens: AuthTokens): Promise<string>;
+    /**
+     * Decrypts tokens from a server-side cookie value.
+     */
+    decryptTokens(ciphertext: string): Promise<AuthTokens | null>;
+}
+
+type RefreshFn = () => Promise<boolean>;
+/**
+ * Authenticated HTTP client that:
+ * - Injects Authorization: Bearer <accessToken>
+ * - Auto-refreshes on 401 and retries the original request once
+ */
+declare class HttpClient {
+    private readonly config;
+    private readonly tokenManager;
+    private refreshFn;
+    private refreshPromise;
+    constructor(config: AuthConfig, tokenManager: TokenManager);
+    /** Register the refresh callback (set by AuthClient to avoid circular deps) */
+    setRefreshFn(fn: RefreshFn): void;
+    /**
+     * Authenticated fetch wrapper.
+     * Automatically injects the Bearer token and handles 401 → refresh → retry.
+     */
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    /**
+     * Raw fetch using the configured fetchFn or global fetch.
+     */
+    doFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    /**
+     * Builds a full URL from a path relative to baseUrl.
+     */
+    url(path: string): string;
+    /**
+     * Ensures only one refresh request is in-flight at a time.
+     */
+    private deduplicatedRefresh;
+}
+
+/**
+ * Derives and caches the current AuthSession from stored tokens.
+ * Fetches the user profile from the /me endpoint when available.
+ */
+declare class SessionManager<User = unknown> {
+    private session;
+    private readonly config;
+    private readonly tokenManager;
+    private readonly httpClient;
+    constructor(config: AuthConfig<User>, tokenManager: TokenManager, httpClient: HttpClient);
+    getSession(): AuthSession<User>;
+    setSession(session: AuthSession<User>): void;
+    /**
+     * Builds a session from stored tokens, optionally fetching the user profile.
+     */
+    loadSession(): Promise<AuthSession<User>>;
+    /**
+     * Updates the session after a successful token refresh.
+     */
+    refreshSession(tokens: AuthTokens): Promise<void>;
+    clearSession(): void;
+    private fetchUser;
+}
+
+/**
+ * Central orchestrator for authentication operations.
+ * Coordinates TokenManager, SessionManager, and HttpClient.
+ */
+declare class AuthClient<User = unknown> {
+    readonly tokenManager: TokenManager;
+    readonly sessionManager: SessionManager<User>;
+    readonly httpClient: HttpClient;
+    private readonly config;
+    private sessionListeners;
+    constructor(config: AuthConfig<User>);
+    /**
+     * Authenticates the user and stores tokens.
+     */
+    login(input: LoginInput): Promise<AuthSession<User>>;
+    /**
+     * Logs out the user, clears tokens, and optionally calls the backend.
+     */
+    logout(): Promise<void>;
+    /**
+     * Refreshes the access token using the stored refresh token.
+     * Returns true on success, false on failure.
+     */
+    refresh(): Promise<boolean>;
+    /**
+     * Loads the session from stored tokens (call on app mount).
+     */
+    initialize(): Promise<AuthSession<User>>;
+    getSession(): AuthSession<User>;
+    /**
+     * Returns the authenticated fetch wrapper.
+     */
+    get fetch(): HttpClient["fetch"];
+    subscribe(listener: (session: AuthSession<User>) => void): () => void;
+    private buildTokens;
+    private notifyListeners;
+}
+
+interface AuthProviderProps<User = unknown> {
+    config: AuthConfig<User>;
+    children: React.ReactNode;
+}
+declare function AuthProvider<User = unknown>({ config, children, }: AuthProviderProps<User>): react_jsx_runtime.JSX.Element;
+
+interface UseAuthReturn<User = unknown> {
+    session: AuthSession<User>;
+    login: (input: LoginInput) => Promise<void>;
+    logout: () => Promise<void>;
+    refresh: () => Promise<void>;
+    isLoading: boolean;
+}
+/**
+ * Primary hook for authentication operations.
+ *
+ * @example
+ * const { session, login, logout, isLoading } = useAuth();
+ */
+declare function useAuth<User = unknown>(): UseAuthReturn<User>;
+
+/**
+ * Returns the current auth session without exposing login/logout actions.
+ *
+ * @example
+ * const { user, isAuthenticated } = useSession();
+ */
+declare function useSession<User = unknown>(): AuthSession<User>;
+
+interface UseRequireAuthOptions {
+    /** Path to redirect unauthenticated users to. @default "/login" */
+    redirectTo?: string;
+    /** Called when the user is not authenticated (use for custom redirect logic) */
+    onUnauthenticated?: () => void;
+}
+/**
+ * Redirects unauthenticated users to the login page.
+ * Works with both Next.js App Router and Pages Router.
+ *
+ * @example
+ * // App Router (client component)
+ * useRequireAuth({ redirectTo: "/login" });
+ *
+ * @example
+ * // Custom handler
+ * useRequireAuth({ onUnauthenticated: () => router.push("/login") });
+ */
+declare function useRequireAuth(options?: UseRequireAuthOptions): void;
+
+/**
+ * Parses an expiry value into seconds.
+ * Accepts:
+ *   - number  → treated as seconds
+ *   - string  → e.g. "15m", "2h", "2d", "7d", "1w"
+ *
+ * @throws if the format is unrecognised
+ */
+declare function parseExpiry(input?: ExpiryInput): number;
+/**
+ * Safely parses an expiry value, returning a fallback on failure.
+ */
+declare function safeParseExpiry(input?: ExpiryInput, fallbackSeconds?: number): number;
+
+/**
+ * Lightweight symmetric encryption using AES-GCM via the Web Crypto API.
+ * Works in both browser and Node.js (>=18) / Edge runtimes.
+ */
+/**
+ * Encrypts a plaintext string using AES-GCM.
+ * Returns a base64url-encoded string: `<iv>.<ciphertext>`
+ */
+declare function encrypt(data: string, secret: string): Promise<string>;
+/**
+ * Decrypts a string produced by `encrypt`.
+ */
+declare function decrypt(data: string, secret: string): Promise<string>;
+
+export { AuthClient, type AuthConfig, AuthProvider, type AuthSession, type AuthTokens, type ExpiryInput, type ExpiryStrategy, HttpClient, type LoginInput, type LoginResponse, SessionManager, TokenManager, type UseAuthReturn, type UseRequireAuthOptions, decrypt, encrypt, parseExpiry, safeParseExpiry, useAuth, useRequireAuth, useSession };

package/dist/index.d.ts

@@ -0,0 +1,283 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+
+type ExpiryInput = number | string;
+type ExpiryStrategy = "backend" | "config" | "hybrid";
+interface AuthTokens {
+    accessToken: string;
+    refreshToken: string;
+    /** Unix timestamp (ms) */
+    accessTokenExpiresAt: number;
+    /** Unix timestamp (ms) */
+    refreshTokenExpiresAt?: number;
+}
+interface AuthSession<User = unknown> {
+    user: User | null;
+    tokens: AuthTokens | null;
+    isAuthenticated: boolean;
+}
+interface LoginInput {
+    [key: string]: unknown;
+}
+interface LoginResponse<User = unknown> {
+    user: User;
+    accessToken: string;
+    refreshToken: string;
+    /** Seconds until access token expires (legacy field) */
+    expiresIn?: number;
+    accessTokenExpiresIn?: number | string;
+    refreshTokenExpiresIn?: number | string;
+}
+interface AuthConfig<User = unknown> {
+    /** Base URL of your backend API */
+    baseUrl: string;
+    endpoints: {
+        login: string;
+        register?: string;
+        refresh: string;
+        logout?: string;
+        /** Endpoint to fetch the current user profile */
+        me?: string;
+    };
+    routes?: {
+        /** Paths that are always accessible without auth */
+        public: string[];
+        /** Paths that require authentication */
+        protected: string[];
+    };
+    token: {
+        storage: "cookie" | "memory";
+        cookieName?: string;
+        secure?: boolean;
+        sameSite?: "strict" | "lax" | "none";
+    };
+    /** Secret used for encrypting stored tokens */
+    secret: string;
+    /** Automatically refresh access token before expiry */
+    autoRefresh?: boolean;
+    /**
+     * Seconds before expiry to trigger a proactive refresh.
+     * @default 60
+     */
+    refreshThreshold?: number;
+    expiry?: {
+        accessTokenExpiresIn?: ExpiryInput;
+        refreshTokenExpiresIn?: ExpiryInput;
+        /**
+         * - "backend"  → trust expiresIn from API response
+         * - "config"   → use config values only
+         * - "hybrid"   → backend first, fallback to config
+         * @default "hybrid"
+         */
+        strategy?: ExpiryStrategy;
+    };
+    /** Optional custom fetch implementation */
+    fetchFn?: typeof fetch;
+    /** Called after a successful login */
+    onLogin?: (session: AuthSession<User>) => void;
+    /** Called after logout */
+    onLogout?: () => void;
+    /** Called when token refresh fails */
+    onRefreshError?: (error: unknown) => void;
+}
+
+/**
+ * Manages storage, retrieval, and expiry checks for auth tokens.
+ * Supports "cookie" and "memory" storage strategies.
+ */
+declare class TokenManager {
+    private memoryStore;
+    private readonly config;
+    constructor(config: AuthConfig);
+    getTokens(): AuthTokens | null;
+    setTokens(tokens: AuthTokens): Promise<void>;
+    clearTokens(): void;
+    isAccessExpired(tokens: AuthTokens): boolean;
+    isRefreshExpired(tokens: AuthTokens): boolean;
+    private cookieName;
+    private readFromCookie;
+    private writeToCookie;
+    private deleteCookie;
+    /**
+     * Encrypts tokens for secure server-side cookie storage.
+     */
+    encryptTokens(tokens: AuthTokens): Promise<string>;
+    /**
+     * Decrypts tokens from a server-side cookie value.
+     */
+    decryptTokens(ciphertext: string): Promise<AuthTokens | null>;
+}
+
+type RefreshFn = () => Promise<boolean>;
+/**
+ * Authenticated HTTP client that:
+ * - Injects Authorization: Bearer <accessToken>
+ * - Auto-refreshes on 401 and retries the original request once
+ */
+declare class HttpClient {
+    private readonly config;
+    private readonly tokenManager;
+    private refreshFn;
+    private refreshPromise;
+    constructor(config: AuthConfig, tokenManager: TokenManager);
+    /** Register the refresh callback (set by AuthClient to avoid circular deps) */
+    setRefreshFn(fn: RefreshFn): void;
+    /**
+     * Authenticated fetch wrapper.
+     * Automatically injects the Bearer token and handles 401 → refresh → retry.
+     */
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    /**
+     * Raw fetch using the configured fetchFn or global fetch.
+     */
+    doFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    /**
+     * Builds a full URL from a path relative to baseUrl.
+     */
+    url(path: string): string;
+    /**
+     * Ensures only one refresh request is in-flight at a time.
+     */
+    private deduplicatedRefresh;
+}
+
+/**
+ * Derives and caches the current AuthSession from stored tokens.
+ * Fetches the user profile from the /me endpoint when available.
+ */
+declare class SessionManager<User = unknown> {
+    private session;
+    private readonly config;
+    private readonly tokenManager;
+    private readonly httpClient;
+    constructor(config: AuthConfig<User>, tokenManager: TokenManager, httpClient: HttpClient);
+    getSession(): AuthSession<User>;
+    setSession(session: AuthSession<User>): void;
+    /**
+     * Builds a session from stored tokens, optionally fetching the user profile.
+     */
+    loadSession(): Promise<AuthSession<User>>;
+    /**
+     * Updates the session after a successful token refresh.
+     */
+    refreshSession(tokens: AuthTokens): Promise<void>;
+    clearSession(): void;
+    private fetchUser;
+}
+
+/**
+ * Central orchestrator for authentication operations.
+ * Coordinates TokenManager, SessionManager, and HttpClient.
+ */
+declare class AuthClient<User = unknown> {
+    readonly tokenManager: TokenManager;
+    readonly sessionManager: SessionManager<User>;
+    readonly httpClient: HttpClient;
+    private readonly config;
+    private sessionListeners;
+    constructor(config: AuthConfig<User>);
+    /**
+     * Authenticates the user and stores tokens.
+     */
+    login(input: LoginInput): Promise<AuthSession<User>>;
+    /**
+     * Logs out the user, clears tokens, and optionally calls the backend.
+     */
+    logout(): Promise<void>;
+    /**
+     * Refreshes the access token using the stored refresh token.
+     * Returns true on success, false on failure.
+     */
+    refresh(): Promise<boolean>;
+    /**
+     * Loads the session from stored tokens (call on app mount).
+     */
+    initialize(): Promise<AuthSession<User>>;
+    getSession(): AuthSession<User>;
+    /**
+     * Returns the authenticated fetch wrapper.
+     */
+    get fetch(): HttpClient["fetch"];
+    subscribe(listener: (session: AuthSession<User>) => void): () => void;
+    private buildTokens;
+    private notifyListeners;
+}
+
+interface AuthProviderProps<User = unknown> {
+    config: AuthConfig<User>;
+    children: React.ReactNode;
+}
+declare function AuthProvider<User = unknown>({ config, children, }: AuthProviderProps<User>): react_jsx_runtime.JSX.Element;
+
+interface UseAuthReturn<User = unknown> {
+    session: AuthSession<User>;
+    login: (input: LoginInput) => Promise<void>;
+    logout: () => Promise<void>;
+    refresh: () => Promise<void>;
+    isLoading: boolean;
+}
+/**
+ * Primary hook for authentication operations.
+ *
+ * @example
+ * const { session, login, logout, isLoading } = useAuth();
+ */
+declare function useAuth<User = unknown>(): UseAuthReturn<User>;
+
+/**
+ * Returns the current auth session without exposing login/logout actions.
+ *
+ * @example
+ * const { user, isAuthenticated } = useSession();
+ */
+declare function useSession<User = unknown>(): AuthSession<User>;
+
+interface UseRequireAuthOptions {
+    /** Path to redirect unauthenticated users to. @default "/login" */
+    redirectTo?: string;
+    /** Called when the user is not authenticated (use for custom redirect logic) */
+    onUnauthenticated?: () => void;
+}
+/**
+ * Redirects unauthenticated users to the login page.
+ * Works with both Next.js App Router and Pages Router.
+ *
+ * @example
+ * // App Router (client component)
+ * useRequireAuth({ redirectTo: "/login" });
+ *
+ * @example
+ * // Custom handler
+ * useRequireAuth({ onUnauthenticated: () => router.push("/login") });
+ */
+declare function useRequireAuth(options?: UseRequireAuthOptions): void;
+
+/**
+ * Parses an expiry value into seconds.
+ * Accepts:
+ *   - number  → treated as seconds
+ *   - string  → e.g. "15m", "2h", "2d", "7d", "1w"
+ *
+ * @throws if the format is unrecognised
+ */
+declare function parseExpiry(input?: ExpiryInput): number;
+/**
+ * Safely parses an expiry value, returning a fallback on failure.
+ */
+declare function safeParseExpiry(input?: ExpiryInput, fallbackSeconds?: number): number;
+
+/**
+ * Lightweight symmetric encryption using AES-GCM via the Web Crypto API.
+ * Works in both browser and Node.js (>=18) / Edge runtimes.
+ */
+/**
+ * Encrypts a plaintext string using AES-GCM.
+ * Returns a base64url-encoded string: `<iv>.<ciphertext>`
+ */
+declare function encrypt(data: string, secret: string): Promise<string>;
+/**
+ * Decrypts a string produced by `encrypt`.
+ */
+declare function decrypt(data: string, secret: string): Promise<string>;
+
+export { AuthClient, type AuthConfig, AuthProvider, type AuthSession, type AuthTokens, type ExpiryInput, type ExpiryStrategy, HttpClient, type LoginInput, type LoginResponse, SessionManager, TokenManager, type UseAuthReturn, type UseRequireAuthOptions, decrypt, encrypt, parseExpiry, safeParseExpiry, useAuth, useRequireAuth, useSession };