@korajs/auth 1.0.0-beta.11 → 1.0.0-beta.13

package/dist/{create-org-session-RsDj9cl4.d.ts → create-org-session-ChFdulEM.d.ts}

@@ -218,13 +218,46 @@ declare function createPersistentDeviceIdentity(options: PersistentDeviceIdentit
 declare class AuthError extends KoraError {
     constructor(message: string, code: string, context?: Record<string, unknown>);
 }
+/**
+ * Thrown by sign-in when the account requires a second factor (AUTH-10).
+ * Complete it with {@link AuthClient.verifyMfa} using {@link mfaToken}.
+ */
+declare class MfaRequiredError extends AuthError {
+    readonly mfaToken: string;
+    constructor(mfaToken: string);
+}
 /**
  * Possible authentication states for the client.
  * - 'loading': Initial state while restoring tokens from storage
- * - 'authenticated': User is signed in with a valid session
- * - 'unauthenticated': No valid session exists
+ * - 'authenticated': A session exists. It may be fresh or offline; see
+ *   {@link AuthClient.session} for the freshness of its credentials.
+ * - 'unauthenticated': No session exists (never signed in, signed out, or the
+ *   auth server definitively rejected the session)
  */
 type AuthState = 'loading' | 'authenticated' | 'unauthenticated';
+/**
+ * Freshness of an authenticated session.
+ * - 'fresh': the last refresh or profile request reached the auth server
+ * - 'offline': authenticated-offline. The identity is known from stored
+ *   credentials, but no fresh access token can be minted right now (network,
+ *   timeout, 5xx, captive portal...). Local data stays available; sync waits.
+ * - 'locked': offline for longer than `maxOfflineGraceMs`, or the device clock
+ *   moved backwards. The UI should lock; local data is never wiped.
+ */
+type AuthSessionStatus = 'fresh' | 'offline' | 'locked';
+/**
+ * The identity of the stored session, independent of token freshness.
+ */
+interface AuthClientSession {
+    /** User id (`sub` of the stored credentials). */
+    userId: string;
+    /** Device id (`dev` of the stored credentials), when known. */
+    deviceId: string | null;
+    /** Freshness of the credentials. */
+    status: AuthSessionStatus;
+    /** Last successful contact with the auth server (ms since epoch). */
+    lastServerContactAt: number;
+}
 /**
  * Authenticated user information.
  */
@@ -247,6 +280,12 @@ interface LinkedOAuthAccount {
 interface OAuthAuthorizationResult {
     url: string;
     state: string;
+    /**
+     * Client binding for this flow (AUTH-3). The client keeps it (session storage
+     * on the web, memory on native) and presents it with the callback; a callback
+     * carrying someone else's code and state is then refused.
+     */
+    binding?: string;
 }
 interface OAuthAuthorizationOptions {
     /**
@@ -268,6 +307,8 @@ interface OAuthAuthorizationOptions {
 interface OAuthCallbackParams {
     code: string;
     state: string;
+    /** Flow binding; looked up from the started flow when omitted. */
+    binding?: string;
     deviceId?: string;
     devicePublicKey?: string;
 }
@@ -299,6 +340,28 @@ interface AuthClientConfig {
      * `deviceId` and `devicePublicKey` fields unless the caller provides them.
      */
     deviceIdentity?: AuthDeviceIdentityProvider;
+    /**
+     * Timeout for every auth request, in milliseconds. A request that has not
+     * answered by then is aborted and treated as a transient failure.
+     * @default 20000
+     */
+    requestTimeoutMs?: number;
+    /**
+     * How long a session may stay authenticated-offline (no successful contact
+     * with the auth server) before it is `locked`. Locking never wipes local data
+     * or tokens; it only tells the UI to ask the user to reconnect.
+     * Defaults to no limit beyond the refresh token's own expiry.
+     */
+    maxOfflineGraceMs?: number;
+    /**
+     * Backoff between refresh attempts after transient failures. The first retry
+     * after a failure is immediate (it recovers a response lost on the wire);
+     * later ones back off exponentially with jitter, honouring `Retry-After`.
+     */
+    refreshBackoff?: {
+        baseDelayMs?: number;
+        maxDelayMs?: number;
+    };
 }
 type MaybePromise<T> = T | Promise<T>;
 interface AuthTokenStorage {
@@ -314,6 +377,15 @@ interface AuthTokenStorage {
  * token refresh, and auth state change notifications. Framework-agnostic --
  * works in any JavaScript environment with `fetch` and optionally `localStorage`.
  *
+ * Offline-first session rules (AUTH-13):
+ * - Only the auth server ends a session: tokens are cleared only on a 401 (or a
+ *   400 `invalid_grant`) carrying a Kora JSON error, on an explicit sign-out, or
+ *   when the refresh token itself has expired.
+ * - Every other failure (no network, timeout, abort, 5xx, 429, 511, HTML from a
+ *   captive portal) keeps the tokens, keeps the user signed in as
+ *   authenticated-offline and retries with jittered backoff.
+ * - One tab refreshes at a time (Web Locks); the others adopt its result.
+ *
  * @example
  * ```typescript
  * const auth = new AuthClient({ serverUrl: 'http://localhost:3001' })
@@ -334,10 +406,22 @@ declare class AuthClient {
     private readonly fetchFn;
     private readonly deviceIdentity;
     private readonly listeners;
+    private readonly sessionListeners;
+    private readonly requestTimeoutMs;
+    private readonly maxOfflineGraceMs;
+    private readonly backoffBaseMs;
+    private readonly backoffMaxMs;
+    private readonly lockName;
     private _state;
     private _user;
     private _refreshPromise;
     private _initialized;
+    private sessionStatus;
+    private lastServerContactAt;
+    private failureCount;
+    private nextAttemptAt;
+    private retryTimer;
+    private readonly detachEnvironment;
     /**
      * Creates a new AuthClient.
      *
@@ -348,13 +432,37 @@ declare class AuthClient {
     get state(): AuthState;
     /** Current authenticated user, or null if not signed in. */
     get currentUser(): AuthUser | null;
-    /** Whether the user is currently authenticated. */
+    /** Whether the user is currently authenticated (fresh or offline). */
     get isAuthenticated(): boolean;
+    /**
+     * The stored session identity and its freshness, or null when signed out.
+     * Unlike {@link getAccessToken}, this is available offline: the identity is
+     * decoupled from whether a fresh access token can be minted right now.
+     */
+    get session(): AuthClientSession | null;
+    private cachedDeviceId;
+    /**
+     * Read the stored session identity (user id and device id) from storage,
+     * without any network request. Returns null when no usable session is stored.
+     */
+    getStoredIdentity(): Promise<{
+        userId: string;
+        deviceId: string | null;
+    } | null>;
+    /**
+     * Decoded (unverified) claims of the stored credentials, preferring the access
+     * token even when it has expired. For client-side hints only (local database
+     * name, sync node id, handshake scope narrowing); the server re-derives
+     * everything it authorizes from a verified token.
+     */
+    getStoredClaims(): Promise<Record<string, unknown> | null>;
     /**
      * Initialize the auth client by restoring a session from stored tokens.
      *
      * Loads tokens from storage, validates the access token, and attempts a
      * refresh if the access token is expired but a refresh token is available.
+     * When the auth server cannot be reached, the stored session is restored as
+     * authenticated-offline instead of being discarded.
      * Safe to call multiple times -- subsequent calls are no-ops once initialized.
      */
     initialize(): Promise<void>;
@@ -385,6 +493,19 @@ declare class AuthClient {
         deviceId?: string;
         devicePublicKey?: string;
     }): Promise<AuthUser>;
+    /**
+     * Finish a sign-in that required a second factor.
+     *
+     * @param mfaToken - From the {@link MfaRequiredError} thrown by sign-in
+     * @param proof - A current TOTP code, or a recovery code
+     * @returns The authenticated AuthUser
+     * @throws {AuthError} If the code or the MFA session is invalid
+     */
+    verifyMfa(mfaToken: string, proof: {
+        code: string;
+    } | {
+        recoveryCode: string;
+    }): Promise<AuthUser>;
     /**
      * Create an OAuth authorization URL and optionally redirect the current window.
      *
@@ -400,7 +521,7 @@ declare class AuthClient {
     /**
      * Create an OAuth authorization URL for linking another provider to the current user.
      */
-    getOAuthAuthorizationUrl(provider: string, options?: OAuthAuthorizationOptions): Promise<OAuthAuthorizationResult>;
+    getOAuthAuthorizationUrl(provider: string, _options?: OAuthAuthorizationOptions): Promise<OAuthAuthorizationResult>;
     /**
      * Link an OAuth provider to the current authenticated user.
      */
@@ -424,10 +545,26 @@ declare class AuthClient {
     /**
      * Get a valid access token, automatically refreshing if expired.
      *
-     * @returns A valid access token string, or null if the user is not
-     *          authenticated and refresh is not possible
+     * Returns null when no fresh token can be obtained right now. That does NOT
+     * mean the user is signed out: check {@link state} / {@link session}. A
+     * transient failure keeps the session (authenticated-offline) and later calls
+     * retry with backoff.
+     *
+     * @returns A valid access token string, or null if none is available now
      */
     getAccessToken(): Promise<string | null>;
+    /**
+     * Refresh the session now, even when the cached access token has not expired
+     * locally. Used after the sync server ended a session with `AUTH_EXPIRED` or
+     * `AUTH_REVOKED`: the server's clock or a revocation says the cached token is
+     * no longer good. Concurrent calls (and other tabs) share one refresh.
+     *
+     * A transient failure keeps the session (authenticated-offline) and returns
+     * null; only a definitive server rejection signs the user out.
+     *
+     * @returns The refreshed access token, or null if none could be obtained now
+     */
+    refreshAccessToken(): Promise<string | null>;
     /**
      * Get a valid token for the sync engine handshake.
      * Alias for {@link getAccessToken}.
@@ -435,6 +572,15 @@ declare class AuthClient {
      * @returns A valid access token string, or null if unavailable
      */
     getSyncToken(): Promise<string | null>;
+    /**
+     * Retry immediately: clears the refresh backoff and attempts a refresh if the
+     * session is offline. Call it when connectivity is known to be back (for
+     * example when a sync transport opens). Also wired to the browser `online`
+     * and `visibilitychange` events automatically.
+     */
+    retryNow(): Promise<void>;
+    /** Remove environment listeners and timers (for tests and teardown). */
+    destroy(): void;
     /**
      * Subscribe to authentication state changes.
      *
@@ -453,39 +599,86 @@ declare class AuthClient {
      * ```
      */
     onAuthChange(callback: (state: AuthState) => void): () => void;
+    /**
+     * Subscribe to session freshness changes (fresh, authenticated-offline,
+     * locked). Fires in addition to {@link onAuthChange}, including when the
+     * state stays 'authenticated' but connectivity to the auth server changes.
+     *
+     * @param callback - Called with the current session (null when signed out)
+     * @returns An unsubscribe function
+     */
+    onSessionChange(callback: (session: AuthClientSession | null) => void): () => void;
     /**
      * Update internal state and notify all listeners.
      */
     private setState;
+    private setSessionStatus;
+    private notifySession;
+    private completeSignIn;
     /**
      * Restore a session from a valid access token by fetching the user profile.
-     * Falls back to extracting the user ID from the token payload if the
-     * /auth/me request fails (offline scenario).
+     * A definitive 401 from `/auth/me` ends the session (NEW-AUTH-4); any other
+     * failure restores it as authenticated-offline from the stored identity.
      */
     private restoreSession;
+    /**
+     * Restore the session from stored credentials while the auth server is
+     * unreachable. Signs out only when the stored refresh token is unusable.
+     */
+    private enterOfflineSession;
+    /** Offline, or locked when the grace period ran out or the clock went backwards. */
+    private offlineStatus;
+    private endSession;
+    /** The refresh token's issue time is the server's clock at the last rotation. */
+    private noteIssuedCredential;
+    private markFresh;
+    private markOffline;
     /**
      * Fetch the current user profile from the server.
      */
     private fetchUserProfile;
     private createOAuthAuthorization;
+    /** Bindings of flows this client started, by state (survives the redirect on web). */
+    private readonly oauthBindings;
+    private rememberOAuthBinding;
+    private takeOAuthBinding;
     private withDeviceIdentity;
     /**
-     * Refresh the access token using a refresh token.
-     * De-duplicates concurrent refresh calls so only one network request is made.
+     * Refresh the session's tokens. De-duplicates concurrent calls in this
+     * client, serializes refreshes across tabs, and applies backoff after
+     * transient failures.
      */
-    private refreshAccessToken;
-    private requireAccessToken;
+    private refresh;
+    private refreshOnce;
     /**
-     * Execute the token refresh network request.
+     * Execute the token refresh network request and classify the answer.
      */
     private performRefresh;
+    private withRefreshLock;
+    /**
+     * Schedule the next allowed refresh attempt. The first retry after a failure
+     * is immediate (it recovers a rotation response lost on the wire); after
+     * that, exponential backoff with equal jitter, never earlier than Retry-After.
+     */
+    private registerFailure;
+    private resetBackoff;
+    /** Background retry so an offline session recovers without the app calling in. */
+    private scheduleRetry;
+    private clearRetryTimer;
+    private attachEnvironmentListeners;
+    private requireAccessToken;
+    /**
+     * Send one request with a timeout and return status plus parsed JSON (if any).
+     * Throws only for transport failures (network, abort, timeout).
+     */
+    private rawRequest;
     /**
      * Make an HTTP request to the auth server.
      *
      * @param path - URL path relative to serverUrl (e.g. '/auth/signin')
      * @param options - Request options
      * @returns Parsed JSON response body
-     * @throws {AuthError} On network failure or non-2xx response
+     * @throws {AuthError} On network failure, timeout, or non-2xx response
      */
     private request;
 }
@@ -689,9 +882,10 @@ declare class OrgClient {
      */
     revokeInvitation(orgId: string, invitationId: string): Promise<void>;
     /**
-     * List pending invitations for the current user's email.
+     * List pending invitations addressed to the signed-in user's verified email.
+     * The server resolves the email from the session; tokens are never returned.
      */
-    listMyInvitations(email: string): Promise<ClientInvitation[]>;
+    listMyInvitations(): Promise<Array<Omit<ClientInvitation, 'token'>>>;
     /**
      * Subscribe to active org changes.
      * @returns Unsubscribe function
@@ -719,4 +913,4 @@ declare function checkOrgPermission(currentRole: string | null, requiredRole: st
  */
 declare function createOrgSession(client: OrgClient): OrgSession;
 
-export { type AuthClientConfig as A, createDeviceKeyStore as B, type ClientInvitation as C, type DeviceKeyStore as D, createMemoryAuthTokenStorage as E, createOrgSession as F, createPersistentDeviceIdentity as G, createWebStorageAuthTokenStorage as H, InMemoryDeviceKeyStore as I, type LinkedOAuthAccount as L, type OAuthAuthorizationOptions as O, type PersistentDeviceIdentityOptions as P, type AuthTokenStorage as a, type AuthKeyValueStorage as b, type AuthDeviceIdentityProvider as c, AuthClient as d, type AuthState as e, type AuthDeviceIdentity as f, AuthDeviceIdentityError as g, AuthError as h, type AuthSession as i, type AuthSessionSnapshot as j, type AuthTokenStorageOptions as k, type AuthUser as l, type ClientMembership as m, type ClientOrganization as n, DeviceKeyStoreError as o, IndexedDBDeviceKeyStore as p, type OAuthAuthorizationResult as q, type OAuthCallbackParams as r, OrgClient as s, type OrgClientConfig as t, OrgClientError as u, type OrgSession as v, type OrgSnapshot as w, checkOrgPermission as x, createAuthSession as y, createAuthTokenStorage as z };
+export { type AuthClientConfig as A, createAuthSession as B, type ClientInvitation as C, type DeviceKeyStore as D, createAuthTokenStorage as E, createDeviceKeyStore as F, createMemoryAuthTokenStorage as G, createOrgSession as H, InMemoryDeviceKeyStore as I, createPersistentDeviceIdentity as J, createWebStorageAuthTokenStorage as K, type LinkedOAuthAccount as L, MfaRequiredError as M, type OAuthAuthorizationOptions as O, type PersistentDeviceIdentityOptions as P, type AuthTokenStorage as a, type AuthKeyValueStorage as b, type AuthDeviceIdentityProvider as c, AuthClient as d, type AuthState as e, type AuthClientSession as f, type AuthDeviceIdentity as g, AuthDeviceIdentityError as h, AuthError as i, type AuthSession as j, type AuthSessionSnapshot as k, type AuthSessionStatus as l, type AuthTokenStorageOptions as m, type AuthUser as n, type ClientMembership as o, type ClientOrganization as p, DeviceKeyStoreError as q, IndexedDBDeviceKeyStore as r, type OAuthAuthorizationResult as s, type OAuthCallbackParams as t, OrgClient as u, type OrgClientConfig as v, OrgClientError as w, type OrgSession as x, type OrgSnapshot as y, checkOrgPermission as z };