@atcute/oauth-browser-client 1.0.4 → 1.0.5

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,222 @@
+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;
+};

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

package/lib/types/client.ts

@@ -0,0 +1,82 @@
+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[];
+}

package/lib/types/dpop.ts

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

package/lib/types/identity.ts

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

package/lib/types/par.ts

@@ -0,0 +1,4 @@
+export interface OAuthParResponse {
+	request_uri: string;
+	expires_in: number;
+}

package/lib/types/server.ts

@@ -0,0 +1,67 @@
+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'
+	> {}

package/lib/types/store.ts

@@ -0,0 +1,6 @@
+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[];
+}