@stackframe/stack-shared 2.7.5 → 2.7.7

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @stackframe/stack-shared
 
+## 2.7.7
+
+### Patch Changes
+
+- Various changes
+  - @stackframe/stack-sc@2.7.7
+
+## 2.7.6
+
+### Patch Changes
+
+- Fixed bugs, updated Neon requirements
+- Updated dependencies
+  - @stackframe/stack-sc@2.7.6
+
 ## 2.7.5
 
 ### 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/schema-fields.js

@@ -243,7 +243,7 @@ export const emailUsernameSchema = yupString().meta({ openapiField: { descriptio
 export const emailSenderEmailSchema = emailSchema.meta({ openapiField: { description: 'Email sender email. Needs to be specified when using type="standard"', exampleValue: 'example@your-domain.com' } });
 export const emailPasswordSchema = passwordSchema.meta({ openapiField: { description: 'Email password. Needs to be specified when using type="standard"', exampleValue: 'your-email-password' } });
 // Project domain config
-export const projectTrustedDomainSchema = yupString().test('is-https', 'Trusted domain must start with https://', (value) => value?.startsWith('https://')).meta({ openapiField: { description: 'Your domain URL. Make sure you own and trust this domain. Needs to start with https://', exampleValue: 'https://example.com' } });
+export const projectTrustedDomainSchema = urlSchema.test('is-https', 'Trusted domain must start with https://', (value) => value?.startsWith('https://')).meta({ openapiField: { description: 'Your domain URL. Make sure you own and trust this domain. Needs to start with https://', exampleValue: 'https://example.com' } });
 export const handlerPathSchema = yupString().test('is-handler-path', 'Handler path must start with /', (value) => value?.startsWith('/')).meta({ openapiField: { description: 'Handler path. If you did not setup a custom handler path, it should be "/handler" by default. It needs to start with /', exampleValue: '/handler' } });
 // Users
 export class ReplaceFieldWithOwnUserId extends Error {

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,11 +62,11 @@ 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>;
@@ -69,7 +75,7 @@ export declare class InternalSession {
      *
      * 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.
      *
-     * 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` with a fallback to `markAccessTokenExpired` and a retry mechanism if the endpoint rejects the token.
      *
      * @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).
      */
@@ -84,12 +90,16 @@ export declare class InternalSession {
     onAccessTokenChange(callback: (newAccessToken: AccessToken | null) => void): {
         unsubscribe: () => void;
     };
+    /**
+     * @returns An access token, which may be expired or expire soon, or null if it is known to be invalid.
+     */
+    private _getPotentiallyInvalidAccessTokenIfAvailable;
     /**
      * @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;
+    private _getOrFetchPotentiallyInvalidAccessToken;
     /**
-     * You should prefer `getPotentiallyExpiredAccessToken` in almost all cases.
+     * You should prefer `_getOrFetchAccessToken` 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)
+            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.
      *
-     * 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` with a fallback to `markAccessTokenExpired` and a retry mechanism if the endpoint rejects the token.
      *
      * @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);
         }
@@ -101,15 +129,24 @@ export class InternalSession {
     onAccessTokenChange(callback) {
         return this._accessToken.onChange(callback);
     }
+    /**
+     * @returns An access token, which may be expired or expire soon, or null if it is known to be invalid.
+     */
+    _getPotentiallyInvalidAccessTokenIfAvailable() {
+        const accessToken = this._accessToken.get();
+        if (accessToken && !accessToken.isExpired())
+            return accessToken;
+        return null;
+    }
     /**
      * @returns An access token (cached if possible), or null if the session either does not represent a user or the session is invalid.
      */
-    async _getPotentiallyExpiredAccessToken() {
+    async _getOrFetchPotentiallyInvalidAccessToken() {
         if (!this._refreshToken)
             return null;
-        if (this._knownToBeInvalid.get())
+        if (this.isKnownToBeInvalid())
             return null;
-        const oldAccessToken = this._accessToken.get();
+        const oldAccessToken = this._getPotentiallyInvalidAccessTokenIfAvailable();
         if (oldAccessToken)
             return oldAccessToken;
         // refresh access token
@@ -119,7 +156,7 @@ export class InternalSession {
         return await this._refreshPromise;
     }
     /**
-     * You should prefer `getPotentiallyExpiredAccessToken` in almost all cases.
+     * You should prefer `_getOrFetchAccessToken` 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackframe/stack-shared",
-  "version": "2.7.5",
+  "version": "2.7.7",
   "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.5"
+    "@stackframe/stack-sc": "2.7.7"
   },
   "devDependencies": {
     "@sentry/nextjs": "^8.40.0",