@atcute/oauth-browser-client 1.0.3 → 1.0.5

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' });
+};

package/lib/errors.ts

@@ -0,0 +1,76 @@
+import type { At } from '@atcute/client/lexicons';
+
+export class LoginError extends Error {
+	override name = 'LoginError';
+}
+
+export class AuthorizationError extends Error {
+	override name = 'AuthorizationError';
+}
+
+export class ResolverError extends Error {
+	override name = 'ResolverError';
+}
+
+export class TokenRefreshError extends Error {
+	override name = 'TokenRefreshError';
+
+	constructor(
+		public readonly sub: At.DID,
+		message: string,
+		options?: ErrorOptions,
+	) {
+		super(message, options);
+	}
+}
+
+export class OAuthResponseError extends Error {
+	override name = 'OAuthResponseError';
+
+	readonly error: string | undefined;
+	readonly description: string | undefined;
+
+	constructor(
+		public readonly response: Response,
+		public readonly data: any,
+	) {
+		const error = ifString(ifObject(data)?.['error']);
+		const errorDescription = ifString(ifObject(data)?.['error_description']);
+
+		const messageError = error ? `"${error}"` : 'unknown';
+		const messageDesc = errorDescription ? `: ${errorDescription}` : '';
+		const message = `OAuth ${messageError} error${messageDesc}`;
+
+		super(message);
+
+		this.error = error;
+		this.description = errorDescription;
+	}
+
+	get status() {
+		return this.response.status;
+	}
+
+	get headers() {
+		return this.response.headers;
+	}
+}
+
+export class FetchResponseError extends Error {
+	override name = 'FetchResponseError';
+
+	constructor(
+		public readonly response: Response,
+		public status: number,
+		message: string,
+	) {
+		super(message);
+	}
+}
+
+const ifString = (v: unknown): string | undefined => {
+	return typeof v === 'string' ? v : undefined;
+};
+const ifObject = (v: unknown): Record<string, unknown> | undefined => {
+	return typeof v === 'object' && v !== null && !Array.isArray(v) ? (v as any) : undefined;
+};

package/lib/index.ts

@@ -0,0 +1,17 @@
+export { configureOAuth, type ConfigureOAuthOptions } from './environment.js';
+
+export * from './errors.js';
+export * from './resolvers.js';
+
+export * from './agents/exchange.js';
+export * from './agents/server-agent.js';
+export * from './agents/sessions.js';
+export * from './agents/user-agent.js';
+
+export * from './types/client.js';
+export * from './types/dpop.js';
+export * from './types/identity.js';
+export * from './types/par.js';
+export * from './types/server.js';
+export * from './types/store.js';
+export * from './types/token.js';