@atcute/oauth-browser-client 1.0.4 → 1.0.5

package/lib/agents/exchange.ts

@@ -0,0 +1,115 @@
+import { createES256Key } from '../dpop.js';
+import { CLIENT_ID, database, REDIRECT_URI } from '../environment.js';
+import { AuthorizationError, LoginError } from '../errors.js';
+import type { IdentityMetadata } from '../types/identity.js';
+import type { AuthorizationServerMetadata } from '../types/server.js';
+import type { Session } from '../types/token.js';
+import { generatePKCE, generateState } from '../utils/runtime.js';
+
+import { OAuthServerAgent } from './server-agent.js';
+import { storeSession } from './sessions.js';
+
+export interface AuthorizeOptions {
+	metadata: AuthorizationServerMetadata;
+	identity?: IdentityMetadata;
+	scope: string;
+}
+
+/**
+ * Create authentication URL for authorization
+ * @param options
+ * @returns URL to redirect the user for authorization
+ */
+export const createAuthorizationUrl = async ({
+	metadata,
+	identity,
+	scope,
+}: AuthorizeOptions): Promise<URL> => {
+	const state = generateState();
+
+	const pkce = await generatePKCE();
+	const dpopKey = await createES256Key();
+
+	const params = {
+		redirect_uri: REDIRECT_URI,
+		code_challenge: pkce.challenge,
+		code_challenge_method: pkce.method,
+		state: state,
+		login_hint: identity?.raw,
+		response_mode: 'fragment',
+		response_type: 'code',
+		display: 'page',
+		// id_token_hint: undefined,
+		// max_age: undefined,
+		// prompt: undefined,
+		scope: scope,
+		// ui_locales: undefined,
+	} satisfies Record<string, string | undefined>;
+
+	database.states.set(state, {
+		dpopKey: dpopKey,
+		metadata: metadata,
+		verifier: pkce.verifier,
+	});
+
+	const server = new OAuthServerAgent(metadata, dpopKey);
+	const response = await server.request('pushed_authorization_request', params);
+
+	const authUrl = new URL(metadata.authorization_endpoint);
+	authUrl.searchParams.set('client_id', CLIENT_ID);
+	authUrl.searchParams.set('request_uri', response.request_uri);
+
+	return authUrl;
+};
+
+/**
+ * Finalize authorization
+ * @param params Search params
+ * @returns Session object, which you can use to instantiate user agents
+ */
+export const finalizeAuthorization = async (params: URLSearchParams) => {
+	const issuer = params.get('iss');
+	const state = params.get('state');
+	const code = params.get('code');
+	const error = params.get('error');
+
+	if (!state || !(code || error)) {
+		throw new LoginError(`missing parameters`);
+	}
+
+	const stored = database.states.get(state);
+	if (stored) {
+		// Delete now that we've caught it
+		database.states.delete(state);
+	} else {
+		throw new LoginError(`unknown state provided`);
+	}
+
+	const dpopKey = stored.dpopKey;
+	const metadata = stored.metadata;
+
+	if (error) {
+		throw new AuthorizationError(params.get('error_description') || error);
+	}
+	if (!code) {
+		throw new LoginError(`missing code parameter`);
+	}
+
+	if (issuer === null) {
+		throw new LoginError(`missing issuer parameter`);
+	} else if (issuer !== metadata.issuer) {
+		throw new LoginError(`issuer mismatch`);
+	}
+
+	// Retrieve authentication tokens
+	const server = new OAuthServerAgent(metadata, dpopKey);
+	const { info, token } = await server.exchangeCode(code, stored.verifier);
+
+	// We're finished!
+	const sub = info.sub;
+	const session: Session = { dpopKey, info, token };
+
+	await storeSession(sub, session);
+
+	return session;
+};

package/lib/agents/server-agent.ts

@@ -0,0 +1,149 @@
+import type { At } from '@atcute/client/lexicons';
+
+import { createDPoPFetch } from '../dpop.js';
+import { CLIENT_ID, REDIRECT_URI } from '../environment.js';
+import { FetchResponseError, OAuthResponseError, TokenRefreshError } from '../errors.js';
+import { resolveFromIdentity } from '../resolvers.js';
+import type { DPoPKey } from '../types/dpop.js';
+import type { OAuthParResponse } from '../types/par.js';
+import type { PersistedAuthorizationServerMetadata } from '../types/server.js';
+import type { ExchangeInfo, OAuthTokenResponse, TokenInfo } from '../types/token.js';
+import { pick } from '../utils/misc.js';
+import { extractContentType } from '../utils/response.js';
+
+export class OAuthServerAgent {
+	#fetch: typeof fetch;
+	#metadata: PersistedAuthorizationServerMetadata;
+
+	constructor(metadata: PersistedAuthorizationServerMetadata, dpopKey: DPoPKey) {
+		this.#metadata = metadata;
+		this.#fetch = createDPoPFetch(CLIENT_ID, dpopKey, true);
+	}
+
+	async request(
+		endpoint: 'pushed_authorization_request',
+		payload: Record<string, unknown>,
+	): Promise<OAuthParResponse>;
+	async request(endpoint: 'token', payload: Record<string, unknown>): Promise<OAuthTokenResponse>;
+	async request(endpoint: 'revocation', payload: Record<string, unknown>): Promise<any>;
+	async request(endpoint: 'introspection', payload: Record<string, unknown>): Promise<any>;
+	async request(endpoint: string, payload: Record<string, unknown>): Promise<any> {
+		const url: string | undefined = (this.#metadata as any)[`${endpoint}_endpoint`];
+		if (!url) {
+			throw new Error(`no endpoint for ${endpoint}`);
+		}
+
+		const response = await this.#fetch(url, {
+			method: 'post',
+			headers: { 'content-type': 'application/json' },
+			body: JSON.stringify({ ...payload, client_id: CLIENT_ID }),
+		});
+
+		if (extractContentType(response.headers) !== 'application/json') {
+			throw new FetchResponseError(response, 2, `unexpected content-type`);
+		}
+
+		const json = await response.json();
+
+		if (response.ok) {
+			return json;
+		} else {
+			throw new OAuthResponseError(response, json);
+		}
+	}
+
+	async revoke(token: string): Promise<void> {
+		try {
+			await this.request('revocation', { token: token });
+		} catch {}
+	}
+
+	async exchangeCode(code: string, verifier?: string): Promise<{ info: ExchangeInfo; token: TokenInfo }> {
+		const response = await this.request('token', {
+			grant_type: 'authorization_code',
+			redirect_uri: REDIRECT_URI,
+			code: code,
+			code_verifier: verifier,
+		});
+
+		try {
+			return await this.#processExchangeResponse(response);
+		} catch (err) {
+			await this.revoke(response.access_token);
+			throw err;
+		}
+	}
+
+	async refresh({ sub, token }: { sub: At.DID; token: TokenInfo }): Promise<TokenInfo> {
+		if (!token.refresh) {
+			throw new TokenRefreshError(sub, 'no refresh token available');
+		}
+
+		const response = await this.request('token', {
+			grant_type: 'refresh_token',
+			refresh_token: token.refresh,
+		});
+
+		try {
+			if (sub !== response.sub) {
+				throw new TokenRefreshError(sub, `sub mismatch in token response; got ${response.sub}`);
+			}
+
+			return this.#processTokenResponse(response);
+		} catch (err) {
+			await this.revoke(response.access_token);
+
+			throw err;
+		}
+	}
+
+	#processTokenResponse(res: OAuthTokenResponse): TokenInfo {
+		if (!res.sub) {
+			throw new TypeError(`missing sub field in token response`);
+		}
+		if (!res.scope) {
+			throw new TypeError(`missing scope field in token response`);
+		}
+		if (res.token_type !== 'DPoP') {
+			throw new TypeError(`token response returned a non-dpop token`);
+		}
+
+		return {
+			scope: res.scope,
+			refresh: res.refresh_token,
+			access: res.access_token,
+			type: res.token_type,
+			expires_at: typeof res.expires_in === 'number' ? Date.now() + res.expires_in * 1_000 : undefined,
+		};
+	}
+
+	async #processExchangeResponse(res: OAuthTokenResponse): Promise<{ info: ExchangeInfo; token: TokenInfo }> {
+		const sub = res.sub;
+		if (!sub) {
+			throw new TypeError(`missing sub field in token response`);
+		}
+
+		const token = this.#processTokenResponse(res);
+		const resolved = await resolveFromIdentity(sub);
+
+		if (resolved.metadata.issuer !== this.#metadata.issuer) {
+			throw new TypeError(`issuer mismatch; got ${resolved.metadata.issuer}`);
+		}
+
+		return {
+			token: token,
+			info: {
+				sub: sub as At.DID,
+				aud: resolved.identity.pds.href,
+				server: pick(resolved.metadata, [
+					'issuer',
+					'authorization_endpoint',
+					'introspection_endpoint',
+					'pushed_authorization_request_endpoint',
+					'revocation_endpoint',
+					'token_endpoint',
+				]),
+			},
+		};
+	}
+}

package/lib/agents/sessions.ts

@@ -0,0 +1,142 @@
+import type { At } from '@atcute/client/lexicons';
+
+import { database } from '../environment.js';
+import { OAuthResponseError, TokenRefreshError } from '../errors.js';
+import type { Session } from '../types/token.js';
+import { locks } from '../utils/runtime.js';
+
+import { OAuthServerAgent } from './server-agent.js';
+
+export interface SessionGetOptions {
+	signal?: AbortSignal;
+	noCache?: boolean;
+	allowStale?: boolean;
+}
+
+type PendingItem<V> = Promise<{ value: V; isFresh: boolean }>;
+const pending = new Map<At.DID, PendingItem<Session>>();
+
+export const getSession = async (sub: At.DID, options?: SessionGetOptions): Promise<Session> => {
+	options?.signal?.throwIfAborted();
+
+	let allowStored = isTokenUsable;
+	if (options?.noCache) {
+		allowStored = returnFalse;
+	} else if (options?.allowStale) {
+		allowStored = returnTrue;
+	}
+
+	// As long as concurrent requests are made for the same key, only one
+	// request will be made to the cache & getter function at a time. This works
+	// because there is no async operation between the while() loop and the
+	// pending.set() call. Because of the "single threaded" nature of
+	// JavaScript, the pending item will be set before the next iteration of the
+	// while loop.
+	let previousExecutionFlow: PendingItem<Session> | undefined;
+	while ((previousExecutionFlow = pending.get(sub))) {
+		try {
+			const { isFresh, value } = await previousExecutionFlow;
+
+			if (isFresh || allowStored(value)) {
+				return value;
+			}
+		} catch {
+			// Ignore errors from previous execution flows (they will have been
+			// propagated by that flow).
+		}
+
+		options?.signal?.throwIfAborted();
+	}
+
+	const run = async (): PendingItem<Session> => {
+		const storedSession = database.sessions.get(sub);
+
+		if (storedSession && allowStored(storedSession)) {
+			// Use the stored value as return value for the current execution
+			// flow. Notify other concurrent execution flows (that should be
+			// "stuck" in the loop before until this promise resolves) that we got
+			// a value, but that it came from the store (isFresh = false).
+			return { isFresh: false, value: storedSession };
+		}
+
+		const newSession = await refreshToken(sub, storedSession);
+
+		await storeSession(sub, newSession);
+		return { isFresh: true, value: newSession };
+	};
+
+	let promise: PendingItem<Session>;
+
+	if (locks) {
+		promise = locks.request(`atcute-oauth:${sub}`, run);
+	} else {
+		promise = run();
+	}
+
+	promise = promise.finally(() => pending.delete(sub));
+
+	if (pending.has(sub)) {
+		// This should never happen. Indeed, there must not be any 'await'
+		// statement between this and the loop iteration check meaning that
+		// this.pending.get returned undefined. It is there to catch bugs that
+		// would occur in future changes to the code.
+		throw new Error('concurrent request for the same key');
+	}
+
+	pending.set(sub, promise);
+
+	const { value } = await promise;
+	return value;
+};
+
+export const storeSession = async (sub: At.DID, newSession: Session): Promise<void> => {
+	try {
+		database.sessions.set(sub, newSession);
+	} catch (err) {
+		await onRefreshError(newSession);
+		throw err;
+	}
+};
+
+export const deleteStoredSession = (sub: At.DID): void => {
+	database.sessions.delete(sub);
+};
+
+export const listStoredSessions = (): At.DID[] => {
+	return database.sessions.keys();
+};
+
+const returnTrue = () => true;
+const returnFalse = () => false;
+
+const refreshToken = async (sub: At.DID, storedSession: Session | undefined): Promise<Session> => {
+	if (storedSession === undefined) {
+		throw new TokenRefreshError(sub, `session deleted by another tab`);
+	}
+
+	const { dpopKey, info, token } = storedSession;
+	const server = new OAuthServerAgent(info.server, dpopKey);
+
+	try {
+		const newToken = await server.refresh({ sub: info.sub, token });
+
+		return { dpopKey, info, token: newToken };
+	} catch (cause) {
+		if (cause instanceof OAuthResponseError && cause.status === 400 && cause.error === 'invalid_grant') {
+			throw new TokenRefreshError(sub, `session was revoked`, { cause });
+		}
+
+		throw cause;
+	}
+};
+
+const onRefreshError = async ({ dpopKey, info, token }: Session) => {
+	// If the token data cannot be stored, let's revoke it
+	const server = new OAuthServerAgent(info.server, dpopKey);
+	await server.revoke(token.refresh ?? token.access);
+};
+
+const isTokenUsable = ({ token }: Session): boolean => {
+	const expires = token.expires_at;
+	return expires == null || Date.now() + 60_000 <= expires;
+};

package/lib/agents/user-agent.ts

@@ -0,0 +1,99 @@
+import type { FetchHandlerObject } from '@atcute/client';
+import type { At } from '@atcute/client/lexicons';
+
+import { createDPoPFetch } from '../dpop.js';
+import { CLIENT_ID } from '../environment.js';
+import type { Session } from '../types/token.js';
+
+import { OAuthServerAgent } from './server-agent.js';
+import { type SessionGetOptions, deleteStoredSession, getSession } from './sessions.js';
+
+export class OAuthUserAgent implements FetchHandlerObject {
+	#fetch: typeof fetch;
+	#getSessionPromise: Promise<Session> | undefined;
+
+	constructor(public session: Session) {
+		this.#fetch = createDPoPFetch(CLIENT_ID, session.dpopKey, false);
+	}
+
+	get sub(): At.DID {
+		return this.session.info.sub;
+	}
+
+	getSession(options?: SessionGetOptions): Promise<Session> {
+		const promise = getSession(this.session.info.sub, options);
+
+		promise
+			.then((session) => {
+				this.session = session;
+			})
+			.finally(() => {
+				this.#getSessionPromise = undefined;
+			});
+
+		return (this.#getSessionPromise = promise);
+	}
+
+	async signOut(): Promise<void> {
+		const sub = this.session.info.sub;
+
+		try {
+			const { dpopKey, info, token } = await getSession(sub, { allowStale: true });
+			const server = new OAuthServerAgent(info.server, dpopKey);
+
+			await server.revoke(token.refresh ?? token.access);
+		} finally {
+			deleteStoredSession(sub);
+		}
+	}
+
+	async handle(pathname: string, init?: RequestInit): Promise<Response> {
+		await this.#getSessionPromise;
+
+		const headers = new Headers(init?.headers);
+
+		let session = this.session;
+		let url = new URL(pathname, session.info.aud);
+
+		headers.set('authorization', `${session.token.type} ${session.token.access}`);
+
+		let response = await this.#fetch(url, { ...init, headers });
+		if (!isInvalidTokenResponse(response)) {
+			return response;
+		}
+
+		try {
+			if (this.#getSessionPromise) {
+				session = await this.#getSessionPromise;
+			} else {
+				session = await this.getSession();
+			}
+		} catch {
+			return response;
+		}
+
+		// Stream already consumed, can't retry.
+		if (init?.body instanceof ReadableStream) {
+			return response;
+		}
+
+		url = new URL(pathname, session.info.aud);
+		headers.set('authorization', `${session.token.type} ${session.token.access}`);
+
+		return await this.#fetch(url, { ...init, headers });
+	}
+}
+
+const isInvalidTokenResponse = (response: Response) => {
+	if (response.status !== 401) {
+		return false;
+	}
+
+	const auth = response.headers.get('www-authenticate');
+
+	return (
+		auth != null &&
+		(auth.startsWith('Bearer ') || auth.startsWith('DPoP ')) &&
+		auth.includes('error="invalid_token"')
+	);
+};

package/lib/constants.ts

@@ -0,0 +1 @@
+export const DEFAULT_APPVIEW_URL = 'https://public.api.bsky.app';

package/lib/dpop.ts

@@ -0,0 +1,154 @@
+import { nanoid } from 'nanoid/non-secure';
+
+import { database } from './environment.js';
+import type { DPoPKey } from './types/dpop.js';
+import { extractContentType } from './utils/response.js';
+import { encoder, fromBase64Url, toBase64Url, toSha256 } from './utils/runtime.js';
+
+const ES256_ALG = { name: 'ECDSA', namedCurve: 'P-256' } as const;
+
+export const createES256Key = async (): Promise<DPoPKey> => {
+	const pair = await crypto.subtle.generateKey(ES256_ALG, true, ['sign', 'verify']);
+
+	const key = await crypto.subtle.exportKey('pkcs8', pair.privateKey);
+	const { ext: _ext, key_ops: _key_opts, ...jwk } = await crypto.subtle.exportKey('jwk', pair.publicKey);
+
+	return {
+		typ: 'ES256',
+		key: toBase64Url(new Uint8Array(key)),
+		jwt: toBase64Url(encoder.encode(JSON.stringify({ typ: 'dpop+jwt', alg: 'ES256', jwk: jwk }))),
+	};
+};
+
+export const createDPoPSignage = (issuer: string, dpopKey: DPoPKey) => {
+	const headerString = dpopKey.jwt;
+	const keyPromise = crypto.subtle.importKey('pkcs8', fromBase64Url(dpopKey.key), ES256_ALG, true, ['sign']);
+
+	const constructPayload = (
+		method: string,
+		url: string,
+		nonce: string | undefined,
+		ath: string | undefined,
+	) => {
+		const now = (Date.now() / 1_000) | 0;
+
+		const payload = {
+			iss: issuer,
+			iat: now,
+			// This seems fine, we can remake the request if it fails.
+			jti: nanoid(12),
+			htm: method,
+			htu: url,
+			nonce: nonce,
+			ath: ath,
+		};
+
+		return toBase64Url(encoder.encode(JSON.stringify(payload)));
+	};
+
+	return async (method: string, url: string, nonce: string | undefined, ath: string | undefined) => {
+		const payloadString = constructPayload(method, url, nonce, ath);
+
+		const signed = await crypto.subtle.sign(
+			{ name: 'ECDSA', hash: { name: 'SHA-256' } },
+			await keyPromise,
+			encoder.encode(headerString + '.' + payloadString),
+		);
+
+		const signatureString = toBase64Url(new Uint8Array(signed));
+
+		return headerString + '.' + payloadString + '.' + signatureString;
+	};
+};
+
+export const createDPoPFetch = (issuer: string, dpopKey: DPoPKey, isAuthServer?: boolean): typeof fetch => {
+	const nonces = database.dpopNonces;
+	const sign = createDPoPSignage(issuer, dpopKey);
+
+	return async (input, init) => {
+		const request: Request = init == null && input instanceof Request ? input : new Request(input, init);
+
+		const authorizationHeader = request.headers.get('authorization');
+		const ath = authorizationHeader?.startsWith('DPoP ')
+			? await toSha256(authorizationHeader.slice(5))
+			: undefined;
+
+		const { method, url } = request;
+		const { origin } = new URL(url);
+
+		let initNonce: string | undefined;
+		try {
+			initNonce = nonces.get(origin);
+		} catch {
+			// Ignore get errors, we will just not send a nonce
+		}
+
+		const initProof = await sign(method, url, initNonce, ath);
+		request.headers.set('dpop', initProof);
+
+		const initResponse = await fetch(request);
+
+		const nextNonce = initResponse.headers.get('dpop-nonce');
+		if (!nextNonce || nextNonce === initNonce) {
+			// No nonce was returned or it is the same as the one we sent. No need to
+			// update the nonce store, or retry the request.
+			return initResponse;
+		}
+
+		// Store the fresh nonce for future requests
+		try {
+			nonces.set(origin, nextNonce);
+		} catch {
+			// Ignore set errors
+		}
+
+		const shouldRetry = await isUseDpopNonceError(initResponse, isAuthServer);
+		if (!shouldRetry) {
+			// Not a "use_dpop_nonce" error, so there is no need to retry
+			return initResponse;
+		}
+
+		// If the input stream was already consumed, we cannot retry the request. A
+		// solution would be to clone() the request but that would bufferize the
+		// entire stream in memory which can lead to memory starvation. Instead, we
+		// will return the original response and let the calling code handle retries.
+
+		if (input === request || init?.body instanceof ReadableStream) {
+			return initResponse;
+		}
+
+		const nextProof = await sign(method, url, nextNonce, ath);
+		const nextRequest = new Request(input, init);
+		nextRequest.headers.set('dpop', nextProof);
+
+		return await fetch(nextRequest);
+	};
+};
+
+const isUseDpopNonceError = async (response: Response, isAuthServer?: boolean): Promise<boolean> => {
+	// https://datatracker.ietf.org/doc/html/rfc6750#section-3
+	// https://datatracker.ietf.org/doc/html/rfc9449#name-resource-server-provided-no
+	if (isAuthServer === undefined || isAuthServer === false) {
+		if (response.status === 401) {
+			const wwwAuth = response.headers.get('www-authenticate');
+			if (wwwAuth?.startsWith('DPoP')) {
+				return wwwAuth.includes('error="use_dpop_nonce"');
+			}
+		}
+	}
+
+	// https://datatracker.ietf.org/doc/html/rfc9449#name-authorization-server-provid
+	if (isAuthServer === undefined || isAuthServer === true) {
+		if (response.status === 400 && extractContentType(response.headers) === 'application/json') {
+			try {
+				const json = await response.clone().json();
+				return typeof json === 'object' && json?.['error'] === 'use_dpop_nonce';
+			} catch {
+				// Response too big (to be "use_dpop_nonce" error) or invalid JSON
+				return false;
+			}
+		}
+	}
+
+	return false;
+};

package/lib/environment.ts

@@ -0,0 +1,27 @@
+import { createOAuthDatabase, type OAuthDatabase } from './store/db.js';
+
+export let CLIENT_ID: string;
+export let REDIRECT_URI: string;
+
+export let database: OAuthDatabase;
+
+export interface ConfigureOAuthOptions {
+	/**
+	 * Client metadata, necessary to drive the whole request
+	 */
+	metadata: {
+		client_id: string;
+		redirect_uri: string;
+	};
+
+	/**
+	 * Name that will be used as prefix for storage keys needed to persist authentication.
+	 * @default "atcute-oauth"
+	 */
+	storageName?: string;
+}
+
+export const configureOAuth = (options: ConfigureOAuthOptions) => {
+	({ client_id: CLIENT_ID, redirect_uri: REDIRECT_URI } = options.metadata);
+	database = createOAuthDatabase({ name: options.storageName ?? 'atcute-oauth' });
+};