@workos-inc/authkit-js0.20.519.0 kB
import {
AuthenticationResponse,
CreateClientOptions,
OnRefreshResponse,
User,
} from "./interfaces";
import { NoClientIdProvidedException } from "./exceptions";
import {
isRedirectCallback,
memoryStorage,
createPkceChallenge,
setSessionData,
removeSessionData,
storageKeys,
} from "./utils";
import { getRefreshToken, getClaims } from "./utils/session-data";
import { RedirectParams } from "./interfaces/create-client-options.interface";
import {
LoginRequiredError,
NoSessionError,
RefreshError,
RefreshTimeoutError,
} from "./errors";
import { withLock, LockError } from "./utils/locking";
import { HttpClient } from "./http-client";
interface RedirectOptions {
/**
* @deprecated We previously required initiate login endpoints to return the `context`
* query parameter when getting the authorization URL. This is no longer necessary.
*/
context?: string;
invitationToken?: string;
loginHint?: string;
organizationId?: string;
passwordResetToken?: string;
state?: any;
screenHint?: "sign-in" | "sign-up";
}
type State =
| { tag: "INITIAL" }
| { tag: "AUTHENTICATING"; response: Promise<AuthenticationResponse> }
| { tag: "AUTHENTICATED" }
| { tag: "SIGNED_OUT" }
| { tag: "ERROR" };
const LEGACY_ORG_ID_KEY = "workos_organization_id";
function orgIdKey(clientId: string) {
return `workos-org-id:${clientId}`;
}
const REFRESH_LOCK_NAME = "WORKOS_REFRESH_SESSION";
function hasSessionCookie(clientId: string): boolean {
// One domain potentially holds several cookies of this name at different
// levels (e.g. app.example.com and admin.internal.example.com).
const matches = document.cookie.matchAll(
/(?:^|;\s*)workos-has-session=([^;]*)/g,
);
for (const [, cookieValue] of matches) {
// cookieValue == 1 is for backwards compat. can remove in april 2027
if (cookieValue === "1" || cookieValue.split(".").includes(clientId)) {
return true;
}
}
return false;
}
export class Client {
#state: State;
#refreshTimer: ReturnType<typeof setTimeout> | undefined;
readonly #clientId: string;
readonly #httpClient: HttpClient;
readonly #redirectUri: string;
readonly #devMode: boolean;
readonly #onBeforeAutoRefresh: () => boolean;
readonly #onRedirectCallback: (params: RedirectParams) => void;
readonly #onRefreshCallback:
| ((response: OnRefreshResponse) => void)
| undefined;
readonly #onRefreshFailure:
| ((params: { signIn: () => Promise<void> }) => void)
| undefined;
readonly #refreshBufferInterval: number;
constructor(
clientId: string,
{
apiHostname: hostname,
https,
port,
redirectUri = window.origin,
devMode = location.hostname === "localhost" ||
location.hostname === "127.0.0.1",
// refresh if this is true
onBeforeAutoRefresh = () => {
return !document.hidden;
},
onRedirectCallback = (_: RedirectParams) => {},
onRefresh,
onRefreshFailure,
refreshBufferInterval = 10,
}: CreateClientOptions = {},
) {
if (!clientId) {
throw new NoClientIdProvidedException();
}
this.#clientId = clientId;
this.#httpClient = new HttpClient({ clientId, hostname, port, https });
this.#devMode = devMode;
this.#redirectUri = redirectUri;
this.#state = { tag: "INITIAL" };
this.#onBeforeAutoRefresh = onBeforeAutoRefresh;
this.#onRedirectCallback = onRedirectCallback;
this.#onRefreshCallback = onRefresh;
this.#onRefreshFailure = onRefreshFailure;
this.#refreshBufferInterval = refreshBufferInterval;
}
async initialize() {
if (this.#state.tag !== "INITIAL") {
return;
}
const searchParams = new URLSearchParams(window.location.search);
if (isRedirectCallback(this.#redirectUri, searchParams)) {
await this.#handleCallback();
} else if (
hasSessionCookie(this.#clientId) ||
getRefreshToken({ devMode: this.#devMode, clientId: this.#clientId })
) {
try {
await this.#refreshSession();
this.#scheduleAutomaticRefresh();
} catch {
// A refresh here is expected to fail if the user has no session, in
// which case #doRefresh moves to the ERROR state and we do nothing.
// For a transient failure (network error, timeout, 429, 5xx) the
// session is preserved (state stays AUTHENTICATED), so still start the
// background refresh loop to renew the token once the blip clears.
this.#scheduleAutomaticRefreshIfAuthenticated();
}
}
}
async getSignInUrl(opts: Omit<RedirectOptions, "screenHint"> = {}) {
const url = await this.#getAuthorizationUrl({ ...opts });
return url;
}
async getSignUpUrl(opts: Omit<RedirectOptions, "screenHint"> = {}) {
const url = await this.#getAuthorizationUrl({
...opts,
screenHint: "sign-up",
});
return url;
}
async signIn(opts: Omit<RedirectOptions, "screenHint"> = {}) {
const url = await this.#getAuthorizationUrl({ ...opts });
window.location.assign(url);
}
async signUp(opts: Omit<RedirectOptions, "screenHint"> = {}) {
const url = await this.#getAuthorizationUrl({
...opts,
screenHint: "sign-up",
});
window.location.assign(url);
}
signOut(options?: { returnTo?: string; navigate?: true }): void;
signOut(options?: { returnTo?: string; navigate: false }): Promise<void>;
signOut(
options: { returnTo?: string; navigate?: boolean } = { navigate: true },
): void | Promise<void> {
const { navigate = true, returnTo } = options;
const accessToken = memoryStorage.getItem(storageKeys.accessToken);
if (typeof accessToken !== "string") {
// With no active session there is no logout URL to route through, and the
// WorkOS allowlist only validates `returnTo` on the logout endpoint.
// Redirecting to a raw `returnTo` here would be an open redirect for
// logged-out users, so always surface NoSessionError and let the caller
// decide what to do (including any redirect it deems safe).
if (navigate) {
throw new NoSessionError();
}
return Promise.reject(new NoSessionError());
}
const { sid: sessionId } = getClaims(accessToken);
const url = this.#httpClient.getLogoutUrl({
sessionId,
returnTo,
});
if (url) {
this.#state = { tag: "SIGNED_OUT" };
clearTimeout(this.#refreshTimer);
removeSessionData({ devMode: this.#devMode, clientId: this.#clientId });
sessionStorage.removeItem(orgIdKey(this.#clientId));
sessionStorage.removeItem(LEGACY_ORG_ID_KEY);
if (navigate) {
window.location.assign(url);
} else {
return new Promise(async (resolve) => {
fetch(url, {
mode: "no-cors",
credentials: "include",
})
.catch((error) => {
console.warn("AuthKit: Failed to send logout request", error);
})
.finally(resolve);
});
}
}
}
async getAccessToken(options?: { forceRefresh?: boolean }): Promise<string> {
if (options?.forceRefresh || this.#shouldRefresh()) {
try {
await this.#refreshSession();
} catch (err) {
if (err instanceof RefreshTimeoutError) {
const token = !options?.forceRefresh
? this.#getUnexpiredAccessToken()
: undefined;
if (token) return token;
try {
await this.#refreshSession();
} catch (retryErr) {
if (retryErr instanceof RefreshTimeoutError) throw retryErr;
if (retryErr instanceof RefreshError) {
// A transient failure preserves the session; surface it so the
// caller can retry rather than forcing re-authentication.
if (retryErr.isTransient) throw retryErr;
throw new LoginRequiredError();
}
throw retryErr;
}
} else if (err instanceof RefreshError) {
// A transient failure preserves the session. If the refresh was
// proactive (the token is within the buffer window but not yet
// expired) and this isn't a forced refresh, return the still-valid
// token so a brief blip doesn't fail a serviceable call. Otherwise
// surface the error so the caller can retry rather than being forced
// to re-authenticate.
if (err.isTransient) {
const token = !options?.forceRefresh
? this.#getUnexpiredAccessToken()
: undefined;
if (token) return token;
throw err;
}
throw new LoginRequiredError();
} else {
throw err;
}
}
}
const accessToken = this.#getAccessToken();
if (!accessToken) {
throw new LoginRequiredError();
}
return accessToken;
}
getUser() {
const user = memoryStorage.getItem(storageKeys.user);
return user ? (user as User) : null;
}
dispose() {
clearTimeout(this.#refreshTimer);
memoryStorage.reset();
}
async #handleCallback() {
if (this.#state.tag !== "INITIAL") {
return;
}
const url = new URL(window.location.href);
const code = url.searchParams.get("code");
const stateParam = url.searchParams.get("state");
// `state` round-trips through the redirect as untrusted URL input, so a
// crafted link can carry a non-JSON value. Treat a malformed state as
// absent instead of letting JSON.parse throw out of the callback (which
// would abort the flow and skip the URL/code-verifier cleanup below).
let state: Record<string, any> | undefined = undefined;
if (stateParam) {
try {
state = JSON.parse(stateParam);
} catch {
console.warn("AuthKit: ignoring malformed `state` parameter");
}
}
// grab the previously stored code verifier from session storage
const codeVerifier = window.sessionStorage.getItem(
storageKeys.codeVerifier,
);
if (code) {
if (codeVerifier) {
try {
this.#state = {
tag: "AUTHENTICATING",
response: this.#httpClient.authenticateWithCode({
code,
codeVerifier,
useCookie: this.#useCookie,
}),
};
const authenticationResponse = await this.#state.response;
if (authenticationResponse) {
this.#state = { tag: "AUTHENTICATED" };
this.#scheduleAutomaticRefresh();
setSessionData(authenticationResponse, {
devMode: this.#devMode,
clientId: this.#clientId,
});
this.#onRefresh(authenticationResponse);
this.#onRedirectCallback({ state, ...authenticationResponse });
}
} catch (error) {
this.#state = { tag: "ERROR" };
console.error(error);
}
} else {
this.#state = { tag: "ERROR" };
console.error(`Couldn't exchange code.
An authorization_code was supplied for a login which did not originate at the application. This could happen for various reasons:
* This could have been an attempted Login CSRF attack. You were not affected.
* The developer may not have configured a Login Initiation endpoint.`);
}
}
// Remove code/state from search params
const cleanUrl = new URL(window.location.toString());
cleanUrl.searchParams.delete("code");
cleanUrl.searchParams.delete("state");
window.sessionStorage.removeItem(storageKeys.codeVerifier);
window.history.replaceState({}, "", cleanUrl);
}
#scheduleAutomaticRefreshIfAuthenticated() {
if (this.#state.tag === "AUTHENTICATED") {
this.#scheduleAutomaticRefresh();
}
}
async #scheduleAutomaticRefresh() {
if (this.#state.tag === "SIGNED_OUT") return;
this.#refreshTimer = setTimeout(() => {
if (this.#shouldRefresh() && this.#onBeforeAutoRefresh()) {
this.#refreshSession()
.catch((e) => {
if (this.#state.tag !== "SIGNED_OUT") console.debug(e);
})
.finally(() => this.#scheduleAutomaticRefresh());
} else {
this.#scheduleAutomaticRefresh();
}
}, 1000);
}
/**
* Switches to the requested organization.
*
* Redirects to the hosted login page for the given organization if the
* switch is unsuccessful.
*/
async switchToOrganization({
organizationId,
signInOpts = {},
}: {
organizationId: string;
signInOpts?: Omit<RedirectOptions, "type" | "organizationId">;
}) {
try {
await this.#refreshSession({ organizationId });
} catch (error) {
if (error instanceof RefreshTimeoutError) {
console.warn(
"Couldn't switch organization: lock acquisition timed out.",
);
} else if (error instanceof RefreshError) {
// A transient failure preserves the session; surface it so the caller
// can retry rather than forcing a full re-authentication redirect.
if (error.isTransient) {
throw error;
}
this.signIn({ ...signInOpts, organizationId });
} else {
throw error;
}
}
}
async #refreshSession({ organizationId }: { organizationId?: string } = {}) {
this.#assertNotSignedOut();
if (this.#state.tag === "AUTHENTICATING") {
await this.#state.response;
return;
}
const beginningState = this.#state;
this.#state = {
tag: "AUTHENTICATING",
response: this.#doRefresh({ organizationId, beginningState }),
};
await this.#state.response;
}
async #doRefresh({
organizationId,
beginningState,
}: {
organizationId?: string;
beginningState: State;
}): Promise<AuthenticationResponse> {
try {
return await withLock(REFRESH_LOCK_NAME, async () => {
this.#assertNotSignedOut();
if (organizationId) {
sessionStorage.setItem(orgIdKey(this.#clientId), organizationId);
} else {
const accessToken = this.#getAccessToken();
if (accessToken) {
organizationId = getClaims(accessToken)?.org_id;
} else {
// Fall back to legacy key for backwards compat
organizationId =
sessionStorage.getItem(orgIdKey(this.#clientId)) ??
sessionStorage.getItem(LEGACY_ORG_ID_KEY) ??
undefined;
}
}
const authenticationResponse =
await this.#httpClient.authenticateWithRefreshToken({
refreshToken: getRefreshToken({
devMode: this.#devMode,
clientId: this.#clientId,
}),
organizationId,
useCookie: this.#useCookie,
});
// Logout may have happened while the refresh request was in flight.
this.#assertNotSignedOut();
this.#state = { tag: "AUTHENTICATED" };
setSessionData(authenticationResponse, {
devMode: this.#devMode,
clientId: this.#clientId,
});
this.#onRefresh(authenticationResponse);
return authenticationResponse;
});
} catch (error) {
this.#assertNotSignedOut();
if (
error instanceof LockError &&
error.name === "AcquisitionTimeoutError"
) {
console.warn("Couldn't acquire refresh lock.");
// preserving the original state so that we can try again next time
this.#state = beginningState;
throw new RefreshTimeoutError(undefined, { cause: error });
}
if (beginningState.tag !== "INITIAL") {
console.debug(error);
}
if (error instanceof RefreshError && !error.isTransient) {
removeSessionData({ devMode: this.#devMode, clientId: this.#clientId });
sessionStorage.removeItem(orgIdKey(this.#clientId));
sessionStorage.removeItem(LEGACY_ORG_ID_KEY);
// fire the refresh failure UNLESS this is the initial refresh attempt
// (the initial refresh is expected to fail if a user has not logged in
// ever or recently)
beginningState.tag !== "INITIAL" &&
this.#onRefreshFailure &&
this.#onRefreshFailure({ signIn: this.signIn.bind(this) });
this.#state = { tag: "ERROR" };
} else {
// A transient failure (network error, timeout, 429, or 5xx) is not a
// signal that the refresh token is dead, so preserve the session data.
// Transitioning into the AUTHENTICATED state ensures that we will
// attempt to refresh the token on future getAccessToken() calls.
//
// this could maybe be a new state for clarity? TEMPORARY_ERROR?
this.#state = { tag: "AUTHENTICATED" };
}
throw error;
}
}
#assertNotSignedOut() {
if (this.#state.tag === "SIGNED_OUT") throw new LoginRequiredError();
}
#shouldRefresh() {
switch (this.#state.tag) {
case "INITIAL":
case "AUTHENTICATING":
return true;
case "SIGNED_OUT":
case "ERROR":
return false;
case "AUTHENTICATED":
const accessToken = memoryStorage.getItem(storageKeys.accessToken) as
| string
| undefined;
const expiresAt = memoryStorage.getItem(storageKeys.expiresAt) as
| number
| undefined;
if (!accessToken || !expiresAt) {
return true;
}
const tokenRefreshBufferInSeconds = this.#refreshBufferInterval * 1000;
const refreshTime = expiresAt - tokenRefreshBufferInSeconds;
return refreshTime < Date.now();
}
}
async #getAuthorizationUrl({
context,
invitationToken,
loginHint,
organizationId,
passwordResetToken,
state,
screenHint,
}: RedirectOptions) {
const { codeVerifier, codeChallenge } = await createPkceChallenge();
// store the code verifier in session storage for later use (after the redirect back from authkit)
window.sessionStorage.setItem(storageKeys.codeVerifier, codeVerifier);
const url = this.#httpClient.getAuthorizationUrl({
codeChallenge,
codeChallengeMethod: "S256",
context,
invitationToken,
loginHint,
organizationId,
passwordResetToken,
redirectUri: this.#redirectUri,
screenHint,
state: state ? JSON.stringify(state) : undefined,
});
return url;
}
#getAccessToken() {
return memoryStorage.getItem(storageKeys.accessToken) as string | undefined;
}
#getUnexpiredAccessToken(): string | undefined {
const accessToken = this.#getAccessToken();
const expiresAt = memoryStorage.getItem(storageKeys.expiresAt) as
| number
| undefined;
return accessToken && expiresAt && expiresAt > Date.now()
? accessToken
: undefined;
}
get #useCookie() {
return !this.#devMode;
}
async #onRefresh(authenticationResponse: AuthenticationResponse) {
if (this.#onRefreshCallback) {
// there's no good reason for client code to access the refresh token
const { refreshToken: _refreshToken, ...onRefreshData } =
authenticationResponse;
this.#onRefreshCallback(onRefreshData);
}
}
}
export async function createClient(
clientId: string,
options: CreateClientOptions = {},
) {
const client = new Client(clientId, options);
await client.initialize();
return client;
}
Shown as plain text from the published tarball, after apm checked it against the version's checksum. Nothing in it runs on this page.