@atcute/xrpc-server 0.1.12 → 1.0.0

package/dist/main/xrpc-error.js

@@ -1,72 +1,112 @@
+/**
+ * formats one or more WWW-Authenticate challenges into a single header value.
+ *
+ * each challenge is emitted as `<scheme>` followed by its params or token68.
+ * multiple challenges are joined with `, `. auth-param values are quoted using
+ * `JSON.stringify` (RFC 7230 quoted-string semantics for ASCII content).
+ *
+ * @param challenges one challenge, or an ordered array of challenges
+ * @returns the formatted header value
+ *
+ * @example
+ * ```ts
+ * formatWWWAuthenticate({ scheme: 'Bearer', params: { error: 'BadJwtSignature' } })
+ * // => `Bearer error="BadJwtSignature"`
+ * ```
+ */
+export const formatWWWAuthenticate = (challenges) => {
+    const list = Array.isArray(challenges) ? challenges : [challenges];
+    return list.map(formatChallenge).join(', ');
+};
+const formatChallenge = (challenge) => {
+    if (challenge.token68 !== undefined) {
+        return `${challenge.scheme} ${challenge.token68}`;
+    }
+    if (challenge.params !== undefined) {
+        const parts = [];
+        for (const name in challenge.params) {
+            const value = challenge.params[name];
+            if (value !== undefined) {
+                parts.push(`${name}=${JSON.stringify(value)}`);
+            }
+        }
+        if (parts.length > 0) {
+            return `${challenge.scheme} ${parts.join(', ')}`;
+        }
+    }
+    return challenge.scheme;
+};
 export class XRPCError extends Error {
     /** response status */
     status;
     /** error name */
     error;
-    /** error message */
-    description;
     /** response headers */
     headers;
-    constructor({ status, error, description, headers }) {
-        super(`${error} > ${description ?? '(unspecified description)'}`);
+    constructor({ status, error, message, headers }) {
+        super(message);
         this.status = status;
         this.error = error;
-        this.description = description;
         this.headers = headers;
     }
     toResponse() {
-        return Response.json({ error: this.error, message: this.description }, { status: this.status, headers: this.headers });
+        return Response.json({ error: this.error, message: this.message || undefined }, { status: this.status, headers: this.headers });
     }
 }
 export class InvalidRequestError extends XRPCError {
-    constructor({ status = 400, error = 'InvalidRequest', description, headers, } = {}) {
-        super({ status, error, description, headers });
+    constructor({ status = 400, error = 'InvalidRequest', message, headers } = {}) {
+        super({ status, error, message, headers });
     }
 }
 export class AuthRequiredError extends XRPCError {
-    constructor({ status = 401, error = 'AuthenticationRequired', description, headers, } = {}) {
-        super({ status, error, description, headers });
+    constructor({ status = 401, error = 'AuthenticationRequired', message, headers, wwwAuthenticate, } = {}) {
+        let mergedHeaders = headers;
+        if (wwwAuthenticate !== undefined) {
+            const target = new Headers(headers);
+            target.set('www-authenticate', formatWWWAuthenticate(wwwAuthenticate));
+            target.append('access-control-expose-headers', 'www-authenticate');
+            mergedHeaders = target;
+        }
+        super({ status, error, message, headers: mergedHeaders });
     }
 }
 export class ForbiddenError extends XRPCError {
-    constructor({ status = 403, error = 'Forbidden', description, headers } = {}) {
-        super({ status, error, description, headers });
+    constructor({ status = 403, error = 'Forbidden', message, headers } = {}) {
+        super({ status, error, message, headers });
     }
 }
 export class RateLimitExceededError extends XRPCError {
-    constructor({ status = 429, error = 'RateLimitExceeded', description, headers, } = {}) {
-        super({ status, error, description, headers });
+    constructor({ status = 429, error = 'RateLimitExceeded', message, headers, } = {}) {
+        super({ status, error, message, headers });
     }
 }
 export class InternalServerError extends XRPCError {
-    constructor({ status = 500, error = 'InternalServerError', description, headers, } = {}) {
-        super({ status, error, description, headers });
+    constructor({ status = 500, error = 'InternalServerError', message, headers, } = {}) {
+        super({ status, error, message, headers });
     }
 }
 export class UpstreamFailureError extends XRPCError {
-    constructor({ status = 502, error = 'UpstreamFailure', description, headers, } = {}) {
-        super({ status, error, description, headers });
+    constructor({ status = 502, error = 'UpstreamFailure', message, headers } = {}) {
+        super({ status, error, message, headers });
     }
 }
 export class NotEnoughResourcesError extends XRPCError {
-    constructor({ status = 503, error = 'NotEnoughResources', description, headers, } = {}) {
-        super({ status, error, description, headers });
+    constructor({ status = 503, error = 'NotEnoughResources', message, headers, } = {}) {
+        super({ status, error, message, headers });
     }
 }
 export class UpstreamTimeoutError extends XRPCError {
-    constructor({ status = 504, error = 'UpstreamTimeout', description, headers, } = {}) {
-        super({ status, error, description, headers });
+    constructor({ status = 504, error = 'UpstreamTimeout', message, headers } = {}) {
+        super({ status, error, message, headers });
     }
 }
 export class XRPCSubscriptionError extends Error {
     closeCode;
     error;
-    description;
-    constructor({ closeCode = 1008, error, description }) {
-        super(`Subscription error: ${error}${description ? ` - ${description}` : ''}`);
+    constructor({ closeCode = 1008, error, message }) {
+        super(message);
         this.closeCode = closeCode;
         this.error = error;
-        this.description = description;
     }
 }
 //# sourceMappingURL=xrpc-error.js.map

package/dist/main/xrpc-error.js.map

@@ -1 +1 @@
-{"version":3,"file":"xrpc-error.js","sourceRoot":"","sources":["../../lib/main/xrpc-error.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"xrpc-error.js","sourceRoot":"","sources":["../../lib/main/xrpc-error.ts"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CACpC,UAAiE,EACxD,EAAE;IACX,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;IACnE,OAAO,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC7C,CAAC,CAAC;AAEF,MAAM,eAAe,GAAG,CAAC,SAAmC,EAAU,EAAE;IACvE,IAAI,SAAS,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACrC,OAAO,GAAG,SAAS,CAAC,MAAM,IAAI,SAAS,CAAC,OAAO,EAAE,CAAC;IACnD,CAAC;IAED,IAAI,SAAS,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QACpC,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,MAAM,EAAE,CAAC;YACrC,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACrC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACzB,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAChD,CAAC;QACF,CAAC;QAED,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtB,OAAO,GAAG,SAAS,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAClD,CAAC;IACF,CAAC;IAED,OAAO,SAAS,CAAC,MAAM,CAAC;AACzB,CAAC,CAAC;AASF,MAAM,OAAO,SAAU,SAAQ,KAAK;IACnC,sBAAsB;IACb,MAAM,CAAS;IAExB,iBAAiB;IACR,KAAK,CAAS;IACvB,uBAAuB;IACd,OAAO,CAAe;IAE/B,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAoB;QAChE,KAAK,CAAC,OAAO,CAAC,CAAC;QAEf,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QAErB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACxB,CAAC;IAED,UAAU;QACT,OAAO,QAAQ,CAAC,IAAI,CACnB,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,SAAS,EAAE,EACzD,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAC9C,CAAC;IACH,CAAC;CACD;AAED,MAAM,OAAO,mBAAoB,SAAQ,SAAS;IACjD,YAAY,EAAE,MAAM,GAAG,GAAG,EAAE,KAAK,GAAG,gBAAgB,EAAE,OAAO,EAAE,OAAO,EAAE,GAA8B,EAAE;QACvG,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IAC5C,CAAC;CACD;AAWD,MAAM,OAAO,iBAAkB,SAAQ,SAAS;IAC/C,YAAY,EACX,MAAM,GAAG,GAAG,EACZ,KAAK,GAAG,wBAAwB,EAChC,OAAO,EACP,OAAO,EACP,eAAe,GACf,GAA6B,EAAE;QAC/B,IAAI,aAAa,GAAG,OAAO,CAAC;QAE5B,IAAI,eAAe,KAAK,SAAS,EAAE,CAAC;YACnC,MAAM,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;YACpC,MAAM,CAAC,GAAG,CAAC,kBAAkB,EAAE,qBAAqB,CAAC,eAAe,CAAC,CAAC,CAAC;YACvE,MAAM,CAAC,MAAM,CAAC,+BAA+B,EAAE,kBAAkB,CAAC,CAAC;YACnE,aAAa,GAAG,MAAM,CAAC;QACxB,CAAC;QAED,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC,CAAC;IAC3D,CAAC;CACD;AAED,MAAM,OAAO,cAAe,SAAQ,SAAS;IAC5C,YAAY,EAAE,MAAM,GAAG,GAAG,EAAE,KAAK,GAAG,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,GAA8B,EAAE;QAClG,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IAC5C,CAAC;CACD;AAED,MAAM,OAAO,sBAAuB,SAAQ,SAAS;IACpD,YAAY,EACX,MAAM,GAAG,GAAG,EACZ,KAAK,GAAG,mBAAmB,EAC3B,OAAO,EACP,OAAO,GACP,GAA8B,EAAE;QAChC,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IAC5C,CAAC;CACD;AAED,MAAM,OAAO,mBAAoB,SAAQ,SAAS;IACjD,YAAY,EACX,MAAM,GAAG,GAAG,EACZ,KAAK,GAAG,qBAAqB,EAC7B,OAAO,EACP,OAAO,GACP,GAA8B,EAAE;QAChC,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IAC5C,CAAC;CACD;AAED,MAAM,OAAO,oBAAqB,SAAQ,SAAS;IAClD,YAAY,EAAE,MAAM,GAAG,GAAG,EAAE,KAAK,GAAG,iBAAiB,EAAE,OAAO,EAAE,OAAO,EAAE,GAA8B,EAAE;QACxG,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IAC5C,CAAC;CACD;AAED,MAAM,OAAO,uBAAwB,SAAQ,SAAS;IACrD,YAAY,EACX,MAAM,GAAG,GAAG,EACZ,KAAK,GAAG,oBAAoB,EAC5B,OAAO,EACP,OAAO,GACP,GAA8B,EAAE;QAChC,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IAC5C,CAAC;CACD;AAED,MAAM,OAAO,oBAAqB,SAAQ,SAAS;IAClD,YAAY,EAAE,MAAM,GAAG,GAAG,EAAE,KAAK,GAAG,iBAAiB,EAAE,OAAO,EAAE,OAAO,EAAE,GAA8B,EAAE;QACxG,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IAC5C,CAAC;CACD;AAQD,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IACtC,SAAS,CAAS;IAClB,KAAK,CAAS;IAEvB,YAAY,EAAE,SAAS,GAAG,IAAI,EAAE,KAAK,EAAE,OAAO,EAAgC;QAC7E,KAAK,CAAC,OAAO,CAAC,CAAC;QAEf,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACpB,CAAC;CACD"}

package/lib/auth/jwt-creator.ts

@@ -1,5 +1,6 @@
 import type { PrivateKey } from '@atcute/crypto';
 import type { Did, Nsid } from '@atcute/lexicons';
+import type { AtprotoAudience } from '@atcute/lexicons/syntax';
 import { toBase64Url } from '@atcute/multibase';
 import { encodeUtf8 } from '@atcute/uint8array';
 
@@ -10,8 +11,9 @@ import type { JwtHeader, JwtPayload } from './jwt.ts';
 export interface CreateServiceJwtOptions {
 	keypair: PrivateKey;
 	issuer: Did;
-	audience: Did;
-	lxm: Nsid | null;
+	/** audience is either a bare DID or a DID with service fragment (e.g. `did:web:x.example#svc`) */
+	audience: Did | AtprotoAudience;
+	lxm: Nsid;
 	issuedAt?: number;
 	expiresIn?: number;
 }
@@ -33,7 +35,7 @@ export const createServiceJwt = async (options: CreateServiceJwtOptions): Promis
 		iat: issuedAt,
 		iss: options.issuer,
 		jti: nanoid(24),
-		lxm: options.lxm ?? undefined,
+		lxm: options.lxm,
 	};
 
 	const headerB64 = encodeJwtPortion(header);

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 !== null && 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;
 			}
@@ -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`,
 			},
 		};