Let interaction-controls callers tell transient failures from rejections

[dahlia]

While moving Hollo's FEP-044f quote handling onto @fedify/interaction-controls (fedify-dev/hollo#635, fedify-dev/hollo#641), most of the code Hollo had to add was not policy logic. It was code that works around the helper hiding why a check failed. An inbox handler has to choose between retrying later and giving up for good, and the 2.4.0 helpers often don't give it enough information to make that choice. Hollo ended up with about 100 lines of workarounds, listed below. Each of them would be better solved once in the package.

The package's code on main is the same as in 2.4.0, so all of the line references below still apply.

Request verification swallows fetch errors

verifyRequest() dereferences the target and the instrument with suppressError: true (control.ts L326–L330). A failed fetch therefore comes back as missingObject or missingInstrument, the same result as a request that never had one. A caller can't tell a timeout apart from a malformed request. If it treats the failure as final, it drops a valid request. If it retries, it retries garbage.

Hollo now resolves the instrument itself before calling the helper (inbox.ts L770–L794). It has to work on a copy re-parsed from JSON-LD so the request it echoes back is left untouched, and it uses its own transient-error check. That defeats much of the point of calling verifyRequest().

Suggestion: when the target or instrument is referenced by IRI and fetching it fails, report the existing unverifiable/notDereferenceable failure with the URL and the cause. Keep missingObject and missingInstrument for requests that really lack them.

Failures don't say whether retrying could help

verifyAuthorization() reports every fetch problem as unverifiable, but callers still need to classify the cause themselves. A 503, a DNS failure, a 404, and a URL blocked by SSRF protection all look alike. On top of that, materialize() passes the same loader as the context loader, so a failed JSON-LD context fetch surfaces as invalidJsonLd (control.ts L781). That is indistinguishable from a document that is actually malformed.

Hollo wraps the document loader to record every error it throws, then classifies those errors: network errors, UrlError with reason: "dns", 5xx, 408, and 429 count as transient (quote.ts L82–L150). Every Fedify application that verifies authorizations from an inbox needs this same logic.

Suggestion: add a transient: boolean (or retryable) flag to unverifiable failures in both verifyRequest() and verifyAuthorization(), computed from the loader error. Report a failed context fetch as notDereferenceable with the context URL instead of invalidJsonLd. The classification could live in @fedify/vocab-runtime next to FetchError and UrlError, so other packages can reuse it.

Errors from matchesApprovalCollection are swallowed

evaluatePolicy() catches anything the matchesApprovalCollection callback throws and turns it into a denied decision with an unverifiableCollection reason (control.ts L984–L990). The callback is usually a database query. If that query fails for a moment, an application that just follows the decision sends a permanent Reject for a request it would have approved.

Hollo checks for that reason and rethrows (inbox.ts L745–L755), but by then the original error is gone.

Suggestion: put the caught error in the reason as cause, and add an option to let callback errors propagate instead of being converted into a denial.

Constructors are stricter than the wire formats they replace

createRevocation() always reduces the authorization to its IRI (control.ts L182–L188). Hollo has always sent the Delete with the QuoteAuthorization embedded, so it can't use the helper without changing its wire format, and it still builds the Delete by hand.

The constructors also require id and to for Accept, Reject, and Delete. For activities passed straight to sendActivity(), Fedify already assigns an ID when it is missing, and the recipients are given separately. Hollo had to copy Fedify's /#Accept/<uuid> ID shape and add a to it didn't send before.

Suggestion: embed the authorization in createRevocation() when the caller passes an object rather than a URL, as createAccept() already does for result. Make id, to, and cc optional in these constructors, matching createRequest().

Compatibility

All four changes can stay backward compatible. The new failure fields and options are additive. The only output that changes is createRevocation() given an object, and an option can gate that if it seems risky. Once these land, Hollo can drop its own instrument resolution, its loader wrapper and error classification, and its rethrow after evaluatePolicy().

[dahlia]

BotKit ran into the matchesApprovalCollection problem too, while moving its FEP-044f code onto quoteInteraction in fedify-dev/botkit#53. It captures the callback's error and rethrows it after evaluatePolicy() returns (bot-impl.ts L1394–L1405).

Most of BotKit's adapter code, though, works around policy choices the helpers make with no way to override them.

A missing canQuote rule is always a denial

For quotes, evaluatePolicy() denies another actor's request when the subject has no interaction policy or no canQuote rule (control.ts L821–L823). BotKit falls back to the bot's configured quote policy instead, which defaults to public, so it clones the target with a synthesized rule before evaluation.

Suggestion: accept a fallback rule in the evaluation options for subjects with no interaction policy or no canQuote rule.

Approval precedence is fixed

evaluatePolicy() checks exact actor entries in both axes before broad entries (control.ts L829–L849), so an actor listed in manualApprovals gets a manual decision even when automaticApprovals contains Public. BotKit has always approved that case automatically. It now calls the helper twice per request, evaluating each axis on a clone with the other axis emptied (bot-impl.ts L1380–L1428).

Suggestion: a precedence: "automatic" option, so applications can keep their existing semantics without evaluating twice. I'm not sure BotKit's order is the better one.

Request validation has no lenient mode

The quote verifier fails with requesterMismatch when the quote has no attribution, and with objectMismatch when quote and quoteUrl disagree (quote.ts L55–L82). BotKit uses the requester as the attribution when none is present and prefers quote over quoteUrl. It passes verifyRequest() a normalized clone and keeps the original request for the application (bot-impl.ts L1273–L1292).

Suggestion: options to use the requester as a missing attribution and to prefer quote over a conflicting quoteUrl. I'm less convinced by the latter; rejecting the conflict is a defensible default.

Authorization objects skip the ID check

verifyAuthorization() compares the authorization's ID with an expected one only when given a URL (control.ts L541). BotKit already has the object, from its repository or Accept.getResult(), so it checks the ID itself before passing the object to the helper (quote-authorization.ts L68–L90). getResult() replaces the result IRI with whatever ID the fetched document claims, so without that check a same-origin server could answer with a different stamp.

Suggestion: an authorizationId option that applies the same idMismatch check to an object. An object fetched from that ID could then also count as authentic without a custom verifyAuthenticity callback.

[dahlia]

Hackers' Pub's migration in hackers-pub/hackerspub#422 has a few additional requirements. The options discussed above would help, but some of our compatibility code would remain with those options alone.

Quote validation against either reference and any attribution

Hackers' Pub accepts a quote when either quote or quoteUrl matches the requested target, even when the two disagree. It also accepts a requester found anywhere in attributedTo, rather than requiring the first attribution to match. We currently normalize the quote references and attributions on a clone before calling verifyRequest().

An opt-in mode that checks either reference against the expected target, and any attribution against the requester, would remove that normalization. Preferring quote alone would still reject requests where only quoteUrl matches. Missing attribution should remain invalid for our use case; we do not need the requester substituted for it. The strict defaults could stay unchanged.

Author-approved authorization aliases

Our existing acceptance path allows an authorization ID on a different origin when the signed Accept comes from the quoted author. For locally issued authorizations, we check the stored ID and quote binding against an unrevoked database row.

verifyAuthorization() rejects an off-origin ID before calling verifyAuthenticity, so that callback cannot express either source of trust. Allowing an explicit authenticity verifier to approve an off-origin authorization would let us use the helper for these paths too. The helper should still check the expected authorization ID, attribution, interacting object, and target. An ID match alone should not establish authenticity, and independently fetched authorizations should keep the current origin requirement by default.

Already resolved objects and separate loaders

Our request handler resolves local targets from the database, including share wrappers, rather than fetching our own public endpoint. It also resolves the instrument before verification to apply the requester's origin check. Options to supply those resolved values to verifyRequest() would avoid cloning the request just to replace its references. Verification should leave the original request untouched, since it is included in the response.

A separate contextLoader option for both verification helpers would also remove our loader-routing wrapper. We use a bounded document loader for remote objects and a separate loader for JSON-LD contexts; passing one loader for both currently makes the application route requests by URL.