Report the key and refusal reason for inbox verification for every mechanism

[2chanhaeng]

Background

DrFed logs, for every inbox request, the mechanism that verified it, the key it used, and why the request was refused (fedify-dev/drfed#12). Fedify reports these unevenly:

• HTTP Signatures: verifyRequestDetailed() returns the key or a reason, and the handler later counts an owner mismatch as actorKeyMismatch.
• Linked Data Signatures: a key the actor does not own is measured as rejected, the same as a bad signature or a failed key fetch.
• Object Integrity Proofs: a valid proof that does not cover the actor is measured as verified, then verifyObject() returns null.

No mechanism hands its key to inbox listeners. DrFed gets it by watching the KvStore entries under kvPrefixes.publicKey, which depends on KvKeyCache's private serialization. #1122 does not cover this: getSignedKey() verifies again.

Proposed work

• Add detailed variants of verifyJsonLd() and verifyObject(), like verifyRequestDetailed(): the key or a reason that distinguishes an invalid signature, a key fetch failure, and an owner mismatch.
• Record that reason, as a bounded set, on the *.verify spans and on activitypub.signature.verification.duration, leaving the HTTP owner mismatch on the inbox span.
• Hand the outcome of inbox verification (mechanism, key, reason) to the application for every request, accepted or refused.
• onVerification(): A new hook, called once per inbox request before the response: only that reaches refused, duplicate, and unlistened requests, as well as enqueued ones, without queuing the key.

AI disclosure

Claude Code (claude-opus-5-5) drafted this issue from the analysis it did for fedify-dev/drfed#12. The user decided the direction and edited out the verbose parts.

[dahlia]

Implementation direction

I'll add onRequestFinished() to the object returned by setInboxListeners(...). The callback will receive a RequestContext and an InboxRequestReport covering verification and inbox processing:

federation
  .setInboxListeners("/users/{identifier}/inbox", "/inbox")
  .onRequestFinished(async (ctx, report) => {
    await recordInboxRequest(ctx, report);
  });

Report structure

The report will distinguish verification attempts, the final authentication decision, and the inbox processing outcome. For example, a Linked Data signature can be cryptographically valid but fail attribution checks, after which an HTTP signature authenticates the request. Both attempts will remain in the report. A valid HTTP signature followed by an actor/key mismatch will retain the successful signature check and the final refusal reason.

attempts will contain the HTTP signature, Linked Data signature, and Object Integrity Proof evaluations. Each attempt will have a verified, rejected, or error result and a checks array for the signatures or proofs it examined. An attempt can record several valid proofs and still fail attribution checks. A verified attempt will reference the successful checks directly; the final authentication result will reference the verified attempts it relied on.

Each check will retain the declared key ID and the public keys actually used, including keys used in failed checks. If cached key A fails and refreshed key B succeeds, both versions will be available. Each check will include any cache retries, but their sequence will not be part of the public contract. The declared key ID will be string | null so the report can retain malformed key ID declarations. Key metadata will use URL | null for id, ownerId, and controllerId, following the vocabulary API, and will include the actual publicKey: CryptoKey. ownerId and controllerId will remain distinct. These fields describe the key document's claims; the authentication result says whether Fedify accepted them for this request.

The report will also include the inbox kind, the local recipient identifier (null for a shared inbox), and the payload and parsed activity when available. Payload availability will be a discriminated union, so parsed JSON null is distinguishable from an unavailable payload. The observer will not cause extra parsing or key fetches. An activity can be present without being authenticated.

The final authentication states will be verified, rejected, skipped, and notDetermined. A request with verification enforcement disabled can still have LD or proof checks in its attempts. The processing outcome will distinguish direct processing, queue registration, duplicates, activities with no listener, refusals, custom responses, and processing failures. It will carry the response status or the original exception, rather than exposing the mutable Response. A custom 202 from onUnverifiedActivity() will remain an unauthenticated custom response, not a successful listener invocation.

Callback contract

The callback will run once for each request dispatched to a configured inbox delivery route, including normal, shared, and portable inboxes. It will cover context preparation and recipient lookup failures as well as verification refusals, duplicates, and enqueued requests. It will not run for inbox collection reads, unmatched routes, programmatic activity routing, or subsequent queue processing. Keys and reports will not be added to queue messages.

Fedify will await the callback before returning the response or rethrowing the original exception. Observer errors will be logged without replacing that response or exception, and will not invoke the observer recursively. Awaiting the callback does not make its write atomic with queue registration or guarantee that the write succeeds. Registration will replace the previous handler, matching the existing inbox error and unverified-activity setters.

Verification and OpenTelemetry

I'll collect detailed results for all three verification mechanisms before exposing the hook, including the keys used in failed checks so DrFed can record them in its key history. Existing verifier return contracts will remain available.

The report and OpenTelemetry fields will come from the same collected results. Bounded failure reasons will distinguish signature failures, key-fetch failures, and attribution or ownership failures. Actual key material will stay out of the default telemetry. Attribution and inbox policy failures will be recorded at the object or inbox level without changing an individual proof's cryptographic verification result.

Regression coverage will include fallback between mechanisms, multiple proofs, failed checks and key refreshes, early preparation and parsing failures, final ownership and nonce checks, and each processing outcome. It will also verify that the callback is awaited and called once, preserves the original response or exception when it fails, and runs independently of trace sampling.

[dahlia]

Implemented in PR #1201, and will ship with Fedify 2.4.0.