feat: Sync to OSS repo

This commit is contained in:
Wanjohi
2026-08-06 22:13:51 +03:00
parent 46d2a56180
commit 3faac3008f
144 changed files with 27561 additions and 0 deletions

729
packages/auth/src/client.ts Normal file
View File

@@ -0,0 +1,729 @@
import type { v1 } from '@standard-schema/spec';
/**
* Use the OpenAuth client kick off your OAuth flows, exchange tokens, refresh tokens,
* and verify tokens.
*
* First, create a client.
*
* ```ts title="client.ts"
* import { createClient } from "@openauthjs/openauth/client"
*
* const client = createClient({
* clientID: "my-client",
* issuer: "https://auth.myserver.com"
* })
* ```
*
* Kick off the OAuth flow by calling `authorize`.
*
* ```ts
* const redirect_uri = "https://myserver.com/callback"
*
* const { url } = await client.authorize(
* redirect_uri,
* "code"
* )
* ```
*
* When the user completes the flow, `exchange` the code for tokens.
*
* ```ts
* const tokens = await client.exchange(query.get("code"), redirect_uri)
* ```
*
* And `verify` the tokens.
*
* ```ts
* const verified = await client.verify(subjects, tokens.access)
* ```
*
* @packageDocumentation
*/
import { createLocalJWKSet, errors, JSONWebKeySet, jwtVerify, decodeJwt } from 'jose';
import {
InvalidAccessTokenError,
InvalidAuthorizationCodeError,
InvalidRefreshTokenError,
InvalidSubjectError
} from './error.js';
import { generatePKCE } from './pkce.js';
import { SubjectSchema } from './subject.js';
/**
* The well-known information for an OAuth 2.0 authorization server.
* @internal
*/
export interface WellKnown {
/**
* The URI to the JWKS endpoint.
*/
jwks_uri: string;
/**
* The URI to the token endpoint.
*/
token_endpoint: string;
/**
* The URI to the authorization endpoint.
*/
authorization_endpoint: string;
}
/**
* The tokens returned by the auth server.
*/
export interface Tokens {
/**
* The access token.
*/
access: string;
/**
* The refresh token.
*/
refresh: string;
/**
* The number of seconds until the access token expires.
*/
expiresIn: number;
}
interface ResponseLike {
json(): Promise<unknown>;
ok: Response['ok'];
}
type FetchLike = (...args: any[]) => Promise<ResponseLike>;
/**
* The challenge that you can use to verify the code.
*/
export type Challenge = {
/**
* The state that was sent to the redirect URI.
*/
state: string;
/**
* The verifier that was sent to the redirect URI.
*/
verifier?: string;
};
/**
* Configure the client.
*/
export interface ClientInput {
/**
* The client ID. This is just a string to identify your app.
*
* If you have a web app and a mobile app, you want to use different client IDs both.
*
* @example
* ```ts
* {
* clientID: "my-client"
* }
* ```
*/
clientID: string;
/**
* The URL of your OpenAuth server.
*
* @example
* ```ts
* {
* issuer: "https://auth.myserver.com"
* }
* ```
*/
issuer?: string;
/**
* Optionally, override the internally used fetch function.
*
* This is useful if you are using a polyfilled fetch function in your application and you
* want the client to use it too.
*/
fetch?: FetchLike;
}
export interface AuthorizeOptions {
/**
* Enable the PKCE flow. This is for SPA apps.
*
* ```ts
* {
* pkce: true
* }
* ```
*
* @default false
*/
pkce?: boolean;
/**
* The provider you want to use for the OAuth flow.
*
* ```ts
* {
* provider: "google"
* }
* ```
*
* If no provider is specified, the user is directed to a page where they can select from the
* list of configured providers.
*
* If there's only one provider configured, the user will be redirected to that.
*/
provider?: string;
}
export interface AuthorizeResult {
/**
* The challenge that you can use to verify the code. This is for the PKCE flow for SPA apps.
*
* This is an object that you _stringify_ and store it in session storage.
*
* ```ts
* sessionStorage.setItem("challenge", JSON.stringify(challenge))
* ```
*/
challenge: Challenge;
/**
* The URL to redirect the user to. This starts the OAuth flow.
*
* For example, for SPA apps.
*
* ```ts
* location.href = url
* ```
*/
url: string;
}
/**
* Returned when the exchange is successful.
*/
export interface ExchangeSuccess {
/**
* This is always `false` when the exchange is successful.
*/
err: false;
/**
* The access and refresh tokens.
*/
tokens: Tokens;
}
/**
* Returned when the exchange fails.
*/
export interface ExchangeError {
/**
* The type of error that occurred. You can handle this by checking the type.
*
* @example
* ```ts
* import { InvalidAuthorizationCodeError } from "@openauthjs/openauth/error"
*
* console.log(err instanceof InvalidAuthorizationCodeError)
*```
*/
err: InvalidAuthorizationCodeError;
}
export interface RefreshOptions {
/**
* Optionally, pass in the access token.
*/
access?: string;
}
/**
* Returned when the refresh is successful.
*/
export interface RefreshSuccess {
/**
* This is always `false` when the refresh is successful.
*/
err: false;
/**
* Returns the refreshed tokens only if they've been refreshed.
*
* If they are still valid, this will be `undefined`.
*/
tokens?: Tokens;
}
/**
* Returned when the refresh fails.
*/
export interface RefreshError {
/**
* The type of error that occurred. You can handle this by checking the type.
*
* @example
* ```ts
* import { InvalidRefreshTokenError } from "@openauthjs/openauth/error"
*
* console.log(err instanceof InvalidRefreshTokenError)
*```
*/
err: InvalidRefreshTokenError | InvalidAccessTokenError;
}
export interface VerifyOptions {
/**
* Optionally, pass in the refresh token.
*
* If passed in, this will automatically refresh the access token if it has expired.
*/
refresh?: string;
/**
* @internal
*/
issuer?: string;
/**
* @internal
*/
audience?: string;
/**
* Optionally, override the internally used fetch function.
*
* This is useful if you are using a polyfilled fetch function in your application and you
* want the client to use it too.
*/
fetch?: FetchLike;
}
export interface VerifyResult<T extends SubjectSchema> {
/**
* This is always `undefined` when the verify is successful.
*/
err?: undefined;
/**
* Returns the refreshed tokens only if theyve been refreshed.
*
* If they are still valid, this will be undefined.
*/
tokens?: Tokens;
/**
* @internal
*/
aud: string;
/**
* The decoded subjects from the access token.
*
* Has the same shape as the subjects you defined when creating the issuer.
*/
subject: {
[type in keyof T]: { type: type; properties: v1.InferOutput<T[type]> };
}[keyof T];
}
/**
* Returned when the verify call fails.
*/
export interface VerifyError {
/**
* The type of error that occurred. You can handle this by checking the type.
*
* @example
* ```ts
* import { InvalidRefreshTokenError } from "@openauthjs/openauth/error"
*
* console.log(err instanceof InvalidRefreshTokenError)
*```
*/
err: InvalidRefreshTokenError | InvalidAccessTokenError;
}
/**
* An instance of the OpenAuth client contains the following methods.
*/
export interface Client {
/**
* Start the autorization flow. For example, in SSR sites.
*
* ```ts
* const { url } = await client.authorize(<redirect_uri>, "code")
* ```
*
* This takes a redirect URI and the type of flow you want to use. The redirect URI is the
* location where the user will be redirected to after the flow is complete.
*
* Supports both the _code_ and _token_ flows. We recommend using the _code_ flow as it's more
* secure.
*
* :::tip
* This returns a URL to redirect the user to. This starts the OAuth flow.
* :::
*
* This returns a URL to the auth server. You can redirect the user to the URL to start the
* OAuth flow.
*
* For SPA apps, we recommend using the PKCE flow.
*
* ```ts {4}
* const { challenge, url } = await client.authorize(
* <redirect_uri>,
* "code",
* { pkce: true }
* )
* ```
*
* This returns a redirect URL and a challenge that you need to use later to verify the code.
*/
authorize(
redirectURI: string,
response: 'code' | 'token',
opts?: AuthorizeOptions
): Promise<AuthorizeResult>;
/**
* Exchange the code for access and refresh tokens.
*
* ```ts
* const exchanged = await client.exchange(<code>, <redirect_uri>)
* ```
*
* You call this after the user has been redirected back to your app after the OAuth flow.
*
* :::tip
* For SSR sites, the code is returned in the query parameter.
* :::
*
* So the code comes from the query parameter in the redirect URI. The redirect URI here is
* the one that you passed in to the `authorize` call when starting the flow.
*
* :::tip
* For SPA sites, the code is returned through the URL hash.
* :::
*
* If you used the PKCE flow for an SPA app, the code is returned as a part of the redirect URL
* hash.
*
* ```ts {4}
* const exchanged = await client.exchange(
* <code>,
* <redirect_uri>,
* <challenge.verifier>
* )
* ```
*
* You also need to pass in the previously stored challenge verifier.
*
* This method returns the access and refresh tokens. Or if it fails, it returns an error that
* you can handle depending on the error.
*
* ```ts
* import { InvalidAuthorizationCodeError } from "@openauthjs/openauth/error"
*
* if (exchanged.err) {
* if (exchanged.err instanceof InvalidAuthorizationCodeError) {
* // handle invalid code error
* }
* else {
* // handle other errors
* }
* }
*
* const { access, refresh } = exchanged.tokens
* ```
*/
exchange(
code: string,
redirectURI: string,
verifier?: string
): Promise<ExchangeSuccess | ExchangeError>;
/**
* Refreshes the tokens if they have expired. This is used in an SPA app to maintain the
* session, without logging the user out.
*
* ```ts
* const next = await client.refresh(<refresh_token>)
* ```
*
* Can optionally take the access token as well. If passed in, this will skip the refresh
* if the access token is still valid.
*
* ```ts
* const next = await client.refresh(<refresh_token>, { access: <access_token> })
* ```
*
* This returns the refreshed tokens only if they've been refreshed.
*
* ```ts
* if (!next.err) {
* // tokens are still valid
* }
* if (next.tokens) {
* const { access, refresh } = next.tokens
* }
* ```
*
* Or if it fails, it returns an error that you can handle depending on the error.
*
* ```ts
* import { InvalidRefreshTokenError } from "@openauthjs/openauth/error"
*
* if (next.err) {
* if (next.err instanceof InvalidRefreshTokenError) {
* // handle invalid refresh token error
* }
* else {
* // handle other errors
* }
* }
* ```
*/
refresh(refresh: string, opts?: RefreshOptions): Promise<RefreshSuccess | RefreshError>;
/**
* Verify the token in the incoming request.
*
* This is typically used for SSR sites where the token is stored in an HTTP only cookie. And
* is passed to the server on every request.
*
* ```ts
* const verified = await client.verify(<subjects>, <token>)
* ```
*
* This takes the subjects that you had previously defined when creating the issuer.
*
* :::tip
* If the refresh token is passed in, it'll automatically refresh the access token.
* :::
*
* This can optionally take the refresh token as well. If passed in, it'll automatically
* refresh the access token if it has expired.
*
* ```ts
* const verified = await client.verify(<subjects>, <token>, { refresh: <refresh_token> })
* ```
*
* This returns the decoded subjects from the access token. And the tokens if they've been
* refreshed.
*
* ```ts
* // based on the subjects you defined earlier
* console.log(verified.subject.properties.userID)
*
* if (verified.tokens) {
* const { access, refresh } = verified.tokens
* }
* ```
*
* Or if it fails, it returns an error that you can handle depending on the error.
*
* ```ts
* import { InvalidRefreshTokenError } from "@openauthjs/openauth/error"
*
* if (verified.err) {
* if (verified.err instanceof InvalidRefreshTokenError) {
* // handle invalid refresh token error
* }
* else {
* // handle other errors
* }
* }
* ```
*/
verify<T extends SubjectSchema>(
subjects: T,
token: string,
options?: VerifyOptions
): Promise<VerifyResult<T> | VerifyError>;
}
/**
* Create an OpenAuth client.
*
* @param input - Configure the client.
*/
export function createClient(input: ClientInput): Client {
const jwksCache = new Map<string, ReturnType<typeof createLocalJWKSet>>();
const issuerCache = new Map<string, WellKnown>();
const issuer = input.issuer || process.env.OPENAUTH_ISSUER;
if (!issuer) throw new Error('No issuer');
const f = input.fetch ?? fetch;
async function getIssuer() {
const cached = issuerCache.get(issuer!);
if (cached) return cached;
const wellKnown = (await (f || fetch)(`${issuer}/.well-known/oauth-authorization-server`).then(
(r) => r.json()
)) as WellKnown;
issuerCache.set(issuer!, wellKnown);
return wellKnown;
}
async function getJWKS() {
const wk = await getIssuer();
const cached = jwksCache.get(issuer!);
if (cached) return cached;
const keyset = (await (f || fetch)(wk.jwks_uri).then((r) => r.json())) as JSONWebKeySet;
const result = createLocalJWKSet(keyset);
jwksCache.set(issuer!, result);
return result;
}
const result = {
async authorize(redirectURI: string, response: 'code' | 'token', opts?: AuthorizeOptions) {
const result = new URL(issuer + '/authorize');
const challenge: Challenge = {
state: crypto.randomUUID()
};
result.searchParams.set('client_id', input.clientID);
result.searchParams.set('redirect_uri', redirectURI);
result.searchParams.set('response_type', response);
result.searchParams.set('state', challenge.state);
if (opts?.provider) result.searchParams.set('provider', opts.provider);
if (opts?.pkce && response === 'code') {
const pkce = await generatePKCE();
result.searchParams.set('code_challenge_method', 'S256');
result.searchParams.set('code_challenge', pkce.challenge);
challenge.verifier = pkce.verifier;
}
return {
challenge,
url: result.toString()
};
},
/**
* @deprecated use `authorize` instead, it will do pkce by default unless disabled with `opts.pkce = false`
*/
async pkce(
redirectURI: string,
opts?: {
provider?: string;
}
) {
const result = new URL(issuer + '/authorize');
if (opts?.provider) result.searchParams.set('provider', opts.provider);
result.searchParams.set('client_id', input.clientID);
result.searchParams.set('redirect_uri', redirectURI);
result.searchParams.set('response_type', 'code');
const pkce = await generatePKCE();
result.searchParams.set('code_challenge_method', 'S256');
result.searchParams.set('code_challenge', pkce.challenge);
return [pkce.verifier, result.toString()];
},
async exchange(
code: string,
redirectURI: string,
verifier?: string
): Promise<ExchangeSuccess | ExchangeError> {
const tokens = await f(issuer + '/token', {
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded'
},
body: new URLSearchParams({
code,
redirect_uri: redirectURI,
grant_type: 'authorization_code',
client_id: input.clientID,
code_verifier: verifier || ''
}).toString()
});
const json = (await tokens.json()) as any;
if (!tokens.ok) {
return {
err: new InvalidAuthorizationCodeError()
};
}
return {
err: false,
tokens: {
access: json.access_token as string,
refresh: json.refresh_token as string,
expiresIn: json.expires_in as number
}
};
},
async refresh(refresh: string, opts?: RefreshOptions): Promise<RefreshSuccess | RefreshError> {
if (opts && opts.access) {
const decoded = decodeJwt(opts.access);
if (!decoded) {
return {
err: new InvalidAccessTokenError()
};
}
// allow 30s window for expiration
if ((decoded.exp || 0) > Date.now() / 1000 + 30) {
return {
err: false
};
}
}
const tokens = await f(issuer + '/token', {
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded'
},
body: new URLSearchParams({
grant_type: 'refresh_token',
refresh_token: refresh
}).toString()
});
const json = (await tokens.json()) as any;
if (!tokens.ok) {
return {
err: new InvalidRefreshTokenError()
};
}
return {
err: false,
tokens: {
access: json.access_token as string,
refresh: json.refresh_token as string,
expiresIn: json.expires_in as number
}
};
},
async verify<T extends SubjectSchema>(
subjects: T,
token: string,
options?: VerifyOptions
): Promise<VerifyResult<T> | VerifyError> {
const jwks = await getJWKS();
try {
const result = await jwtVerify<{
mode: 'access';
type: keyof T;
properties: v1.InferInput<T[keyof T]>;
}>(token, jwks, {
issuer
});
const validated = await subjects[result.payload.type]['~standard'].validate(
result.payload.properties
);
if (!validated.issues && result.payload.mode === 'access') {
return {
aud: result.payload.aud as string,
subject: {
type: result.payload.type,
properties: validated.value
} as any
};
}
return {
err: new InvalidSubjectError()
};
} catch (e) {
if (e instanceof errors.JWTExpired && options?.refresh) {
const refreshed = await this.refresh(options.refresh);
if (refreshed.err) return refreshed;
const verified = await result.verify(subjects, refreshed.tokens!.access, {
refresh: refreshed.tokens!.refresh,
issuer,
fetch: options?.fetch
});
if (verified.err) return verified;
verified.tokens = refreshed.tokens;
return verified;
}
return {
err: new InvalidAccessTokenError()
};
}
}
};
return result;
}