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

package/dist/{federation-BDzIgqOd.cjs → federation-D6giSGUT.cjs}

@@ -1,10 +1,10 @@
 const { URLPattern } = require("urlpattern-polyfill");
 const require_rolldown_runtime = require("./rolldown-runtime-Dmm3t92W.cjs");
 const require_transformers = require("./transformers-BalCrSsr.cjs");
-const require_http = require("./http-1fZ83jj7.cjs");
+const require_http = require("./http-Cki-npuA.cjs");
 const require_types = require("./types-poIao40f.cjs");
-const require_portable_collection = require("./portable-collection-r-mHg1PV.cjs");
-const require_kv_cache = require("./kv-cache-BEWuZSB4.cjs");
+const require_portable_collection = require("./portable-collection-DqTUBKY7.cjs");
+const require_kv_cache = require("./kv-cache-D73yVcE5.cjs");
 let _logtape_logtape = require("@logtape/logtape");
 let _fedify_uri_template = require("@fedify/uri-template");
 let _fedify_vocab = require("@fedify/vocab");
@@ -100,6 +100,7 @@ var FederationBuilderImpl = class {
 	featuredTagsCallbacks;
 	inboxListeners;
 	outboxListeners;
+	inboxRequestFinishedHandler;
 	inboxErrorHandler;
 	outboxListenerErrorHandler;
 	outboxAuthorizePredicate;
@@ -161,6 +162,7 @@ var FederationBuilderImpl = class {
 		f.featuredTagsCallbacks = this.featuredTagsCallbacks == null ? void 0 : { ...this.featuredTagsCallbacks };
 		f.inboxListeners = this.inboxListeners?.clone();
 		f.outboxListeners = this.outboxListeners?.clone();
+		f.inboxRequestFinishedHandler = this.inboxRequestFinishedHandler;
 		f.inboxErrorHandler = this.inboxErrorHandler;
 		f.outboxListenerErrorHandler = this.outboxListenerErrorHandler;
 		f.outboxAuthorizePredicate = this.outboxAuthorizePredicate;
@@ -641,6 +643,10 @@ var FederationBuilderImpl = class {
 				this.inboxErrorHandler = handler;
 				return setters;
 			},
+			onRequestFinished: (handler) => {
+				this.inboxRequestFinishedHandler = handler;
+				return setters;
+			},
 			onUnverifiedActivity: (handler) => {
 				this.unverifiedActivityHandler = handler;
 				return setters;
@@ -1447,6 +1453,111 @@ async function buildCollectionSynchronizationHeader(collectionId, actorIds) {
 	return `collectionId="${collectionId}", url="${url}", digest="${(0, byte_encodings_hex.encodeHex)(await digest(actorIds))}"`;
 }
 //#endregion
+//#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 _fedify_vocab.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 {
+				(0, _logtape_logtape.getLogger)([
+					"fedify",
+					"federation",
+					"inbox"
+				]).error("An unexpected error occurred in inbox request finished handler:\n{error}", { error });
+			} catch {}
+		}
+	}
+};
+//#endregion
 //#region src/sig/compound-proof.ts
 const textEncoder = new TextEncoder();
 /**
@@ -1935,7 +2046,23 @@ async function verifyDiscoveredProofDocuments(discovered, options) {
 			verified: false,
 			reason: { type: "missingContext" }
 		});
-		const key = await require_http.verifyMapLocalProof(document.securedDocument, options);
+		const inherited = options[require_http.verificationObservation];
+		let subjectId = null;
+		if (inherited != null && document.id != null) try {
+			subjectId = (0, _fedify_vocab_runtime.parseIri)(document.id);
+		} catch {}
+		const key = await require_http.observeAttempt({ [require_http.verificationObservation]: inherited == null ? void 0 : {
+			...inherited,
+			attempt: void 0,
+			check: void 0,
+			subject: {
+				id: subjectId,
+				pointer: document.path
+			}
+		} }, "objectIntegrity", (observation) => require_http.verifyMapLocalProof(document.securedDocument, {
+			...options,
+			[require_http.verificationObservation]: inherited == null ? void 0 : observation
+		}), (key) => key != null);
 		return key == null ? Object.freeze({
 			...metadata,
 			verified: false,
@@ -4579,13 +4706,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 ?? _opentelemetry_api.trace.getTracerProvider();
 	const tracer = tracerProvider.getTracer(require_http.name, require_http.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"
 	};
@@ -4631,7 +4758,7 @@ async function handleCollection(request, { name: name$1, identifier, uriGetter,
 							span.setStatus({ code: _opentelemetry_api.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;
@@ -4673,7 +4800,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: _opentelemetry_api.SpanKind.SERVER,
 				attributes: {
 					"activitypub.collection.id": uri.href,
@@ -4689,7 +4816,7 @@ async function handleCollection(request, { name: name$1, identifier, uriGetter,
 						span.setStatus({ code: _opentelemetry_api.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 {
@@ -5170,6 +5297,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 ?? _opentelemetry_api.trace.getTracerProvider()).getTracer(require_http.name, require_http.version).startActiveSpan("activitypub.inbox", {
 		kind: options.queue == null ? _opentelemetry_api.SpanKind.SERVER : _opentelemetry_api.SpanKind.PRODUCER,
 		attributes: { "activitypub.shared_inbox": options.recipient == null }
@@ -5178,12 +5315,14 @@ async function handleInbox(request, options) {
 		try {
 			return await handleInboxInternal(request, options, span);
 		} catch (e) {
+			options.observation.hasException = true;
 			span.setStatus({
 				code: _opentelemetry_api.SpanStatusCode.ERROR,
 				message: String(e)
 			});
 			throw e;
 		} finally {
+			options.observation.project(span);
 			span.end();
 		}
 	});
@@ -5198,6 +5337,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 = { [require_http.verificationObservation]: observation.verification };
 	const logger = (0, _logtape_logtape.getLogger)([
 		"fedify",
 		"federation",
@@ -5222,6 +5363,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: _opentelemetry_api.SpanStatusCode.ERROR,
@@ -5232,6 +5377,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: _opentelemetry_api.SpanStatusCode.ERROR,
@@ -5242,11 +5391,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 require_types.readBoundedText(request.clone(), require_types.MAX_BODY_SIZE, request.url));
 	} catch (error) {
 		if (error instanceof require_types.BodyTooLargeError) {
+			observation.result = {
+				disposition: "rejected",
+				reason: "bodyTooLarge"
+			};
 			request.body?.cancel(error).catch(() => {});
 			span.setStatus({
 				code: _opentelemetry_api.SpanStatusCode.ERROR,
@@ -5276,6 +5434,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,
@@ -5305,6 +5472,10 @@ async function handleInboxInternal(request, parameters, span) {
 			code: _opentelemetry_api.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" }
@@ -5322,11 +5493,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}", {
@@ -5338,6 +5523,7 @@ async function handleInboxInternal(request, parameters, span) {
 			compactedJsonWithoutSig = require_http.detachSignature(compactedJson);
 			try {
 				ldSigVerified = await require_http.verifyCompactJsonLd(compactedJson, {
+					...signatureObservation,
 					contextLoader: ctx.contextLoader,
 					documentLoader: ctx.documentLoader,
 					keyCache,
@@ -5351,6 +5537,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" }
@@ -5370,6 +5560,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" }
@@ -5390,7 +5584,7 @@ async function handleInboxInternal(request, parameters, span) {
 			json
 		});
 		try {
-			activity = await _fedify_vocab.Activity.fromJsonLd(compactedJsonWithoutSig, {
+			activity = observation.activity = await _fedify_vocab.Activity.fromJsonLd(compactedJsonWithoutSig, {
 				...ctx,
 				contextLoader: require_http.getNormalizationContextLoader(ctx.contextLoader)
 			});
@@ -5402,6 +5596,7 @@ async function handleInboxInternal(request, parameters, span) {
 		activityVerified = true;
 		if (!skipSignatureVerification && isPortableActivity(activity)) try {
 			proofVerified = await require_http.verifyObject(_fedify_vocab.Activity, jsonWithoutSig, {
+				...signatureObservation,
 				contextLoader: require_http.wrapContextLoaderForJsonLd(ctx.contextLoader),
 				documentLoader: ctx.documentLoader,
 				keyCache,
@@ -5422,6 +5617,7 @@ async function handleInboxInternal(request, parameters, span) {
 		});
 		try {
 			activity = await require_http.verifyObject(_fedify_vocab.Activity, jsonWithoutSig, {
+				...signatureObservation,
 				contextLoader: require_http.wrapContextLoaderForJsonLd(ctx.contextLoader),
 				documentLoader: ctx.documentLoader,
 				keyCache,
@@ -5457,6 +5653,10 @@ async function handleInboxInternal(request, parameters, span) {
 				code: _opentelemetry_api.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" }
@@ -5480,6 +5680,7 @@ async function handleInboxInternal(request, parameters, span) {
 	if (activity == null) {
 		if (!skipSignatureVerification) {
 			const verification = await require_http.verifyRequestDetailed(request, {
+				...signatureObservation,
 				contextLoader: ctx.contextLoader,
 				documentLoader: ctx.documentLoader,
 				timeWindow: signatureTimeWindow,
@@ -5490,6 +5691,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 ? require_http.getRemoteHost(reason.keyId) : void 0;
 				require_http.getFederationMetrics(parameters.meterProvider).recordSignatureVerificationFailure(reason.type, remoteHost);
@@ -5504,7 +5713,7 @@ async function handleInboxInternal(request, parameters, span) {
 				});
 				if (unverifiedActivityHandler == null) return await getFailedSignatureResponse(inboxChallengePolicy, kv, kvPrefixes);
 				try {
-					activity = await _fedify_vocab.Activity.fromJsonLd(jsonWithoutSig, ctx);
+					activity = observation.activity = await _fedify_vocab.Activity.fromJsonLd(jsonWithoutSig, ctx);
 				} catch (error) {
 					logger.error("Failed to parse activity:\n{error}", {
 						recipient,
@@ -5520,6 +5729,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" }
@@ -5542,6 +5755,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,
@@ -5558,7 +5776,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;
@@ -5568,7 +5789,7 @@ async function handleInboxInternal(request, parameters, span) {
 			httpSigKey = verification.key;
 		}
 		try {
-			activity = await _fedify_vocab.Activity.fromJsonLd(jsonWithoutSig, {
+			activity = observation.activity = await _fedify_vocab.Activity.fromJsonLd(jsonWithoutSig, {
 				...ctx,
 				contextLoader: require_http.wrapContextLoaderForJsonLd(ctx.contextLoader)
 			});
@@ -5577,6 +5798,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", (0, _fedify_vocab.getTypeId)(activity).href);
 	span.addEvent("activitypub.activity.received", {
@@ -5588,6 +5815,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,
@@ -5605,20 +5839,36 @@ async function handleInboxInternal(request, parameters, span) {
 		});
 	}
 	if (!skipSignatureVerification && activity.id != null && require_http.isPortableId(activity.id)) {
-		const rejection = await verifyPortableActivityId(activity.id, jsonWithoutSig, {
-			contextLoader: require_http.wrapContextLoaderForJsonLd(ctx.contextLoader),
-			documentLoader: ctx.documentLoader,
-			keyCache,
-			meterProvider,
-			tracerProvider
-		});
+		const rejection = await require_http.observeAttempt(signatureObservation, "objectIntegrity", async (verification) => {
+			const rejection = await verifyPortableActivityId(activity.id, jsonWithoutSig, {
+				[require_http.verificationObservation]: verification,
+				contextLoader: require_http.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: _opentelemetry_api.SpanStatusCode.ERROR,
@@ -5632,6 +5882,14 @@ async function handleInboxInternal(request, parameters, span) {
 	}
 	if (httpSigKey != null && !await require_portable_collection.doesActorOwnKey(activity, httpSigKey, ctx)) {
 		if (deferredLdSignatureError != null) throw deferredLdSignatureError;
+		observation.authentication = {
+			status: "rejected",
+			reason: {
+				type: "actorKeyMismatch",
+				key: require_http.snapshotKey(httpSigKey),
+				actorIds: activity.actorIds.map((id) => new URL(id.href))
+			}
+		};
 		require_http.getFederationMetrics(parameters.meterProvider).recordSignatureVerificationFailure("actorKeyMismatch", httpSigKey.id == null ? void 0 : require_http.getRemoteHost(httpSigKey.id));
 		logger.error("The signer ({keyId}) and the actor ({actorId}) do not match.", {
 			activity: json,
@@ -5651,13 +5909,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 require_http.observeAttempt(signatureObservation, "objectIntegrity", async (verification) => {
+				const result = await verifyCompoundPortableObjectProofs(compoundJson, INBOX_COMPOUND_PROOF_LIMITS, {
+					[require_http.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,
@@ -5676,11 +5956,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" }
+			};
 			require_http.getFederationMetrics(parameters.meterProvider).recordSignatureVerificationFailure("invalidNonce", httpSigKey?.id == null ? void 0 : require_http.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,
@@ -5692,7 +5981,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,
@@ -5728,30 +6024,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",
@@ -5880,8 +6190,8 @@ var CustomCollectionHandler = class {
 	* @param CollectionPage The CollectionPage constructor.
 	* @param filterPredicate Optional filter predicate for items.
 	*/
-	constructor(name$2, values, context, callbacks, tracerProvider = _opentelemetry_api.trace.getTracerProvider(), meterProvider, Collection, CollectionPage, filterPredicate, portable) {
-		this.name = name$2;
+	constructor(name$1, values, context, callbacks, tracerProvider = _opentelemetry_api.trace.getTracerProvider(), meterProvider, Collection, CollectionPage, filterPredicate, portable) {
+		this.name = name$1;
 		this.values = values;
 		this.context = context;
 		this.callbacks = callbacks;
@@ -6417,19 +6727,19 @@ function isPortableActivity(activity) {
 */
 async function verifyPortableActivityId(activityId, jsonLd, options) {
 	const expectedId = require_http.getCanonicalPortableId(activityId);
-	if (expectedId == null) return "malformed portable ID";
+	if (expectedId == null) return { type: "invalidObjectId" };
 	let verification;
 	try {
 		verification = await require_http.verifyPortableObjectProofWithRoot(jsonLd, options);
 	} catch (error) {
-		if (error instanceof require_http.InvalidPortableObjectIdError) return "malformed portable ID";
+		if (error instanceof require_http.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" || require_http.getCanonicalPortableId((0, _fedify_vocab_runtime.parseIri)(rootId)) !== expectedId) return "the verified document has another ID";
+	if (typeof rootId !== "string" || require_http.getCanonicalPortableId((0, _fedify_vocab_runtime.parseIri)(rootId)) !== expectedId) return { type: "subjectMismatch" };
 	return null;
 }
 //#endregion
@@ -9409,7 +9719,7 @@ var FederationImpl = class extends FederationBuilderImpl {
 				return await (0, _logtape_logtape.withContext)({
 					traceId: spanCtx.traceId,
 					spanId: spanCtx.spanId
-				}, async () => {
+				}, () => this.#observeInboxFetch(metricState, async () => {
 					const logger = (0, _logtape_logtape.getLogger)([
 						"fedify",
 						"federation",
@@ -9424,8 +9734,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", require_http.getDurationMs(metricStart), { routeTemplate: metricState.routeTemplate });
 						span.setStatus({
 							code: _opentelemetry_api.SpanStatusCode.ERROR,
@@ -9464,7 +9780,7 @@ var FederationImpl = class extends FederationBuilderImpl {
 					else if (response.status >= 400) logger.warn(logTpl, values);
 					else logger.info(logTpl, values);
 					return response;
-				});
+				}));
 			});
 		});
 	}
@@ -9506,8 +9822,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,
@@ -9566,6 +9891,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": {
@@ -9641,9 +9988,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) });
 				}
@@ -9936,7 +10283,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);
@@ -9960,7 +10349,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 }) {
@@ -9989,63 +10379,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 _fedify_vocab.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,
-			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.");
+		let context;
+		try {
+			context = this.#createContext(request, contextData);
+		} catch (error) {
+			return await this.#reportInboxPreparationError(request, contextData, {
+				kind: "portable",
+				recipient: identifier
+			}, error, span, metricState);
+		}
+		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 _fedify_vocab.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