feat(oauth-browser-client): initial commit

README.md

···
 			<td><code>whitewind</code>: adds <code>com.whtwnd.*</code> definitions</td>
 		</tr>
 		<tr>
+			<th colspan="2" align="left">OAuth packages</th>
+		</tr>
+		<tr>
+			<td><code>oauth-browser-client</code>: minimal OAuth browser client implementation</td>
+		</tr>
+		<tr>
 			<th colspan="2" align="left">Utility packages</th>
 		</tr>
 		<tr>

packages/oauth/browser-client/README.md

···
+# @atcute/oauth-browser-client
+
+minimal OAuth browser client implementation for AT Protocol.
+
+- **only the bare minimum**: enough code to get authentication reasonably working, with only one
+  happy path is supported (only ES256 keys for DPoP. PKCE and DPoP-bound PAR is required.)
+- **does not use IndexedDB**: makes the library work under Safari's lockdown mode, and has less
+  [maintenance headache][indexeddb-woes] overall, but it also means this is "less secure" (it won't
+  be able to use non-exportable keys as recommended by [DPoP specification][idb-dpop-spec].)
+- **no independent DNS/HTTP handle checks**: the default handle resolver makes use of Bluesky's
+  AppView to retrieve the correct DID identifier. you should be able to write your own resolver
+  function that'll resolve via DNS-over-HTTPS or via other PDSes.
+- **not well-tested**: it has been used in personal projects for quite some time, but hasn't seen
+  any use outside of that. using the [reference implementation][oauth-atproto-lib] is recommended if
+  you are unsure about the implications presented here.
+
+[indexeddb-woes]: https://gist.github.com/pesterhazy/4de96193af89a6dd5ce682ce2adff49a
+[idb-dpop-spec]: https://datatracker.ietf.org/doc/html/rfc9449#section-2-4
+[oauth-atproto-lib]: https://npm.im/@atproto/oauth-client-browser
+
+## usage
+
+### setup
+
+initialize the client by importing and calling `configureOAuth` with the client ID and redirect URL.
+this call should be placed before any other calls you make with this library.
+
+```ts
+import { configureOAuth } from '@atcute/oauth-browser-client';
+
+configureOAuth({
+	metadata: {
+		client_id: 'https://example.com/oauth/client-metadata.json',
+		redirect_uri: 'https://example.com/oauth/callback',
+	},
+});
+```
+
+### starting an authorization flow
+
+if your application involves asking for the user's handle or DID, you can use `resolveFromIdentity`
+which resolves the user's identity to get its PDS, and the metadata of its authorization server.
+
+```ts
+import { resolveFromIdentity } from '@atcute/oauth-browser-client';
+
+const { identity, metadata } = await resolveFromIdentity('mary.my.id');
+```
+
+alternatively, if it involves asking for the user's PDS, then you can use `resolveFromService` which
+just grabs the authorization server metadata.
+
+```ts
+import { resolveFromService } from '@atcute/oauth-browser-client';
+
+const { metadata } = await resolveFromService('bsky.social');
+```
+
+we can then proceed with authorization by calling `createAuthorizationUrl` with the resolved
+`metadata` (and `identity`, if using `resolveFromIdentity`) along with the scope of the
+authorization, which should either match the one in your client metadata, or a reduced set of it.
+
+```ts
+import { createAuthorizationUrl } from '@atcute/oauth-browser-client';
+
+// passing `identity` is optional,
+// it allows for the login form to be autofilled with the user's handle or DID
+const authUrl = await createAuthorizationUrl({
+	metadata: metadata,
+	identity: identity,
+	scope: 'atproto transition:generic transition:chat.bsky',
+});
+
+// recommended to wait for the browser to persist local storage before proceeding
+await sleep(200);
+
+// redirect the user to sign in and authorize the app
+window.location.assign(authUrl);
+
+// if this is on an async function, ideally the function should never ever resolve.
+// the only way it should resolve at this point is if the user aborted the authorization
+// by returning back to this page (thanks to back-forward page caching)
+await new Promise((_resolve, reject) => {
+	const listener = () => {
+		reject(new Error(`user aborted the login request`));
+	};
+
+	window.addEventListener('pageshow', listener, { once: true });
+});
+```
+
+### finalizing authorization
+
+once the user has been redirected to your redirect URL, we can call `finalizeAuthorization` with the
+parameters that have been provided.
+
+```ts
+import { XRPC } from '@atcute/client';
+import { OAuthUserAgent, finalizeAuthorization } from '@atcute/oauth-browser-client';
+
+// `createAuthorizationUrl` asks for the server to redirect here with the
+// parameters assigned in the hash, not the search string.
+const params = new URLSearchParams(location.hash.slice(1));
+
+// this is optional, but after retrieving the parameters, we should ideally
+// scrub it from history to prevent this authorization state to be replayed,
+// just for good measure.
+history.replaceState(null, '', location.pathname + location.search);
+
+// you'd be given a session object that you can then pass to OAuthUserAgent!
+const session = await finalizeAuthorization(params);
+
+// now you can start making requests!
+const agent = new OAuthUserAgent(session);
+
+// pass it onto the XRPC so you can make RPC calls with the PDS.
+const rpc = new XRPC({ handler: agent });
+```
+
+the `session` object returned by `finalizeAuthorization` should not be stored anywhere else, as it
+is already persisted in the internal database. you are expected to keep track of who's signed in and
+who was last signed in for your own UI, as the sessions stored by the database is not guaranteed to
+be permanent (mostly if they don't come with a refresh token.)
+
+### resuming existing sessions
+
+you can resume existing sessions by calling `getSession` with the DID identifier you intend to
+resume.
+
+```ts
+import { XRPC } from '@atcute/client';
+import { OAuthUserAgent, getSession } from '@atcute/oauth-browser-client';
+
+const session = await getSession('did:plc:ia76kvnndjutgedggx2ibrem', { allowStale: true });
+
+const agent = new OAuthUserAgent(session);
+const rpc = new XRPC({ handler: agent });
+```
+
+### removing sessions
+
+you can manually remove sessions via `deleteStoredSession`, but ideally, you should revoke the token
+first before doing so.
+
+```ts
+import { OAuthUserAgent, deleteStoredSession, getSession } from '@atcute/oauth-browser-client';
+
+const did = 'did:plc:ia76kvnndjutgedggx2ibrem';
+
+try {
+	const session = await getSession(did, { allowStale: true });
+	const agent = new OAuthUserAgent(session);
+
+	await agent.signOut();
+} catch (err) {
+	// `signOut` also deletes the session, we only serve as fallback if it fails.
+	deleteStoredSession(did);
+}
+```

packages/oauth/browser-client/lib/agents/exchange.ts

···
+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;
+};

packages/oauth/browser-client/lib/agents/server-agent.ts

···
+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 {
+		const sub = res.sub;
+		const scope = res.scope;
+		if (!sub) {
+			throw new TypeError(`missing sub field in token response`);
+		}
+		if (!scope) {
+			throw new TypeError(`missing scope field in token response`);
+		}
+
+		return {
+			scope: scope,
+			refresh: res.refresh_token,
+			access: res.access_token,
+			type: res.token_type ?? 'Bearer',
+			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',
+				]),
+			},
+		};
+	}
+}

packages/oauth/browser-client/lib/agents/sessions.ts

···
+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 { 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 lockKey = `atcute-oauth:${sub}`;
+
+	let promise: PendingItem<Session>;
+
+	promise = navigator.locks.request(lockKey, async (): PendingItem<Session> => {
+		const storedSession = database.sessions.get(sub);
+
+		console.log(storedSession, allowStored);
+
+		if (storedSession && allowStored(storedSession)) {
+			console.log('true');
+			// 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 };
+		}
+
+		console.log('false');
+
+		const newSession = await refreshToken(sub, storedSession);
+
+		await storeSession(sub, newSession);
+		return { isFresh: true, value: newSession };
+	});
+
+	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;
+};

packages/oauth/browser-client/lib/agents/user-agent.ts

···
+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 did(): 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"')
+	);
+};

packages/oauth/browser-client/lib/constants.ts

···
+export const DEFAULT_APPVIEW_URL = 'https://public.api.bsky.app';

packages/oauth/browser-client/lib/dpop.ts

···
+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;
+};

packages/oauth/browser-client/lib/environment.ts

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

packages/oauth/browser-client/lib/errors.ts

···
+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;
+};

packages/oauth/browser-client/lib/index.ts

···
+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';

packages/oauth/browser-client/lib/resolvers.ts

···
+import type { At, ComAtprotoIdentityResolveHandle } from '@atcute/client/lexicons';
+import { type DidDocument, getPdsEndpoint } from '@atcute/client/utils/did';
+
+import { DEFAULT_APPVIEW_URL } from './constants.js';
+import { ResolverError } from './errors.js';
+import type { IdentityMetadata } from './types/identity.js';
+import type { AuthorizationServerMetadata, ProtectedResourceMetadata } from './types/server.js';
+import { extractContentType } from './utils/response.js';
+import { isDid } from './utils/strings.js';
+
+const DID_WEB_RE = /^([a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*(?:\.[a-zA-Z]{2,}))$/;
+
+/**
+ * Resolves domain handles into DID identifiers, by requesting Bluesky's AppView
+ * for identity resolution.
+ * @param handle Domain handle to resolve
+ * @returns DID identifier resolved from the domain handle
+ */
+export const resolveHandle = async (handle: string): Promise<At.DID> => {
+	const url = DEFAULT_APPVIEW_URL + `/xrpc/com.atproto.identity.resolveHandle` + `?handle=${handle}`;
+
+	const response = await fetch(url);
+	if (response.status === 400) {
+		throw new ResolverError(`domain handle not found`);
+	} else if (!response.ok) {
+		throw new ResolverError(`directory is unreachable`);
+	}
+
+	const json = (await response.json()) as ComAtprotoIdentityResolveHandle.Output;
+	return json.did;
+};
+
+/**
+ * Get DID documents of did:plc (via plc.directory) and did:web identifiers
+ * @param did DID identifier we're seeking DID doc from
+ * @returns Retrieved DID document
+ */
+export const getDidDocument = async (did: At.DID): Promise<DidDocument> => {
+	const colon_index = did.indexOf(':', 4);
+
+	const type = did.slice(4, colon_index);
+	const ident = did.slice(colon_index + 1);
+
+	// 2. retrieve their DID documents
+	let doc: DidDocument;
+
+	if (type === 'plc') {
+		const response = await fetch(`https://plc.directory/${did}`);
+
+		if (response.status === 404) {
+			throw new ResolverError(`did not found in directory`);
+		} else if (!response.ok) {
+			throw new ResolverError(`directory is unreachable`);
+		}
+
+		const json = await response.json();
+
+		doc = json as DidDocument;
+	} else if (type === 'web') {
+		if (!DID_WEB_RE.test(ident)) {
+			throw new ResolverError(`invalid identifier`);
+		}
+
+		const response = await fetch(`https://${ident}/.well-known/did.json`);
+
+		if (!response.ok) {
+			throw new ResolverError(`did document is unreachable`);
+		}
+
+		const json = await response.json();
+
+		doc = json as DidDocument;
+	} else {
+		throw new ResolverError(`unsupported did method`);
+	}
+
+	return doc;
+};
+
+/**
+ * Get OAuth protected resource metadata from a host
+ * @param host URL of the host
+ * @returns Retrieved protected resource metadata
+ */
+export const getProtectedResourceMetadata = async (host: string): Promise<ProtectedResourceMetadata> => {
+	const url = new URL(`/.well-known/oauth-protected-resource`, host);
+	const response = await fetch(url, {
+		redirect: 'manual',
+		headers: {
+			accept: 'application/json',
+		},
+	});
+
+	if (response.status !== 200 || extractContentType(response.headers) !== 'application/json') {
+		throw new ResolverError(`unexpected response`);
+	}
+
+	const metadata = (await response.json()) as ProtectedResourceMetadata;
+	if (metadata.resource !== url.origin) {
+		throw new ResolverError(`unexpected issuer`);
+	}
+
+	return metadata;
+};
+
+/**
+ * Get OAuth authorization server metadata from a host
+ * @param host URL of the host
+ * @returns Retrieved authorization server metadata
+ */
+export const getAuthorizationServerMetadata = async (host: string): Promise<AuthorizationServerMetadata> => {
+	const url = new URL(`/.well-known/oauth-authorization-server`, host);
+	const response = await fetch(url, {
+		redirect: 'manual',
+		headers: {
+			accept: 'application/json',
+		},
+	});
+
+	if (response.status !== 200 || extractContentType(response.headers) !== 'application/json') {
+		throw new ResolverError(`unexpected response`);
+	}
+
+	const metadata = (await response.json()) as AuthorizationServerMetadata;
+	if (metadata.issuer !== url.origin) {
+		throw new ResolverError(`unexpected issuer`);
+	}
+	if (!metadata.client_id_metadata_document_supported) {
+		throw new ResolverError(`authorization server does not support 'client_id_metadata_document'`);
+	}
+	if (!metadata.pushed_authorization_request_endpoint) {
+		throw new ResolverError(`authorization server does not support 'pushed_authorization request'`);
+	}
+	if (metadata.response_types_supported) {
+		if (!metadata.response_types_supported.includes('code')) {
+			throw new ResolverError(`authorization server does not support 'code' response type`);
+		}
+	}
+
+	return metadata;
+};
+
+/**
+ * Resolve handle domains or DID identifiers to get their PDS and its authorization server metadata
+ * @param ident Handle domain or DID identifier to resolve
+ * @returns Resolved PDS and authorization server metadata
+ */
+export const resolveFromIdentity = async (
+	ident: string,
+): Promise<{ identity: IdentityMetadata; metadata: AuthorizationServerMetadata }> => {
+	let did: At.DID;
+	if (isDid(ident)) {
+		did = ident;
+	} else {
+		const resolved = await resolveHandle(ident);
+		did = resolved;
+	}
+
+	const doc = await getDidDocument(did);
+	const pds = getPdsEndpoint(doc);
+
+	if (!pds) {
+		throw new ResolverError(`missing pds endpoint`);
+	}
+
+	return {
+		identity: {
+			id: did,
+			raw: ident,
+			pds: new URL(pds),
+		},
+		metadata: await getMetadataFromResourceServer(pds),
+	};
+};
+
+/**
+ * Request authorization server metadata from a PDS
+ * @param host URL of the host
+ * @returns Resolved authorization server metadata
+ */
+export const resolveFromService = async (
+	host: string,
+): Promise<{ metadata: AuthorizationServerMetadata }> => {
+	try {
+		const metadata = await getMetadataFromResourceServer(host);
+		return { metadata };
+	} catch (err) {
+		if (err instanceof ResolverError) {
+			try {
+				const metadata = await getAuthorizationServerMetadata(host);
+				return { metadata };
+			} catch {}
+		}
+
+		throw err;
+	}
+};
+
+/**
+ * Request authorization server metadata from its protected resource metadata
+ * @param input URL of the host whose authorization server is delegated
+ * @returns Resolved authorization server metadata
+ */
+export const getMetadataFromResourceServer = async (input: string) => {
+	const rs_metadata = await getProtectedResourceMetadata(input);
+
+	if (rs_metadata.authorization_servers?.length !== 1) {
+		throw new ResolverError(`expected exactly one authorization server in the listing`);
+	}
+
+	const issuer = rs_metadata.authorization_servers[0];
+
+	const as_metadata = await getAuthorizationServerMetadata(issuer);
+
+	if (as_metadata.protected_resources) {
+		if (!as_metadata.protected_resources.includes(rs_metadata.resource)) {
+			throw new ResolverError(`server is not in authorization server's jurisdiction`);
+		}
+	}
+
+	return as_metadata;
+};

packages/oauth/browser-client/lib/store/db.ts

···
+import type { At } from '@atcute/client/lexicons';
+
+import type { DPoPKey } from '../types/dpop.js';
+import type { AuthorizationServerMetadata } from '../types/server.js';
+import type { SimpleStore } from '../types/store.js';
+import type { Session } from '../types/token.js';
+import { locks } from '../utils/runtime.js';
+
+export interface OAuthDatabaseOptions {
+	name: string;
+}
+
+interface SchemaItem<T> {
+	value: T;
+	expiresAt: number | null;
+}
+
+interface Schema {
+	sessions: {
+		key: At.DID;
+		value: Session;
+		indexes: {
+			expiresAt: number;
+		};
+	};
+	states: {
+		key: string;
+		value: {
+			dpopKey: DPoPKey;
+			metadata: AuthorizationServerMetadata;
+			verifier?: string;
+		};
+	};
+
+	dpopNonces: {
+		key: string;
+		value: string;
+	};
+}
+
+const parse = (raw: string | null) => {
+	if (raw != null) {
+		const parsed = JSON.parse(raw);
+		if (parsed != null) {
+			return parsed;
+		}
+	}
+
+	return {};
+};
+
+export type OAuthDatabase = ReturnType<typeof createOAuthDatabase>;
+
+export const createOAuthDatabase = ({ name }: OAuthDatabaseOptions) => {
+	const controller = new AbortController();
+	const signal = controller.signal;
+
+	const createStore = <N extends keyof Schema>(
+		subname: N,
+		expiresAt: (item: Schema[N]['value']) => null | number,
+	): SimpleStore<Schema[N]['key'], Schema[N]['value']> => {
+		let store: any;
+
+		const storageKey = `${name}:${subname}`;
+
+		const persist = () => store && localStorage.setItem(storageKey, JSON.stringify(store));
+		const read = () => {
+			if (signal.aborted) {
+				throw new Error(`store closed`);
+			}
+
+			return (store ??= parse(localStorage.getItem(storageKey)));
+		};
+
+		{
+			const listener = (ev: StorageEvent) => {
+				if (ev.key === storageKey) {
+					store = undefined;
+				}
+			};
+
+			window.addEventListener('storage', listener, { signal });
+		}
+
+		locks.request(`${storageKey}:cleanup`, { ifAvailable: true }, async (lock) => {
+			if (!lock || signal.aborted) {
+				return;
+			}
+
+			await new Promise((resolve) => setTimeout(resolve, 10_000));
+			if (signal.aborted) {
+				return;
+			}
+
+			let now = Date.now();
+			let changed = false;
+
+			read();
+
+			for (const key in store) {
+				const item = store[key];
+				const expiresAt = item.expiresAt;
+
+				if (expiresAt !== null && now > expiresAt) {
+					changed = true;
+					delete store[key];
+				}
+			}
+
+			if (changed) {
+				persist();
+			}
+		});
+
+		return {
+			get(key) {
+				read();
+
+				const item: SchemaItem<Schema[N]['value']> = store[key];
+				if (!item) {
+					return;
+				}
+
+				const expiresAt = item.expiresAt;
+				if (expiresAt !== null && Date.now() > expiresAt) {
+					delete store[key];
+					persist();
+
+					return;
+				}
+
+				return item.value;
+			},
+			set(key, value) {
+				read();
+
+				const item: SchemaItem<Schema[N]['value']> = {
+					expiresAt: expiresAt(value),
+					value: value,
+				};
+
+				store[key] = item;
+				persist();
+			},
+			delete(key) {
+				read();
+
+				if (store[key] !== undefined) {
+					delete store[key];
+					persist();
+				}
+			},
+			keys() {
+				read();
+
+				return Object.keys(store);
+			},
+		};
+	};
+
+	return {
+		dispose: () => {
+			controller.abort();
+		},
+
+		sessions: createStore('sessions', ({ token }) => {
+			if (token.refresh) {
+				return null;
+			}
+
+			return token.expires_at ?? null;
+		}),
+		states: createStore('states', (_item) => Date.now() + 10 * 60 * 1_000),
+		dpopNonces: createStore('dpopNonces', (_item) => Date.now() + 10 * 60 * 1_000),
+	};
+};

packages/oauth/browser-client/lib/types/client.ts

···
+export interface ClientMetadata {
+	redirect_uris: string[];
+	response_types: (
+		| 'code'
+		| 'token'
+		| 'none'
+		| 'code id_token token'
+		| 'code id_token'
+		| 'code token'
+		| 'id_token token'
+		| 'id_token'
+	)[];
+	grant_types: (
+		| 'authorization_code'
+		| 'implicit'
+		| 'refresh_token'
+		| 'password'
+		| 'client_credentials'
+		| 'urn:ietf:params:oauth:grant-type:jwt-bearer'
+		| 'urn:ietf:params:oauth:grant-type:saml2-bearer'
+	)[];
+	scope?: string;
+	token_endpoint_auth_method?:
+		| 'none'
+		| 'client_secret_basic'
+		| 'client_secret_jwt'
+		| 'client_secret_post'
+		| 'private_key_jwt'
+		| 'self_signed_tls_client_auth'
+		| 'tls_client_auth';
+	token_endpoint_auth_signing_alg?: string;
+	introspection_endpoint_auth_method?:
+		| 'none'
+		| 'client_secret_basic'
+		| 'client_secret_jwt'
+		| 'client_secret_post'
+		| 'private_key_jwt'
+		| 'self_signed_tls_client_auth'
+		| 'tls_client_auth';
+	introspection_endpoint_auth_signing_alg?: string;
+	revocation_endpoint_auth_method?:
+		| 'none'
+		| 'client_secret_basic'
+		| 'client_secret_jwt'
+		| 'client_secret_post'
+		| 'private_key_jwt'
+		| 'self_signed_tls_client_auth'
+		| 'tls_client_auth';
+	revocation_endpoint_auth_signing_alg?: string;
+	pushed_authorization_request_endpoint_auth_method?:
+		| 'none'
+		| 'client_secret_basic'
+		| 'client_secret_jwt'
+		| 'client_secret_post'
+		| 'private_key_jwt'
+		| 'self_signed_tls_client_auth'
+		| 'tls_client_auth';
+	pushed_authorization_request_endpoint_auth_signing_alg?: string;
+	userinfo_signed_response_alg?: string;
+	userinfo_encrypted_response_alg?: string;
+	jwks_uri?: string;
+	jwks?: unknown;
+	application_type?: 'web' | 'native';
+	subject_type?: 'public' | 'pairwise';
+	request_object_signing_alg?: string;
+	id_token_signed_response_alg?: string;
+	authorization_signed_response_alg?: string;
+	authorization_encrypted_response_enc?: 'A128CBC-HS256';
+	authorization_encrypted_response_alg?: string;
+	client_id?: string;
+	client_name?: string;
+	client_uri?: string;
+	policy_uri?: string;
+	tos_uri?: string;
+	logo_uri?: string;
+	default_max_age?: number;
+	require_auth_time?: boolean;
+	contacts?: string[];
+	tls_client_certificate_bound_access_tokens?: boolean;
+	dpop_bound_access_tokens?: boolean;
+	authorization_details_types?: string[];
+}

packages/oauth/browser-client/lib/types/dpop.ts

···
+export interface DPoPKey {
+	typ: 'ES256';
+	/** private key in base64url-encoded pkcs #8 */
+	key: string;
+	/** base64url-encoded jwt token */
+	jwt: string;
+}

packages/oauth/browser-client/lib/types/identity.ts

···
+import type { At } from '@atcute/client/lexicons';
+
+export interface IdentityMetadata {
+	id: At.DID;
+	raw: string;
+	pds: URL;
+}

packages/oauth/browser-client/lib/types/par.ts

···
+export interface OAuthParResponse {
+	request_uri: string;
+	expires_in: number;
+}

packages/oauth/browser-client/lib/types/server.ts

···
+export interface ProtectedResourceMetadata {
+	resource: string;
+	jwks_uri?: string;
+	authorization_servers?: string[];
+	scopes_supported?: string[];
+	bearer_methods_supported?: ('header' | 'body' | 'query')[];
+	resource_signing_alg_values_supported?: string[];
+	resource_documentation?: string;
+	resource_policy_uri?: string;
+	resource_tos_uri?: string;
+}
+
+export interface AuthorizationServerMetadata {
+	issuer: string;
+	authorization_endpoint: string;
+	token_endpoint: string;
+	jwks_uri?: string;
+	scopes_supported?: string[];
+	claims_supported?: string[];
+	claims_locales_supported?: string[];
+	claims_parameter_supported?: boolean;
+	request_parameter_supported?: boolean;
+	request_uri_parameter_supported?: boolean;
+	require_request_uri_registration?: boolean;
+	subject_types_supported?: string[];
+	response_types_supported?: string[];
+	response_modes_supported?: string[];
+	grant_types_supported?: string[];
+	code_challenge_methods_supported?: string[];
+	ui_locales_supported?: string[];
+	id_token_signing_alg_values_supported?: string[];
+	display_values_supported?: string[];
+	request_object_signing_alg_values_supported?: string[];
+	authorization_response_iss_parameter_supported?: boolean;
+	authorization_details_types_supported?: string[];
+	request_object_encryption_alg_values_supported?: string[];
+	request_object_encryption_enc_values_supported?: string[];
+	token_endpoint_auth_methods_supported?: string[];
+	token_endpoint_auth_signing_alg_values_supported?: string[];
+	revocation_endpoint?: string;
+	revocation_endpoint_auth_methods_supported?: string[];
+	revocation_endpoint_auth_signing_alg_values_supported?: string[];
+	introspection_endpoint?: string;
+	introspection_endpoint_auth_methods_supported?: string[];
+	introspection_endpoint_auth_signing_alg_values_supported?: string[];
+	pushed_authorization_request_endpoint?: string;
+	pushed_authorization_request_endpoint_auth_methods_supported?: string[];
+	pushed_authorization_request_endpoint_auth_signing_alg_values_supported?: string[];
+	require_pushed_authorization_requests?: boolean;
+	userinfo_endpoint?: string;
+	end_session_endpoint?: string;
+	registration_endpoint?: string;
+	dpop_signing_alg_values_supported?: string[];
+	protected_resources?: string[];
+	client_id_metadata_document_supported?: boolean;
+}
+
+export interface PersistedAuthorizationServerMetadata
+	extends Pick<
+		AuthorizationServerMetadata,
+		| 'issuer'
+		| 'authorization_endpoint'
+		| 'introspection_endpoint'
+		| 'pushed_authorization_request_endpoint'
+		| 'revocation_endpoint'
+		| 'token_endpoint'
+	> {}

packages/oauth/browser-client/lib/types/store.ts

···
+export interface SimpleStore<K extends string | number, V extends {} | null> {
+	get: (key: K) => undefined | V;
+	set: (key: K, value: V) => void;
+	delete: (key: K) => void;
+	keys: () => K[];
+}

packages/oauth/browser-client/lib/types/token.ts

···
+import type { At } from '@atcute/client/lexicons';
+
+import type { DPoPKey } from './dpop.js';
+import type { PersistedAuthorizationServerMetadata } from './server.js';
+
+export interface OAuthTokenResponse {
+	access_token: string;
+	// Can be DPoP or Bearer, normalize casing.
+	token_type: string;
+	issuer?: string;
+	sub?: string;
+	scope?: string;
+	id_token?: `${string}.${string}.${string}`;
+	refresh_token?: string;
+	expires_in?: number;
+	authorization_details?:
+		| {
+				type: string;
+				locations?: string[];
+				actions?: string[];
+				datatypes?: string[];
+				identifier?: string;
+				privileges?: string[];
+		  }[]
+		| undefined;
+}
+
+export interface TokenInfo {
+	scope: string;
+	type: string;
+	expires_at?: number;
+	refresh?: string;
+	access: string;
+}
+
+export interface ExchangeInfo {
+	sub: At.DID;
+	aud: string;
+	server: PersistedAuthorizationServerMetadata;
+}
+
+export interface Session {
+	dpopKey: DPoPKey;
+	info: ExchangeInfo;
+	token: TokenInfo;
+}

packages/oauth/browser-client/lib/utils/misc.ts

···
+type UnwrapArray<T> = T extends (infer V)[] ? V : never;
+
+export const pick = <T, K extends (keyof T)[]>(obj: T, keys: K): Pick<T, UnwrapArray<K>> => {
+	const cloned = {};
+
+	for (let idx = 0, len = keys.length; idx < len; idx++) {
+		const key = keys[idx];
+
+		// @ts-expect-error
+		cloned[key] = obj[key];
+	}
+
+	return cloned as Pick<T, UnwrapArray<K>>;
+};

packages/oauth/browser-client/lib/utils/response.ts

···
+export const extractContentType = (headers: Headers): string | undefined => {
+	return headers.get('content-type')?.split(';')[0];
+};

packages/oauth/browser-client/lib/utils/runtime.ts

···
+export const encoder = new TextEncoder();
+
+export const locks = navigator.locks;
+
+export const toBase64Url = (input: Uint8Array): string => {
+	const CHUNK_SIZE = 0x8000;
+	const arr = [];
+
+	for (let i = 0; i < input.byteLength; i += CHUNK_SIZE) {
+		// @ts-expect-error
+		arr.push(String.fromCharCode.apply(null, input.subarray(i, i + CHUNK_SIZE)));
+	}
+
+	return btoa(arr.join('')).replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+};
+
+export const fromBase64Url = (input: string): Uint8Array => {
+	try {
+		const binary = atob(input.replace(/-/g, '+').replace(/_/g, '/').replace(/\s/g, ''));
+		const bytes = new Uint8Array(binary.length);
+
+		for (let i = 0; i < binary.length; i++) {
+			bytes[i] = binary.charCodeAt(i);
+		}
+
+		return bytes;
+	} catch (err) {
+		throw new TypeError(`invalid base64url`, { cause: err });
+	}
+};
+
+export const toSha256 = async (input: string): Promise<string> => {
+	const bytes = encoder.encode(input);
+	const digest = await crypto.subtle.digest('SHA-256', bytes);
+
+	return toBase64Url(new Uint8Array(digest));
+};
+
+export const randomBytes = (length: number): string => {
+	return toBase64Url(crypto.getRandomValues(new Uint8Array(length)));
+};
+
+export const generateState = (): string => {
+	return randomBytes(16);
+};
+
+export const generatePKCE = async (): Promise<{ verifier: string; challenge: string; method: string }> => {
+	const verifier = randomBytes(32);
+
+	return {
+		verifier: verifier,
+		challenge: await toSha256(verifier),
+		method: 'S256',
+	};
+};

packages/oauth/browser-client/lib/utils/strings.ts

···
+import type { At } from '@atcute/client/lexicons';
+
+export const isDid = (value: string): value is At.DID => {
+	return value.startsWith('did:');
+};

packages/oauth/browser-client/package.json

···
+{
+	"type": "module",
+	"name": "@atcute/oauth-browser-client",
+	"version": "1.0.0",
+	"description": "minimal OAuth browser client implementation for AT Protocol",
+	"license": "MIT",
+	"repository": {
+		"url": "https://codeberg.org/mary-ext/atcute"
+	},
+	"files": [
+		"dist/"
+	],
+	"exports": {
+		".": "./dist/index.js"
+	},
+	"sideEffects": false,
+	"scripts": {
+		"build": "tsc --project tsconfig.build.json",
+		"test": "bun test --coverage",
+		"prepublish": "rm -rf dist; pnpm run build"
+	},
+	"dependencies": {
+		"@atcute/client": "workspace:^",
+		"nanoid": "^5.0.7"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.1.10"
+	}
+}

packages/oauth/browser-client/tsconfig.build.json

···
+{
+	"extends": "./tsconfig.json",
+	"exclude": ["**/*.test.ts"]
+}

packages/oauth/browser-client/tsconfig.json

···
+{
+	"compilerOptions": {
+		"types": ["bun"],
+		"outDir": "dist/",
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"target": "ESNext",
+		"allowJs": true,
+		"resolveJsonModule": true,
+		"moduleDetection": "force",
+		"isolatedModules": true,
+		"verbatimModuleSyntax": true,
+		"strict": true,
+		"noImplicitOverride": true,
+		"noUnusedLocals": true,
+		"noUnusedParameters": true,
+		"noFallthroughCasesInSwitch": true,
+		"module": "NodeNext",
+		"sourceMap": true,
+		"declaration": true,
+	},
+	"include": ["lib"],
+}

pnpm-lock.yaml

···
         specifier: ^5.1.0
         version: 5.1.0
 
+  packages/oauth/browser-client:
+    dependencies:
+      '@atcute/client':
+        specifier: workspace:^
+        version: link:../../core/client
+      nanoid:
+        specifier: ^5.0.7
+        version: 5.0.7
+    devDependencies:
+      '@types/bun':
+        specifier: ^1.1.10
+        version: 1.1.10
+
   packages/utilities/base32:
     devDependencies:
       '@types/bun':
···
   nanoid@3.3.7:
     resolution: {integrity: sha512-eSRppjcPIatRIMC1U6UngP8XFcz8MQWGQdt1MTBQ7NaAmvXDfvNxbvWV3x2y6CdEUciCSsDHDQZbhYaB8QEo2g==}
     engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
+    hasBin: true
+
+  nanoid@5.0.7:
+    resolution: {integrity: sha512-oLxFY2gd2IqnjcYyOXD8XGCftpGtZP2AbHbOkthDkvRywH5ayNtPVy9YlOPcHckXzbLTCHpkb7FB+yuxKV13pQ==}
+    engines: {node: ^18 || >=20}
     hasBin: true
 
   napi-build-utils@1.0.2:
···
   multiformats@9.9.0: {}
 
   nanoid@3.3.7: {}
+
+  nanoid@5.0.7: {}
 
   napi-build-utils@1.0.2: {}
 

pnpm-workspace.yaml

···
 packages:
   - packages/core/*
   - packages/definitions/*
+  - packages/oauth/*
   - packages/utilities/*
   - packages/bluesky/*
   - packages/internal/*