halkyon/packages/halkyon_base_server/lib/src/register/account_register.dart

import 'dart:typed_data';

import 'package:halkyon_base_server/src/generated/protocol.dart';
import 'package:halkyon_base_server/src/halkyon_base.dart';
import 'package:halkyon_base_server/src/register/accounts_mode.dart';
import 'package:halkyon_base_server/src/register/local_register.dart';
import 'package:halkyon_base_server/src/register/remote_register.dart';
import 'package:halkyon_base_server/src/register/sessions_ended.dart';
import 'package:serverpod/serverpod.dart';

/// The instance's register of accounts (ADR 0016): what one person is across
/// every service of the instance, kept by the service its operator names.
/// This server asks it here for everything the register keeps, so the same
/// call works whether this server holds the register itself
/// ([LocalRegister]) or is one of its members.
///
/// A person is named by their account ID, which is their `AuthUser`'s ID in
/// every service of the instance.
abstract interface class AccountRegister {
  /// The register [pod] asks: its own database while it holds the register
  /// (also unconfigured, as tests of a host's own code run), else the
  /// register's server ([RemoteRegister]), which needs the instance's shared
  /// secret.
  static AccountRegister of(Serverpod pod) =>
      _ofPod[pod] ??
      switch (HalkyonBase.maybeOf(pod)?.accounts) {
        MemberOfRegister(:final register) => RemoteRegister(
          register,
          secret:
              instanceSecretOf(pod) ??
              (throw StateError(
                'A member of an instance needs its shared secret: set '
                'instanceSecret in the passwords (INSTANCE_SECRET).',
              )),
        ),
        HoldsRegister() || null => const LocalRegister(),
      };

  /// Puts [register] in place of the one [pod] asks, or with null the one its
  /// configuration names back: tests do.
  static void use(Serverpod pod, AccountRegister? register) =>
      _ofPod[pod] = register;

  static final _ofPod = Expando<AccountRegister>('Account register');

  /// [person]'s public profile, as apps see it; null for none.
  Future<Profile?> profileOf(Session session, UuidValue person);

  /// The public profiles of those of [people] who have one, by person.
  Future<Map<UuidValue, Profile>> profilesOf(
    Session session,
    Set<UuidValue> people,
  );

  /// The public profile whose handle is [handle], whatever its case; null for
  /// none.
  Future<Profile?> profileByHandle(Session session, String handle);

  /// The person whose handle is [handle], whatever its case; null for none.
  /// For a host's own code (who is blocked, who wrote), never for apps:
  /// profiles never say whose they are.
  Future<UuidValue?> personWithHandle(Session session, String handle);

  /// Saves [person]'s public profile, making it if they have none. Throws
  /// `ProfileRefusedException` when it can't be saved (see
  /// `ProfileRefusal`): a handle someone else has, whatever its case, or a
  /// new handle once theirs is fixed.
  Future<Profile> saveProfile(
    Session session,
    UuidValue person, {
    required String handle,
    required String displayName,
    required String bio,
    required List<String> links,
  });

  /// Why [handle] couldn't be [person]'s, as saving it would refuse it; null
  /// when it can.
  Future<ProfileRefusal?> checkHandle(
    Session session,
    UuidValue person,
    String handle,
  );

  /// Checks which of [person]'s links' pages link back to their profile's
  /// page with `rel="me"`, and keeps the answer; at most 10 times an hour.
  /// Throws `ProfileNotFoundException` while they have no profile.
  Future<Profile> checkLinks(Session session, UuidValue person);

  /// Shows [png] as [person]'s avatar: a PNG of at most 1 MB. Throws
  /// `ProfileRefusedException` for anything else, and
  /// `ProfileNotFoundException` while they have no profile.
  Future<Profile> setAvatar(Session session, UuidValue person, ByteData png);

  /// Shows no avatar for [person] any more. Throws
  /// `ProfileNotFoundException` while they have no profile.
  Future<Profile> removeAvatar(Session session, UuidValue person);

  /// Removes [person]'s public profile, freeing its handle; nothing when they
  /// have none. Throws `ProfileRefusedException` once their handle is fixed.
  Future<void> removeProfile(Session session, UuidValue person);

  /// Fixes [person]'s handle, as others now refer to it (Halkyon Learn: their
  /// first publish); nothing when it is fixed already or they have no
  /// profile.
  Future<void> fixHandle(Session session, UuidValue person);

  /// Whether people can sign in with an email address: the register mails
  /// the codes.
  Future<bool> emailSignInOffered(Session session);

  /// Mails a sign-in code to [address] in [language], the codes asked for
  /// from [network] counted; the request it answers. Refusals as
  /// `sendSignInCode`'s.
  Future<UuidValue> sendSignInCode(
    Session session, {
    required String address,
    required String language,
    required String network,
  });

  /// Links the GitHub account [gitHubUserId] to [person] (an account of the
  /// register, under their ID). Refusals as `linkGitHubAccount`'s.
  Future<void> linkGitHub(
    Session session, {
    required UuidValue person,
    required String gitHubUserId,
  });

  /// The account that signs in with the GitHub account [gitHubUserId]; null
  /// for none.
  Future<UuidValue?> accountWithGitHub(Session session, String gitHubUserId);

  /// How [person] signs in: with GitHub, an email address, a password and
  /// whether an authenticator is confirmed.
  Future<SignInWays> signInWaysOf(Session session, UuidValue person);

  /// Whether people sign in with a password and TOTP (ADR 0017): the
  /// register holds the keys it needs.
  Future<bool> passwordSignInOffered(Session session);

  /// Gives [person] the password [setup] describes, with the address [code]
  /// proves for [request] unless they have one. Refusals as `setPassword`'s.
  Future<void> setPassword(
    Session session, {
    required UuidValue person,
    required PasswordSetup setup,
    UuidValue? request,
    String? code,
  });

  /// A password sign-in's first step for [address], the sign-ins begun from
  /// [network] counted. Refusals as `beginPasswordSignIn`'s.
  Future<PasswordChallenge> beginPasswordSignIn(
    Session session, {
    required String address,
    required String network,
  });

  /// A password sign-in's second step: the account it proved, for the
  /// caller's session; a [code] mailed for [request] in place of the second
  /// factor of a setup never finished. Refusals as
  /// `completePasswordSignIn`'s.
  Future<PasswordProof> completePasswordSignIn(
    Session session, {
    required UuidValue challenge,
    required ByteData clientValue,
    required ByteData clientProof,
    String? totpCode,
    String? recoveryCode,
    UuidValue? request,
    String? code,
    required String host,
    String? address,
    String? language,
  });

  /// Signs up with the address [code] proves for [request] and the password
  /// [setup] describes: the account, new or one with the address and no
  /// password, for the caller's session. Refusals as `signUpWithCode`'s.
  Future<UuidValue> signUpWithCode(
    Session session, {
    required UuidValue request,
    required String code,
    required PasswordSetup setup,
  });

  /// A new authenticator of [person]. Refusals as `enrolAuthenticator`'s.
  Future<AuthenticatorEnrolment> enrolAuthenticator(
    Session session, {
    required UuidValue person,
    required String name,
    required String label,
  });

  /// Confirms [person]'s [authenticator], with [existingCode] from one
  /// confirmed before where the account has one; the first one's recovery
  /// codes. Refusals as `confirmAuthenticator`'s.
  Future<List<String>> confirmAuthenticator(
    Session session, {
    required UuidValue person,
    required UuidValue authenticator,
    required String code,
    String? existingCode,
  });

  /// [person]'s authenticators, the oldest first.
  Future<List<Authenticator>> authenticatorsOf(
    Session session,
    UuidValue person,
  );

  /// Removes [person]'s [authenticator]. Refusals as
  /// `removeAuthenticator`'s.
  Future<void> removeAuthenticator(
    Session session, {
    required UuidValue person,
    required UuidValue authenticator,
    String? code,
  });

  /// New recovery codes for [person]. Refusals as `newRecoveryCodes`'.
  Future<List<String>> newRecoveryCodes(
    Session session, {
    required UuidValue person,
    required String code,
  });

  /// Asks for the reset of a lost authenticator. Refusals as
  /// `resetAuthenticator`'s.
  Future<ResetPending> resetAuthenticator(
    Session session, {
    required UuidValue challenge,
    required ByteData clientValue,
    required ByteData clientProof,
    required String address,
    required String language,
    UuidValue? request,
    String? code,
    UuidValue? keyChallenge,
    ByteData? signature,
    required String host,
  });

  /// The first step of proving the recovery phrase for [address], the
  /// proofs begun from [network] counted. Refusals as `beginKeyProof`'s.
  Future<KeyProofChallenge> beginKeyProof(
    Session session, {
    required String address,
    required String network,
  });

  /// Sets a new password with the recovery phrase's proof; the account, for
  /// the caller's session made after its sessions ended. Refusals as
  /// `resetPasswordWithPhrase`'s.
  Future<AccountSessionsEnded> resetPasswordWithPhrase(
    Session session, {
    required UuidValue challenge,
    required ByteData signature,
    required NewPassword password,
    String? totpCode,
    String? recoveryCode,
    required String host,
    String? address,
    String? language,
  });

  /// Asks for the reset of a whole account. Refusals as
  /// `startAccountReset`'s.
  Future<ResetPending> startAccountReset(
    Session session, {
    required String address,
    required String language,
    required UuidValue request,
    required String code,
  });

  /// Carries out the reset of a whole account; the account, for the
  /// caller's session made after its sessions ended. Refusals as
  /// `completeAccountReset`'s.
  Future<AccountSessionsEnded> completeAccountReset(
    Session session, {
    required String address,
    required UuidValue request,
    required String code,
    required PasswordSetup setup,
  });

  /// The first step of [person] proving their password to change it.
  /// Refusals as `beginPasswordChange`'s.
  Future<PasswordChallenge> beginPasswordChange(
    Session session, {
    required UuidValue person,
  });

  /// Changes [person]'s password, ending their sessions everywhere but
  /// [keepSession]. Refusals as `changePassword`'s.
  Future<void> changePassword(
    Session session, {
    required UuidValue person,
    required UuidValue challenge,
    required ByteData clientValue,
    required ByteData clientProof,
    String? totpCode,
    String? recoveryCode,
    required NewPassword password,
    UuidValue? keepSession,
    required String host,
  });

  /// Replaces the wrapping of [person]'s keys under their recovery phrase
  /// and the phrase's proof key, with the password's proof and a code.
  /// Refusals as `setRecoveryKeys`'.
  Future<void> setRecoveryKeys(
    Session session, {
    required UuidValue person,
    required UuidValue challenge,
    required ByteData clientValue,
    required ByteData clientProof,
    String? totpCode,
    String? recoveryCode,
    required WrappedKeys recoveryKeys,
    required ByteData recoveryProofKey,
    required String host,
  });

  /// Deletes the account [person] with everything the register's server has
  /// of them, and has every member of the instance delete theirs: one with a
  /// password only with [proof] (`requireOwnerToDelete`).
  Future<void> deleteAccount(
    Session session,
    UuidValue person, {
    DeletionProof? proof,
  });

  /// Those of [people] that are accounts of the register.
  Future<Set<UuidValue>> knownAccounts(
    Session session,
    Set<UuidValue> people,
  );
}