identity-service-api: Add store_invitation endpoint.

[Frinksy]

Resolves: #333

Since we already have an invitation module, I thought I would put it there instead of in invite::store_invitation::v2.

[iinuwa]

In addition to the comment about Medium, I also noticed two other things:

The spec for this endpoint says:

In addition to the request parameters specified below, an arbitrary number of other parameters may also be specified. These may be used in the invite message generation described below.

I think that means that the JSON object can contain any arbitrary parameters at the top level. We should support de-/serializing those properties.

Earlier in the module documentation, it also says:

An identity server can store pending invitations to a user's 3PID, which will be retrieved and can be either notified on or look up when the 3PID is associated with a Matrix user ID.

At a later point, if the owner of that particular 3PID binds it with a Matrix user ID, the identity server will attempt to make an HTTP POST to the Matrix user's homeserver via the /3pid/onbind endpoint. The request MUST be signed with a long-term private key for the identity server.

When it says "the request MUST be signed," is that referring to the store-invite request, or the /3pid/onbind request? If the former, perhaps we should handle that signature here as well.

[jplatte]

I think that means that the JSON object can contain any arbitrary parameters at the top level.

Oh, that again 🙄

@Frinksy Would be good to handle this the same way as we handle custom capabilities in ruma-client-api/src/r0/capabilities.rs (that is, private #[serde(flatten)]ed field plus get and set methods).

[Frinksy]

When it says "the request MUST be signed," is that referring to the store-invite request, or the /3pid/onbind request? If the former, perhaps we should handle that signature here as well.

I'm pretty sure that it is the /3pid/onbind request which must be signed. The request contains a signature from the identity server:

Required. Signature from the identity server using a long-term private key.

This seems to be in accordance with the Invitation storage docs

At a later point, if the owner of that particular 3PID binds it with a Matrix user ID, the identity server will attempt to make an HTTP POST to the Matrix user's homeserver via the /3pid/onbind endpoint. The request MUST be signed with a long-term private key for the identity server.

[iinuwa]

I'm pretty sure that it is the /3pid/onbind request which must be signed. The request contains a signature from the identity server:

Sounds good!

[iinuwa]

Looks good, thanks!