HTTP signature keys for portable actor gateways

[dahlia]

Background

FEP-ef61 says that when HTTP signatures are necessary for communicating with other servers, each gateway that makes requests on behalf of a portable actor should use a separate secret key. The corresponding public keys must be added to the actor document using the assertionMethod property described by FEP-521a.

Fedify already has HTTP Signature support for ordinary ActivityPub actors, and it already supports Object Integrity Proofs and FEP-521a. Portable actors add a different case: the actor's canonical identifier is an ap+ef61: URI, while one or more HTTP(S) gateways may send signed requests on that actor's behalf.

This matters for gateway-to-gateway inbox forwarding, ordinary ActivityPub delivery from portable actors, and compatibility with servers that expect HTTP signatures even when portable object proofs provide the stronger object-level authentication.

Proposed work

Define how Fedify represents, exposes, and verifies HTTP signature keys used by gateways acting on behalf of portable actors.

The work should include:

• deciding how a gateway-specific signing key is represented in a portable actor document;
• making sure the public key can be exposed through assertionMethod as described by FEP-521a;
• deciding how the existing actor key dispatcher or key-pair callback model maps to portable actor gateway keys;
• allowing outgoing requests made by a gateway on behalf of a portable actor to be signed with the gateway's own key;
• allowing incoming HTTP signatures from portable actor gateways to resolve to the corresponding assertionMethod key;
• preserving existing HTTP Signature behavior for ordinary ActivityPub actors;
• making sure this works with compatible FEP-ef61 identifiers when a remote server does not understand ap+ef61: IDs directly;
• documenting the security relationship between HTTP Signatures and FEP-ef61 Object Integrity Proofs.

This should not make HTTP Signatures the primary authenticity mechanism for portable objects. Portable actors, activities, and objects still need FEP-ef61 proof policy checks. HTTP Signatures are the transport-level mechanism needed for existing ActivityPub delivery flows and for gateway-to-gateway requests.

Design questions

The implementation should settle these API and behavior details before finalizing the code path:

• Should portable gateway HTTP signature keys reuse the existing actor key-pair dispatcher API, or does Fedify need a small extension for gateway-specific keys?
• How should the current gateway be identified when choosing the signing key for an outgoing request?
• Should the key ID be an ap+ef61: URI, a compatible gateway URL, a DID URL, or an HTTP(S) URL under the gateway?
• How should Fedify expose multiple gateway public keys in a portable actor's assertionMethod collection?
• How should verification behave when a remote request is signed by a gateway key but the activity/object proof is missing or invalid?
• How should verification behave when the HTTP signature is valid but the signing gateway is not listed in the portable actor's gateways property?
• Should gateway-to-gateway inbox forwarding use this key model from the first implementation?
• How much of this should be public API, and how much can be internal behavior built on existing key callbacks?

Scope

This issue is only about HTTP signature key handling for gateways acting on behalf of portable actors.

It does not include:

• implementing the portable inbox endpoint itself;
• implementing gateway-to-gateway forwarding itself;
• implementing FEP-ae97 outbox posting;
• adding new DID methods;
• replacing FEP-ef61 Object Integrity Proof verification;
• automatic gateway registration or key rotation workflows;
• storage for private gateway secret keys.

Key rotation and multi-device gateway management should be considered during design, but they can be split into follow-up work if they require broader API changes.

Dependencies

This should depend on the lower-level portable URI, vocabulary, proof, and actor document work under #288:

• Support ap: and ap+ef61: URI schemes in vocabulary codecs #826 for ap:/ap+ef61: URI support in vocabulary codecs;
• Resolve did:key verification methods for Object Integrity Proofs #827 for resolving did:key verification methods for Object Integrity Proofs;
• Canonicalize and compare ap:/ap+ef61: URIs #828 for portable URI canonicalization and comparison;
• Support cryptographic origins for ap:/ap+ef61: URIs #829 for FEP-fe34 cryptographic origins;
• FEP-ef61 vocabulary terms #830 for FEP-ef61 vocabulary terms;
• FEP-ef61 proof policy for portable objects #832 for the FEP-ef61 proof policy;
• Compatible FEP-ef61 identifiers for portable objects #833 for compatible FEP-ef61 identifier conversion.

It should also inform #839, because portable inbox forwarding needs a concrete choice of gateway signing key for outgoing requests.

Tests

Add regression tests for portable actor gateway HTTP signature keys.

The tests should cover:

• serializing a portable actor document with gateway public keys in assertionMethod;
• selecting the expected gateway key for an outgoing request made on behalf of a portable actor;
• signing an outgoing request from a gateway using that key;
• resolving and verifying an incoming HTTP signature made with a portable actor gateway key;
• rejecting or treating as unauthenticated a request signed by a gateway that is not listed in the portable actor's gateways property;
• preserving existing ordinary actor HTTP Signature behavior;
• interaction with compatible FEP-ef61 identifiers;
• behavior when the HTTP signature is valid but the portable object proof policy fails.

This should be added as a sub-issue of #288.