Plays the client in federated sign-in: it lets users of other gerbeur instances sign in here with their account there, their home.

  1. The login or register page names the user's home, and startLogin answers the home's /authorize page with a request: a random state, the hash of a PKCE verifier, and a nonce, kept in federation_logins for 10 minutes.
  2. The home sends the user back to the /federation/callback page with a code. completeLogin trades it for the home's identity token, checks its signature against the home's keys, and finds or creates the local account linked to it (user_identities), named <name>@<host>.
  3. The home's events (receiveEvent) keep the account's name, email and avatar in step, and end its sessions when the home says so.

Whether a user of another instance may join is the admin's call (federation-peer-service.ts): from a trusted instance they may, from a blocked one they may not, and from any other only with an invite, which the register page carries. None may while the deployment turns sign-ins from other instances off (FEDERATION.incoming). Once here, an account works like any other, but its password, email, avatar and name are its home's (assertLocalUser), and change on its pages there (homePageUrl).

Functions

f
completeLogin(request: FederationSessionRequest): Promise<User>

Finishes a sign-in begun by startLogin, for POST /api/federation/sessions, and returns the account it signs in to: the one linked to the identity, brought up to date, or a new one. A login works once. A new account needs the home to be trusted, or the invite the login was started with, claimed now.

f
homePageUrl(
user: User,
path?: string
): Promise<string>

Returns the URL of path on the home of user, an account from another instance, for GET /api/users/:key/home: their profile there by default, or another of its pages, such as /settings, where they change their password. A handle's host is its home's issuer, the API's origin, which needn't be its pages': those are where its /authorize page is, and the home's metadata says. While it doesn't answer, the issuer stands in.

f
receiveEvent(token: string): Promise<void>

Applies the signed event token from a user's home, for POST /api/federation/events: update brings their account in step, revoke ends their sessions here. Only an instance some account here comes from, and not blocked, may send one, about one of those accounts, and at most EVENT_LIMIT's rate. The sender gives up on an event at a 4xx other than 429, and tries it again later otherwise.

f
startLogin(request: FederationLoginRequest): Promise<string>

Starts a sign-in with an account on the instance request.instance names, and returns its /authorize page with the request, for POST /api/federation/logins. Unless that instance is trusted, or someone here already comes from it, the request must carry a valid invite, which is claimed only once the account is made; completeLogin makes no account without one.

Usage

import * as mod from "api/services/federation-service.ts";