@logto/client 2.3.3 → 2.5.0

package/lib/adapter/defaults.cjs

@@ -0,0 +1,28 @@
+'use strict';
+
+var js = require('@logto/js');
+var jose = require('jose');
+
+const issuedAtTimeTolerance = 300; // 5 minutes
+const verifyIdToken = async (idToken, clientId, issuer, jwks) => {
+    const result = await jose.jwtVerify(idToken, jwks, { audience: clientId, issuer });
+    if (Math.abs((result.payload.iat ?? 0) - Date.now() / 1000) > issuedAtTimeTolerance) {
+        throw new js.LogtoError('id_token.invalid_iat');
+    }
+};
+class DefaultJwtVerifier {
+    constructor(client) {
+        this.client = client;
+    }
+    async verifyIdToken(idToken) {
+        const { appId } = this.client.logtoConfig;
+        const { issuer, jwksUri } = await this.client.getOidcConfig();
+        if (!this.getJwtVerifyGetKey) {
+            this.getJwtVerifyGetKey = jose.createRemoteJWKSet(new URL(jwksUri));
+        }
+        await verifyIdToken(idToken, appId, issuer, this.getJwtVerifyGetKey);
+    }
+}
+
+exports.DefaultJwtVerifier = DefaultJwtVerifier;
+exports.verifyIdToken = verifyIdToken;

package/lib/adapter/defaults.d.ts

@@ -0,0 +1,10 @@
+import type { JWTVerifyGetKey } from 'jose';
+import { type StandardLogtoClient } from '../client.js';
+import { type JwtVerifier } from './types.js';
+export declare const verifyIdToken: (idToken: string, clientId: string, issuer: string, jwks: JWTVerifyGetKey) => Promise<void>;
+export declare class DefaultJwtVerifier implements JwtVerifier {
+    protected client: StandardLogtoClient;
+    protected getJwtVerifyGetKey?: JWTVerifyGetKey;
+    constructor(client: StandardLogtoClient);
+    verifyIdToken(idToken: string): Promise<void>;
+}

package/lib/adapter/defaults.js

@@ -0,0 +1,25 @@
+import { LogtoError } from '@logto/js';
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+
+const issuedAtTimeTolerance = 300; // 5 minutes
+const verifyIdToken = async (idToken, clientId, issuer, jwks) => {
+    const result = await jwtVerify(idToken, jwks, { audience: clientId, issuer });
+    if (Math.abs((result.payload.iat ?? 0) - Date.now() / 1000) > issuedAtTimeTolerance) {
+        throw new LogtoError('id_token.invalid_iat');
+    }
+};
+class DefaultJwtVerifier {
+    constructor(client) {
+        this.client = client;
+    }
+    async verifyIdToken(idToken) {
+        const { appId } = this.client.logtoConfig;
+        const { issuer, jwksUri } = await this.client.getOidcConfig();
+        if (!this.getJwtVerifyGetKey) {
+            this.getJwtVerifyGetKey = createRemoteJWKSet(new URL(jwksUri));
+        }
+        await verifyIdToken(idToken, appId, issuer, this.getJwtVerifyGetKey);
+    }
+}
+
+export { DefaultJwtVerifier, verifyIdToken };

package/lib/adapter/index.d.ts

@@ -6,9 +6,9 @@ export declare class ClientAdapterInstance implements ClientAdapter {
     storage: Storage<StorageKey | PersistKey>;
     unstable_cache?: Storage<CacheKey> | undefined;
     navigate: Navigate;
-    generateState: () => string;
-    generateCodeVerifier: () => string;
-    generateCodeChallenge: (codeVerifier: string) => Promise<string>;
+    generateState: () => string | Promise<string>;
+    generateCodeVerifier: () => string | Promise<string>;
+    generateCodeChallenge: (codeVerifier: string) => string | Promise<string>;
     constructor(adapter: ClientAdapter);
     setStorageItem(key: InferStorageKey<typeof this.storage>, value: Nullable<string>): Promise<void>;
     /**

package/lib/adapter/types.d.ts

@@ -33,14 +33,43 @@ export type Storage<Keys extends string> = {
     removeItem(key: Keys): Promise<void>;
 };
 export type InferStorageKey<S> = S extends Storage<infer Key> ? Key : never;
-/** The navigation function that redirects the user to the specified URL. */
-export type Navigate = (url: string) => void | Promise<void>;
+/**
+ * The navigation function that redirects the user to the specified URL.
+ *
+ * @param url The URL to navigate to.
+ * @param parameters The parameters for the navigation.
+ * @param parameters.redirectUri The redirect URI that the user will be redirected to after the
+ * flow is completed. That is, the "redirect URI" for "sign-in" and "post-logout redirect URI" for
+ * "sign-out". For the "post-sign-in" navigation, it should be ignored.
+ * @param parameters.for The purpose of the navigation. It can be either "sign-in", "sign-out", or
+ * "post-sign-in".
+ * @remarks Usually, the `redirectUri` parameter can be ignored unless the client needs to pass the
+ * redirect scheme or other parameters to the native app, such as `ASWebAuthenticationSession` in
+ * iOS.
+ */
+export type Navigate = (url: string, parameters: {
+    redirectUri?: string;
+    for: 'sign-in' | 'sign-out' | 'post-sign-in';
+}) => void | Promise<void>;
+export type JwtVerifier = {
+    verifyIdToken(idToken: string): Promise<void>;
+};
 /**
  * The adapter object that allows the customizations of the client behavior
  * for different environments.
  */
 export type ClientAdapter = {
+    /**
+     * The fetch-like function for network requests.
+     *
+     * @see {@link Requester}
+     */
     requester: Requester;
+    /**
+     * The storage for storing tokens and sessions. It is usually persistent.
+     *
+     * @see {@link Requester}
+     */
     storage: Storage<StorageKey | PersistKey>;
     /**
      * An optional storage for caching well-known data.
@@ -54,21 +83,21 @@ export type ClientAdapter = {
      *
      * @returns The state string.
      */
-    generateState: () => string;
+    generateState: () => string | Promise<string>;
     /**
      * The function that generates a random code verifier string for PKCE.
      *
-     * @see {@link https://www.rfc-editor.org/rfc/rfc7636.html| RFC 7636}
+     * @see {@link https://www.rfc-editor.org/rfc/rfc7636.html | RFC 7636}
      * @returns The code verifier string.
      */
-    generateCodeVerifier: () => string;
+    generateCodeVerifier: () => string | Promise<string>;
     /**
      * The function that generates a code challenge string based on the code verifier
      * for PKCE.
      *
-     * @see {@link https://www.rfc-editor.org/rfc/rfc7636.html| RFC 7636}
+     * @see {@link https://www.rfc-editor.org/rfc/rfc7636.html | RFC 7636}
      * @param codeVerifier The code verifier string.
      * @returns The code challenge string.
      */
-    generateCodeChallenge: (codeVerifier: string) => Promise<string>;
+    generateCodeChallenge: (codeVerifier: string) => string | Promise<string>;
 };

package/lib/client.cjs

@@ -0,0 +1,377 @@
+'use strict';
+
+var js = require('@logto/js');
+var index$1 = require('./adapter/index.cjs');
+var errors = require('./errors.cjs');
+var index = require('./types/index.cjs');
+var index$2 = require('./utils/index.cjs');
+var memoize = require('./utils/memoize.cjs');
+var once = require('./utils/once.cjs');
+var types = require('./adapter/types.cjs');
+
+/* eslint-disable max-lines */
+/**
+ * The Logto base client class that provides the essential methods for
+ * interacting with the Logto server.
+ *
+ * It also provides an adapter object that allows the customizations of the
+ * client behavior for different environments.
+ *
+ * NOTE: Usually, you would use the `LogtoClient` class instead of `StandardLogtoClient` since it
+ * provides the default JWT verifier. However, if you want to avoid the use of `jose` package
+ * which is useful for certain environments that don't support native modules like `crypto`, you
+ * can use `StandardLogtoClient` and provide your own JWT verifier.
+ */
+class StandardLogtoClient {
+    constructor(logtoConfig, adapter, buildJwtVerifier) {
+        /**
+         * Get the OIDC configuration from the discovery endpoint. This method will
+         * only fetch the configuration once and cache the result.
+         */
+        this.getOidcConfig = once.once(this.#getOidcConfig);
+        /**
+         * Get the access token from the storage with refresh strategy.
+         *
+         * - If the access token has expired, it will try to fetch a new one using the Refresh Token.
+         * - If there's an ongoing Promise to fetch the access token, it will return the Promise.
+         *
+         * If you want to get the access token claims, use {@link getAccessTokenClaims} instead.
+         *
+         * @param resource The resource that the access token is granted for. If not
+         * specified, the access token will be used for OpenID Connect or the default
+         * resource, as specified in the Logto Console.
+         * @returns The access token string.
+         * @throws LogtoClientError if the user is not authenticated.
+         */
+        this.getAccessToken = memoize.memoize(this.#getAccessToken);
+        /**
+         * Get the access token for the specified organization from the storage with refresh strategy.
+         *
+         * Scope {@link UserScope.Organizations} is required in the config to use organization-related
+         * methods.
+         *
+         * @param organizationId The ID of the organization that the access token is granted for.
+         * @returns The access token string.
+         * @throws LogtoClientError if the user is not authenticated.
+         * @remarks
+         * It uses the same refresh strategy as {@link getAccessToken}.
+         */
+        this.getOrganizationToken = memoize.memoize(this.#getOrganizationToken);
+        /**
+         * Handle the sign-in callback by parsing the authorization code from the
+         * callback URI and exchanging it for the tokens.
+         *
+         * @param callbackUri The callback URI, including the search params, that the user is redirected to after the sign-in flow is completed.
+         * The origin and pathname of this URI must match the origin and pathname of the redirect URI specified in {@link signIn}.
+         * In many cases you'll probably end up passing `window.location.href` as the argument to this function.
+         * @throws LogtoClientError if the sign-in session is not found.
+         */
+        this.handleSignInCallback = memoize.memoize(this.#handleSignInCallback);
+        this.accessTokenMap = new Map();
+        this.logtoConfig = index.normalizeLogtoConfig(logtoConfig);
+        this.adapter = new index$1.ClientAdapterInstance(adapter);
+        this.jwtVerifier = buildJwtVerifier(this);
+        void this.loadAccessTokenMap();
+    }
+    /**
+     * Check if the user is authenticated by checking if the ID token exists.
+     */
+    async isAuthenticated() {
+        return Boolean(await this.getIdToken());
+    }
+    /**
+     * Get the Refresh Token from the storage.
+     */
+    async getRefreshToken() {
+        return this.adapter.storage.getItem('refreshToken');
+    }
+    /**
+     * Get the ID Token from the storage. If you want to get the ID Token claims,
+     * use {@link getIdTokenClaims} instead.
+     */
+    async getIdToken() {
+        return this.adapter.storage.getItem('idToken');
+    }
+    /**
+     * Get the ID Token claims.
+     */
+    async getIdTokenClaims() {
+        const idToken = await this.getIdToken();
+        if (!idToken) {
+            throw new errors.LogtoClientError('not_authenticated');
+        }
+        return js.decodeIdToken(idToken);
+    }
+    /**
+     * Get the access token claims for the specified resource.
+     *
+     * @param resource The resource that the access token is granted for. If not
+     * specified, the access token will be used for OpenID Connect or the default
+     * resource, as specified in the Logto Console.
+     */
+    async getAccessTokenClaims(resource) {
+        const accessToken = await this.getAccessToken(resource);
+        return js.decodeAccessToken(accessToken);
+    }
+    /**
+     * Get the organization token claims for the specified organization.
+     *
+     * @param organizationId The ID of the organization that the access token is granted for.
+     */
+    async getOrganizationTokenClaims(organizationId) {
+        const accessToken = await this.getOrganizationToken(organizationId);
+        return js.decodeAccessToken(accessToken);
+    }
+    /**
+     * Get the user information from the Userinfo Endpoint.
+     *
+     * Note the Userinfo Endpoint will return more claims than the ID Token. See
+     * {@link https://docs.logto.io/docs/recipes/integrate-logto/vanilla-js/#fetch-user-information | Fetch user information}
+     * for more information.
+     *
+     * @returns The user information.
+     * @throws LogtoClientError if the user is not authenticated.
+     */
+    async fetchUserInfo() {
+        const { userinfoEndpoint } = await this.getOidcConfig();
+        const accessToken = await this.getAccessToken();
+        if (!accessToken) {
+            throw new errors.LogtoClientError('fetch_user_info_failed');
+        }
+        return js.fetchUserInfo(userinfoEndpoint, accessToken, this.adapter.requester);
+    }
+    async signIn(options, mode) {
+        const { redirectUri: redirectUriUrl, postRedirectUri: postRedirectUriUrl, interactionMode, } = typeof options === 'string' || options instanceof URL
+            ? { redirectUri: options, postRedirectUri: undefined, interactionMode: mode }
+            : options;
+        const redirectUri = redirectUriUrl.toString();
+        const postRedirectUri = postRedirectUriUrl?.toString();
+        const { appId: clientId, prompt, resources, scopes } = this.logtoConfig;
+        const { authorizationEndpoint } = await this.getOidcConfig();
+        const [codeVerifier, state] = await Promise.all([
+            this.adapter.generateCodeVerifier(),
+            this.adapter.generateState(),
+        ]);
+        const codeChallenge = await this.adapter.generateCodeChallenge(codeVerifier);
+        const signInUri = js.generateSignInUri({
+            authorizationEndpoint,
+            clientId,
+            redirectUri: redirectUri.toString(),
+            codeChallenge,
+            state,
+            scopes,
+            resources,
+            prompt,
+            interactionMode,
+        });
+        await Promise.all([
+            this.setSignInSession({ redirectUri, postRedirectUri, codeVerifier, state }),
+            this.setRefreshToken(null),
+            this.setIdToken(null),
+        ]);
+        await this.adapter.navigate(signInUri, { redirectUri, for: 'sign-in' });
+    }
+    /**
+     * Check if the user is redirected from the sign-in page by checking if the
+     * current URL matches the redirect URI in the sign-in session.
+     *
+     * If there's no sign-in session, it will return `false`.
+     *
+     * @param url The current URL.
+     */
+    async isSignInRedirected(url) {
+        const signInSession = await this.getSignInSession();
+        if (!signInSession) {
+            return false;
+        }
+        const { redirectUri } = signInSession;
+        const { origin, pathname } = new URL(url);
+        return `${origin}${pathname}` === redirectUri;
+    }
+    /**
+     * Start the sign-out flow with the specified redirect URI. The URI must be
+     * registered in the Logto Console.
+     *
+     * It will also revoke all the tokens and clean up the storage.
+     *
+     * The user will be redirected that URI after the sign-out flow is completed.
+     * If the `postLogoutRedirectUri` is not specified, the user will be redirected
+     * to a default page.
+     */
+    async signOut(postLogoutRedirectUri) {
+        const { appId: clientId } = this.logtoConfig;
+        const { endSessionEndpoint, revocationEndpoint } = await this.getOidcConfig();
+        const refreshToken = await this.getRefreshToken();
+        if (refreshToken) {
+            try {
+                await js.revoke(revocationEndpoint, clientId, refreshToken, this.adapter.requester);
+            }
+            catch {
+                // Do nothing at this point, as we don't want to break the sign-out flow even if the revocation is failed
+            }
+        }
+        const url = js.generateSignOutUri({
+            endSessionEndpoint,
+            postLogoutRedirectUri,
+            clientId,
+        });
+        this.accessTokenMap.clear();
+        await Promise.all([
+            this.setRefreshToken(null),
+            this.setIdToken(null),
+            this.adapter.storage.removeItem('accessToken'),
+        ]);
+        await this.adapter.navigate(url, { redirectUri: postLogoutRedirectUri, for: 'sign-out' });
+    }
+    async getSignInSession() {
+        const jsonItem = await this.adapter.storage.getItem('signInSession');
+        if (!jsonItem) {
+            return null;
+        }
+        const item = JSON.parse(jsonItem);
+        if (!index.isLogtoSignInSessionItem(item)) {
+            throw new errors.LogtoClientError('sign_in_session.invalid');
+        }
+        return item;
+    }
+    async setSignInSession(value) {
+        return this.adapter.setStorageItem(types.PersistKey.SignInSession, value && JSON.stringify(value));
+    }
+    async setIdToken(value) {
+        return this.adapter.setStorageItem(types.PersistKey.IdToken, value);
+    }
+    async setRefreshToken(value) {
+        return this.adapter.setStorageItem(types.PersistKey.RefreshToken, value);
+    }
+    async getAccessTokenByRefreshToken(resource, organizationId) {
+        const currentRefreshToken = await this.getRefreshToken();
+        if (!currentRefreshToken) {
+            throw new errors.LogtoClientError('not_authenticated');
+        }
+        const accessTokenKey = index$2.buildAccessTokenKey(resource, organizationId);
+        const { appId: clientId } = this.logtoConfig;
+        const { tokenEndpoint } = await this.getOidcConfig();
+        const requestedAt = Math.round(Date.now() / 1000);
+        const { accessToken, refreshToken, idToken, scope, expiresIn } = await js.fetchTokenByRefreshToken({
+            clientId,
+            tokenEndpoint,
+            refreshToken: currentRefreshToken,
+            resource,
+            organizationId,
+        }, this.adapter.requester);
+        this.accessTokenMap.set(accessTokenKey, {
+            token: accessToken,
+            scope,
+            /** The `expiresAt` variable provides an approximate estimation of the actual `exp` property
+             * in the token claims. It is utilized by the client to determine if the cached access token
+             * has expired and when a new access token should be requested.
+             */
+            expiresAt: requestedAt + expiresIn,
+        });
+        await this.saveAccessTokenMap();
+        if (refreshToken) {
+            await this.setRefreshToken(refreshToken);
+        }
+        if (idToken) {
+            await this.jwtVerifier.verifyIdToken(idToken);
+            await this.setIdToken(idToken);
+        }
+        return accessToken;
+    }
+    async saveAccessTokenMap() {
+        const data = {};
+        for (const [key, accessToken] of this.accessTokenMap.entries()) {
+            // eslint-disable-next-line @silverhand/fp/no-mutation
+            data[key] = accessToken;
+        }
+        await this.adapter.storage.setItem('accessToken', JSON.stringify(data));
+    }
+    async loadAccessTokenMap() {
+        const raw = await this.adapter.storage.getItem('accessToken');
+        if (!raw) {
+            return;
+        }
+        try {
+            const json = JSON.parse(raw);
+            if (!index.isLogtoAccessTokenMap(json)) {
+                return;
+            }
+            this.accessTokenMap.clear();
+            for (const [key, accessToken] of Object.entries(json)) {
+                this.accessTokenMap.set(key, accessToken);
+            }
+        }
+        catch (error) {
+            console.warn(error);
+        }
+    }
+    async #getOidcConfig() {
+        return this.adapter.getWithCache(types.CacheKey.OpenidConfig, async () => {
+            return js.fetchOidcConfig(index$2.getDiscoveryEndpoint(this.logtoConfig.endpoint), this.adapter.requester);
+        });
+    }
+    async #getAccessToken(resource, organizationId) {
+        if (!(await this.isAuthenticated())) {
+            throw new errors.LogtoClientError('not_authenticated');
+        }
+        const accessTokenKey = index$2.buildAccessTokenKey(resource, organizationId);
+        const accessToken = this.accessTokenMap.get(accessTokenKey);
+        if (accessToken && accessToken.expiresAt > Date.now() / 1000) {
+            return accessToken.token;
+        }
+        // Since the access token has expired, delete it from the map.
+        if (accessToken) {
+            this.accessTokenMap.delete(accessTokenKey);
+        }
+        /**
+         * Need to fetch a new access token using refresh token.
+         */
+        return this.getAccessTokenByRefreshToken(resource, organizationId);
+    }
+    async #getOrganizationToken(organizationId) {
+        if (!this.logtoConfig.scopes?.includes(js.UserScope.Organizations)) {
+            throw new errors.LogtoClientError('missing_scope_organizations');
+        }
+        return this.getAccessToken(undefined, organizationId);
+    }
+    async #handleSignInCallback(callbackUri) {
+        const signInSession = await this.getSignInSession();
+        if (!signInSession) {
+            throw new errors.LogtoClientError('sign_in_session.not_found');
+        }
+        const { redirectUri, postRedirectUri, state, codeVerifier } = signInSession;
+        const code = js.verifyAndParseCodeFromCallbackUri(callbackUri, redirectUri, state);
+        // NOTE: Will add scope to accessTokenKey when needed. (Linear issue LOG-1589)
+        const accessTokenKey = index$2.buildAccessTokenKey();
+        const { appId: clientId } = this.logtoConfig;
+        const { tokenEndpoint } = await this.getOidcConfig();
+        const requestedAt = Math.round(Date.now() / 1000);
+        const { idToken, refreshToken, accessToken, scope, expiresIn } = await js.fetchTokenByAuthorizationCode({
+            clientId,
+            tokenEndpoint,
+            redirectUri,
+            codeVerifier,
+            code,
+        }, this.adapter.requester);
+        await this.jwtVerifier.verifyIdToken(idToken);
+        await this.setRefreshToken(refreshToken ?? null);
+        await this.setIdToken(idToken);
+        this.accessTokenMap.set(accessTokenKey, {
+            token: accessToken,
+            scope,
+            /** The `expiresAt` variable provides an approximate estimation of the actual `exp` property
+             * in the token claims. It is utilized by the client to determine if the cached access token
+             * has expired and when a new access token should be requested.
+             */
+            expiresAt: requestedAt + expiresIn,
+        });
+        await this.saveAccessTokenMap();
+        await this.setSignInSession(null);
+        if (postRedirectUri) {
+            await this.adapter.navigate(postRedirectUri, { for: 'post-sign-in' });
+        }
+    }
+}
+/* eslint-enable max-lines */
+
+exports.StandardLogtoClient = StandardLogtoClient;