@stackframe/stack-shared 2.7.6 → 2.7.8

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @stackframe/stack-shared
 
+## 2.7.8
+
+### Patch Changes
+
+- Various changes
+- Updated dependencies
+  - @stackframe/stack-sc@2.7.8
+
+## 2.7.7
+
+### Patch Changes
+
+- Various changes
+  - @stackframe/stack-sc@2.7.7
+
 ## 2.7.6
 
 ### Patch Changes

package/dist/interface/clientInterface.js

@@ -163,9 +163,9 @@ export class StackClientInterface {
         /**
          * `tokenObj === null` means the session is invalid/not logged in
          */
-        let tokenObj = await session.getPotentiallyExpiredTokens();
+        let tokenObj = await session.getOrFetchLikelyValidTokens(20000);
         let adminSession = "projectOwnerSession" in this.options ? this.options.projectOwnerSession : null;
-        let adminTokenObj = adminSession ? await adminSession.getPotentiallyExpiredTokens() : null;
+        let adminTokenObj = adminSession ? await adminSession.getOrFetchLikelyValidTokens(20000) : null;
         // all requests should be dynamic to prevent Next.js caching
         await cookies?.();
         const url = this.getApiUrl() + path;
@@ -638,7 +638,7 @@ export class StackClientInterface {
             url.searchParams.set("after_callback_redirect_url", options.afterCallbackRedirectUrl);
         }
         if (options.type === "link") {
-            const tokens = await options.session.getPotentiallyExpiredTokens();
+            const tokens = await options.session.getOrFetchLikelyValidTokens(20000);
             url.searchParams.set("token", tokens?.accessToken.token || "");
             if (options.providerScope) {
                 url.searchParams.set("provider_scope", options.providerScope);
@@ -682,7 +682,7 @@ export class StackClientInterface {
         };
     }
     async signOut(session) {
-        const tokenObj = await session.getPotentiallyExpiredTokens();
+        const tokenObj = await session.getOrFetchLikelyValidTokens(20000);
         if (tokenObj) {
             const resOrError = await this.sendClientRequestAndCatchKnownError("/auth/sessions/current", {
                 method: "DELETE",

package/dist/sessions.d.ts

@@ -1,6 +1,12 @@
 export declare class AccessToken {
     readonly token: string;
     constructor(token: string);
+    get expiresAt(): Date;
+    /**
+     * @returns The number of milliseconds until the access token expires, or 0 if it has already expired.
+     */
+    get expiresInMillis(): number;
+    isExpired(): boolean;
 }
 export declare class RefreshToken {
     readonly token: string;
@@ -56,20 +62,20 @@ export declare class InternalSession {
     /**
      * Returns the access token if it is found in the cache, fetching it otherwise.
      *
-     * This is usually the function you want to call to get an access token. When using the access token, you should catch errors that occur if it expires, and call `markAccessTokenExpired` to mark the token as expired if so (after which a call to this function will always refetch the token).
+     * This is usually the function you want to call to get an access token. Either set `minMillisUntilExpiration` to a reasonable value, or catch errors that occur if it expires, and call `markAccessTokenExpired` to mark the token as expired if so (after which a call to this function will always refetch the token).
      *
      * @returns null if the session is known to be invalid, cached tokens if they exist in the cache (which may or may not be valid still), or new tokens otherwise.
      */
-    getPotentiallyExpiredTokens(): Promise<{
+    getOrFetchLikelyValidTokens(minMillisUntilExpiration: number): Promise<{
         accessToken: AccessToken;
         refreshToken: RefreshToken | null;
     } | null>;
     /**
      * Fetches new tokens that are, at the time of fetching, guaranteed to be valid.
      *
-     * The newly generated tokens are shortlived, so it's good practice not to rely on their validity (if possible). However, this function is useful in some cases where you only want to pass access tokens to a service, and you want to make sure said access token has the longest possible lifetime.
+     * The newly generated tokens are short-lived, so it's good practice not to rely on their validity (if possible). However, this function is useful in some cases where you only want to pass access tokens to a service, and you want to make sure said access token has the longest possible lifetime.
      *
-     * In most cases, you should prefer `getPotentiallyExpiredTokens` with a fallback to `markAccessTokenExpired` and a retry mechanism if the endpoint rejects the token.
+     * In most cases, you should prefer `getOrFetchLikelyValidTokens`.
      *
      * @returns null if the session is known to be invalid, or new tokens otherwise (which, at the time of fetching, are guaranteed to be valid).
      */
@@ -85,11 +91,11 @@ export declare class InternalSession {
         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.
+     * @returns An access token, which may be expired or expire soon, or null if it is known to be invalid.
      */
-    private _getPotentiallyExpiredAccessToken;
+    private _getPotentiallyInvalidAccessTokenIfAvailable;
     /**
-     * You should prefer `getPotentiallyExpiredAccessToken` in almost all cases.
+     * You should prefer `_getOrFetchPotentiallyInvalidAccessToken` 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.
      */

package/dist/sessions.js

@@ -1,3 +1,4 @@
+import * as jose from 'jose';
 import { StackAssertionError } from "./utils/errors";
 import { Store } from "./utils/stores";
 export class AccessToken {
@@ -7,6 +8,21 @@ export class AccessToken {
             throw new StackAssertionError("Access token is the string 'undefined'; it's unlikely this is the correct value. They're supposed to be unguessable!");
         }
     }
+    get expiresAt() {
+        const { exp } = jose.decodeJwt(this.token);
+        if (exp === undefined)
+            return new Date(8640000000000000); // max date value
+        return new Date(exp * 1000);
+    }
+    /**
+     * @returns The number of milliseconds until the access token expires, or 0 if it has already expired.
+     */
+    get expiresInMillis() {
+        return Math.max(0, this.expiresAt.getTime() - Date.now());
+    }
+    isExpired() {
+        return this.expiresInMillis <= 0;
+    }
 }
 export class RefreshToken {
     constructor(token) {
@@ -69,20 +85,31 @@ export class InternalSession {
     /**
      * Returns the access token if it is found in the cache, fetching it otherwise.
      *
-     * This is usually the function you want to call to get an access token. When using the access token, you should catch errors that occur if it expires, and call `markAccessTokenExpired` to mark the token as expired if so (after which a call to this function will always refetch the token).
+     * This is usually the function you want to call to get an access token. Either set `minMillisUntilExpiration` to a reasonable value, or catch errors that occur if it expires, and call `markAccessTokenExpired` to mark the token as expired if so (after which a call to this function will always refetch the token).
      *
      * @returns null if the session is known to be invalid, cached tokens if they exist in the cache (which may or may not be valid still), or new tokens otherwise.
      */
-    async getPotentiallyExpiredTokens() {
-        const accessToken = await this._getPotentiallyExpiredAccessToken();
-        return accessToken ? { accessToken, refreshToken: this._refreshToken } : null;
+    async getOrFetchLikelyValidTokens(minMillisUntilExpiration) {
+        if (minMillisUntilExpiration >= 60000) {
+            throw new Error(`Required access token expiry ${minMillisUntilExpiration}ms is too long; access tokens are too short to be used for more than 60s`);
+        }
+        const accessToken = this._getPotentiallyInvalidAccessTokenIfAvailable();
+        if (!accessToken || accessToken.expiresInMillis < minMillisUntilExpiration) {
+            const newTokens = await this.fetchNewTokens();
+            const expiresInMillis = newTokens?.accessToken.expiresInMillis;
+            if (expiresInMillis && expiresInMillis < minMillisUntilExpiration) {
+                throw new StackAssertionError(`Required access token expiry ${minMillisUntilExpiration}ms is too long; access tokens are too short when they're generated (${expiresInMillis}ms)`);
+            }
+            return newTokens;
+        }
+        return { accessToken, refreshToken: this._refreshToken };
     }
     /**
      * Fetches new tokens that are, at the time of fetching, guaranteed to be valid.
      *
-     * The newly generated tokens are shortlived, so it's good practice not to rely on their validity (if possible). However, this function is useful in some cases where you only want to pass access tokens to a service, and you want to make sure said access token has the longest possible lifetime.
+     * The newly generated tokens are short-lived, so it's good practice not to rely on their validity (if possible). However, this function is useful in some cases where you only want to pass access tokens to a service, and you want to make sure said access token has the longest possible lifetime.
      *
-     * In most cases, you should prefer `getPotentiallyExpiredTokens` with a fallback to `markAccessTokenExpired` and a retry mechanism if the endpoint rejects the token.
+     * In most cases, you should prefer `getOrFetchLikelyValidTokens`.
      *
      * @returns null if the session is known to be invalid, or new tokens otherwise (which, at the time of fetching, are guaranteed to be valid).
      */
@@ -91,6 +118,7 @@ export class InternalSession {
         return accessToken ? { accessToken, refreshToken: this._refreshToken } : null;
     }
     markAccessTokenExpired(accessToken) {
+        // TODO we don't need this anymore, since we now check the expiry by ourselves
         if (this._accessToken.get() === accessToken) {
             this._accessToken.set(null);
         }
@@ -102,24 +130,20 @@ export class InternalSession {
         return this._accessToken.onChange(callback);
     }
     /**
-     * @returns An access token (cached if possible), or null if the session either does not represent a user or the session is invalid.
+     * @returns An access token, which may be expired or expire soon, or null if it is known to be invalid.
      */
-    async _getPotentiallyExpiredAccessToken() {
+    _getPotentiallyInvalidAccessTokenIfAvailable() {
         if (!this._refreshToken)
             return null;
-        if (this._knownToBeInvalid.get())
+        if (this.isKnownToBeInvalid())
             return null;
-        const oldAccessToken = this._accessToken.get();
-        if (oldAccessToken)
-            return oldAccessToken;
-        // refresh access token
-        if (!this._refreshPromise) {
-            this._refreshAndSetRefreshPromise(this._refreshToken);
-        }
-        return await this._refreshPromise;
+        const accessToken = this._accessToken.get();
+        if (accessToken && !accessToken.isExpired())
+            return accessToken;
+        return null;
     }
     /**
-     * You should prefer `getPotentiallyExpiredAccessToken` in almost all cases.
+     * You should prefer `_getOrFetchPotentiallyInvalidAccessToken` 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.
      */
@@ -128,7 +152,9 @@ export class InternalSession {
             return null;
         if (this._knownToBeInvalid.get())
             return null;
-        this._refreshAndSetRefreshPromise(this._refreshToken);
+        if (!this._refreshPromise) {
+            this._refreshAndSetRefreshPromise(this._refreshToken);
+        }
         return await this._refreshPromise;
     }
     _refreshAndSetRefreshPromise(refreshToken) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackframe/stack-shared",
-  "version": "2.7.6",
+  "version": "2.7.8",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -51,7 +51,7 @@
     "oauth4webapi": "^2.10.3",
     "semver": "^7.6.3",
     "uuid": "^9.0.1",
-    "@stackframe/stack-sc": "2.7.6"
+    "@stackframe/stack-sc": "2.7.8"
   },
   "devDependencies": {
     "@sentry/nextjs": "^8.40.0",