@stackframe/stack-shared 2.4.13 → 2.4.14

package/dist/interface/clientInterface.js

@@ -1,10 +1,11 @@
 import * as oauth from 'oauth4webapi';
 import { Result } from "../utils/results";
-import { AsyncStore } from '../utils/stores';
 import { KnownError, KnownErrors } from '../known-errors';
-import { StackAssertionError } from '../utils/errors';
+import { StackAssertionError, captureError, throwErr } from '../utils/errors';
 import { cookies } from '@stackframe/stack-sc';
 import { generateSecureRandomString } from '../utils/crypto';
+import { AccessToken, Session } from '../sessions';
+import { globalVar } from '../utils/globals';
 export const sharedProviders = [
     "shared-github",
     "shared-google",
@@ -37,18 +38,10 @@ export class StackClientInterface {
     getApiUrl() {
         return this.options.baseUrl + "/api/v1";
     }
-    async refreshAccessToken(tokenStore) {
+    async fetchNewAccessToken(refreshToken) {
         if (!('publishableClientKey' in this.options)) {
-            // TODO fix
-            throw new Error("Admin session token is currently not supported for fetching new access token");
-        }
-        const refreshToken = (await tokenStore.getOrWait()).refreshToken;
-        if (!refreshToken) {
-            tokenStore.set({
-                accessToken: null,
-                refreshToken: null,
-            });
-            return;
+            // TODO support it
+            throw new Error("Admin session token is currently not supported for fetching new access token. Did you try to log in on a StackApp initiated with the admin session?");
         }
         const as = {
             issuer: this.options.baseUrl,
@@ -60,15 +53,12 @@ export class StackClientInterface {
             client_secret: this.options.publishableClientKey,
             token_endpoint_auth_method: 'client_secret_basic',
         };
-        const rawResponse = await oauth.refreshTokenGrantRequest(as, client, refreshToken);
+        const rawResponse = await oauth.refreshTokenGrantRequest(as, client, refreshToken.token);
         const response = await this._processResponse(rawResponse);
         if (response.status === "error") {
             const error = response.error;
             if (error instanceof KnownErrors.RefreshTokenError) {
-                return tokenStore.set({
-                    accessToken: null,
-                    refreshToken: null,
-                });
+                return null;
             }
             throw error;
         }
@@ -86,17 +76,23 @@ export class StackClientInterface {
             // TODO Handle OAuth 2.0 response body error
             throw new StackAssertionError("OAuth error", { result });
         }
-        tokenStore.update(old => ({
-            accessToken: result.access_token ?? null,
-            refreshToken: result.refresh_token ?? old?.refreshToken ?? null,
-        }));
+        if (!result.access_token) {
+            throw new StackAssertionError("Access token not found in token endpoint response, this is weird!");
+        }
+        return new AccessToken(result.access_token);
     }
-    async sendClientRequest(path, requestOptions, tokenStoreOrNull, requestType = "client") {
-        const tokenStore = tokenStoreOrNull ?? new AsyncStore({
-            accessToken: null,
+    async sendClientRequest(path, requestOptions, session, requestType = "client") {
+        session ??= this.createSession({
             refreshToken: null,
         });
-        return await Result.orThrowAsync(Result.retry(() => this.sendClientRequestInner(path, requestOptions, tokenStore, requestType), 5, { exponentialDelayBase: 1000 }));
+        return await Result.orThrowAsync(Result.retry(() => this.sendClientRequestInner(path, requestOptions, session, requestType), 5, { exponentialDelayBase: 1000 }));
+    }
+    createSession(options) {
+        const session = new Session({
+            refreshAccessTokenCallback: async (refreshToken) => await this.fetchNewAccessToken(refreshToken),
+            ...options,
+        });
+        return session;
     }
     async sendClientRequestAndCatchKnownError(path, requestOptions, tokenStoreOrNull, errorsToCatch) {
         try {
@@ -111,26 +107,13 @@ export class StackClientInterface {
             throw e;
         }
     }
-    async sendClientRequestInner(path, options, 
-    /**
-     * This object will be modified for future retries, so it should be passed by reference.
-     */
-    tokenStore, requestType) {
-        let tokenObj = await tokenStore.getOrWait();
-        if (!tokenObj.accessToken && tokenObj.refreshToken) {
-            await this.refreshAccessToken(tokenStore);
-            tokenObj = await tokenStore.getOrWait();
-        }
-        let adminTokenStore = null;
-        let adminTokenObj = null;
-        if ("projectOwnerTokens" in this.options) {
-            adminTokenStore = this.options.projectOwnerTokens;
-            adminTokenObj = await adminTokenStore.getOrWait();
-            if (!adminTokenObj.accessToken) {
-                await this.options.refreshProjectOwnerTokens();
-                adminTokenObj = await adminTokenStore.getOrWait();
-            }
-        }
+    async sendClientRequestInner(path, options, session, requestType) {
+        /**
+         * `tokenObj === null` means the session is invalid/not logged in
+         */
+        let tokenObj = await session.getPotentiallyExpiredTokens();
+        let adminSession = "projectOwnerSession" in this.options ? this.options.projectOwnerSession : null;
+        let adminTokenObj = adminSession ? await adminSession.getPotentiallyExpiredTokens() : null;
         // all requests should be dynamic to prevent Next.js caching
         cookies?.();
         const url = this.getApiUrl() + path;
@@ -145,7 +128,7 @@ export class StackClientInterface {
              * However, Cloudflare Workers don't actually support `credentials`, so we only set it
              * if Cloudflare-exclusive globals are not detected. https://github.com/cloudflare/workers-sdk/issues/2514
              */
-            ..."WebSocketPair" in globalThis ? {} : {
+            ..."WebSocketPair" in globalVar ? {} : {
                 credentials: "omit",
             },
             ...options,
@@ -154,18 +137,18 @@ export class StackClientInterface {
                 "X-Stack-Project-Id": this.projectId,
                 "X-Stack-Request-Type": requestType,
                 "X-Stack-Client-Version": this.options.clientVersion,
-                ...tokenObj.accessToken ? {
-                    "Authorization": "StackSession " + tokenObj.accessToken,
-                    "X-Stack-Access-Token": tokenObj.accessToken,
+                ...tokenObj ? {
+                    "Authorization": "StackSession " + tokenObj.accessToken.token,
+                    "X-Stack-Access-Token": tokenObj.accessToken.token,
                 } : {},
-                ...tokenObj.refreshToken ? {
-                    "X-Stack-Refresh-Token": tokenObj.refreshToken,
+                ...tokenObj?.refreshToken ? {
+                    "X-Stack-Refresh-Token": tokenObj.refreshToken.token,
                 } : {},
                 ...'publishableClientKey' in this.options ? {
                     "X-Stack-Publishable-Client-Key": this.options.publishableClientKey,
                 } : {},
                 ...adminTokenObj ? {
-                    "X-Stack-Admin-Access-Token": adminTokenObj.accessToken ?? "",
+                    "X-Stack-Admin-Access-Token": adminTokenObj.accessToken.token,
                 } : {},
                 /**
                  * Next.js until v15 would cache fetch requests by default, and forcefully disabling it was nearly impossible.
@@ -181,7 +164,7 @@ export class StackClientInterface {
             /**
              * Cloudflare Workers does not support cache, so don't pass it there
              */
-            ..."WebSocketPair" in globalThis ? {} : {
+            ..."WebSocketPair" in globalVar ? {} : {
                 cache: "no-store",
             },
         };
@@ -199,24 +182,24 @@ export class StackClientInterface {
         }
         const processedRes = await this._processResponse(rawRes);
         if (processedRes.status === "error") {
-            // If the access token is expired, reset it and retry
+            // If the access token is invalid, reset it and retry
             if (processedRes.error instanceof KnownErrors.InvalidAccessToken) {
-                tokenStore.set({
-                    accessToken: null,
-                    refreshToken: tokenObj.refreshToken,
-                });
-                return Result.error(new Error("Access token expired"));
+                if (!tokenObj) {
+                    throw new StackAssertionError("Received invalid access token, but session is not logged in", { tokenObj, processedRes });
+                }
+                session.markAccessTokenExpired(tokenObj.accessToken);
+                return Result.error(processedRes.error);
             }
             // Same for the admin access token
-            // TODO HACK: Some of the backend hasn't been ported to use the new error codes, so if we have project owner tokens we need to check for ApiKeyNotFound too. Once the migration to smartRouteHandlers is complete, we can check for AdminAccessTokenExpired only.
-            if (adminTokenStore && (processedRes.error instanceof KnownErrors.AdminAccessTokenExpired || processedRes.error instanceof KnownErrors.ApiKeyNotFound)) {
-                adminTokenStore.set({
-                    accessToken: null,
-                    refreshToken: adminTokenObj.refreshToken,
-                });
-                return Result.error(new Error("Admin access token expired"));
+            // TODO HACK: Some of the backend hasn't been ported to use the new error codes, so if we have project owner tokens we need to check for ApiKeyNotFound too. Once the migration to smartRouteHandlers is complete, we can check for InvalidAdminAccessToken only.
+            if (adminSession && (processedRes.error instanceof KnownErrors.InvalidAdminAccessToken || processedRes.error instanceof KnownErrors.ApiKeyNotFound)) {
+                if (!adminTokenObj) {
+                    throw new StackAssertionError("Received invalid admin access token, but admin session is not logged in", { adminTokenObj, processedRes });
+                }
+                adminSession.markAccessTokenExpired(adminTokenObj.accessToken);
+                return Result.error(processedRes.error);
             }
-            // Known errors are client side errors, and should hence not be retried (except for access token expired above).
+            // Known errors are client side errors, so except for the ones above they should not be retried
             // Hence, throw instead of returning an error
             throw processedRes.error;
         }
@@ -246,7 +229,7 @@ export class StackClientInterface {
         if (res.headers.has("x-stack-known-error")) {
             const errorJson = await res.json();
             if (res.headers.get("x-stack-known-error") !== errorJson.code) {
-                throw new Error("Mismatch between x-stack-known-error header and error code in body; the server's response is invalid");
+                throw new StackAssertionError("Mismatch between x-stack-known-error header and error code in body; the server's response is invalid");
             }
             const error = KnownError.fromJson(errorJson);
             return Result.error(error);
@@ -268,7 +251,7 @@ export class StackClientInterface {
             return res.error;
         }
     }
-    async sendVerificationEmail(emailVerificationRedirectUrl, tokenStore) {
+    async sendVerificationEmail(emailVerificationRedirectUrl, session) {
         const res = await this.sendClientRequestAndCatchKnownError("/auth/send-verification-email", {
             method: "POST",
             headers: {
@@ -277,7 +260,7 @@ export class StackClientInterface {
             body: JSON.stringify({
                 emailVerificationRedirectUrl,
             }),
-        }, tokenStore, [KnownErrors.EmailAlreadyVerified]);
+        }, session, [KnownErrors.EmailAlreadyVerified]);
         if (res.status === "error") {
             return res.error;
         }
@@ -309,14 +292,14 @@ export class StackClientInterface {
             return res.error;
         }
     }
-    async updatePassword(options, tokenStore) {
+    async updatePassword(options, session) {
         const res = await this.sendClientRequestAndCatchKnownError("/auth/update-password", {
             method: "POST",
             headers: {
                 "Content-Type": "application/json"
             },
             body: JSON.stringify(options),
-        }, tokenStore, [KnownErrors.PasswordMismatch, KnownErrors.PasswordRequirementsNotMet]);
+        }, session, [KnownErrors.PasswordMismatch, KnownErrors.PasswordRequirementsNotMet]);
         if (res.status === "error") {
             return res.error;
         }
@@ -342,7 +325,7 @@ export class StackClientInterface {
             return res.error;
         }
     }
-    async signInWithCredential(email, password, tokenStore) {
+    async signInWithCredential(email, password, session) {
         const res = await this.sendClientRequestAndCatchKnownError("/auth/signin", {
             method: "POST",
             headers: {
@@ -352,17 +335,17 @@ export class StackClientInterface {
                 email,
                 password,
             }),
-        }, tokenStore, [KnownErrors.EmailPasswordMismatch]);
+        }, session, [KnownErrors.EmailPasswordMismatch]);
         if (res.status === "error") {
             return res.error;
         }
         const result = await res.data.json();
-        tokenStore.set({
+        return {
             accessToken: result.accessToken,
             refreshToken: result.refreshToken,
-        });
+        };
     }
-    async signUpWithCredential(email, password, emailVerificationRedirectUrl, tokenStore) {
+    async signUpWithCredential(email, password, emailVerificationRedirectUrl, session) {
         const res = await this.sendClientRequestAndCatchKnownError("/auth/signup", {
             headers: {
                 "Content-Type": "application/json"
@@ -373,17 +356,17 @@ export class StackClientInterface {
                 password,
                 emailVerificationRedirectUrl,
             }),
-        }, tokenStore, [KnownErrors.UserEmailAlreadyExists, KnownErrors.PasswordRequirementsNotMet]);
+        }, session, [KnownErrors.UserEmailAlreadyExists, KnownErrors.PasswordRequirementsNotMet]);
         if (res.status === "error") {
             return res.error;
         }
         const result = await res.data.json();
-        tokenStore.set({
+        return {
             accessToken: result.accessToken,
             refreshToken: result.refreshToken,
-        });
+        };
     }
-    async signInWithMagicLink(code, tokenStore) {
+    async signInWithMagicLink(code, session) {
         const res = await this.sendClientRequestAndCatchKnownError("/auth/magic-link-verification", {
             method: "POST",
             headers: {
@@ -397,11 +380,11 @@ export class StackClientInterface {
             return res.error;
         }
         const result = await res.data.json();
-        tokenStore.set({
+        return {
             accessToken: result.accessToken,
             refreshToken: result.refreshToken,
-        });
-        return { newUser: result.newUser };
+            newUser: result.newUser,
+        };
     }
     async getOAuthUrl(provider, redirectUrl, codeChallenge, state) {
         const updatedRedirectUrl = new URL(redirectUrl);
@@ -427,7 +410,7 @@ export class StackClientInterface {
         url.searchParams.set("response_type", "code");
         return url.toString();
     }
-    async callOAuthCallback(oauthParams, redirectUri, codeVerifier, state, tokenStore) {
+    async callOAuthCallback(oauthParams, redirectUri, codeVerifier, state) {
         if (!('publishableClientKey' in this.options)) {
             // TODO fix
             throw new Error("Admin session token is currently not supported for OAuth");
@@ -444,41 +427,46 @@ export class StackClientInterface {
         };
         const params = oauth.validateAuthResponse(as, client, oauthParams, state);
         if (oauth.isOAuth2Error(params)) {
-            throw new StackAssertionError("Error validating OAuth response", { params }); // Handle OAuth 2.0 redirect error
+            throw new StackAssertionError("Error validating outer OAuth response", { params }); // Handle OAuth 2.0 redirect error
         }
         const response = await oauth.authorizationCodeGrantRequest(as, client, params, redirectUri, codeVerifier);
         let challenges;
         if ((challenges = oauth.parseWwwAuthenticateChallenges(response))) {
             // TODO Handle WWW-Authenticate Challenges as needed
-            throw new StackAssertionError("OAuth WWW-Authenticate challenge not implemented", { challenges });
+            throw new StackAssertionError("Outer OAuth WWW-Authenticate challenge not implemented", { challenges });
         }
         const result = await oauth.processAuthorizationCodeOAuth2Response(as, client, response);
         if (oauth.isOAuth2Error(result)) {
             // TODO Handle OAuth 2.0 response body error
-            throw new StackAssertionError("OAuth error", { result });
+            throw new StackAssertionError("Outer OAuth error during authorization code response", { result });
         }
-        tokenStore.update(old => ({
-            accessToken: result.access_token ?? null,
-            refreshToken: result.refresh_token ?? old?.refreshToken ?? null,
-        }));
-        return result;
+        return {
+            newUser: result.newUser,
+            accessToken: result.access_token,
+            refreshToken: result.refresh_token ?? throwErr("Refresh token not found in outer OAuth response"),
+        };
     }
-    async signOut(tokenStore) {
-        const tokenObj = await tokenStore.getOrWait();
-        const res = await this.sendClientRequest("/auth/signout", {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json"
-            },
-            body: JSON.stringify({
-                refreshToken: tokenObj.refreshToken ?? "",
-            }),
-        }, tokenStore);
-        await res.json();
-        tokenStore.set({
-            accessToken: null,
-            refreshToken: null,
-        });
+    async signOut(session) {
+        const tokenObj = await session.getPotentiallyExpiredTokens();
+        if (tokenObj) {
+            if (!tokenObj.refreshToken) {
+                // TODO implement this
+                captureError("clientInterface.signOut()", new StackAssertionError("Signing out a user without access to the refresh token does not invalidate the session on the server. Please open an issue in the Stack repository if you see this error"));
+            }
+            else {
+                const res = await this.sendClientRequest("/auth/signout", {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json"
+                    },
+                    body: JSON.stringify({
+                        refreshToken: tokenObj.refreshToken.token,
+                    }),
+                }, session);
+                await res.json();
+            }
+        }
+        session.invalidate();
     }
     async getClientUserByToken(tokenStore) {
         const response = await this.sendClientRequest("/current-user", {}, tokenStore);
@@ -487,13 +475,13 @@ export class StackClientInterface {
             return Result.error(new Error("Failed to get user"));
         return Result.ok(user);
     }
-    async listClientUserTeamPermissions(options, tokenStore) {
-        const response = await this.sendClientRequest(`/current-user/teams/${options.teamId}/permissions?type=${options.type}&direct=${options.direct}`, {}, tokenStore);
+    async listClientUserTeamPermissions(options, session) {
+        const response = await this.sendClientRequest(`/current-user/teams/${options.teamId}/permissions?type=${options.type}&direct=${options.direct}`, {}, session);
         const permissions = await response.json();
         return permissions;
     }
-    async listClientUserTeams(tokenStore) {
-        const response = await this.sendClientRequest("/current-user/teams", {}, tokenStore);
+    async listClientUserTeams(session) {
+        const response = await this.sendClientRequest("/current-user/teams", {}, session);
         const teams = await response.json();
         return teams;
     }
@@ -504,31 +492,31 @@ export class StackClientInterface {
             return Result.error(new Error("Failed to get project"));
         return Result.ok(project);
     }
-    async setClientUserCustomizableData(update, tokenStore) {
+    async setClientUserCustomizableData(update, session) {
         await this.sendClientRequest("/current-user", {
             method: "PUT",
             headers: {
                 "content-type": "application/json",
             },
             body: JSON.stringify(update),
-        }, tokenStore);
+        }, session);
     }
-    async listProjects(tokenStore) {
-        const response = await this.sendClientRequest("/projects", {}, tokenStore);
+    async listProjects(session) {
+        const response = await this.sendClientRequest("/projects", {}, session);
         if (!response.ok) {
             throw new Error("Failed to list projects: " + response.status + " " + (await response.text()));
         }
         const json = await response.json();
         return json;
     }
-    async createProject(project, tokenStore) {
+    async createProject(project, session) {
         const fetchResponse = await this.sendClientRequest("/projects", {
             method: "POST",
             headers: {
                 "content-type": "application/json",
             },
             body: JSON.stringify(project),
-        }, tokenStore);
+        }, session);
         if (!fetchResponse.ok) {
             throw new Error("Failed to create project: " + fetchResponse.status + " " + (await fetchResponse.text()));
         }

package/dist/interface/serverInterface.d.ts

@@ -1,7 +1,8 @@
-import { ClientInterfaceOptions, UserJson, TokenStore, StackClientInterface, ReadonlyTokenStore, OrglikeJson, UserUpdateJson, PermissionDefinitionJson, PermissionDefinitionScopeJson as PermissionDefinitionScopeJson, TeamMemberJson } from "./clientInterface";
+import { ClientInterfaceOptions, UserJson, StackClientInterface, OrglikeJson, UserUpdateJson, PermissionDefinitionJson, PermissionDefinitionScopeJson as PermissionDefinitionScopeJson, TeamMemberJson } from "./clientInterface";
 import { Result } from "../utils/results";
 import { ReadonlyJson } from "../utils/json";
 import { EmailTemplateCrud, ListEmailTemplatesCrud } from "./crud/email-templates";
+import { Session } from "../sessions";
 export type ServerUserJson = UserJson & {
     serverMetadata: ReadonlyJson;
 };
@@ -28,27 +29,27 @@ export type ServerPermissionDefinitionJson = PermissionDefinitionJson & ServerPe
 export type ServerAuthApplicationOptions = (ClientInterfaceOptions & ({
     readonly secretServerKey: string;
 } | {
-    readonly projectOwnerTokens: ReadonlyTokenStore;
+    readonly projectOwnerSession: Session;
 }));
 export declare const emailTemplateTypes: readonly ["EMAIL_VERIFICATION", "PASSWORD_RESET", "MAGIC_LINK"];
 export type EmailTemplateType = typeof emailTemplateTypes[number];
 export declare class StackServerInterface extends StackClientInterface {
     options: ServerAuthApplicationOptions;
     constructor(options: ServerAuthApplicationOptions);
-    protected sendServerRequest(path: string, options: RequestInit, tokenStore: TokenStore | null, requestType?: "server" | "admin"): Promise<Response & {
-        usedTokens: Readonly<{
-            refreshToken: string | null;
-            accessToken: string | null;
-        }>;
+    protected sendServerRequest(path: string, options: RequestInit, session: Session | null, requestType?: "server" | "admin"): Promise<Response & {
+        usedTokens: {
+            accessToken: import("../sessions").AccessToken;
+            refreshToken: import("../sessions").RefreshToken | null;
+        } | null;
     }>;
-    getServerUserByToken(tokenStore: TokenStore): Promise<Result<ServerUserJson>>;
+    getServerUserByToken(session: Session): Promise<Result<ServerUserJson>>;
     getServerUserById(userId: string): Promise<Result<ServerUserJson>>;
     listServerUserTeamPermissions(options: {
         teamId: string;
         type: 'global' | 'team';
         direct: boolean;
-    }, tokenStore: TokenStore): Promise<ServerPermissionDefinitionJson[]>;
-    listServerUserTeams(tokenStore: TokenStore): Promise<ServerTeamJson[]>;
+    }, session: Session): Promise<ServerPermissionDefinitionJson[]>;
+    listServerUserTeams(session: Session): Promise<ServerTeamJson[]>;
     listPermissionDefinitions(): Promise<ServerPermissionDefinitionJson[]>;
     createPermissionDefinition(data: ServerPermissionDefinitionCustomizableJson): Promise<ServerPermissionDefinitionJson>;
     updatePermissionDefinition(permissionId: string, data: Partial<ServerPermissionDefinitionCustomizableJson>): Promise<void>;

package/dist/interface/serverInterface.js

@@ -7,17 +7,17 @@ export class StackServerInterface extends StackClientInterface {
         super(options);
         this.options = options;
     }
-    async sendServerRequest(path, options, tokenStore, requestType = "server") {
+    async sendServerRequest(path, options, session, requestType = "server") {
         return await this.sendClientRequest(path, {
             ...options,
             headers: {
                 "x-stack-secret-server-key": "secretServerKey" in this.options ? this.options.secretServerKey : "",
                 ...options.headers,
             },
-        }, tokenStore, requestType);
+        }, session, requestType);
     }
-    async getServerUserByToken(tokenStore) {
-        const response = await this.sendServerRequest("/current-user?server=true", {}, tokenStore);
+    async getServerUserByToken(session) {
+        const response = await this.sendServerRequest("/current-user?server=true", {}, session);
         const user = await response.json();
         if (!user)
             return Result.error(new Error("Failed to get user"));
@@ -30,13 +30,13 @@ export class StackServerInterface extends StackClientInterface {
             return Result.error(new Error("Failed to get user"));
         return Result.ok(user);
     }
-    async listServerUserTeamPermissions(options, tokenStore) {
-        const response = await this.sendServerRequest(`/current-user/teams/${options.teamId}/permissions?type=${options.type}&direct=${options.direct}&server=true`, {}, tokenStore);
+    async listServerUserTeamPermissions(options, session) {
+        const response = await this.sendServerRequest(`/current-user/teams/${options.teamId}/permissions?type=${options.type}&direct=${options.direct}&server=true`, {}, session);
         const permissions = await response.json();
         return permissions;
     }
-    async listServerUserTeams(tokenStore) {
-        const response = await this.sendServerRequest("/current-user/teams?server=true", {}, tokenStore);
+    async listServerUserTeams(session) {
+        const response = await this.sendServerRequest("/current-user/teams?server=true", {}, session);
         const teams = await response.json();
         return teams;
     }

package/dist/sessions.d.ts

@@ -0,0 +1,75 @@
+export declare class AccessToken {
+    readonly token: string;
+    constructor(token: string);
+}
+export declare class RefreshToken {
+    readonly token: string;
+    constructor(token: string);
+}
+/**
+ * A session represents a user's session, which may or may not be valid. It may contain an access token, a refresh token, or both.
+ *
+ * A session never changes which user or session it belongs to, but the tokens may change over time.
+ */
+export declare class Session {
+    private readonly _options;
+    /**
+    * Each session has a session key that depends on the tokens inside. If the session has a refresh token, the session key depends only on the refresh token. If the session does not have a refresh token, the session key depends only on the access token.
+    *
+    * Multiple Session objects may have the same session key, which implies that they represent the same session by the same user. Furthermore, a session's key never changes over the lifetime of a session object.
+    *
+    * This makes session keys useful for caching and indexing sessions.
+    */
+    readonly sessionKey: string;
+    /**
+     * An access token that is not known to be invalid (ie. may be valid, but may have expired).
+     */
+    private _accessToken;
+    private readonly _refreshToken;
+    /**
+     * Whether the session as a whole is known to be invalid. Used as a cache to avoid making multiple requests to the server (sessions never go back to being valid after being invalidated).
+     *
+     * Applies to both the access token and the refresh token (it is possible for the access token to be invalid but the refresh token to be valid, in which case the session is still valid).
+     */
+    private _knownToBeInvalid;
+    private _refreshPromise;
+    constructor(_options: {
+        refreshAccessTokenCallback(refreshToken: RefreshToken): Promise<AccessToken | null>;
+        refreshToken: string | null;
+        accessToken?: string | null;
+    });
+    static calculateSessionKey(ofTokens: {
+        refreshToken: string | null;
+        accessToken?: string | null;
+    }): string;
+    invalidate(): void;
+    onInvalidate(callback: () => void): {
+        unsubscribe: () => void;
+    };
+    getPotentiallyExpiredTokens(): Promise<{
+        accessToken: AccessToken;
+        refreshToken: RefreshToken | null;
+    } | null>;
+    getNewlyFetchedTokens(): Promise<{
+        accessToken: AccessToken;
+        refreshToken: RefreshToken | null;
+    } | null>;
+    markAccessTokenExpired(accessToken: AccessToken): void;
+    /**
+     * Note that a callback invocation with `null` does not mean the session has been invalidated; the access token may just have expired. Use `onInvalidate` to detect invalidation.
+     */
+    onAccessTokenChange(callback: (newAccessToken: AccessToken | null) => void): {
+        unsubscribe: () => void;
+    };
+    /**
+     * @returns An access token (cached if possible), or null if the session either does not represent a user or the session is invalid.
+     */
+    private _getPotentiallyExpiredAccessToken;
+    /**
+     * You should prefer `getPotentiallyExpiredAccessToken` in almost all cases.
+     *
+     * @returns A newly fetched access token (never read from cache), or null if the session either does not represent a user or the session is invalid.
+     */
+    private _getNewlyFetchedAccessToken;
+    private _refreshAndSetRefreshPromise;
+}