@atcute/oauth-browser-client 1.0.4 → 1.0.6

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

package/lib/resolvers.ts

@@ -0,0 +1,225 @@
+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, isValidUrl } 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 (!isValidUrl(metadata.authorization_endpoint)) {
+		throw new ResolverError(`authorization server provided incorrect authorization endpoint`);
+	}
+	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;
+};

package/lib/store/db.ts

@@ -0,0 +1,184 @@
+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;
+				}
+			};
+
+			globalThis.addEventListener('storage', listener, { signal });
+		}
+
+		{
+			const cleanup = async (lock: Lock | true | null) => {
+				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();
+				}
+			};
+
+			if (locks) {
+				locks.request(`${storageKey}:cleanup`, { ifAvailable: true }, cleanup);
+			} else {
+				cleanup(true);
+			}
+		}
+
+		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),
+	};
+};