@atcute/xrpc-server 0.1.0

package/lib/auth/jwt-verifier.ts

@@ -0,0 +1,215 @@
+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;
+	audience: 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,
+				audience: payload.aud,
+				lxm: payload.lxm,
+			},
+		};
+	}
+}

package/lib/auth/jwt.ts

@@ -0,0 +1,124 @@
+import * as v from '@badrap/valita';
+
+import { isDid, isNsid } from '@atcute/lexicons/syntax';
+import { fromBase64Url } from '@atcute/multibase';
+import { decodeUtf8From, encodeUtf8 } from '@atcute/uint8array';
+
+import type { Result } from '../types/misc.js';
+
+import type { AuthError } from './types.js';
+
+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({
+		/** issuer */
+		iss: didString,
+		/** target audience */
+		aud: didString,
+		/** expiration time */
+		exp: integer,
+		/** creation time */
+		iat: integer.optional(),
+		/** xrpc operation being invoked */
+		lxm: nsidString.optional(),
+		/** unique identifier */
+		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(fromBase64Url(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: fromBase64Url(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: encodeUtf8(`${headerString}.${payloadString}`),
+			signature: signature.value,
+		},
+	};
+};

package/lib/auth/types.ts

@@ -0,0 +1,4 @@
+export type AuthError = {
+	error: string;
+	description: string;
+};

package/lib/main/index.ts

@@ -0,0 +1,3 @@
+export * from './response.js';
+export * from './router.js';
+export * from './xrpc-error.js';

package/lib/main/response.ts

@@ -0,0 +1,9 @@
+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);
+};

package/lib/main/router.ts

@@ -0,0 +1,237 @@
+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 { constructMimeValidator } from './utils/request-input.js';
+import { constructParamsHandler } from './utils/request-params.js';
+import { invalidRequest, validationError } from './utils/response.js';
+
+import { XRPCError } from './xrpc-error.js';
+
+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 validateInputType = procedure.input ? constructMimeValidator(procedure.input) : 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 = {};
+				}
+
+				if (requiresInput) {
+					if (request.body === null) {
+						return invalidRequest(`request body is expected but none was provided`);
+					}
+
+					if (validateInputType !== null) {
+						const result = validateInputType(request);
+						if (!result.ok) {
+							return invalidRequest(result.error);
+						}
+					}
+
+					if (inputSchema !== null) {
+						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 (request.body !== null) {
+						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);
+			},
+		};
+	}
+}

package/lib/main/types/operation.ts

@@ -0,0 +1,87 @@
+import type {
+	InferOutput,
+	ObjectSchema,
+	XRPCBlobBodyParam,
+	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> =
+	(TProcedure['input'] extends XRPCBlobBodyParam
+		? {
+				request: Request & { readonly body: ReadableStream<Uint8Array> };
+			}
+		: TProcedure['input'] extends XRPCLexBodyParam
+			? {
+					request: Request & { readonly body: null };
+				}
+			: {
+					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>;
+};

package/lib/main/utils/middlewares.ts

@@ -0,0 +1,13 @@
+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`)),
+	);
+};