@atcute/oauth-browser-client 1.0.27 → 2.0.0

package/lib/agents/exchange.ts

@@ -1,20 +1,30 @@
 import { nanoid } from 'nanoid';
 
+import type { ActorIdentifier } from '@atcute/lexicons';
+
 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 { ResolvedIdentity } from '../types/identity.js';
 import type { AuthorizationServerMetadata } from '../types/server.js';
 import type { Session } from '../types/token.js';
 import { generatePKCE } from '../utils/runtime.js';
 
+import { resolveFromIdentifier, resolveFromService } from '../resolvers.js';
 import { OAuthServerAgent } from './server-agent.js';
 import { storeSession } from './sessions.js';
 
+export type AuthorizeTargetOptions =
+	| { type: 'account'; identifier: ActorIdentifier }
+	| { type: 'pds'; serviceUrl: string };
+
 export interface AuthorizeOptions {
-	metadata: AuthorizationServerMetadata;
-	identity?: IdentityMetadata;
+	target: AuthorizeTargetOptions;
 	scope: string;
+	state?: unknown;
+	prompt?: 'none' | 'login' | 'consent' | 'select_account';
+	display?: 'page' | 'popup' | 'touch' | 'wap';
+	locale?: string;
 }
 
 /**
@@ -22,36 +32,52 @@ export interface AuthorizeOptions {
  * @param options
  * @returns URL to redirect the user for authorization
  */
-export const createAuthorizationUrl = async ({
-	metadata,
-	identity,
-	scope,
-}: AuthorizeOptions): Promise<URL> => {
-	const state = nanoid(24);
+export const createAuthorizationUrl = async (options: AuthorizeOptions): Promise<URL> => {
+	const { target, scope, state = null, ...reqs } = options;
+
+	let resolved: { identity?: ResolvedIdentity; metadata: AuthorizationServerMetadata };
+	switch (target.type) {
+		case 'account': {
+			resolved = await resolveFromIdentifier(target.identifier);
+			break;
+		}
+		case 'pds': {
+			resolved = await resolveFromService(target.serviceUrl);
+		}
+	}
+
+	const { identity, metadata } = resolved;
+	const loginHint = identity
+		? identity.handle !== 'handle.invalid'
+			? identity.handle
+			: identity.did
+		: undefined;
+
+	const sid = nanoid(24);
 
 	const pkce = await generatePKCE();
 	const dpopKey = await createES256Key();
 
 	const params = {
+		display: reqs.display,
+		ui_locales: reqs.locale,
+		prompt: reqs.prompt,
+
 		redirect_uri: REDIRECT_URI,
 		code_challenge: pkce.challenge,
 		code_challenge_method: pkce.method,
-		state: state,
-		login_hint: identity?.raw,
+		state: sid,
+		login_hint: loginHint,
 		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, {
+	database.states.set(sid, {
 		dpopKey: dpopKey,
 		metadata: metadata,
 		verifier: pkce.verifier,
+		state: state,
 	});
 
 	const server = new OAuthServerAgent(metadata, dpopKey);
@@ -71,25 +97,22 @@ export const createAuthorizationUrl = async ({
  */
 export const finalizeAuthorization = async (params: URLSearchParams) => {
 	const issuer = params.get('iss');
-	const state = params.get('state');
+	const sid = params.get('state');
 	const code = params.get('code');
 	const error = params.get('error');
 
-	if (!state || !(code || error)) {
+	if (!sid || !(code || error)) {
 		throw new LoginError(`missing parameters`);
 	}
 
-	const stored = database.states.get(state);
+	const stored = database.states.get(sid);
 	if (stored) {
 		// Delete now that we've caught it
-		database.states.delete(state);
+		database.states.delete(sid);
 	} 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);
 	}
@@ -97,6 +120,10 @@ export const finalizeAuthorization = async (params: URLSearchParams) => {
 		throw new LoginError(`missing code parameter`);
 	}
 
+	const dpopKey = stored.dpopKey;
+	const metadata = stored.metadata;
+	const state = stored.state ?? null;
+
 	if (issuer === null) {
 		throw new LoginError(`missing issuer parameter`);
 	} else if (issuer !== metadata.issuer) {
@@ -113,5 +140,5 @@ export const finalizeAuthorization = async (params: URLSearchParams) => {
 
 	await storeSession(sub, session);
 
-	return session;
+	return { session, state };
 };

package/lib/agents/server-agent.ts

@@ -1,9 +1,9 @@
 import type { Did } from '@atcute/lexicons';
 
-import { createDPoPFetch } from '../dpop.js';
-import { CLIENT_ID, REDIRECT_URI } from '../environment.js';
+import { createDPoPFetch, createDPoPSignage } from '../dpop.js';
+import { CLIENT_ID, fetchClientAssertion, REDIRECT_URI } from '../environment.js';
 import { FetchResponseError, OAuthResponseError, TokenRefreshError } from '../errors.js';
-import { resolveFromIdentity } from '../resolvers.js';
+import { resolveFromIdentifier } from '../resolvers.js';
 import type { DPoPKey } from '../types/dpop.js';
 import type { OAuthParResponse } from '../types/par.js';
 import type { PersistedAuthorizationServerMetadata } from '../types/server.js';
@@ -14,9 +14,11 @@ import { extractContentType } from '../utils/response.js';
 export class OAuthServerAgent {
 	#fetch: typeof fetch;
 	#metadata: PersistedAuthorizationServerMetadata;
+	#dpopKey: DPoPKey;
 
 	constructor(metadata: PersistedAuthorizationServerMetadata, dpopKey: DPoPKey) {
 		this.#metadata = metadata;
+		this.#dpopKey = dpopKey;
 		this.#fetch = createDPoPFetch(dpopKey, true);
 	}
 
@@ -33,6 +35,24 @@ export class OAuthServerAgent {
 			throw new Error(`no endpoint for ${endpoint}`);
 		}
 
+		if (endpoint === 'token' && fetchClientAssertion !== undefined) {
+			const jkt = this.#dpopKey.jkt;
+			if (jkt === undefined) {
+				throw new Error(`DPoP key missing jkt field`);
+			}
+
+			const clientAssertionCredentials = await fetchClientAssertion({
+				jkt: jkt,
+				aud: this.#metadata.issuer,
+				createDpopProof: async (url) => {
+					const sign = createDPoPSignage(this.#dpopKey);
+					return await sign('POST', url, undefined, undefined);
+				},
+			});
+
+			payload = { ...payload, ...clientAssertionCredentials };
+		}
+
 		const response = await this.#fetch(url, {
 			method: 'post',
 			headers: { 'content-type': 'application/json' },
@@ -124,7 +144,7 @@ export class OAuthServerAgent {
 		}
 
 		const token = this.#processTokenResponse(res);
-		const resolved = await resolveFromIdentity(sub);
+		const resolved = await resolveFromIdentifier(sub as Did);
 
 		if (resolved.metadata.issuer !== this.#metadata.issuer) {
 			throw new TypeError(`issuer mismatch; got ${resolved.metadata.issuer}`);
@@ -134,7 +154,7 @@ export class OAuthServerAgent {
 			token: token,
 			info: {
 				sub: sub as Did,
-				aud: resolved.identity.pds.href,
+				aud: resolved.identity.pds,
 				server: pick(resolved.metadata, [
 					'issuer',
 					'authorization_endpoint',

package/lib/dpop.ts

@@ -16,10 +16,14 @@ export const createES256Key = async (): Promise<DPoPKey> => {
 	const key = await crypto.subtle.exportKey('pkcs8', pair.privateKey);
 	const { ext: _ext, key_ops: _key_opts, ...jwk } = await crypto.subtle.exportKey('jwk', pair.publicKey);
 
+	const canonicalJwk = JSON.stringify({ crv: jwk.crv, kty: jwk.kty, x: jwk.x, y: jwk.y });
+	const jkt = await stringToSha256(canonicalJwk);
+
 	return {
 		typ: 'ES256',
 		key: toBase64Url(new Uint8Array(key)),
 		jwt: toBase64Url(encodeUtf8(JSON.stringify({ typ: 'dpop+jwt', alg: 'ES256', jwk: jwk }))),
+		jkt: jkt,
 	};
 };
 

package/lib/environment.ts

@@ -1,27 +1,44 @@
+import type { IdentityResolver } from './types/identity.js';
+
 import { createOAuthDatabase, type OAuthDatabase } from './store/db.js';
+import type { ClientAssertionFetcher } from './types/client-assertion.js';
 
 export let CLIENT_ID: string;
 export let REDIRECT_URI: string;
 
+export let fetchClientAssertion: ClientAssertionFetcher | undefined;
+
 export let database: OAuthDatabase;
 
+export let identityResolver: IdentityResolver;
+
 export interface ConfigureOAuthOptions {
 	/**
-	 * Client metadata, necessary to drive the whole request
+	 * client metadata, necessary to drive the whole request
 	 */
 	metadata: {
 		client_id: string;
 		redirect_uri: string;
 	};
 
+	/** resolves actor identifiers into identity metadata */
+	identityResolver: IdentityResolver;
+
 	/**
-	 * Name that will be used as prefix for storage keys needed to persist authentication.
+	 * optional function to fetch DPoP-bound client assertions from your backend.
+	 */
+	fetchClientAssertion?: ClientAssertionFetcher;
+
+	/**
+	 * name that will be used as prefix for storage keys needed to persist authentication.
 	 * @default "atcute-oauth"
 	 */
 	storageName?: string;
 }
 
 export const configureOAuth = (options: ConfigureOAuthOptions) => {
+	({ identityResolver, fetchClientAssertion } = options);
 	({ client_id: CLIENT_ID, redirect_uri: REDIRECT_URI } = options.metadata);
+
 	database = createOAuthDatabase({ name: options.storageName ?? 'atcute-oauth' });
 };

package/lib/index.ts

@@ -1,13 +1,13 @@
 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-assertion.js';
 export * from './types/client.js';
 export * from './types/dpop.js';
 export * from './types/identity.js';
@@ -15,3 +15,5 @@ export * from './types/par.js';
 export * from './types/server.js';
 export * from './types/store.js';
 export * from './types/token.js';
+
+export * from './utils/identity-resolver.js';

package/lib/resolvers.ts

@@ -1,91 +1,42 @@
-import type { ComAtprotoIdentityResolveHandle } from '@atcute/atproto';
-import { type DidDocument, getPdsEndpoint } from '@atcute/identity';
-import type { Did } from '@atcute/lexicons';
-import { isDid } from '@atcute/lexicons/syntax';
+import type { ActorIdentifier } from '@atcute/lexicons';
 
-import { DEFAULT_APPVIEW_URL } from './constants.js';
+import { identityResolver } from './environment.js';
 import { ResolverError } from './errors.js';
-import type { IdentityMetadata } from './types/identity.js';
+import type { ResolvedIdentity } from './types/identity.js';
 import type { AuthorizationServerMetadata, ProtectedResourceMetadata } from './types/server.js';
 import { extractContentType } from './utils/response.js';
 import { 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<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;
+export const resolveFromIdentifier = async (
+	ident: ActorIdentifier,
+): Promise<{ identity: ResolvedIdentity; metadata: AuthorizationServerMetadata }> => {
+	const identity = await identityResolver.resolve(ident);
 
-	return json.did;
+	return {
+		identity: identity,
+		metadata: await getMetadataFromResourceServer(identity.pds),
+	};
 };
 
-/**
- * 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: 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`);
+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 {}
 		}
 
-		const json = await response.json();
-
-		doc = json as DidDocument;
-	} else {
-		throw new ResolverError(`unsupported did method`);
+		throw err;
 	}
-
-	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 getProtectedResourceMetadata = async (host: string): Promise<ProtectedResourceMetadata> => {
 	const url = new URL(`/.well-known/oauth-protected-resource`, host);
 	const response = await fetch(url, {
 		redirect: 'manual',
@@ -106,12 +57,7 @@ export const getProtectedResourceMetadata = async (host: string): Promise<Protec
 	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 getAuthorizationServerMetadata = async (host: string): Promise<AuthorizationServerMetadata> => {
 	const url = new URL(`/.well-known/oauth-authorization-server`, host);
 	const response = await fetch(url, {
 		redirect: 'manual',
@@ -146,68 +92,7 @@ export const getAuthorizationServerMetadata = async (host: string): Promise<Auth
 	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: 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 getMetadataFromResourceServer = async (input: string) => {
 	const rs_metadata = await getProtectedResourceMetadata(input);
 
 	if (rs_metadata.authorization_servers?.length !== 1) {

package/lib/store/db.ts

@@ -30,6 +30,7 @@ interface Schema {
 			dpopKey: DPoPKey;
 			metadata: AuthorizationServerMetadata;
 			verifier?: string;
+			state?: unknown;
 		};
 	};
 

package/lib/types/client-assertion.ts

@@ -0,0 +1,25 @@
+const CLIENT_ASSERTION_TYPE_JWT_BEARER = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer';
+
+export interface ClientAssertionCredentials {
+	client_assertion: string;
+	client_assertion_type: typeof CLIENT_ASSERTION_TYPE_JWT_BEARER;
+}
+
+export interface FetchClientAssertionParams {
+	/** JWK thumbprint of the DPoP key to bind the assertion to */
+	jkt: string;
+	/** authorization server issuer (audience for the assertion) */
+	aud: string;
+
+	/**
+	 * create a DPoP proof to prove you possess the key for the claimed jkt.
+	 *
+	 * @param htu origin and pathname to your backend
+	 * @returns DPoP proof that can be included in the assertion
+	 */
+	createDpopProof: (htu: string) => Promise<string>;
+}
+
+export type ClientAssertionFetcher = (
+	params: FetchClientAssertionParams,
+) => Promise<ClientAssertionCredentials>;

package/lib/types/dpop.ts

@@ -4,4 +4,6 @@ export interface DPoPKey {
 	key: string;
 	/** base64url-encoded jwt token */
 	jwt: string;
+	/** JWK thumbprint (RFC 7638) for this key, used for client assertion binding */
+	jkt: string | undefined;
 }

package/lib/types/identity.ts

@@ -1,7 +1,16 @@
-import type { Did } from '@atcute/lexicons';
+import type { ActorIdentifier, Did, Handle } from '@atcute/lexicons';
 
-export interface IdentityMetadata {
-	id: Did;
-	raw: string;
-	pds: URL;
+export interface ResolvedIdentity {
+	did: Did;
+	handle: Handle;
+	pds: string;
+}
+
+export interface ResolveIdentityOptions {
+	signal?: AbortSignal;
+	noCache?: boolean;
+}
+
+export interface IdentityResolver {
+	resolve(actor: ActorIdentifier, options?: ResolveIdentityOptions): Promise<ResolvedIdentity>;
 }

package/lib/utils/identity-resolver.ts

@@ -0,0 +1,59 @@
+import { getAtprotoHandle, getPdsEndpoint } from '@atcute/identity';
+import type { DidDocumentResolver, HandleResolver } from '@atcute/identity-resolver';
+import type { ActorIdentifier, Did, Handle } from '@atcute/lexicons';
+import { isDid } from '@atcute/lexicons/syntax';
+
+import { ResolverError } from '../errors.js';
+import type { IdentityResolver, ResolvedIdentity, ResolveIdentityOptions } from '../types/identity.js';
+
+export interface DefaultIdentityResolverOptions {
+	handleResolver: HandleResolver;
+	didDocumentResolver: DidDocumentResolver;
+}
+
+export const defaultIdentityResolver = ({
+	handleResolver,
+	didDocumentResolver,
+}: DefaultIdentityResolverOptions): IdentityResolver => {
+	return {
+		async resolve(actor: ActorIdentifier, options?: ResolveIdentityOptions): Promise<ResolvedIdentity> {
+			const identifierIsDid = isDid(actor);
+
+			let did: Did;
+			if (identifierIsDid) {
+				did = actor;
+			} else {
+				did = await handleResolver.resolve(actor, options);
+			}
+
+			const doc = await didDocumentResolver.resolve(did, options);
+
+			const pds = getPdsEndpoint(doc);
+			if (!pds) {
+				throw new ResolverError(`missing pds endpoint`);
+			}
+
+			let handle: Handle = 'handle.invalid';
+			if (identifierIsDid) {
+				const writtenHandle = getAtprotoHandle(doc);
+				if (writtenHandle) {
+					try {
+						const resolved = await handleResolver.resolve(writtenHandle, options);
+
+						if (resolved === did) {
+							handle = writtenHandle;
+						}
+					} catch {}
+				}
+			} else if (getAtprotoHandle(doc) === actor) {
+				handle = actor;
+			}
+
+			return {
+				did: did,
+				handle: handle,
+				pds: new URL(pds).href,
+			};
+		},
+	};
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@atcute/oauth-browser-client",
-  "version": "1.0.27",
+  "version": "2.0.0",
   "description": "minimal OAuth browser client implementation for AT Protocol",
   "license": "0BSD",
   "repository": {
@@ -20,14 +20,15 @@
   "sideEffects": false,
   "dependencies": {
     "nanoid": "^5.1.5",
-    "@atcute/client": "^4.0.4",
+    "@atcute/client": "^4.0.5",
     "@atcute/identity": "^1.1.1",
-    "@atcute/lexicons": "^1.2.2",
+    "@atcute/identity-resolver": "^1.1.4",
     "@atcute/multibase": "^1.1.6",
+    "@atcute/lexicons": "^1.2.2",
     "@atcute/uint8array": "^1.0.5"
   },
   "devDependencies": {
-    "@atcute/atproto": "^3.1.6"
+    "@atcute/atproto": "^3.1.8"
   },
   "scripts": {
     "build": "tsc --project tsconfig.build.json",