@fedify/fedify 2.4.0-dev.2256 → 2.4.0-dev.2259

package/dist/{middleware-Dxn0E9ES.mjs → middleware-CkjwiEBd.mjs}

@@ -3,28 +3,29 @@ import "urlpattern-polyfill";
 globalThis.addEventListener = () => {};
 import { d as isPortableUri, f as isSameObjectId, i as getPortableDid, l as isPortableId, n as getCanonicalPortableId, o as hasPortableActor, r as getGatewayKeyBase, s as isCompatibleKeyId, t as getAuthenticationOrigin, u as isPortableKeyId } from "./portable-key-id-Ca30-hOa.mjs";
 import { n as isPubliclyAddressedNode, t as isInAudience } from "./audience-CHQ-FlLD.mjs";
-import { n as version, t as name } from "./deno-AmcRMq5z.mjs";
-import { a as instrumentDocumentLoader, b as recordWebFingerHandle, c as recordCircuitBreakerStateChange, d as recordCollectionRequest, f as recordCollectionTotalItems, g as recordInboxActivity, h as recordFanoutRecipients, i as getRemoteHost, l as recordCollectionDispatchDuration, n as getDurationMs, o as isAbortError, r as getFederationMetrics, u as recordCollectionPageItems, v as recordOutboxActivity, x as registerQueueDepthGauge, y as recordOutboxEnqueue } from "./metrics-CocsZP0E.mjs";
+import { a as verificationObservation, r as snapshotKey, t as observeAttempt } from "./verification-Dpfcw8ml.mjs";
+import { n as version, t as name } from "./deno-C8XaXmPB.mjs";
+import { a as instrumentDocumentLoader, b as recordWebFingerHandle, c as recordCircuitBreakerStateChange, d as recordCollectionRequest, f as recordCollectionTotalItems, g as recordInboxActivity, h as recordFanoutRecipients, i as getRemoteHost, l as recordCollectionDispatchDuration, n as getDurationMs, o as isAbortError, r as getFederationMetrics, u as recordCollectionPageItems, v as recordOutboxActivity, x as registerQueueDepthGauge, y as recordOutboxEnqueue } from "./metrics-DWCn4VXX.mjs";
 import { t as formatAcceptSignature } from "./accept-CPVqki78.mjs";
-import { c as validateCryptoKey, n as exportJwk, s as importJwk } from "./key-CEsu7oaD.mjs";
+import { c as validateCryptoKey, n as exportJwk, s as importJwk } from "./key-DecAtABm.mjs";
 import { r as normalizeOutgoingActivityJsonLd } from "./outgoing-jsonld-4IJqPYos.mjs";
-import { _ as wrapContextLoaderForJsonLd, a as compactJsonLd, c as getNormalizationContextLoader, d as isClearlyMalformedContextReference, f as isInvalidUrlTypeError, l as hasSignature, m as verifyCompactJsonLd, p as signJsonLd, r as assertSafeJsonLd, s as detachSignature, t as InvalidContextReferenceError, u as hasSignatureLike } from "./ld-Cf4CPWN_.mjs";
-import { a as signObject, c as verifyPortableObjectProof, i as hasProofLike, s as verifyObject, t as InvalidPortableObjectIdError, u as verifyPortableObjectProofWithRoot } from "./proof-8WiH_-Gq.mjs";
-import { a as listRequestSignatures, c as selectRequestSignature, d as validateMaxSignatures, f as verifyRequest, p as verifyRequestDetailed, s as parseRfc9421SignatureInput } from "./http-DkqWu-sm.mjs";
-import { t as getAuthenticatedDocumentLoader } from "./docloader-CIP_SG39.mjs";
-import { n as kvCache } from "./kv-cache-CJS4mImS.mjs";
+import { _ as wrapContextLoaderForJsonLd, a as compactJsonLd, c as getNormalizationContextLoader, d as isClearlyMalformedContextReference, f as isInvalidUrlTypeError, l as hasSignature, m as verifyCompactJsonLd, p as signJsonLd, r as assertSafeJsonLd, s as detachSignature, t as InvalidContextReferenceError, u as hasSignatureLike } from "./ld-UsN-TIPh.mjs";
+import { a as signObject, c as verifyPortableObjectProof, i as hasProofLike, s as verifyObject, t as InvalidPortableObjectIdError, u as verifyPortableObjectProofWithRoot } from "./proof-BHRf_jMG.mjs";
+import { a as listRequestSignatures, c as selectRequestSignature, d as validateMaxSignatures, f as verifyRequest, p as verifyRequestDetailed, s as parseRfc9421SignatureInput } from "./http-BqSbUEiQ.mjs";
+import { t as getAuthenticatedDocumentLoader } from "./docloader-CpdFLwAg.mjs";
+import { n as kvCache } from "./kv-cache-CWWlMv-s.mjs";
 import { d as readBoundedText, l as BodyTooLargeError, t as getNodeInfo, u as MAX_BODY_SIZE } from "./client-CEnNz8O7.mjs";
 import { t as nodeInfoToJson } from "./types-DE_LV1JB.mjs";
-import { n as getKeyOwner, t as doesActorOwnKey } from "./owner-DSJ7nFgy.mjs";
-import { t as verifyPortableObject } from "./portable-collection-qskqXJrH.mjs";
-import { a as getOrderingDestination, i as sendActivityThroughGateways, n as extractInboxes, r as sendActivity, t as SendActivityError } from "./send-JKzZBgPU.mjs";
-import { n as FederationBuilderImpl, t as ACTOR_ALIAS_PREFIX } from "./builder-DvSQqk2l.mjs";
+import { n as getKeyOwner, t as doesActorOwnKey } from "./owner-CEBn81LD.mjs";
+import { t as verifyPortableObject } from "./portable-collection-qFSYw4TG.mjs";
+import { a as getOrderingDestination, i as sendActivityThroughGateways, n as extractInboxes, r as sendActivity, t as SendActivityError } from "./send-DjG8DDU_.mjs";
+import { n as FederationBuilderImpl, t as ACTOR_ALIAS_PREFIX } from "./builder-CBNa1Uw2.mjs";
 import { t as CircuitBreaker } from "./circuit-breaker-XJ53md4S.mjs";
 import { t as buildCollectionSynchronizationHeader } from "./collection-CnnP1UAv.mjs";
-import { a as verifyCompoundPortableObjectProofs, i as inspectCompoundPortableObjectApplicability, r as findUnsupportedCompoundProofShape, s as verifyServedPortableObjects, t as containsCompoundPortableObject } from "./compound-proof-5bg_j_ye.mjs";
+import { a as verifyCompoundPortableObjectProofs, i as inspectCompoundPortableObjectApplicability, r as findUnsupportedCompoundProofShape, s as verifyServedPortableObjects, t as containsCompoundPortableObject } from "./compound-proof-CMPv4UK0.mjs";
 import { t as KvKeyCache } from "./keycache-Da8A8mZa.mjs";
 import { t as acceptsJsonLd } from "./negotiation-CCocWT_N.mjs";
-import { t as hasMalformedKnownTemporalLiteral } from "./temporal-CT3fRaMH.mjs";
+import { t as hasMalformedKnownTemporalLiteral } from "./temporal-BRFH_dte.mjs";
 import { t as createExponentialBackoffPolicy } from "./retry-zX5xw5e0.mjs";
 import { t as TaskCodec } from "./codec-C6rTrpIp.mjs";
 import { getLogger, withContext } from "@logtape/logtape";
@@ -39,6 +40,111 @@ import { ATTR_HTTP_REQUEST_HEADER, ATTR_HTTP_REQUEST_METHOD, ATTR_HTTP_RESPONSE_
 import jsonld from "@fedify/vocab-runtime/jsonld";
 import { DataPointType, MeterProvider as MeterProvider$1, MetricReader } from "@opentelemetry/sdk-metrics";
 import { domainToASCII } from "node:url";
+//#region src/federation/inbox-observation.ts
+/** Internal state owned by the ingress boundary, never serialized into queues. */
+var InboxObservation = class {
+	inbox;
+	payload = { status: "unavailable" };
+	activity = null;
+	authentication = { status: "notDetermined" };
+	hasException = false;
+	stage = "prepare";
+	result = {
+		disposition: "rejected",
+		reason: "recipientNotFound"
+	};
+	verification = {
+		attempts: [],
+		subject: {
+			id: null,
+			pointer: ""
+		},
+		parsedObject: (object) => {
+			if (object instanceof Activity) {
+				this.activity = object;
+				this.verification.subject.id = object.id == null ? null : new URL(object.id.href);
+			}
+		}
+	};
+	constructor(inbox) {
+		this.inbox = inbox;
+	}
+	/** Run an ingress operation and project telemetry; fetch owns completion. */
+	async run(operation, span) {
+		let response;
+		let outcome;
+		let threw = false;
+		let originalError;
+		try {
+			response = await operation();
+			outcome = {
+				type: "response",
+				status: response.status,
+				...this.result
+			};
+		} catch (error) {
+			threw = true;
+			this.hasException = true;
+			originalError = error;
+			outcome = {
+				type: "exception",
+				stage: this.stage,
+				error
+			};
+		}
+		if (span != null) this.project(span, outcome);
+		if (threw) throw originalError;
+		return response;
+	}
+	/** Complete standalone handler calls that have no enclosing fetch boundary. */
+	async runAndFinish(getContext, handler, operation) {
+		let response;
+		try {
+			response = await this.run(operation);
+		} catch (error) {
+			await this.finish(getContext(), handler, {
+				type: "exception",
+				stage: this.stage,
+				error
+			});
+			throw error;
+		}
+		await this.finish(getContext(), handler, {
+			type: "response",
+			status: response.status,
+			...this.result
+		});
+		return response;
+	}
+	project(span, outcome) {
+		span.setAttribute("activitypub.authentication.status", this.authentication.status);
+		if (this.authentication.status === "rejected") span.setAttribute("activitypub.verification.failure_reason", this.authentication.reason.type);
+		span.setAttribute("activitypub.inbox.disposition", outcome?.type === "exception" || this.hasException ? "exception" : this.result.disposition);
+	}
+	async finish(context, handler, outcome) {
+		if (handler == null) return;
+		const report = {
+			inbox: this.inbox,
+			payload: this.payload,
+			activity: this.activity,
+			attempts: this.verification.attempts,
+			authentication: this.authentication,
+			outcome
+		};
+		try {
+			await handler(context, report);
+		} catch (error) {
+			try {
+				getLogger([
+					"fedify",
+					"federation",
+					"inbox"
+				]).error("An unexpected error occurred in inbox request finished handler:\n{error}", { error });
+			} catch {}
+		}
+	}
+};
+//#endregion
 //#region src/compat/transformers.ts
 const logger$2 = getLogger([
 	"fedify",
@@ -1620,13 +1726,13 @@ function recordCollectionMetrics(meterProvider, base, result, options = {}) {
 * @param parameters The parameters for handling the collection.
 * @returns A promise that resolves to an HTTP response.
 */
-async function handleCollection(request, { name: name$1, identifier, uriGetter, filter, filterPredicate, context, collectionCallbacks, portable, tracerProvider, meterProvider, onUnauthorized, onNotFound }) {
-	const spanName = name$1.trim().replace(/\s+/g, "_");
+async function handleCollection(request, { name: name$2, identifier, uriGetter, filter, filterPredicate, context, collectionCallbacks, portable, tracerProvider, meterProvider, onUnauthorized, onNotFound }) {
+	const spanName = name$2.trim().replace(/\s+/g, "_");
 	tracerProvider = tracerProvider ?? trace.getTracerProvider();
 	const tracer = tracerProvider.getTracer(name, version);
 	const cursor = new URL(request.url).searchParams.get("cursor");
 	const metricBase = {
-		kind: getCollectionMetricKind(name$1),
+		kind: getCollectionMetricKind(name$2),
 		page: cursor != null,
 		dispatcher: "built_in"
 	};
@@ -1672,7 +1778,7 @@ async function handleCollection(request, { name: name$1, identifier, uriGetter,
 							span.setStatus({ code: SpanStatusCode.ERROR });
 							return await onNotFound(request);
 						}
-						const items = filterCollectionItems(page.items, name$1, filterPredicate);
+						const items = filterCollectionItems(page.items, name$2, filterPredicate);
 						itemCount = items.length;
 						span.setAttribute("fedify.collection.items", itemCount);
 						return items;
@@ -1714,7 +1820,7 @@ async function handleCollection(request, { name: name$1, identifier, uriGetter,
 		} else {
 			const uri = new URL(portable == null ? baseUri : pageBase);
 			uri.searchParams.set("cursor", cursor);
-			const pageOrResponse = await tracer.startActiveSpan(`activitypub.dispatch_collection_page ${name$1}`, {
+			const pageOrResponse = await tracer.startActiveSpan(`activitypub.dispatch_collection_page ${name$2}`, {
 				kind: SpanKind.SERVER,
 				attributes: {
 					"activitypub.collection.id": uri.href,
@@ -1730,7 +1836,7 @@ async function handleCollection(request, { name: name$1, identifier, uriGetter,
 						span.setStatus({ code: SpanStatusCode.ERROR });
 						return await onNotFound(request);
 					}
-					const items = filterCollectionItems(page.items, name$1, filterPredicate);
+					const items = filterCollectionItems(page.items, name$2, filterPredicate);
 					itemCount = items.length;
 					span.setAttribute("fedify.collection.items", itemCount);
 					return {
@@ -2211,6 +2317,16 @@ async function handleMediaUpload(request, { identifier, context: ctx, mediaUploa
 * @returns A promise that resolves to an HTTP response.
 */
 async function handleInbox(request, options) {
+	if (options.observation == null) {
+		const observation = new InboxObservation({
+			kind: options.portableInbox != null ? "portable" : options.recipient == null ? "shared" : "personal",
+			recipient: options.recipient
+		});
+		return await observation.runAndFinish(() => options.context, options.inboxRequestFinishedHandler, () => handleInbox(request, {
+			...options,
+			observation
+		}));
+	}
 	return await (options.tracerProvider ?? trace.getTracerProvider()).getTracer(name, version).startActiveSpan("activitypub.inbox", {
 		kind: options.queue == null ? SpanKind.SERVER : SpanKind.PRODUCER,
 		attributes: { "activitypub.shared_inbox": options.recipient == null }
@@ -2219,12 +2335,14 @@ async function handleInbox(request, options) {
 		try {
 			return await handleInboxInternal(request, options, span);
 		} catch (e) {
+			options.observation.hasException = true;
 			span.setStatus({
 				code: SpanStatusCode.ERROR,
 				message: String(e)
 			});
 			throw e;
 		} finally {
+			options.observation.project(span);
 			span.end();
 		}
 	});
@@ -2239,6 +2357,8 @@ async function handleInbox(request, options) {
 */
 async function handleInboxInternal(request, parameters, span) {
 	const { recipient, context: ctx, inboxContextFactory, kv, kvPrefixes, publicKeyTtl, queue, actorDispatcher, inboxListeners, inboxErrorHandler, unverifiedActivityHandler, onNotFound, signatureTimeWindow, maxHttpSignatures, skipSignatureVerification, inboxChallengePolicy, meterProvider, tracerProvider, portableInbox } = parameters;
+	const observation = parameters.observation;
+	const signatureObservation = { [verificationObservation]: observation.verification };
 	const logger = getLogger([
 		"fedify",
 		"federation",
@@ -2263,6 +2383,10 @@ async function handleInboxInternal(request, parameters, span) {
 		}
 	}
 	if (request.bodyUsed) {
+		observation.result = {
+			disposition: "failed",
+			reason: "bodyUnavailable"
+		};
 		logger.error("Request body has already been read.", { recipient });
 		span.setStatus({
 			code: SpanStatusCode.ERROR,
@@ -2273,6 +2397,10 @@ async function handleInboxInternal(request, parameters, span) {
 			headers: { "Content-Type": "text/plain; charset=utf-8" }
 		});
 	} else if (request.body?.locked) {
+		observation.result = {
+			disposition: "failed",
+			reason: "bodyUnavailable"
+		};
 		logger.error("Request body is locked.", { recipient });
 		span.setStatus({
 			code: SpanStatusCode.ERROR,
@@ -2283,11 +2411,20 @@ async function handleInboxInternal(request, parameters, span) {
 			headers: { "Content-Type": "text/plain; charset=utf-8" }
 		});
 	}
+	observation.stage = "parse";
+	observation.result = {
+		disposition: "rejected",
+		reason: "invalidJson"
+	};
 	let json;
 	try {
 		json = JSON.parse(await readBoundedText(request.clone(), MAX_BODY_SIZE, request.url));
 	} catch (error) {
 		if (error instanceof BodyTooLargeError) {
+			observation.result = {
+				disposition: "rejected",
+				reason: "bodyTooLarge"
+			};
 			request.body?.cancel(error).catch(() => {});
 			span.setStatus({
 				code: SpanStatusCode.ERROR,
@@ -2317,6 +2454,15 @@ async function handleInboxInternal(request, parameters, span) {
 			headers: { "Content-Type": "text/plain; charset=utf-8" }
 		});
 	}
+	observation.payload = {
+		status: "parsed",
+		value: structuredClone(json)
+	};
+	observation.result = {
+		disposition: "rejected",
+		reason: "invalidActivity"
+	};
+	observation.stage = "verify";
 	const keyCache = new KvKeyCache(kv, kvPrefixes.publicKey, {
 		documentLoader: ctx.documentLoader,
 		contextLoader: ctx.contextLoader,
@@ -2346,6 +2492,10 @@ async function handleInboxInternal(request, parameters, span) {
 			code: SpanStatusCode.ERROR,
 			message: `Failed to parse activity:\n${error}`
 		});
+		observation.result = {
+			disposition: "rejected",
+			reason: "invalidActivity"
+		};
 		return new Response("Invalid activity.", {
 			status: 400,
 			headers: { "Content-Type": "text/plain; charset=utf-8" }
@@ -2363,11 +2513,25 @@ async function handleInboxInternal(request, parameters, span) {
 					recipient,
 					error
 				});
+				observation.result = {
+					disposition: "rejected",
+					reason: "invalidJsonLd"
+				};
 				return new Response("Invalid JSON-LD.", {
 					status: 400,
 					headers: { "Content-Type": "text/plain; charset=utf-8" }
 				});
 			}
+			observation.verification.attempts.push({
+				mechanism: "linkedData",
+				subject: {
+					id: null,
+					pointer: ""
+				},
+				checks: [],
+				status: "error",
+				error
+			});
 			if (!canAttemptAlternateAuthAfterLdSignatureFailure) throw error;
 			if (!skipSignatureVerification) deferredLdSignatureError = error;
 			logger.debug("Failed to normalize JSON-LD for Linked Data Signatures; deferring to another authentication path only if it verifies:\n{error}", {
@@ -2379,6 +2543,7 @@ async function handleInboxInternal(request, parameters, span) {
 			compactedJsonWithoutSig = detachSignature(compactedJson);
 			try {
 				ldSigVerified = await verifyCompactJsonLd(compactedJson, {
+					...signatureObservation,
 					contextLoader: ctx.contextLoader,
 					documentLoader: ctx.documentLoader,
 					keyCache,
@@ -2392,6 +2557,10 @@ async function handleInboxInternal(request, parameters, span) {
 						recipient,
 						error
 					});
+					observation.result = {
+						disposition: "rejected",
+						reason: "invalidJsonLd"
+					};
 					return new Response("Invalid JSON-LD.", {
 						status: 400,
 						headers: { "Content-Type": "text/plain; charset=utf-8" }
@@ -2411,6 +2580,10 @@ async function handleInboxInternal(request, parameters, span) {
 							recipient,
 							error: parseError
 						});
+						observation.result = {
+							disposition: "rejected",
+							reason: "invalidJsonLd"
+						};
 						return new Response("Invalid JSON-LD.", {
 							status: 400,
 							headers: { "Content-Type": "text/plain; charset=utf-8" }
@@ -2431,7 +2604,7 @@ async function handleInboxInternal(request, parameters, span) {
 			json
 		});
 		try {
-			activity = await Activity.fromJsonLd(compactedJsonWithoutSig, {
+			activity = observation.activity = await Activity.fromJsonLd(compactedJsonWithoutSig, {
 				...ctx,
 				contextLoader: getNormalizationContextLoader(ctx.contextLoader)
 			});
@@ -2443,6 +2616,7 @@ async function handleInboxInternal(request, parameters, span) {
 		activityVerified = true;
 		if (!skipSignatureVerification && isPortableActivity(activity)) try {
 			proofVerified = await verifyObject(Activity, jsonWithoutSig, {
+				...signatureObservation,
 				contextLoader: wrapContextLoaderForJsonLd(ctx.contextLoader),
 				documentLoader: ctx.documentLoader,
 				keyCache,
@@ -2463,6 +2637,7 @@ async function handleInboxInternal(request, parameters, span) {
 		});
 		try {
 			activity = await verifyObject(Activity, jsonWithoutSig, {
+				...signatureObservation,
 				contextLoader: wrapContextLoaderForJsonLd(ctx.contextLoader),
 				documentLoader: ctx.documentLoader,
 				keyCache,
@@ -2498,6 +2673,10 @@ async function handleInboxInternal(request, parameters, span) {
 				code: SpanStatusCode.ERROR,
 				message: `Failed to parse activity:\n${error}`
 			});
+			observation.result = {
+				disposition: "rejected",
+				reason: "invalidActivity"
+			};
 			return new Response("Invalid activity.", {
 				status: 400,
 				headers: { "Content-Type": "text/plain; charset=utf-8" }
@@ -2521,6 +2700,7 @@ async function handleInboxInternal(request, parameters, span) {
 	if (activity == null) {
 		if (!skipSignatureVerification) {
 			const verification = await verifyRequestDetailed(request, {
+				...signatureObservation,
 				contextLoader: ctx.contextLoader,
 				documentLoader: ctx.documentLoader,
 				timeWindow: signatureTimeWindow,
@@ -2531,6 +2711,14 @@ async function handleInboxInternal(request, parameters, span) {
 			});
 			if (verification.verified === false) {
 				if (deferredLdSignatureError != null) throw deferredLdSignatureError;
+				observation.authentication = {
+					status: "rejected",
+					reason: { type: "verificationFailed" }
+				};
+				observation.result = {
+					disposition: "rejected",
+					reason: "authentication"
+				};
 				const reason = verification.reason;
 				const remoteHost = "keyId" in reason && reason.keyId != null ? getRemoteHost(reason.keyId) : void 0;
 				getFederationMetrics(parameters.meterProvider).recordSignatureVerificationFailure(reason.type, remoteHost);
@@ -2545,7 +2733,7 @@ async function handleInboxInternal(request, parameters, span) {
 				});
 				if (unverifiedActivityHandler == null) return await getFailedSignatureResponse(inboxChallengePolicy, kv, kvPrefixes);
 				try {
-					activity = await Activity.fromJsonLd(jsonWithoutSig, ctx);
+					activity = observation.activity = await Activity.fromJsonLd(jsonWithoutSig, ctx);
 				} catch (error) {
 					logger.error("Failed to parse activity:\n{error}", {
 						recipient,
@@ -2561,6 +2749,10 @@ async function handleInboxInternal(request, parameters, span) {
 							recipient
 						});
 					}
+					observation.result = {
+						disposition: "rejected",
+						reason: "invalidActivity"
+					};
 					return new Response("Invalid activity.", {
 						status: 400,
 						headers: { "Content-Type": "text/plain; charset=utf-8" }
@@ -2583,6 +2775,11 @@ async function handleInboxInternal(request, parameters, span) {
 				try {
 					response = await unverifiedActivityHandler(ctx, activity, reason);
 				} catch (error) {
+					observation.result = {
+						disposition: "failed",
+						reason: "listenerError",
+						error
+					};
 					logger.error("An unexpected error occurred in unverified activity handler:\n{error}", {
 						error,
 						activity: json,
@@ -2599,7 +2796,10 @@ async function handleInboxInternal(request, parameters, span) {
 					}
 					return await getFailedSignatureResponse(inboxChallengePolicy, kv, kvPrefixes);
 				}
-				if (response instanceof Response) return response;
+				if (response instanceof Response) {
+					observation.result = { disposition: "customResponse" };
+					return response;
+				}
 				return await getFailedSignatureResponse(inboxChallengePolicy, kv, kvPrefixes);
 			} else {
 				if (inboxChallengePolicy?.enabled && inboxChallengePolicy.requestNonce) pendingNonceLabel = verification.signatureLabel;
@@ -2609,7 +2809,7 @@ async function handleInboxInternal(request, parameters, span) {
 			httpSigKey = verification.key;
 		}
 		try {
-			activity = await Activity.fromJsonLd(jsonWithoutSig, {
+			activity = observation.activity = await Activity.fromJsonLd(jsonWithoutSig, {
 				...ctx,
 				contextLoader: wrapContextLoaderForJsonLd(ctx.contextLoader)
 			});
@@ -2618,6 +2818,12 @@ async function handleInboxInternal(request, parameters, span) {
 			return await respondInvalidActivity(error);
 		}
 	}
+	observation.activity = activity;
+	observation.stage = "policy";
+	observation.result = {
+		disposition: "rejected",
+		reason: "authentication"
+	};
 	if (activity.id != null) span.setAttribute("activitypub.activity.id", activity.id.href);
 	span.setAttribute("activitypub.activity.type", getTypeId(activity).href);
 	span.addEvent("activitypub.activity.received", {
@@ -2629,6 +2835,13 @@ async function handleInboxInternal(request, parameters, span) {
 	});
 	if (!skipSignatureVerification && !proofVerified && (isPortableActivity(activity) || isPortableActorKey(httpSigKey))) {
 		if (deferredLdSignatureError != null) throw deferredLdSignatureError;
+		observation.authentication = {
+			status: "rejected",
+			reason: {
+				type: "proofPolicy",
+				policy: "portableActor"
+			}
+		};
 		logger.error("The activity {activityId} of the portable actor {actorId} is not authenticated by a valid Object Integrity Proof.", {
 			activity: json,
 			recipient,
@@ -2646,20 +2859,36 @@ async function handleInboxInternal(request, parameters, span) {
 		});
 	}
 	if (!skipSignatureVerification && activity.id != null && isPortableId(activity.id)) {
-		const rejection = await verifyPortableActivityId(activity.id, jsonWithoutSig, {
-			contextLoader: wrapContextLoaderForJsonLd(ctx.contextLoader),
-			documentLoader: ctx.documentLoader,
-			keyCache,
-			meterProvider,
-			tracerProvider
-		});
+		const rejection = await observeAttempt(signatureObservation, "objectIntegrity", async (verification) => {
+			const rejection = await verifyPortableActivityId(activity.id, jsonWithoutSig, {
+				[verificationObservation]: verification,
+				contextLoader: wrapContextLoaderForJsonLd(ctx.contextLoader),
+				documentLoader: ctx.documentLoader,
+				keyCache,
+				meterProvider,
+				tracerProvider
+			});
+			if (rejection != null) verification.attempt.reason = {
+				type: "proofPolicy",
+				reason: rejection
+			};
+			return rejection;
+		}, (value) => value == null);
 		if (rejection != null) {
 			if (deferredLdSignatureError != null) throw deferredLdSignatureError;
+			observation.authentication = {
+				status: "rejected",
+				reason: {
+					type: "proofPolicy",
+					policy: "portableActivity",
+					detail: rejection
+				}
+			};
 			logger.error("The portable activity {activityId} is not authenticated by an Object Integrity Proof of its own DID: {reason}", {
 				activity: json,
 				recipient,
 				activityId: activity.id.href,
-				reason: rejection
+				reason: rejection.type
 			});
 			span.setStatus({
 				code: SpanStatusCode.ERROR,
@@ -2673,6 +2902,14 @@ async function handleInboxInternal(request, parameters, span) {
 	}
 	if (httpSigKey != null && !await doesActorOwnKey(activity, httpSigKey, ctx)) {
 		if (deferredLdSignatureError != null) throw deferredLdSignatureError;
+		observation.authentication = {
+			status: "rejected",
+			reason: {
+				type: "actorKeyMismatch",
+				key: snapshotKey(httpSigKey),
+				actorIds: activity.actorIds.map((id) => new URL(id.href))
+			}
+		};
 		getFederationMetrics(parameters.meterProvider).recordSignatureVerificationFailure("actorKeyMismatch", httpSigKey.id == null ? void 0 : getRemoteHost(httpSigKey.id));
 		logger.error("The signer ({keyId}) and the actor ({actorId}) do not match.", {
 			activity: json,
@@ -2692,13 +2929,35 @@ async function handleInboxInternal(request, parameters, span) {
 	if (!skipSignatureVerification) {
 		const compoundJson = Array.isArray(json) ? json : jsonWithoutSig;
 		if (inspectCompoundPortableObjectApplicability(compoundJson, INBOX_COMPOUND_PROOF_LIMITS) !== "absent") {
-			const compoundProof = await verifyCompoundPortableObjectProofs(compoundJson, INBOX_COMPOUND_PROOF_LIMITS, {
-				documentLoader: ctx.documentLoader,
-				keyCache,
-				meterProvider,
-				tracerProvider
-			});
+			const compoundProof = await observeAttempt(signatureObservation, "objectIntegrity", async (verification) => {
+				const result = await verifyCompoundPortableObjectProofs(compoundJson, INBOX_COMPOUND_PROOF_LIMITS, {
+					[verificationObservation]: verification,
+					documentLoader: ctx.documentLoader,
+					keyCache,
+					meterProvider,
+					tracerProvider
+				});
+				if (result.status === "unsupported") verification.attempt.reason = {
+					type: "proofPolicy",
+					reason: result.reason
+				};
+				else if (!result.verified) {
+					const failed = result.portableObjects.find((object) => !object.verified);
+					verification.attempt.reason = {
+						type: "proofPolicy",
+						reason: failed?.verified === false ? failed.reason : { type: "invalidProof" }
+					};
+				}
+				return result;
+			}, (result) => result.status === "ok" && result.verified);
 			if (compoundProof.status !== "ok" || !compoundProof.verified) {
+				observation.authentication = {
+					status: "rejected",
+					reason: {
+						type: "proofPolicy",
+						policy: "compound"
+					}
+				};
 				logger.error("Failed to verify compound portable Object Integrity Proofs.", {
 					recipient,
 					activity: json,
@@ -2717,11 +2976,20 @@ async function handleInboxInternal(request, parameters, span) {
 	}
 	if (pendingNonceLabel != null) {
 		if (!await verifySignatureNonce(request, kv, kvPrefixes.acceptSignatureNonce, pendingNonceLabel)) {
+			observation.authentication = {
+				status: "rejected",
+				reason: { type: "invalidNonce" }
+			};
 			getFederationMetrics(parameters.meterProvider).recordSignatureVerificationFailure("invalidNonce", httpSigKey?.id == null ? void 0 : getRemoteHost(httpSigKey.id));
 			logger.error("Signature nonce verification failed (missing, expired, or replayed).", { recipient });
 			return await getFailedSignatureResponse(inboxChallengePolicy, kv, kvPrefixes);
 		}
 	}
+	observation.authentication = skipSignatureVerification ? { status: "skipped" } : {
+		status: "verified",
+		attempts: observation.verification.attempts.filter((attempt) => attempt.status === "verified")
+	};
+	observation.stage = "dispatch";
 	const routeResult = await routeActivity({
 		context: ctx,
 		json,
@@ -2733,7 +3001,14 @@ async function handleInboxInternal(request, parameters, span) {
 		inboxListeners,
 		inboxContextFactory,
 		listenerInboxContextFactory: ldSigVerified ? inboxContextFactory[rawInboxContextFactorySymbol] : void 0,
-		inboxErrorHandler,
+		inboxErrorHandler: async (context, error) => {
+			observation.result = {
+				disposition: "failed",
+				reason: "listenerError",
+				error
+			};
+			await inboxErrorHandler?.(context, error);
+		},
 		kv,
 		kvPrefixes,
 		queue,
@@ -2769,30 +3044,44 @@ async function handleInboxInternal(request, parameters, span) {
 			error
 		});
 	}
-	if (routeResult === "alreadyProcessed") return new Response(`Activity <${activity.id}> has already been processed.`, {
-		status: 202,
-		headers: { "Content-Type": "text/plain; charset=utf-8" }
-	});
-	else if (routeResult === "missingActor") return new Response("Missing actor.", {
-		status: 400,
-		headers: { "Content-Type": "text/plain; charset=utf-8" }
-	});
-	else if (routeResult === "enqueued") return new Response("Activity is enqueued.", {
-		status: 202,
-		headers: { "Content-Type": "text/plain; charset=utf-8" }
-	});
-	else if (routeResult === "unsupportedActivity") return new Response("", {
-		status: 202,
-		headers: { "Content-Type": "text/plain; charset=utf-8" }
-	});
-	else if (routeResult === "error") return new Response("Internal server error.", {
+	if (routeResult === "alreadyProcessed") {
+		observation.result = { disposition: "duplicate" };
+		return new Response(`Activity <${activity.id}> has already been processed.`, {
+			status: 202,
+			headers: { "Content-Type": "text/plain; charset=utf-8" }
+		});
+	} else if (routeResult === "missingActor") {
+		observation.result = {
+			disposition: "rejected",
+			reason: "missingActor"
+		};
+		return new Response("Missing actor.", {
+			status: 400,
+			headers: { "Content-Type": "text/plain; charset=utf-8" }
+		});
+	} else if (routeResult === "enqueued") {
+		observation.result = { disposition: "enqueued" };
+		return new Response("Activity is enqueued.", {
+			status: 202,
+			headers: { "Content-Type": "text/plain; charset=utf-8" }
+		});
+	} else if (routeResult === "unsupportedActivity") {
+		observation.result = { disposition: "unhandled" };
+		return new Response("", {
+			status: 202,
+			headers: { "Content-Type": "text/plain; charset=utf-8" }
+		});
+	} else if (routeResult === "error") return new Response("Internal server error.", {
 		status: 500,
 		headers: { "Content-Type": "text/plain; charset=utf-8" }
 	});
-	else return new Response("", {
-		status: 202,
-		headers: { "Content-Type": "text/plain; charset=utf-8" }
-	});
+	else {
+		observation.result = { disposition: "processed" };
+		return new Response("", {
+			status: 202,
+			headers: { "Content-Type": "text/plain; charset=utf-8" }
+		});
+	}
 }
 const PORTABLE_INBOX_FORWARDABLE_RESULTS = /* @__PURE__ */ new Set([
 	"success",
@@ -2921,8 +3210,8 @@ var CustomCollectionHandler = class {
 	* @param CollectionPage The CollectionPage constructor.
 	* @param filterPredicate Optional filter predicate for items.
 	*/
-	constructor(name$2, values, context, callbacks, tracerProvider = trace.getTracerProvider(), meterProvider, Collection, CollectionPage, filterPredicate, portable) {
-		this.name = name$2;
+	constructor(name$1, values, context, callbacks, tracerProvider = trace.getTracerProvider(), meterProvider, Collection, CollectionPage, filterPredicate, portable) {
+		this.name = name$1;
 		this.values = values;
 		this.context = context;
 		this.callbacks = callbacks;
@@ -3458,19 +3747,19 @@ function isPortableActivity(activity) {
 */
 async function verifyPortableActivityId(activityId, jsonLd, options) {
 	const expectedId = getCanonicalPortableId(activityId);
-	if (expectedId == null) return "malformed portable ID";
+	if (expectedId == null) return { type: "invalidObjectId" };
 	let verification;
 	try {
 		verification = await verifyPortableObjectProofWithRoot(jsonLd, options);
 	} catch (error) {
-		if (error instanceof InvalidPortableObjectIdError) return "malformed portable ID";
+		if (error instanceof InvalidPortableObjectIdError) return { type: "invalidObjectId" };
 		if (!isPermanentActivityParseError(error)) throw error;
-		return "malformed document";
+		return { type: "invalidDocument" };
 	}
 	const { result, root } = verification;
-	if (!result.verified) return result.reason.type;
+	if (!result.verified) return result.reason;
 	const rootId = root?.["@id"];
-	if (typeof rootId !== "string" || getCanonicalPortableId(parseIri(rootId)) !== expectedId) return "the verified document has another ID";
+	if (typeof rootId !== "string" || getCanonicalPortableId(parseIri(rootId)) !== expectedId) return { type: "subjectMismatch" };
 	return null;
 }
 //#endregion
@@ -5950,7 +6239,7 @@ var FederationImpl = class extends FederationBuilderImpl {
 				return await withContext({
 					traceId: spanCtx.traceId,
 					spanId: spanCtx.spanId
-				}, async () => {
+				}, () => this.#observeInboxFetch(metricState, async () => {
 					const logger = getLogger([
 						"fedify",
 						"federation",
@@ -5965,8 +6254,14 @@ var FederationImpl = class extends FederationBuilderImpl {
 							tracer,
 							metricState
 						});
+						if (metricState.inboxCompletion != null) metricState.inboxCompletion.observation.stage = "respond";
 						if (metricState.endpoint !== "hashlink_media" && acceptsJsonLd(request)) response.headers.set("Vary", "Accept");
 					} catch (error) {
+						metricState.inboxCompletion?.observation.project(span, {
+							type: "exception",
+							stage: metricState.inboxCompletion.observation.stage,
+							error
+						});
 						this.metrics.recordHttpServerRequest(request.method, metricState.endpoint ?? "error", getDurationMs(metricStart), { routeTemplate: metricState.routeTemplate });
 						span.setStatus({
 							code: SpanStatusCode.ERROR,
@@ -6005,7 +6300,7 @@ var FederationImpl = class extends FederationBuilderImpl {
 					else if (response.status >= 400) logger.warn(logTpl, values);
 					else logger.info(logTpl, values);
 					return response;
-				});
+				}));
 			});
 		});
 	}
@@ -6047,8 +6342,17 @@ var FederationImpl = class extends FederationBuilderImpl {
 		metricState.routeTemplate = route.template;
 		metricState.endpoint = getEndpointCategory(route.name);
 		span.updateName(`${request.method} ${route.template}`);
-		let context = this.#createContext(request, contextData);
 		const routeName = route.name.replace(/:.*$/, "");
+		let context;
+		try {
+			context = this.#createContext(request, contextData);
+		} catch (error) {
+			if (request.method !== "POST" || routeName !== "inbox" && routeName !== "sharedInbox") throw error;
+			return await this.#reportInboxPreparationError(request, contextData, {
+				kind: routeName === "inbox" ? "personal" : "shared",
+				recipient: route.values.identifier ?? null
+			}, error, span, metricState);
+		}
 		switch (routeName) {
 			case "webfinger": return await handleWebFinger(request, {
 				context,
@@ -6107,6 +6411,28 @@ var FederationImpl = class extends FederationBuilderImpl {
 			});
 			return response;
 		}
+		if (request.method === "POST" && (routeName === "inbox" || routeName === "sharedInbox")) {
+			const recipient = route.values.identifier ?? null;
+			const observation = new InboxObservation({
+				kind: routeName === "inbox" ? "personal" : "shared",
+				recipient
+			});
+			this.#setInboxCompletion(metricState, observation, () => context);
+			return await observation.run(async () => {
+				if (routeName === "inbox") context = this.#createContext(request, contextData, { documentLoader: await context.getDocumentLoader({ identifier: recipient }) });
+				else if (this.sharedInboxKeyDispatcher != null) {
+					const identity = await this.sharedInboxKeyDispatcher(context);
+					if (identity != null) context = this.#createContext(request, contextData, { documentLoader: "identifier" in identity || "username" in identity ? await context.getDocumentLoader(identity) : context.getDocumentLoader(identity) });
+				}
+				return await this.#handleInbox(request, {
+					recipient,
+					context,
+					contextData,
+					onNotFound,
+					observation
+				});
+			}, span);
+		}
 		switch (routeName) {
 			case "actor":
 			case "actorAlias": {
@@ -6182,9 +6508,9 @@ var FederationImpl = class extends FederationBuilderImpl {
 					onUnauthorized,
 					onNotFound
 				});
-				context = this.#createContext(request, contextData, { documentLoader: await context.getDocumentLoader({ identifier: route.values.identifier }) });
+				throw new Error("Unreachable inbox delivery.");
 			case "sharedInbox":
-				if (routeName !== "inbox" && this.sharedInboxKeyDispatcher != null) {
+				if (this.sharedInboxKeyDispatcher != null) {
 					const identity = await this.sharedInboxKeyDispatcher(context);
 					if (identity != null) context = this.#createContext(request, contextData, { documentLoader: "identifier" in identity || "username" in identity ? await context.getDocumentLoader(identity) : context.getDocumentLoader(identity) });
 				}
@@ -6477,7 +6803,49 @@ var FederationImpl = class extends FederationBuilderImpl {
 		}
 		return await onNotFound(request);
 	}
-	async #handleInbox(request, { recipient, context, contextData, onNotFound, portableInbox }) {
+	#setInboxCompletion(metricState, observation, getContext) {
+		const handler = this.inboxRequestFinishedHandler;
+		metricState.inboxCompletion = {
+			observation,
+			finish: (outcome) => observation.finish(getContext(), handler, outcome)
+		};
+	}
+	async #observeInboxFetch(metricState, operation) {
+		let response;
+		try {
+			response = await operation();
+		} catch (error) {
+			const completion = metricState.inboxCompletion;
+			if (completion != null) await completion.finish({
+				type: "exception",
+				stage: completion.observation.stage,
+				error
+			});
+			throw error;
+		}
+		const completion = metricState.inboxCompletion;
+		if (completion != null) await completion.finish({
+			type: "response",
+			status: response.status,
+			...completion.observation.result
+		});
+		return response;
+	}
+	async #reportInboxPreparationError(request, contextData, inbox, error, span, metricState) {
+		const unavailableLoader = () => Promise.reject(error);
+		const context = new RequestContextImpl({
+			url: new URL(request.url),
+			request,
+			federation: this,
+			data: contextData,
+			documentLoader: unavailableLoader,
+			contextLoader: unavailableLoader
+		});
+		const observation = new InboxObservation(inbox);
+		this.#setInboxCompletion(metricState, observation, () => context);
+		return await observation.run(() => Promise.reject(error), span);
+	}
+	async #handleInbox(request, { recipient, context, contextData, onNotFound, portableInbox, observation }) {
 		if (!this.manuallyStartQueue) this._startQueueInternal(contextData);
 		const inboxContextFactory = context.toInboxContext.bind(context);
 		inboxContextFactory[rawInboxContextFactorySymbol] = context.toInboxContext.bind(context);
@@ -6501,7 +6869,8 @@ var FederationImpl = class extends FederationBuilderImpl {
 			meterProvider: this.meterProvider,
 			tracerProvider: this.tracerProvider,
 			idempotencyStrategy: this.idempotencyStrategy,
-			portableInbox
+			portableInbox,
+			observation
 		});
 	}
 	async #fetchPortableInbox(request, portable, { onNotFound, contextData, span, metricState }) {
@@ -6530,63 +6899,79 @@ var FederationImpl = class extends FederationBuilderImpl {
 		metricState.endpoint = "inbox";
 		span.updateName(`${request.method} ${metricState.routeTemplate}`);
 		const identifier = route.values.identifier;
-		let context = this.#createContext(request, contextData);
-		const actor = this.actorCallbacks?.dispatcher == null ? null : await this.actorCallbacks.dispatcher(context, identifier);
-		const localOrigin = context.canonicalOrigin;
-		const resolution = resolvePortableInboxRecipient(actor == null || actor instanceof Tombstone ? null : actor, {
-			authority: portable.portableRequest.authority,
-			canonicalInboxId: portable.canonicalId,
-			localOrigin
-		});
-		if (resolution.status === "rejected") {
-			logger.debug("Not accepting a delivery to the portable inbox {inbox} on behalf of the actor {identifier}: {reason}.", {
-				inbox: portable.canonicalId,
-				identifier,
-				reason: resolution.reason
-			});
-			return await onNotFound(request);
+		let context;
+		try {
+			context = this.#createContext(request, contextData);
+		} catch (error) {
+			return await this.#reportInboxPreparationError(request, contextData, {
+				kind: "portable",
+				recipient: identifier
+			}, error, span, metricState);
 		}
-		const { recipient } = resolution;
-		if (this.actorCallbacks?.keyPairsDispatcher != null) context = this.#createContext(request, contextData, { documentLoader: await context.getDocumentLoader({ identifier }) });
-		const excludedOrigins = [localOrigin, new URL(request.url).origin];
-		return await this.#handleInbox(request, {
-			recipient: identifier,
-			context,
-			contextData,
-			onNotFound,
-			portableInbox: {
-				recipient,
-				forward: async (activity, activityId, activityType, signatures) => {
-					if (this.portableInboxForwarding.maxTargets < 1) return;
-					if (this.kv.cas == null) {
-						if (!this.#portableInboxForwardingWarned) {
-							this.#portableInboxForwardingWarned = true;
-							logger.warn("Activities delivered to FEP-ef61 portable inboxes are not forwarded to the other gateways, as the key–value store does not support compare-and-swap (KvStore.cas()), which is needed to forward each activity at most once.");
+		const observation = new InboxObservation({
+			kind: "portable",
+			recipient: identifier
+		});
+		this.#setInboxCompletion(metricState, observation, () => context);
+		return await observation.run(async () => {
+			const actor = this.actorCallbacks?.dispatcher == null ? null : await this.actorCallbacks.dispatcher(context, identifier);
+			const localOrigin = context.canonicalOrigin;
+			const resolution = resolvePortableInboxRecipient(actor == null || actor instanceof Tombstone ? null : actor, {
+				authority: portable.portableRequest.authority,
+				canonicalInboxId: portable.canonicalId,
+				localOrigin
+			});
+			if (resolution.status === "rejected") {
+				logger.debug("Not accepting a delivery to the portable inbox {inbox} on behalf of the actor {identifier}: {reason}.", {
+					inbox: portable.canonicalId,
+					identifier,
+					reason: resolution.reason
+				});
+				return await onNotFound(request);
+			}
+			const { recipient } = resolution;
+			if (this.actorCallbacks?.keyPairsDispatcher != null) context = this.#createContext(request, contextData, { documentLoader: await context.getDocumentLoader({ identifier }) });
+			const excludedOrigins = [localOrigin, new URL(request.url).origin];
+			return await this.#handleInbox(request, {
+				recipient: identifier,
+				observation,
+				context,
+				contextData,
+				onNotFound,
+				portableInbox: {
+					recipient,
+					forward: async (activity, activityId, activityType, signatures) => {
+						if (this.portableInboxForwarding.maxTargets < 1) return;
+						if (this.kv.cas == null) {
+							if (!this.#portableInboxForwardingWarned) {
+								this.#portableInboxForwardingWarned = true;
+								logger.warn("Activities delivered to FEP-ef61 portable inboxes are not forwarded to the other gateways, as the key–value store does not support compare-and-swap (KvStore.cas()), which is needed to forward each activity at most once.");
+							}
+							return;
 						}
-						return;
+						await forwardPortableInboxActivity({
+							recipient,
+							activity,
+							activityId,
+							activityType,
+							excludedOrigins,
+							baseUrl: context.origin,
+							kv: this.kv,
+							kvPrefix: this.kvPrefixes.portableInboxForwarding,
+							outboxQueue: this.outboxQueue,
+							startQueue: this.manuallyStartQueue ? void 0 : () => this._startQueueInternal(contextData),
+							allowPrivateAddress: this.allowPrivateAddress,
+							getKeys: () => this.#getPortableGatewayKeyPairs(context, identifier, recipient),
+							specDeterminer: new KvSpecDeterminer(this.kv, this.kvPrefixes.httpMessageSignaturesSpec, this.firstKnock, { specTtl: this.httpMessageSignaturesSpecTtl }),
+							signatures,
+							options: this.portableInboxForwarding,
+							meterProvider: this.meterProvider,
+							tracerProvider: this.tracerProvider
+						});
 					}
-					await forwardPortableInboxActivity({
-						recipient,
-						activity,
-						activityId,
-						activityType,
-						excludedOrigins,
-						baseUrl: context.origin,
-						kv: this.kv,
-						kvPrefix: this.kvPrefixes.portableInboxForwarding,
-						outboxQueue: this.outboxQueue,
-						startQueue: this.manuallyStartQueue ? void 0 : () => this._startQueueInternal(contextData),
-						allowPrivateAddress: this.allowPrivateAddress,
-						getKeys: () => this.#getPortableGatewayKeyPairs(context, identifier, recipient),
-						specDeterminer: new KvSpecDeterminer(this.kv, this.kvPrefixes.httpMessageSignaturesSpec, this.firstKnock, { specTtl: this.httpMessageSignaturesSpecTtl }),
-						signatures,
-						options: this.portableInboxForwarding,
-						meterProvider: this.meterProvider,
-						tracerProvider: this.tracerProvider
-					});
 				}
-			}
-		});
+			});
+		}, span);
 	}
 	/**
 	* Gets this server's gateway key pairs for the portable actor that owns