feat(xrpc-server): initial commit

Squashed commit of the following:

commit f9ea5d0dca042804a0e1e2a1e1e49ea568e059b6
Author: Mary <[e-mail]>
Date: Tue May 27 07:49:35 2025 +0700

wip

commit 2782c60f2176d5349cb3efade4f824f4279de8ab
Author: Mary <[e-mail]>
Date: Mon May 26 16:13:20 2025 +0700

wip

commit 0e7f468cf5ba20931fdbb729fbf3b735e224382a
Author: Mary <[e-mail]>
Date: Sat May 24 16:44:21 2025 +0700

wip

commit e81c4c1a4a84b8ddfb5fcb5e004e14fa6b21d6db
Author: Mary <[e-mail]>
Date: Fri May 23 17:39:33 2025 +0700

wip

commit 71fb9ebce01cd1dc0f9188b7736ff033e428c089
Author: Mary <[e-mail]>
Date: Mon May 19 06:14:57 2025 +0700

wip

commit dd46d0c58a52c4cec19ad7cb45b4ca73532781c5
Author: Mary <[e-mail]>
Date: Sat May 17 08:03:59 2025 +0700

wip

commit 8571bf1d7910cb5e545e1051f6c6f5480eacee99
Author: Mary <[e-mail]>
Date: Thu May 15 22:02:03 2025 +0700

wip

packages/identity/identity-resolver/lib/types.ts

···
 	noCache?: boolean;
 }
 
-export interface DidDocumentResolver<TMethod extends string> {
+export interface DidDocumentResolver<TMethod extends string = string> {
 	resolve(did: Did<TMethod>, options?: ResolveDidDocumentOptions): Promise<DidDocument>;
 }
 

packages/servers/xrpc-server/README.md

···
+# @atcute/xrpc-server
+
+```ts
+import { parseCanonicalResourceUri, type Nsid } from '@atcute/lexicons';
+
+import { AuthRequiredError, InvalidRequestError, XRPCRouter, json } from '@atcute/xrpc-server';
+import { ServiceJwtVerifier, type VerifiedJwt } from '@atcute/xrpc-server/auth';
+
+import {
+	CompositeDidDocumentResolver,
+	PlcDidDocumentResolver,
+	WebDidDocumentResolver,
+} from '@atcute/identity-resolver';
+
+import { AppBskyFeedGetFeedSkeleton } from '@atcute/bluesky';
+
+const SERVICE_DID = 'did:web:feedgen.example.com';
+
+const router = new XRPCRouter();
+const jwtVerifier = new ServiceJwtVerifier({
+	serviceDid: SERVICE_DID,
+	resolver: new CompositeDidDocumentResolver({
+		methods: {
+			plc: new PlcDidDocumentResolver(),
+			web: new WebDidDocumentResolver(),
+		},
+	}),
+});
+
+const requireAuth = async (request: Request, lxm: Nsid): Promise<VerifiedJwt> => {
+	const auth = request.headers.get('authorization');
+	if (auth === null) {
+		throw new AuthRequiredError({ description: `missing authorization header` });
+	}
+	if (!auth.startsWith('Bearer ')) {
+		throw new AuthRequiredError({ description: `invalid authorization scheme` });
+	}
+
+	const jwtString = auth.slice('Bearer '.length).trim();
+
+	const result = await jwtVerifier.verify(jwtString, { lxm });
+	if (!result.ok) {
+		throw new AuthRequiredError(result.error);
+	}
+
+	return result.value;
+};
+
+router.add(AppBskyFeedGetFeedSkeleton.mainSchema, {
+	async handler({ params: { feed }, request }) {
+		await requireAuth(request, 'app.bsky.feed.getFeedSkeleton');
+
+		const feedUri = parseCanonicalResourceUri(feed);
+
+		if (
+			!feedUri.ok ||
+			feedUri.value.collection !== 'app.bsky.feed.generator' ||
+			feedUri.value.repo !== SERVICE_DID ||
+			feedUri.value.rkey !== 'feed'
+		) {
+			throw new InvalidRequestError({
+				error: 'InvalidFeed',
+				description: `invalid feed`,
+			});
+		}
+
+		return json({
+			feed: [
+				{ post: 'at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post/3l6oveex3ii2l' },
+				{ post: 'at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post/3lpk2lf7k6k2t' },
+			],
+		});
+	},
+});
+
+export default router;
+```

packages/servers/xrpc-server/lib/auth/index.ts

···
+export * from './jwt-verifier.js';

packages/servers/xrpc-server/lib/auth/jwt-verifier.ts

···
+import { getPublicKeyFromDidController, verifySig, type FoundPublicKey } from '@atcute/crypto';
+import { getAtprotoVerificationMaterial, type DidDocument } from '@atcute/identity';
+import { type DidDocumentResolver } from '@atcute/identity-resolver';
+import type { Did, Nsid } from '@atcute/lexicons';
+import * as uint8arrays from '@atcute/uint8array';
+
+import type { Result } from '../types/misc.js';
+
+import { parseJwt, type ParsedJwt } from './jwt.js';
+import type { AuthError } from './types.js';
+
+export interface ServiceJwtVerifierOptions {
+	serviceDid: Did | null;
+	resolver: DidDocumentResolver;
+}
+
+export interface VerifyJwtOptions {
+	lxm: Nsid | Nsid[] | null;
+}
+
+export interface VerifiedJwt {
+	issuer: Did;
+	lxm: string | undefined;
+}
+
+export class ServiceJwtVerifier {
+	didDocResolver: DidDocumentResolver;
+	serviceDid: Did | null;
+
+	constructor(options: ServiceJwtVerifierOptions) {
+		this.didDocResolver = options.resolver;
+		this.serviceDid = options.serviceDid;
+	}
+
+	async #getSigningKey(issuer: Did, noCache: boolean): Promise<Result<FoundPublicKey, AuthError>> {
+		let didDocument: DidDocument;
+		let key: FoundPublicKey;
+
+		try {
+			didDocument = await this.didDocResolver.resolve(issuer, { noCache });
+		} catch {
+			return {
+				ok: false,
+				error: {
+					error: 'UnresolvedDidDocument',
+					description: `failed to retrieve did document for ${issuer}`,
+				},
+			};
+		}
+
+		const controller = getAtprotoVerificationMaterial(didDocument);
+		if (!controller) {
+			return {
+				ok: false,
+				error: {
+					error: 'BadJwtIssuer',
+					description: `${issuer} does not have an atproto verification material`,
+				},
+			};
+		}
+
+		try {
+			key = getPublicKeyFromDidController(controller);
+		} catch {
+			return {
+				ok: false,
+				error: {
+					error: 'BadJwtIssuer',
+					description: `${issuer} has invalid atproto verification material`,
+				},
+			};
+		}
+
+		return { ok: true, value: key };
+	}
+
+	async #verifySignature(key: FoundPublicKey, jwt: ParsedJwt): Promise<Result<boolean, AuthError>> {
+		try {
+			return {
+				ok: true,
+				value: await verifySig(key, jwt.signature, jwt.message, { allowMalleableSig: true }),
+			};
+		} catch {
+			return {
+				ok: false,
+				error: {
+					error: 'BadJwtSignature',
+					description: `could not verify jwt signature`,
+				},
+			};
+		}
+	}
+
+	async verify(jwtString: string, options?: VerifyJwtOptions): Promise<Result<VerifiedJwt, AuthError>> {
+		const parsed = parseJwt(jwtString);
+		if (!parsed.ok) {
+			return parsed;
+		}
+
+		const { header, payload } = parsed.value;
+
+		switch (header.typ) {
+			case 'at+jwt':
+			case 'refresh+jwt':
+			case 'dpop+jwt': {
+				return {
+					ok: false,
+					error: {
+						error: 'BadJwtType',
+						description: `invalid jwt type`,
+					},
+				};
+			}
+		}
+
+		if (Date.now() / 1_000 > payload.exp) {
+			return {
+				ok: false,
+				error: {
+					error: 'JwtExpired',
+					description: `jwt is expired`,
+				},
+			};
+		}
+
+		if (this.serviceDid !== undefined && this.serviceDid !== payload.aud) {
+			return {
+				ok: false,
+				error: {
+					error: 'BadJwtAudience',
+					description: `jwt audience does not match (expected ${this.serviceDid})`,
+				},
+			};
+		}
+
+		if (
+			options?.lxm != null &&
+			(typeof options.lxm === 'string' ? options.lxm !== payload.lxm : !options.lxm.includes(payload.lxm!))
+		) {
+			return {
+				ok: false,
+				error: {
+					error: `BadJwtLexiconMethod`,
+					description: `jwt lexicon method does not match (expected ${options.lxm})`,
+				},
+			};
+		}
+
+		const key = await this.#getSigningKey(payload.iss, false);
+		if (!key.ok) {
+			return key;
+		}
+
+		let isValid = false;
+
+		if (key.value.jwtAlg === header.alg) {
+			const result = await this.#verifySignature(key.value, parsed.value);
+			if (!result.ok) {
+				return result;
+			}
+
+			isValid = result.value;
+		}
+
+		if (!isValid) {
+			// try again, uncached
+			const freshKey = await this.#getSigningKey(payload.iss, true);
+			if (!freshKey.ok) {
+				return freshKey;
+			}
+
+			// at this point we can't ignore the jwt alg difference
+			if (freshKey.value.jwtAlg !== header.alg) {
+				return {
+					ok: false,
+					error: {
+						error: 'BadJwtIssuer',
+						description: `mismatching cryptographic key format (jwt is ${header.alg})`,
+					},
+				};
+			}
+
+			// only revalidate if it's a different key
+			if (!uint8arrays.equals(freshKey.value.publicKeyBytes, key.value.publicKeyBytes)) {
+				const result = await this.#verifySignature(key.value, parsed.value);
+				if (!result.ok) {
+					return result;
+				}
+
+				isValid = result.value;
+			}
+		}
+
+		if (!isValid) {
+			// too bad
+			return {
+				ok: false,
+				error: {
+					error: 'BadJwtSignature',
+					description: `invalid jwt signature`,
+				},
+			};
+		}
+
+		return {
+			ok: true,
+			value: {
+				issuer: payload.iss,
+				lxm: payload.lxm,
+			},
+		};
+	}
+}

packages/servers/xrpc-server/lib/auth/jwt.ts

···
+import * as v from '@badrap/valita';
+
+import { isDid, isNsid } from '@atcute/lexicons/syntax';
+import { fromBase64 } from '@atcute/multibase';
+import { decodeUtf8From } from '@atcute/uint8array';
+
+import type { Result } from '../types/misc.js';
+
+import type { AuthError } from './types.js';
+
+const encoder = new TextEncoder();
+
+const didString = v.string().assert(isDid, `must be a did`);
+const nsidString = v.string().assert(isNsid, `must be an nsid`);
+
+const integer = v.number().assert((input) => input >= 0 && Number.isSafeInteger(input), `must be an integer`);
+
+const jwtHeader = v.object({
+	typ: v.string().optional(),
+	alg: v.string(),
+});
+
+export interface JwtHeader extends v.Infer<typeof jwtHeader> {}
+
+const jwtPayload = v
+	.object({
+		iss: didString,
+		aud: didString,
+		exp: integer,
+		iat: integer.optional(),
+		lxm: nsidString.optional(),
+		jti: v.string().optional(),
+	})
+	.assert(({ iat, exp }) => iat === undefined || exp > iat, {
+		message: `expiry time must be greater than issued time`,
+		path: ['exp'],
+	});
+
+export interface JwtPayload extends v.Infer<typeof jwtPayload> {}
+
+export interface ParsedJwt {
+	header: JwtHeader;
+	payload: JwtPayload;
+	message: Uint8Array;
+	signature: Uint8Array;
+}
+
+const readJwtPortion = <T>(schema: v.Type<T>, input: string): Result<T, AuthError> => {
+	try {
+		const raw = decodeUtf8From(fromBase64(input));
+		const json = JSON.parse(raw);
+
+		const result = schema.try(json);
+		if (result.ok) {
+			return result;
+		}
+	} catch {}
+
+	return {
+		ok: false,
+		error: {
+			error: `MalformedJwt`,
+			description: `jwt is malformed`,
+		},
+	};
+};
+
+const readJwtSignature = (input: string): Result<Uint8Array, AuthError> => {
+	try {
+		return { ok: true, value: fromBase64(input) };
+	} catch {}
+
+	return {
+		ok: false,
+		error: {
+			error: `MalformedJwt`,
+			description: `jwt is malformed`,
+		},
+	};
+};
+
+export const parseJwt = (jwtString: string): Result<ParsedJwt, AuthError> => {
+	const parts = jwtString.split('.');
+	if (parts.length !== 3) {
+		return {
+			ok: false,
+			error: {
+				error: `MalformedJwt`,
+				description: `jwt is malformed`,
+			},
+		};
+	}
+
+	const [headerString, payloadString, signatureString] = parts;
+
+	const header = readJwtPortion(jwtHeader, headerString);
+	if (!header.ok) {
+		return header;
+	}
+
+	const payload = readJwtPortion(jwtPayload, payloadString);
+	if (!payload.ok) {
+		return payload;
+	}
+
+	const signature = readJwtSignature(signatureString);
+	if (!signature.ok) {
+		return signature;
+	}
+
+	return {
+		ok: true,
+		value: {
+			header: header.value,
+			payload: payload.value,
+			message: encoder.encode(`${headerString}.${payloadString}`),
+			signature: signature.value,
+		},
+	};
+};

packages/servers/xrpc-server/lib/auth/types.ts

···
+export type AuthError = {
+	error: string;
+	description: string;
+};

packages/servers/xrpc-server/lib/main/index.ts

···
+export * from './response.js';
+export * from './router.js';
+export * from './xrpc-error.js';

packages/servers/xrpc-server/lib/main/response.ts

···
+declare const kJson: unique symbol;
+
+export type JSONResponse<TData> = Response & { [kJson]: TData };
+
+export const json: {
+	<TData>(data: NoInfer<TData>, init?: ResponseInit): JSONResponse<TData>;
+} = (data: any, init?: ResponseInit): any => {
+	return Response.json(data, init);
+};

packages/servers/xrpc-server/lib/main/router.ts

···
+import { safeParse, type XRPCProcedureMetadata, type XRPCQueryMetadata } from '@atcute/lexicons/validations';
+
+import type { Literal, Promisable } from '../types/misc.js';
+
+import type { ProcedureConfig, QueryConfig, UnknownOperationContext } from './types/operation.js';
+import { createAsyncMiddlewareRunner, type Middleware } from './utils/middlewares.js';
+import { constructParamsHandler } from './utils/request-params.js';
+import { invalidRequest, validationError } from './utils/response.js';
+
+import { XRPCError } from './xrpc-error.js';
+
+const JSON_TYPE_RE = /^\s*application\/json\s*(?:$|;)/i;
+
+type InternalRequestContext = {
+	url: URL;
+	request: Request;
+};
+
+type InternalRequestHandler = (context: InternalRequestContext) => Promise<Response>;
+
+type InternalRouteData = {
+	method: 'GET' | 'POST';
+	handler: InternalRequestHandler;
+};
+
+export type FetchMiddleware = Middleware<[request: Request], Promise<Response>>;
+
+export type NotFoundHandler = (request: Request) => Promisable<Response>;
+export type ExceptionHandler = (error: unknown, request: Request) => Promisable<Response>;
+
+export const defaultExceptionHandler: ExceptionHandler = (error: unknown) => {
+	if (error instanceof XRPCError) {
+		return error.toResponse();
+	}
+
+	if (error instanceof Response) {
+		return error;
+	}
+
+	return Response.json(
+		{ error: 'InternalServerError', message: `an exception happened whilst processing this request` },
+		{ status: 500 },
+	);
+};
+
+export const defaultNotFoundHandler: NotFoundHandler = () => {
+	return new Response('Not Found', { status: 404 });
+};
+
+export interface XRPCRouterOptions {
+	middlewares?: FetchMiddleware[];
+	handleNotFound?: NotFoundHandler;
+	handleException?: ExceptionHandler;
+}
+
+export class XRPCRouter {
+	#handlers: Record<string, InternalRouteData> = {};
+	#handleNotFound: NotFoundHandler;
+	#handleException: ExceptionHandler;
+
+	fetch: (request: Request) => Promise<Response>;
+
+	constructor({
+		middlewares = [],
+		handleException = defaultExceptionHandler,
+		handleNotFound = defaultNotFoundHandler,
+	}: XRPCRouterOptions = {}) {
+		this.fetch = createAsyncMiddlewareRunner([...middlewares, (request) => this.#dispatch(request)]);
+		this.#handleException = handleException;
+		this.#handleNotFound = handleNotFound;
+	}
+
+	async #dispatch(request: Request): Promise<Response> {
+		const url = new URL(request.url);
+		const pathname = url.pathname;
+
+		if (!pathname.startsWith('/xrpc/')) {
+			return this.#handleNotFound(request);
+		}
+
+		const nsid = pathname.slice('/xrpc/'.length);
+		const route = this.#handlers[nsid];
+
+		if (route === undefined) {
+			return this.#handleNotFound(request);
+		}
+
+		if (request.method !== route.method) {
+			return Response.json(
+				{ error: 'InvalidHttpMethod', message: `invalid http method (expected ${route.method})` },
+				{ status: 405, headers: { allow: `${route.method}` } },
+			);
+		}
+
+		try {
+			const response = await route.handler({
+				request: request,
+				url: url,
+			});
+
+			return response;
+		} catch (err) {
+			return this.#handleException(err, request);
+		}
+	}
+
+	add<TQuery extends XRPCQueryMetadata>(query: TQuery, config: QueryConfig<TQuery>): void;
+	add<TProcedure extends XRPCProcedureMetadata>(
+		procedure: TProcedure,
+		config: ProcedureConfig<TProcedure>,
+	): void;
+	add(operation: XRPCQueryMetadata | XRPCProcedureMetadata, config: any): void {
+		switch (operation.type) {
+			case 'xrpc_query': {
+				return this.#addQuery(operation, config);
+			}
+			case 'xrpc_procedure': {
+				return this.#addProcedure(operation, config);
+			}
+		}
+	}
+
+	#addQuery<TQuery extends XRPCQueryMetadata>(query: TQuery, config: QueryConfig<TQuery>): void {
+		const handleParams = query.params ? constructParamsHandler(query.params) : null;
+
+		const handler = config.handler;
+
+		this.#handlers[query.nsid] = {
+			method: 'GET',
+			handler: async ({ request, url }) => {
+				let params: Record<string, Literal | Literal[]>;
+
+				if (handleParams !== null) {
+					const result = handleParams(url.searchParams);
+					if (!result.ok) {
+						return validationError('params', result);
+					}
+
+					params = result.value;
+				} else {
+					params = {};
+				}
+
+				const context: UnknownOperationContext = {
+					request: request,
+					params: params,
+				};
+
+				const output = await handler(context as any);
+
+				if (output instanceof Response) {
+					return output;
+				}
+
+				return new Response(null);
+			},
+		};
+	}
+
+	#addProcedure<TProcedure extends XRPCProcedureMetadata>(
+		procedure: TProcedure,
+		config: ProcedureConfig<TProcedure>,
+	): void {
+		const handleParams = procedure.params ? constructParamsHandler(procedure.params) : null;
+
+		const requiresInput = procedure.input !== null;
+		const inputSchema = procedure.input?.type === 'lex' ? procedure.input.schema : null;
+
+		const handler = config.handler;
+
+		this.#handlers[procedure.nsid] = {
+			method: 'POST',
+			handler: async ({ request, url }) => {
+				let params: Record<string, Literal | Literal[]>;
+				let input: Record<string, unknown> | undefined;
+
+				if (handleParams !== null) {
+					const result = handleParams(url.searchParams);
+					if (!result.ok) {
+						return validationError('params', result);
+					}
+
+					params = result.value;
+				} else {
+					params = {};
+				}
+
+				const headers = request.headers;
+				if (requiresInput) {
+					if (!isBodyPresent(headers)) {
+						return invalidRequest(`request body is expected but none was provided`);
+					}
+
+					if (inputSchema !== null) {
+						{
+							const type = headers.get('content-type');
+							if (type === null) {
+								return invalidRequest(`request encoding not provided`);
+							}
+
+							if (!JSON_TYPE_RE.test(type)) {
+								return invalidRequest(`invalid request encoding (expected application/json)`);
+							}
+						}
+
+						let raw: any;
+						try {
+							raw = await request.json();
+						} catch (err) {
+							return invalidRequest(`invalid request body (failed to parse json)`);
+						}
+
+						const result = safeParse(inputSchema, raw);
+						if (!result.ok) {
+							return validationError('input', result);
+						}
+
+						input = result.value;
+					}
+				} else {
+					if (isBodyPresent(headers)) {
+						return invalidRequest(`request body is provided when none was expected`);
+					}
+				}
+
+				const context: UnknownOperationContext = {
+					request: request,
+					params: params,
+					input: input,
+				};
+
+				const output = await handler(context as any);
+
+				if (output instanceof Response) {
+					return output;
+				}
+
+				return new Response(null);
+			},
+		};
+	}
+}
+
+const isBodyPresent = (headers: Headers): boolean => {
+	return headers.get('content-length') !== null && headers.get('transfer-encoding') !== null;
+};

packages/servers/xrpc-server/lib/main/types/operation.ts

···
+import type {
+	InferOutput,
+	ObjectSchema,
+	XRPCLexBodyParam,
+	XRPCProcedureMetadata,
+	XRPCQueryMetadata,
+} from '@atcute/lexicons/validations';
+
+import type { Literal, Promisable } from '../../types/misc.js';
+
+import type { JSONResponse } from '../response.js';
+
+export type UnknownOperationContext = {
+	request: Request;
+	params: Record<string, Literal | Literal[]>;
+	input?: Record<string, unknown>;
+};
+
+// #region Query
+
+export type QueryContext<TQuery extends XRPCQueryMetadata> = {
+	request: Request;
+} & (TQuery['params'] extends ObjectSchema
+	? {
+			params: InferOutput<TQuery['params']>;
+		}
+	: {
+			// params
+		});
+
+export type QueryHandler<TQuery extends XRPCQueryMetadata> = (
+	context: QueryContext<TQuery>,
+) => Promisable<
+	TQuery['output'] extends null
+		? Response | void
+		: TQuery['output'] extends XRPCLexBodyParam
+			? Response | JSONResponse<InferOutput<TQuery['output']['schema']>>
+			: Response
+>;
+
+export type QueryConfig<TQuery extends XRPCQueryMetadata = XRPCQueryMetadata> = {
+	handler: QueryHandler<TQuery>;
+};
+
+// #region Procedure
+
+export type ProcedureContext<TProcedure extends XRPCProcedureMetadata> = {
+	request: Request;
+} & (TProcedure['params'] extends ObjectSchema
+	? {
+			params: InferOutput<TProcedure['params']>;
+		}
+	: {
+			// params
+		}) &
+	(TProcedure['input'] extends XRPCLexBodyParam
+		? {
+				input: InferOutput<TProcedure['input']['schema']>;
+			}
+		: {
+				// input
+			});
+
+export type ProcedureHandler<TProcedure extends XRPCProcedureMetadata> = (
+	context: ProcedureContext<TProcedure>,
+) => Promisable<
+	TProcedure['output'] extends null
+		? Response | void
+		: TProcedure['output'] extends XRPCLexBodyParam
+			? Response | JSONResponse<InferOutput<TProcedure['output']['schema']>>
+			: Response
+>;
+
+export type ProcedureConfig<TProcedure extends XRPCProcedureMetadata = XRPCProcedureMetadata> = {
+	handler: ProcedureHandler<TProcedure>;
+};

packages/servers/xrpc-server/lib/main/utils/middlewares.ts

···
+export type Middleware<TParams extends any[], TReturn> = (
+	...params: [...TParams, next: (...params: TParams) => TReturn]
+) => TReturn;
+
+export const createAsyncMiddlewareRunner = <TParams extends any[], TReturn>(
+	middlewares: [...Middleware<TParams, Promise<TReturn>>[], Middleware<TParams, Promise<TReturn>>],
+) => {
+	// prettier-ignore
+	return middlewares.reduceRight<(...params: TParams) => Promise<TReturn>>(
+		(next, run) => (...args) => run(...args, next),
+		() => Promise.reject(new Error(`middleware chain exhausted`)),
+	);
+};

packages/servers/xrpc-server/lib/main/utils/request-params.ts

···
+import {
+	safeParse,
+	type ArraySchema,
+	type BaseSchema,
+	type ObjectSchema,
+	type OptionalSchema,
+	type ValidationResult,
+} from '@atcute/lexicons/validations';
+
+import type { Literal } from '../../types/misc.js';
+
+const isArraySchema = (schema: BaseSchema): schema is ArraySchema => {
+	return schema.type === 'array';
+};
+
+const isOptionalSchema = (schema: BaseSchema): schema is OptionalSchema => {
+	return schema.type === 'optional';
+};
+
+const unwrapOptional = (schema: BaseSchema): BaseSchema => {
+	return isOptionalSchema(schema) ? schema.wrapped : schema;
+};
+
+const unwrapArray = (schema: BaseSchema): BaseSchema => {
+	return isArraySchema(schema) ? schema.item : schema;
+};
+
+const coerceBoolean = (str: string): boolean => {
+	return str === 'true';
+};
+
+const coerceInteger = (str: string): number => {
+	return Number(str);
+};
+
+export const constructParamsHandler = <TSchema extends ObjectSchema>(schema: TSchema) => {
+	const entries = Object.entries(schema.shape).map(([key, schema]) => {
+		const nonnullable = unwrapOptional(schema);
+		const singular = unwrapArray(nonnullable);
+
+		let coerce: ((x: string) => Literal) | undefined;
+		switch (singular.type) {
+			case 'boolean': {
+				coerce = coerceBoolean;
+				break;
+			}
+			case 'integer': {
+				coerce = coerceInteger;
+				break;
+			}
+		}
+
+		return {
+			key: key,
+			coerce: coerce,
+			multiple: isArraySchema(nonnullable),
+			optional: isOptionalSchema(schema),
+		};
+	});
+
+	const len = entries.length;
+
+	return (searchParams: URLSearchParams): ValidationResult<Record<string, Literal | Literal[]>> => {
+		const input: Record<string, Literal | Literal[]> = {};
+
+		for (let idx = 0; idx < len; idx++) {
+			const entry = entries[idx];
+			const key = entry.key;
+			const coerce = entry.coerce;
+
+			const raw = searchParams.getAll(key);
+			const count = raw.length;
+
+			let value: Literal | Literal[];
+
+			if (entry.multiple) {
+				if (count === 0 && entry.optional) {
+					continue;
+				}
+
+				value = coerce !== undefined ? raw.map(coerce) : raw;
+			} else {
+				if (count === 0) {
+					continue;
+				}
+
+				value = coerce !== undefined ? coerce(raw[0]) : raw[0];
+			}
+
+			/*#__INLINE__*/ set(input, key, value);
+		}
+
+		return safeParse(schema, input);
+	};
+};
+
+const set = <K extends PropertyKey, V>(obj: Record<K, V>, key: NoInfer<K>, value: NoInfer<V>): void => {
+	if (key === '__proto__') {
+		Object.defineProperty(obj, key, { value });
+	} else {
+		obj[key] = value;
+	}
+};

packages/servers/xrpc-server/lib/main/utils/response.ts

···
+import type { Err } from '@atcute/lexicons/validations';
+
+export const invalidRequest = (message: string) => {
+	return Response.json({ error: 'InvalidRequest', message }, { status: 400 });
+};
+
+export const validationError = (kind: 'params' | 'input', err: Err): Response => {
+	const message = `invalid ${kind}: ${err.message}`;
+
+	return Response.json(
+		{ error: 'InvalidRequest', message: message, 'net.kelinci.atcute.issues': err.issues },
+		{ status: 400 },
+	);
+};

packages/servers/xrpc-server/lib/main/xrpc-error.ts

···
+export interface XRPCErrorOptions {
+	status: number;
+	error: string;
+	description?: string;
+}
+
+export class XRPCError extends Error {
+	/** response status */
+	readonly status: number;
+
+	/** error name */
+	readonly error: string;
+	/** error message */
+	readonly description?: string;
+
+	constructor({ status, error, description }: XRPCErrorOptions) {
+		super(`${error} > ${description ?? '(unspecified description)'}`);
+
+		this.status = status;
+
+		this.error = error;
+		this.description = description;
+	}
+
+	toResponse(): Response {
+		return Response.json({ error: this.error, message: this.description }, { status: this.status });
+	}
+}
+
+export class InvalidRequestError extends XRPCError {
+	constructor({ status = 400, error = 'InvalidRequest', description }: Partial<XRPCErrorOptions> = {}) {
+		super({ status, error, description });
+	}
+}
+
+export class AuthRequiredError extends XRPCError {
+	constructor({
+		status = 401,
+		error = 'AuthenticationRequired',
+		description,
+	}: Partial<XRPCErrorOptions> = {}) {
+		super({ status, error, description });
+	}
+}
+
+export class ForbiddenError extends XRPCError {
+	constructor({ status = 403, error = 'Forbidden', description }: Partial<XRPCErrorOptions> = {}) {
+		super({ status, error, description });
+	}
+}
+
+export class RateLimitExceededError extends XRPCError {
+	constructor({ status = 429, error = 'RateLimitExceeded', description }: Partial<XRPCErrorOptions> = {}) {
+		super({ status, error, description });
+	}
+}
+
+export class InternalServerError extends XRPCError {
+	constructor({ status = 500, error = 'InternalServerError', description }: Partial<XRPCErrorOptions> = {}) {
+		super({ status, error, description });
+	}
+}
+
+export class UpstreamFailureError extends XRPCError {
+	constructor({ status = 502, error = 'UpstreamFailure', description }: Partial<XRPCErrorOptions> = {}) {
+		super({ status, error, description });
+	}
+}
+
+export class NotEnoughResourcesError extends XRPCError {
+	constructor({ status = 503, error = 'NotEnoughResources', description }: Partial<XRPCErrorOptions> = {}) {
+		super({ status, error, description });
+	}
+}
+
+export class UpstreamTimeoutError extends XRPCError {
+	constructor({ status = 504, error = 'UpstreamTimeout', description }: Partial<XRPCErrorOptions> = {}) {
+		super({ status, error, description });
+	}
+}

packages/servers/xrpc-server/lib/middlewares/cors.ts

···
+import type { FetchMiddleware } from '../main/router.js';
+
+export interface CORSOptions {
+	/** Additional headers to expose to the client */
+	exposedHeaders?: string[];
+	/** Additional headers to allow */
+	allowedHeaders?: string[];
+}
+
+const DEFAULT_EXPOSED_HEADERS = [
+	'dpop-nonce',
+	'www-authenticate',
+
+	'ratelimit-limit',
+	'ratelimit-policy',
+	'ratelimit-remaining',
+	'ratelimit-reset',
+];
+
+const DEFAULT_ALLOWED_HEADERS = [
+	'content-type',
+
+	'authorization',
+	'dpop',
+
+	'atproto-accept-labelers',
+	'atproto-proxy',
+];
+
+export const cors = (options: CORSOptions = {}): FetchMiddleware => {
+	const exposedHeaders = Array.from(
+		new Set([...DEFAULT_EXPOSED_HEADERS, ...(options.exposedHeaders?.map((h) => h.toLowerCase()) || [])]),
+	).sort();
+
+	const allowedHeaders = Array.from(
+		new Set([...DEFAULT_ALLOWED_HEADERS, ...(options.allowedHeaders?.map((h) => h.toLowerCase()) || [])]),
+	)
+		.sort()
+		.join(',');
+
+	return async (request, next) => {
+		const origin = request.headers.get('origin') || '*';
+
+		// Handle preflight requests
+		if (request.method === 'OPTIONS') {
+			const headers = new Headers();
+			headers.set('access-control-max-age', '86400');
+			headers.set('access-control-allow-origin', origin);
+
+			if (allowedHeaders) {
+				headers.set('access-control-allow-headers', allowedHeaders);
+			}
+
+			return new Response(null, { status: 204, headers: headers });
+		}
+
+		const response = await next(request);
+
+		const expose = exposedHeaders.filter((h) => response.headers.has(h)).join(',');
+
+		response.headers.set('access-control-allow-origin', origin);
+		if (expose.length > 0) {
+			response.headers.append('access-control-expose-headers', expose);
+		}
+
+		return response;
+	};
+};

packages/servers/xrpc-server/lib/types/misc.ts

···
+export type Promisable<T> = T | Promise<T>;
+export type Literal = string | number | boolean;
+
+export type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };

packages/servers/xrpc-server/package.json

···
+{
+	"type": "module",
+	"name": "@atcute/xrpc-server",
+	"version": "1.0.0",
+	"description": "xrpc server",
+	"license": "MIT",
+	"repository": {
+		"url": "https://github.com/mary-ext/atcute",
+		"directory": "packages/servers/xrpc-server"
+	},
+	"files": [
+		"dist/",
+		"lib/",
+		"!lib/**/*.bench.ts",
+		"!lib/**/*.test.ts"
+	],
+	"exports": {
+		".": "./dist/main/index.js",
+		"./auth": "./dist/auth/index.js",
+		"./middlewares/cors": "./dist/middlewares/cors.js"
+	},
+	"scripts": {
+		"build": "tsc --project tsconfig.build.json",
+		"test": "vitest run --coverage",
+		"prepublish": "rm -rf dist; pnpm run build"
+	},
+	"dependencies": {
+		"@atcute/crypto": "workspace:^",
+		"@atcute/identity": "workspace:^",
+		"@atcute/identity-resolver": "workspace:^",
+		"@atcute/lexicons": "workspace:^",
+		"@atcute/multibase": "workspace:^",
+		"@atcute/uint8array": "workspace:^",
+		"@badrap/valita": "^0.4.4"
+	},
+	"devDependencies": {
+		"@atcute/atproto": "workspace:^",
+		"@atcute/bluesky": "workspace:^",
+		"@atcute/xrpc-server": "file:",
+		"@vitest/coverage-v8": "^3.0.4",
+		"vitest": "^3.0.4"
+	}
+}

packages/servers/xrpc-server/tsconfig.build.json

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

packages/servers/xrpc-server/tsconfig.json

···
+{
+	"compilerOptions": {
+		"types": [],
+		"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

···
         version: 1.2.13
       vitest:
         specifier: ^3.1.3
-        version: 3.1.3(@types/node@22.15.17)
+        version: 3.1.3(@types/node@22.15.17)(yaml@2.8.0)
 
   packages/bluesky/richtext-builder:
     dependencies:
···
         version: link:../../internal/dev-env
       '@vitest/coverage-v8':
         specifier: ^3.1.3
-        version: 3.1.3(vitest@3.1.3(@types/node@22.15.17))
+        version: 3.1.3(vitest@3.1.3(@types/node@22.15.17)(yaml@2.8.0))
       vitest:
         specifier: ^3.1.3
-        version: 3.1.3(@types/node@22.15.17)
+        version: 3.1.3(@types/node@22.15.17)(yaml@2.8.0)
 
   packages/clients/jetstream:
     dependencies:
···
     devDependencies:
       '@vitest/coverage-v8':
         specifier: ^3.0.4
-        version: 3.1.3(vitest@3.1.3(@types/node@22.15.17))
+        version: 3.1.3(vitest@3.1.3(@types/node@22.15.17)(yaml@2.8.0))
       vitest:
         specifier: ^3.0.4
-        version: 3.1.3(@types/node@22.15.17)
+        version: 3.1.3(@types/node@22.15.17)(yaml@2.8.0)
 
   packages/definitions/atproto:
     dependencies:
···
         version: 0.15.6
       vitest:
         specifier: ^3.1.3
-        version: 3.1.3(@types/node@22.15.17)
+        version: 3.1.3(@types/node@22.15.17)(yaml@2.8.0)
 
   packages/definitions/frontpage:
     dependencies:
···
         version: link:../../lexicons/lex-cli
       vitest:
         specifier: ^3.1.3
-        version: 3.1.3(@types/node@22.15.17)
+        version: 3.1.3(@types/node@22.15.17)(yaml@2.8.0)
 
   packages/definitions/leaflet:
     dependencies:
···
         version: file:packages/definitions/tangled
       vitest:
         specifier: ^3.1.3
-        version: 3.1.3(@types/node@22.15.17)
+        version: 3.1.3(@types/node@22.15.17)(yaml@2.8.0)
 
   packages/definitions/whitewind:
     dependencies:
···
     devDependencies:
       '@vitest/coverage-v8':
         specifier: ^3.1.3
-        version: 3.1.3(vitest@3.1.3(@types/node@22.15.17))
+        version: 3.1.3(vitest@3.1.3(@types/node@22.15.17)(yaml@2.8.0))
       vitest:
         specifier: ^3.1.3
-        version: 3.1.3(@types/node@22.15.17)
+        version: 3.1.3(@types/node@22.15.17)(yaml@2.8.0)
 
   packages/misc/util-fetch:
     dependencies:
···
         specifier: workspace:^
         version: link:../../definitions/atproto
 
+  packages/servers/xrpc-server:
+    dependencies:
+      '@atcute/crypto':
+        specifier: workspace:^
+        version: link:../../utilities/crypto
+      '@atcute/identity':
+        specifier: workspace:^
+        version: link:../../identity/identity
+      '@atcute/identity-resolver':
+        specifier: workspace:^
+        version: link:../../identity/identity-resolver
+      '@atcute/lexicons':
+        specifier: workspace:^
+        version: link:../../lexicons/lexicons
+      '@atcute/multibase':
+        specifier: workspace:^
+        version: link:../../utilities/multibase
+      '@atcute/uint8array':
+        specifier: workspace:^
+        version: link:../../utilities/uint8array
+      '@badrap/valita':
+        specifier: ^0.4.4
+        version: 0.4.4
+    devDependencies:
+      '@atcute/atproto':
+        specifier: workspace:^
+        version: link:../../definitions/atproto
+      '@atcute/bluesky':
+        specifier: workspace:^
+        version: link:../../definitions/bluesky
+      '@atcute/xrpc-server':
+        specifier: 'file:'
+        version: file:packages/servers/xrpc-server
+      '@vitest/coverage-v8':
+        specifier: ^3.0.4
+        version: 3.1.3(vitest@3.1.3(@types/node@22.15.17)(yaml@2.8.0))
+      vitest:
+        specifier: ^3.0.4
+        version: 3.1.3(@types/node@22.15.17)(yaml@2.8.0)
+
   packages/utilities/car:
     dependencies:
       '@atcute/cbor':
···
         version: 1.2.13
       '@vitest/coverage-v8':
         specifier: ^3.1.3
-        version: 3.1.3(vitest@3.1.3(@types/node@22.15.17))
+        version: 3.1.3(vitest@3.1.3(@types/node@22.15.17)(yaml@2.8.0))
       vitest:
         specifier: ^3.1.3
-        version: 3.1.3(@types/node@22.15.17)
+        version: 3.1.3(@types/node@22.15.17)(yaml@2.8.0)
 
   packages/utilities/multibase:
     dependencies:
···
     devDependencies:
       vitest:
         specifier: ^3.1.3
-        version: 3.1.3(@types/node@22.15.17)
+        version: 3.1.3(@types/node@22.15.17)(yaml@2.8.0)
 
   packages/utilities/uint8array:
     devDependencies:
···
     devDependencies:
       vitest:
         specifier: ^3.1.3
-        version: 3.1.3(@types/node@22.15.17)
+        version: 3.1.3(@types/node@22.15.17)(yaml@2.8.0)
 
 packages:
 
···
 
   '@atcute/whitewind@file:packages/definitions/whitewind':
     resolution: {directory: packages/definitions/whitewind, type: directory}
+
+  '@atcute/xrpc-server@file:packages/servers/xrpc-server':
+    resolution: {directory: packages/servers/xrpc-server, type: directory}
 
   '@atproto-labs/fetch-node@0.1.8':
     resolution: {integrity: sha512-OOTIhZNPEDDm7kaYU8iYRgzM+D5n3mP2iiBSyKuLakKTaZBL5WwYlUsJVsqX26SnUXtGEroOJEVJ6f66OcG80w==}
···
     resolution: {integrity: sha512-LKYU1iAXJXUgAXn9URjiu+MWhyUXHsvfp7mcuYm9dSUKK0/CjtrUwFAxD82/mCWbtLsGjFIad0wIsod4zrTAEQ==}
     engines: {node: '>=0.4'}
 
+  yaml@2.8.0:
+    resolution: {integrity: sha512-4lLa/EcQCB0cJkyts+FpIRx5G/llPxfP6VQU5KByHEhLxY3IJCH0f0Hy1MHI8sClTvsIb8qwRJ6R/ZdlDJ/leQ==}
+    engines: {node: '>= 14.6'}
+    hasBin: true
+
   yocto-queue@1.2.1:
     resolution: {integrity: sha512-AyeEbWOu/TAXdxlV9wmGcR0+yh2j3vYPGOECcIj2S7MkrLyC7ne+oye2BKTItt0ii2PHk4cDy+95+LshzbXnGg==}
     engines: {node: '>=12.20'}
···
     dependencies:
       '@atcute/lexicons': link:packages/lexicons/lexicons
 
+  '@atcute/xrpc-server@file:packages/servers/xrpc-server':
+    dependencies:
+      '@atcute/crypto': link:packages/utilities/crypto
+      '@atcute/identity': link:packages/identity/identity
+      '@atcute/identity-resolver': link:packages/identity/identity-resolver
+      '@atcute/lexicons': link:packages/lexicons/lexicons
+      '@atcute/multibase': link:packages/utilities/multibase
+      '@atcute/uint8array': link:packages/utilities/uint8array
+      '@badrap/valita': 0.4.4
+
   '@atproto-labs/fetch-node@0.1.8':
     dependencies:
       '@atproto-labs/fetch': 0.2.2
···
     dependencies:
       undici-types: 6.21.0
 
-  '@vitest/coverage-v8@3.1.3(vitest@3.1.3(@types/node@22.15.17))':
+  '@vitest/coverage-v8@3.1.3(vitest@3.1.3(@types/node@22.15.17)(yaml@2.8.0))':
     dependencies:
       '@ampproject/remapping': 2.3.0
       '@bcoe/v8-coverage': 1.0.2
···
       std-env: 3.9.0
       test-exclude: 7.0.1
       tinyrainbow: 2.0.0
-      vitest: 3.1.3(@types/node@22.15.17)
+      vitest: 3.1.3(@types/node@22.15.17)(yaml@2.8.0)
     transitivePeerDependencies:
       - supports-color
 
···
       chai: 5.2.0
       tinyrainbow: 2.0.0
 
-  '@vitest/mocker@3.1.3(vite@6.3.5(@types/node@22.15.17))':
+  '@vitest/mocker@3.1.3(vite@6.3.5(@types/node@22.15.17)(yaml@2.8.0))':
     dependencies:
       '@vitest/spy': 3.1.3
       estree-walker: 3.0.3
       magic-string: 0.30.17
     optionalDependencies:
-      vite: 6.3.5(@types/node@22.15.17)
+      vite: 6.3.5(@types/node@22.15.17)(yaml@2.8.0)
 
   '@vitest/pretty-format@3.1.3':
     dependencies:
···
 
   vary@1.1.2: {}
 
-  vite-node@3.1.3(@types/node@22.15.17):
+  vite-node@3.1.3(@types/node@22.15.17)(yaml@2.8.0):
     dependencies:
       cac: 6.7.14
       debug: 4.4.0
       es-module-lexer: 1.7.0
       pathe: 2.0.3
-      vite: 6.3.5(@types/node@22.15.17)
+      vite: 6.3.5(@types/node@22.15.17)(yaml@2.8.0)
     transitivePeerDependencies:
       - '@types/node'
       - jiti
···
       - tsx
       - yaml
 
-  vite@6.3.5(@types/node@22.15.17):
+  vite@6.3.5(@types/node@22.15.17)(yaml@2.8.0):
     dependencies:
       esbuild: 0.25.4
       fdir: 6.4.4(picomatch@4.0.2)
···
     optionalDependencies:
       '@types/node': 22.15.17
       fsevents: 2.3.3
+      yaml: 2.8.0
 
-  vitest@3.1.3(@types/node@22.15.17):
+  vitest@3.1.3(@types/node@22.15.17)(yaml@2.8.0):
     dependencies:
       '@vitest/expect': 3.1.3
-      '@vitest/mocker': 3.1.3(vite@6.3.5(@types/node@22.15.17))
+      '@vitest/mocker': 3.1.3(vite@6.3.5(@types/node@22.15.17)(yaml@2.8.0))
       '@vitest/pretty-format': 3.1.3
       '@vitest/runner': 3.1.3
       '@vitest/snapshot': 3.1.3
···
       tinyglobby: 0.2.13
       tinypool: 1.0.2
       tinyrainbow: 2.0.0
-      vite: 6.3.5(@types/node@22.15.17)
-      vite-node: 3.1.3(@types/node@22.15.17)
+      vite: 6.3.5(@types/node@22.15.17)(yaml@2.8.0)
+      vite-node: 3.1.3(@types/node@22.15.17)(yaml@2.8.0)
       why-is-node-running: 2.3.0
     optionalDependencies:
       '@types/node': 22.15.17
···
   ws@8.18.2: {}
 
   xtend@4.0.2: {}
+
+  yaml@2.8.0:
+    optional: true
 
   yocto-queue@1.2.1: {}
 

pnpm-workspace.yaml

···
   - packages/lexicons/*
   - packages/misc/*
   - packages/oauth/*
+  - packages/servers/*
   - packages/utilities/*