@atcute/xrpc-server 0.1.11 → 1.0.0

package/lib/auth/jwt-verifier.ts

@@ -1,61 +1,161 @@
 import { getPublicKeyFromDidController, verifySig, type FoundPublicKey } from '@atcute/crypto';
-import { getAtprotoVerificationMaterial, type DidDocument } from '@atcute/identity';
+import { getVerificationMaterial, type DidDocument } from '@atcute/identity';
 import { type DidDocumentResolver } from '@atcute/identity-resolver';
 import type { Did, Nsid } from '@atcute/lexicons';
+import type { AtprotoAudience } from '@atcute/lexicons/syntax';
 import * as uint8arrays from '@atcute/uint8array';
 
+import { AuthRequiredError } from '../main/xrpc-error.ts';
 import type { Result } from '../types/misc.ts';
 
 import { parseJwt, type ParsedJwt } from './jwt.ts';
 import type { AuthError } from './types.ts';
 
+type SupportedKid = `#${string}`;
+/** only `#atproto` is accepted as a signing key identifier for now */
+const DEFAULT_KID: SupportedKid = '#atproto';
+
+/**
+ * replay-protection store for service JWTs. when configured on a verifier,
+ * tokens must carry a `jti` claim and the verifier consults this store to
+ * reject duplicates.
+ */
+export interface ReplayStore {
+	/**
+	 * record a `(iss, jti)` pair seen now.
+	 *
+	 * @param key issuer + token identifier; implementations decide how to
+	 *   encode this into a storage key.
+	 * @param ttlSeconds how long the entry must be retained. implementations
+	 *   are free to retain it for longer.
+	 * @returns `true` if the pair was previously unseen (token is unique),
+	 *   `false` if the pair has been recorded before (replay).
+	 */
+	check(key: { iss: Did; jti: string }, ttlSeconds: number): Promise<boolean>;
+}
+
 export interface ServiceJwtVerifierOptions {
-	serviceDid: Did | null;
+	/**
+	 * list of `aud` values accepted by this service; each entry is a bare DID or a DID with
+	 * service fragment (e.g. `did:web:x.example#svc`), and incoming tokens must exact-match any entry.
+	 *
+	 * pass `null` to skip audience validation (accept any audience). an empty array rejects every
+	 * audience, which is useful when a service wants to fail closed until configured.
+	 */
+	acceptAudiences: (Did | AtprotoAudience)[] | null;
 	resolver: DidDocumentResolver;
+	/**
+	 * maximum token lifetime window in seconds. rejects tokens whose `exp` is
+	 * more than this far in the future or whose `iat` is more than this far in
+	 * the past. defaults to 300 (5 minutes), matching atproto convention.
+	 */
+	maxAge?: number;
+	/**
+	 * clock-skew leeway in seconds applied to `exp` and `nbf` comparisons.
+	 * defaults to 5 seconds.
+	 */
+	clockLeeway?: number;
+	/**
+	 * optional replay-protection store. when provided, tokens must carry a
+	 * `jti` claim and the verifier rejects any `(iss, jti)` the store reports
+	 * as previously seen.
+	 */
+	replayStore?: ReplayStore;
 }
 
 export interface VerifyJwtOptions {
-	lxm: Nsid | Nsid[] | null;
+	lxm: Nsid | Nsid[];
+	/** abort signal forwarded to DID resolution; falls back to `request.signal` in `verifyRequest`. */
+	signal?: AbortSignal;
 }
 
 export interface VerifiedJwt {
 	issuer: Did;
-	audience: Did;
-	lxm: string | undefined;
+	audience: Did | AtprotoAudience;
+	lxm: Nsid;
 }
 
+const BEARER_PREFIX = 'Bearer ';
+
 export class ServiceJwtVerifier {
 	didDocResolver: DidDocumentResolver;
-	serviceDid: Did | null;
+	acceptAudiences: (Did | AtprotoAudience)[] | null;
+	maxAge: number;
+	clockLeeway: number;
+	replayStore?: ReplayStore;
 
 	constructor(options: ServiceJwtVerifierOptions) {
 		this.didDocResolver = options.resolver;
-		this.serviceDid = options.serviceDid;
+		this.acceptAudiences = options.acceptAudiences;
+		this.maxAge = options.maxAge ?? 5 * 60;
+		this.clockLeeway = options.clockLeeway ?? 5;
+		this.replayStore = options.replayStore;
+	}
+
+	/**
+	 * parse the Authorization header, verify the bearer token, and return the
+	 * validated claims. throws {@link AuthRequiredError} with a populated
+	 * `WWW-Authenticate: Bearer` challenge on every failure path.
+	 *
+	 * @param request incoming request; `request.signal` is forwarded to DID
+	 *   resolution unless `options.signal` overrides it.
+	 * @param options verification options; `lxm` restricts which lexicon
+	 *   methods the token is allowed to invoke.
+	 * @throws {AuthRequiredError} on missing header, malformed token,
+	 *   signature mismatch, audience/lxm rejection, replay, or expiry.
+	 */
+	async verifyRequest(request: Request, options: VerifyJwtOptions): Promise<VerifiedJwt> {
+		const authorization = request.headers.get('authorization');
+		if (authorization === null) {
+			throw new AuthRequiredError({
+				message: 'authorization header required',
+				wwwAuthenticate: { scheme: 'Bearer' },
+			});
+		}
+
+		if (!authorization.startsWith(BEARER_PREFIX)) {
+			throw authError({ error: 'MissingBearer', description: 'expected a bearer token' });
+		}
+
+		const token = authorization.slice(BEARER_PREFIX.length).trim();
+		const signal = options.signal ?? request.signal;
+
+		const result = await this.#verifyToken(token, { lxm: options.lxm, signal });
+		if (!result.ok) {
+			throw authError(result.error);
+		}
+
+		return result.value;
 	}
 
-	async #getSigningKey(issuer: Did, noCache: boolean): Promise<Result<FoundPublicKey, AuthError>> {
+	async #getSigningKey(
+		issuer: Did,
+		kid: SupportedKid,
+		noCache: boolean,
+		signal: AbortSignal,
+	): Promise<Result<FoundPublicKey, AuthError>> {
 		let didDocument: DidDocument;
 		let key: FoundPublicKey;
 
 		try {
-			didDocument = await this.didDocResolver.resolve(issuer, { noCache });
+			didDocument = await this.didDocResolver.resolve(issuer, { noCache, signal });
 		} catch {
 			return {
 				ok: false,
 				error: {
-					error: 'UnresolvedDidDocument',
+					error: 'DidResolutionFailed',
 					description: `failed to retrieve did document for ${issuer}`,
 				},
 			};
 		}
 
-		const controller = getAtprotoVerificationMaterial(didDocument);
+		const controller = getVerificationMaterial(didDocument, kid);
 		if (!controller) {
 			return {
 				ok: false,
 				error: {
 					error: 'BadJwtIssuer',
-					description: `${issuer} does not have an atproto verification material`,
+					description: `${issuer} does not have a ${kid} verification material`,
 				},
 			};
 		}
@@ -67,7 +167,7 @@ export class ServiceJwtVerifier {
 				ok: false,
 				error: {
 					error: 'BadJwtIssuer',
-					description: `${issuer} has invalid atproto verification material`,
+					description: `${issuer} has invalid ${kid} verification material`,
 				},
 			};
 		}
@@ -92,8 +192,11 @@ export class ServiceJwtVerifier {
 		}
 	}
 
-	async verify(jwtString: string, options?: VerifyJwtOptions): Promise<Result<VerifiedJwt, AuthError>> {
-		const parsed = parseJwt(jwtString);
+	async #verifyToken(
+		token: string,
+		options: { lxm: Nsid | Nsid[]; signal: AbortSignal },
+	): Promise<Result<VerifiedJwt, AuthError>> {
+		const parsed = parseJwt(token);
 		if (!parsed.ok) {
 			return parsed;
 		}
@@ -114,7 +217,33 @@ export class ServiceJwtVerifier {
 			}
 		}
 
-		if (Date.now() / 1_000 > payload.exp) {
+		// resolve the `kid` header (defaulting to `#atproto`) and restrict to the set of
+		// identifiers this verifier knows how to look up in the issuer's DID document.
+		// matches proposal 0014's "safe default" for SDKs.
+		const kid: string = header.kid ?? DEFAULT_KID;
+		if (kid !== DEFAULT_KID) {
+			return {
+				ok: false,
+				error: {
+					error: 'BadJwtIssuer',
+					description: `unsupported signing key identifier (${kid})`,
+				},
+			};
+		}
+
+		const now = Math.floor(Date.now() / 1_000);
+
+		if (payload.nbf !== undefined && now < payload.nbf - this.clockLeeway) {
+			return {
+				ok: false,
+				error: {
+					error: 'JwtNotYetValid',
+					description: `jwt is not yet valid`,
+				},
+			};
+		}
+
+		if (now > payload.exp + this.clockLeeway) {
 			return {
 				ok: false,
 				error: {
@@ -124,20 +253,33 @@ export class ServiceJwtVerifier {
 			};
 		}
 
-		if (this.serviceDid !== undefined && this.serviceDid !== payload.aud) {
+		// prevent issuers from minting very long-lived tokens: the configured max-age
+		// window bounds how far `exp` can be in the future and how far `iat` can be in
+		// the past.
+		if (payload.exp - now > this.maxAge || (payload.iat !== undefined && now - payload.iat > this.maxAge)) {
+			return {
+				ok: false,
+				error: {
+					error: 'JwtTooOld',
+					description: `jwt exceeds maximum age (${this.maxAge}s)`,
+				},
+			};
+		}
+
+		if (this.acceptAudiences !== null && !this.acceptAudiences.includes(payload.aud)) {
 			return {
 				ok: false,
 				error: {
-					error: 'BadJwtAudience',
-					description: `jwt audience does not match (expected ${this.serviceDid})`,
+					error: 'InvalidAudience',
+					description:
+						this.acceptAudiences.length === 0
+							? `jwt audience does not match (no audiences accepted)`
+							: `jwt audience does not match (expected one of: ${this.acceptAudiences.join(', ')})`,
 				},
 			};
 		}
 
-		if (
-			options?.lxm != null &&
-			(typeof options.lxm === 'string' ? options.lxm !== payload.lxm : !options.lxm.includes(payload.lxm!))
-		) {
+		if (typeof options.lxm === 'string' ? options.lxm !== payload.lxm : !options.lxm.includes(payload.lxm)) {
 			return {
 				ok: false,
 				error: {
@@ -147,7 +289,22 @@ export class ServiceJwtVerifier {
 			};
 		}
 
-		const key = await this.#getSigningKey(payload.iss, false);
+		let jti: string | undefined;
+		if (this.replayStore !== undefined) {
+			if (payload.jti === undefined) {
+				return {
+					ok: false,
+					error: {
+						error: 'BadJwt',
+						description: `jwt is missing the jti claim (required for replay protection)`,
+					},
+				};
+			}
+
+			jti = payload.jti;
+		}
+
+		const key = await this.#getSigningKey(payload.iss, kid, false, options.signal);
 		if (!key.ok) {
 			return key;
 		}
@@ -165,7 +322,7 @@ export class ServiceJwtVerifier {
 
 		if (!isValid) {
 			// try again, uncached
-			const freshKey = await this.#getSigningKey(payload.iss, true);
+			const freshKey = await this.#getSigningKey(payload.iss, kid, true, options.signal);
 			if (!freshKey.ok) {
 				return freshKey;
 			}
@@ -183,7 +340,7 @@ export class ServiceJwtVerifier {
 
 			// 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);
+				const result = await this.#verifySignature(freshKey.value, parsed.value);
 				if (!result.ok) {
 					return result;
 				}
@@ -203,6 +360,22 @@ export class ServiceJwtVerifier {
 			};
 		}
 
+		// replay-store check runs after signature verification so forged tokens
+		// can't burn entries (memory dos) or evict legitimate `(iss, jti)` pairs
+		// before the real request lands.
+		if (this.replayStore !== undefined && jti !== undefined) {
+			const unique = await this.replayStore.check({ iss: payload.iss, jti }, this.maxAge);
+			if (!unique) {
+				return {
+					ok: false,
+					error: {
+						error: 'NonceNotUnique',
+						description: `jwt has been used before`,
+					},
+				};
+			}
+		}
+
 		return {
 			ok: true,
 			value: {
@@ -213,3 +386,10 @@ export class ServiceJwtVerifier {
 		};
 	}
 }
+
+const authError = (err: AuthError): AuthRequiredError => {
+	return new AuthRequiredError({
+		message: err.description,
+		wwwAuthenticate: { scheme: 'Bearer', params: { error: err.error } },
+	});
+};

package/lib/auth/jwt.ts

@@ -1,5 +1,6 @@
+import { isAtprotoAudience } from '@atcute/identity';
 import type { Did, Nsid } from '@atcute/lexicons';
-import { isDid, isNsid } from '@atcute/lexicons/syntax';
+import { isDid, isNsid, type AtprotoAudience } from '@atcute/lexicons/syntax';
 import { fromBase64Url } from '@atcute/multibase';
 import { decodeUtf8From, encodeUtf8 } from '@atcute/uint8array';
 
@@ -10,6 +11,9 @@ import type { Result } from '../types/misc.ts';
 import type { AuthError } from './types.ts';
 
 const didString = v.string().assert(isDid, `must be a did`);
+const audienceString = v
+	.string()
+	.assert((input) => isAtprotoAudience(input) || isDid(input), `must be a did or atproto audience`);
 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`);
@@ -17,19 +21,24 @@ const integer = v.number().assert((input) => input >= 0 && Number.isSafeInteger(
 export interface JwtHeader {
 	typ?: string;
 	alg: string;
+	/** signing key identifier; a DID fragment, defaults to `#atproto` when absent */
+	kid?: string;
 }
 
 const jwtHeader: v.Type<JwtHeader> = v.object({
 	typ: v.string().optional(),
 	alg: v.string(),
+	kid: v.string().optional(),
 });
 
 export interface JwtPayload {
 	iss: Did;
-	aud: Did;
+	aud: Did | AtprotoAudience;
 	exp: number;
 	iat?: number;
-	lxm?: Nsid;
+	/** not-before time; token is invalid before this unix timestamp */
+	nbf?: number;
+	lxm: Nsid;
 	jti?: string;
 }
 
@@ -37,14 +46,16 @@ const jwtPayload: v.Type<JwtPayload> = v
 	.object({
 		/** issuer */
 		iss: didString,
-		/** target audience */
-		aud: didString,
+		/** target audience; a bare DID or a DID with service fragment (e.g. `did:web:x.example#svc`) */
+		aud: audienceString,
 		/** expiration time */
 		exp: integer,
 		/** creation time */
 		iat: integer.optional(),
-		/** xrpc operation being invoked */
-		lxm: nsidString.optional(),
+		/** not-before time */
+		nbf: integer.optional(),
+		/** xrpc operation being invoked; required per atproto service auth spec */
+		lxm: nsidString,
 		/** unique identifier */
 		jti: v.string().optional(),
 	})
@@ -74,7 +85,7 @@ const readJwtPortion = <T>(schema: v.Type<T>, input: string): Result<T, AuthErro
 	return {
 		ok: false,
 		error: {
-			error: `MalformedJwt`,
+			error: `BadJwt`,
 			description: `jwt is malformed`,
 		},
 	};
@@ -88,7 +99,7 @@ const readJwtSignature = (input: string): Result<Uint8Array<ArrayBuffer>, AuthEr
 	return {
 		ok: false,
 		error: {
-			error: `MalformedJwt`,
+			error: `BadJwt`,
 			description: `jwt is malformed`,
 		},
 	};
@@ -100,7 +111,7 @@ export const parseJwt = (jwtString: string): Result<ParsedJwt, AuthError> => {
 		return {
 			ok: false,
 			error: {
-				error: `MalformedJwt`,
+				error: `BadJwt`,
 				description: `jwt is malformed`,
 			},
 		};

package/lib/main/router.ts

@@ -38,8 +38,13 @@ type InternalRouteData = {
 export type FetchMiddleware = Middleware<[request: Request], Promise<Response>>;
 
 export type NotFoundHandler = (request: Request) => Promisable<Response>;
+export type HealthCheckHandler = (request: Request) => Promisable<Response>;
 export type ExceptionHandler = (error: unknown, request: Request) => Promisable<Response>;
-export type SubscriptionExceptionHandler = (error: unknown, request: Request) => void;
+
+/** telemetry hook invoked for unexpected HTTP handler errors; fire-and-forget. */
+export type ErrorObserver = (ctx: { error: unknown; request: Request }) => void;
+/** telemetry hook invoked for unexpected subscription errors; fire-and-forget. */
+export type SocketErrorObserver = (ctx: { error: unknown; request: Request }) => void;
 
 export const defaultExceptionHandler: ExceptionHandler = (error: unknown) => {
 	if (error instanceof XRPCError) {
@@ -60,23 +65,40 @@ export const defaultNotFoundHandler: NotFoundHandler = () => {
 	return new Response('Not Found', { status: 404 });
 };
 
-export const defaultSubscriptionExceptionHandler: SubscriptionExceptionHandler = (error: unknown) => {
-	throw error;
-};
-
 export interface XRPCRouterOptions {
 	middlewares?: FetchMiddleware[];
 	handleNotFound?: NotFoundHandler;
+	/**
+	 * optional handler for `/xrpc/_health`. when provided, the router answers
+	 * health-check requests by invoking this handler; when absent, the path
+	 * falls through to `handleNotFound`. `_health` is not part of the atproto
+	 * XRPC spec, so callers opt in explicitly.
+	 */
+	handleHealthCheck?: HealthCheckHandler;
+	/** translates a thrown error into an HTTP response. */
 	handleException?: ExceptionHandler;
-	handleSubscriptionException?: SubscriptionExceptionHandler;
+	/**
+	 * fire-and-forget telemetry hook for unexpected HTTP errors. not invoked for
+	 * client-induced errors (aborted requests, `XRPCError` subclasses, thrown
+	 * `Response` objects).
+	 */
+	onError?: ErrorObserver;
+	/**
+	 * fire-and-forget telemetry hook for unexpected subscription errors. not
+	 * invoked for aborted signals or `XRPCSubscriptionError` (which is
+	 * translated to an error frame).
+	 */
+	onSocketError?: SocketErrorObserver;
 	websocket?: WebSocketAdapter;
 }
 
 export class XRPCRouter {
 	#handlers: Record<string, InternalRouteData> = {};
 	#handleNotFound: NotFoundHandler;
+	#handleHealthCheck?: HealthCheckHandler;
 	#handleException: ExceptionHandler;
-	#handleSubscriptionException: SubscriptionExceptionHandler;
+	#onError?: ErrorObserver;
+	#onSocketError?: SocketErrorObserver;
 	#websocket?: WebSocketAdapter;
 
 	fetch: (request: Request) => Promise<Response>;
@@ -85,7 +107,9 @@ export class XRPCRouter {
 		middlewares = [],
 		handleException = defaultExceptionHandler,
 		handleNotFound = defaultNotFoundHandler,
-		handleSubscriptionException = defaultSubscriptionExceptionHandler,
+		handleHealthCheck,
+		onError,
+		onSocketError,
 		websocket,
 	}: XRPCRouterOptions = {}) {
 		const runner = createAsyncMiddlewareRunner([...middlewares, (request) => this.#dispatch(request)]);
@@ -93,10 +117,46 @@ export class XRPCRouter {
 		this.fetch = (request) => runner(request);
 		this.#handleException = handleException;
 		this.#handleNotFound = handleNotFound;
-		this.#handleSubscriptionException = handleSubscriptionException;
+		this.#handleHealthCheck = handleHealthCheck;
+		this.#onError = onError;
+		this.#onSocketError = onSocketError;
 		this.#websocket = websocket;
 	}
 
+	#observeError(error: unknown, request: Request): void {
+		// client-induced errors are not bugs; skip telemetry
+		if (request.signal.aborted) {
+			return;
+		}
+		if (error instanceof XRPCError) {
+			return;
+		}
+		if (error instanceof Response) {
+			return;
+		}
+
+		try {
+			this.#onError?.({ error, request });
+		} catch {
+			// observer threw; swallow to keep response path deterministic
+		}
+	}
+
+	#observeSocketError(error: unknown, request: Request): void {
+		if (request.signal.aborted) {
+			return;
+		}
+		if (error instanceof XRPCSubscriptionError) {
+			return;
+		}
+
+		try {
+			this.#onSocketError?.({ error, request });
+		} catch {
+			// observer threw; swallow to keep socket close path deterministic
+		}
+	}
+
 	async #dispatch(request: Request): Promise<Response> {
 		const url = new URL(request.url);
 		const pathname = url.pathname;
@@ -107,15 +167,31 @@ export class XRPCRouter {
 
 		const nsid = pathname.slice('/xrpc/'.length);
 
+		if (nsid === '_health' && this.#handleHealthCheck !== undefined) {
+			try {
+				return await this.#handleHealthCheck(request);
+			} catch (err) {
+				if (request.signal.aborted) {
+					return new Response(null, { status: 499 });
+				}
+
+				this.#observeError(err, request);
+				return this.#handleException(err, request);
+			}
+		}
+
 		const route = this.#handlers[nsid];
 		if (route === undefined) {
 			return this.#handleNotFound(request);
 		}
 
-		if (request.method !== route.method) {
+		// allow HEAD alongside GET; the runtime is responsible for stripping the
+		// response body per the Fetch API.
+		const allowed = request.method === route.method || (route.method === 'GET' && request.method === 'HEAD');
+		if (!allowed) {
 			return Response.json(
-				{ error: 'InvalidHttpMethod', message: `invalid http method (expected ${route.method})` },
-				{ status: 405, headers: { allow: `${route.method}` } },
+				{ error: 'InvalidRequest', message: `invalid http method (expected ${route.method})` },
+				{ status: 405, headers: { allow: route.method === 'GET' ? 'GET, HEAD' : route.method } },
 			);
 		}
 
@@ -131,6 +207,7 @@ export class XRPCRouter {
 				return new Response(null, { status: 499 });
 			}
 
+			this.#observeError(err, request);
 			return this.#handleException(err, request);
 		}
 	}
@@ -350,23 +427,29 @@ export class XRPCRouter {
 
 							const frame = encodeMessageFrame(body, type);
 							await ws.send(frame);
+							const drained = ws.drain();
+							if (drained) {
+								await drained;
+							}
 						}
 
 						ws.close(1000);
 					} catch (err) {
 						if (err instanceof XRPCSubscriptionError) {
-							const frame = encodeErrorFrame(err.error, err.description);
+							const frame = encodeErrorFrame(err.error, err.message || undefined);
 
 							try {
 								await ws.send(frame);
-							} catch {}
+							} catch {
+								// best-effort, socket may already be closed
+							}
 
 							ws.close(err.closeCode, err.error);
 							return;
 						}
 
 						ws.close(1011, `internal server error`);
-						this.#handleSubscriptionException(err, request);
+						this.#observeSocketError(err, request);
 					}
 				});
 

package/lib/main/types/operation.ts

@@ -12,6 +12,14 @@ import type {
 import type { Literal, Promisable } from '../../types/misc.ts';
 import type { JSONResponse } from '../response.ts';
 
+/**
+ * untyped variant of {@link QueryContext} / {@link ProcedureContext}.
+ *
+ * `input` is set only when the lexicon declares a `lex` input body and the
+ * request JSON parsed successfully. for blob inputs (and for procedures that
+ * declare no input at all) it is `undefined`; handlers that expect a blob
+ * should stream from `request.body` directly.
+ */
 export type UnknownOperationContext = {
 	request: Request;
 	signal: AbortSignal;

package/lib/main/types/websocket.ts

@@ -3,6 +3,14 @@ import type { Promisable } from '../../types/misc.ts';
 export interface WebSocketConnection {
 	signal: AbortSignal;
 	send(data: Uint8Array): void | Promise<void>;
+	/**
+	 * backpressure hook invoked by the router after every frame it sends.
+	 * adapters that can observe the outgoing send buffer (Node `ws`, Bun, Deno)
+	 * should resolve only once the buffer has drained below a healthy threshold.
+	 * adapters without that visibility (e.g. Cloudflare Workers) should return
+	 * synchronously.
+	 */
+	drain(): void | Promise<void>;
 	close(code?: number, reason?: string): void;
 }