FEP-f9ec IndieAuth display handles

=> Source (manually imported from Hedgedoc)

Summary

[IndieAuth] provides a simple, standards-based way for websites to authenticate with a domain or web URL. To easily verify authenticity, we can let users show IndieAuth URLs as their username.

IndieAuth extensions

The following  HTML tags,  tags, and HTTP headers MUST be used alongside the existing ones defined in the Discovery by Clients section of the IndieAuth spec.

• The authenticity_signature_endpoint rel in a  tag or a Link header: the value/href MUST refer to an endpoint that generates a signature (see Authenticity signature endpoint section below).
• The authenticity_public_key meta name, or the Authenticity-Public-Key header: the value MUST be an ED25519 public key, which MUST be in hexadecimal with no prefix and consistent casing, but it SHOULD use all lowercase.

Authenticity signature endpoint

This endpoint, which has no set path, MUST be queried as an IndieAuth token authenticated GET request. The server will introspect the token to determine the domain from the client ID and will sign a string made of the internationalized domain name [IDN], the ampersand &, and the original URL of the IndieAuth login. The server will respond with an appropriate error code and message should this fail for any reason, and a 200 OK response with the signature -- without the signed data -- in unprefixed hexadecimal.

Example

(This section is non-normative.)

http
GET /indieauth/sign
Accept: text/plain
Authorization: Bearer cb9cd737e449...

---
200 OK
Content-Type: text/plain
4ac5236c6b1e435daaa8b6b78c9b3fff...

ActivityPub extension

(Note that this section depends on FEP-888d.)

The following fields are declared in the namespace https://w3id.org/fep/f9ec#, which MAY be referred to with the compact IRI indieauth:*. To implement this FEP, these MUST be used on Actors who have signed in with IndieAuth and opted in to displaying their login URL as their handle. If the ActivityPub server is a provider, it MUST NOT reference the server's provider.

• handleVerification: a String with the signature as returned from the endpoint.
• preferredHandle: a String with the login URL used in the signature. This will be used EXACTLY AS-IS, so make sure you get it right.

Verification procedure

Before displaying the IndieAuth-based handle for the first time, servers MUST verify that the signature is valid against the currently advertised key. This is the procedure for doing so.

1. The verifying server looks up the login referenced in the preferredHandle of the Actor. * When the handle has not yet been verified, the authenticity_public_key meta value or equivalent header (see IndieAuth extensions section above) MUST be present and configured.

• If this handle has previously been verified but is now failing this check, the verifying server MAY choose to hide the handle and retry later, or it MAY choose to continue showing it until a few failed retries ("a few", in this case, is the maximum retries the server is configured for), after which it SHOULD consider the handle no longer verified and stop showing it.

2. The verifying server recomposes the signed data based on the known domain of the user and the preferredHandle.

3. The verifying server finally verifies the Ed25519 signature against the data and advertised public key.

• If this fails, the preferredHandle should stop being shown immediately and it MUST no longer be considered verified; instead, the server assumes that the use of the handle has been de-authorized. The server MAY notify the user (such as by email) that the signature is no longer valid and the user must sign in again to reauthorize it.

Display

(This section is non-normative.)

The handle, when verified, should be shown alongside an appropriate monotone IndieAuth icon, and in place of the handle or URL that the software already shows. Non-standard APIs, such as the Mastodon API, should put the IndieAuth display handle into a separate field.

References

• [ActivityPub] Christine Lemmer Webber, Jessica Tallon, ActivityPub, 2018
• [IDN] John C Klensin, Internationalized Domain Names in Applications (IDNA): Protocol
• [IndieAuth] Aaron Parecki, IndieAuth, 2018

=> [ActivityPub] | [IDN] | [IndieAuth]

Draft notes

(This section is non-normative.)

• This should be checked over to make sure terms are used consistently and necessary references are made.
• Still need to add the FEP metadata headers.
• Still need to make the JSON-LD context.
• Maybe rewrite the summary to make it a real elevator pitch.