halkyon/packages/halkyon_app/lib/src/auth/data/auth_gateway.dart

import 'package:halkyon_app/src/auth/model/auth_status.dart';
import 'package:halkyon_app/src/auth/model/email_sign_in.dart';
import 'package:halkyon_app/src/auth/model/github_link_outcome.dart';
import 'package:halkyon_app/src/auth/model/session_grant.dart';
import 'package:halkyon_app/src/auth/model/sign_in_ways.dart';

/// The boundary to the server's authentication: who is signed in, and signing
/// in and out. Tests replace it with a fake.
abstract interface class AuthGateway() {
  /// Who is signed in right now.
  AuthStatus get status;

  /// Every later change of [status].
  Stream<AuthStatus> get statusChanges;

  /// Creates an anonymous account on the server and signs in with it.
  Future<void> signInAnonymously();

  /// Signs out on this device.
  Future<void> signOut();

  /// Deletes the signed-in person with everything they have, on the server
  /// and so on all their devices, and forgets the session here.
  Future<void> deleteAccount();

  /// The client ID of this instance's GitHub OAuth app; null when GitHub
  /// sign-in is off on this instance.
  Future<String?> gitHubClientId();

  /// Authorizes with GitHub in the browser and links the GitHub account to the
  /// signed-in person: the lossless upgrade from an anonymous account.
  Future<GitHubLinkOutcome> linkGitHub();

  /// Authorizes with GitHub again and switches this device to the person who
  /// has that GitHub account; false when the person cancelled on GitHub.
  Future<bool> switchToGitHub();

  /// Whether the app itself waits for GitHub's page in the browser, so that
  /// only the app can cancel it (Linux, Windows). Elsewhere the system's
  /// sign-in screen has its own Cancel.
  bool get canCancelGitHub;

  /// Stops waiting for GitHub's page in the browser: the [linkGitHub] or
  /// [switchToGitHub] in progress ends as cancelled. Does nothing once
  /// GitHub has answered.
  Future<void> cancelGitHub();

  /// Whether this instance offers signing in with an email address.
  Future<bool> offersEmailSignIn();

  /// Mails a code to [address], worded in [language] (`en`, `de`), and
  /// returns the request it answers. Throws [EmailSignInFailed].
  Future<String> sendEmailCode(String address, {required String language});

  /// Accepts [code] for [request]: the address becomes the signed-in
  /// person's, the lossless upgrade from an anonymous account, unless it is
  /// another person's. Throws [EmailSignInFailed].
  Future<EmailCodeOutcome> verifyEmailCode(String request, String code);

  /// Switches this device to the person [switchToken] signs in as, and
  /// returns them (their `AuthUser` id). Throws [EmailSignInFailed].
  Future<String> switchToEmail(String switchToken);

  /// How the signed-in person signs in.
  Future<SignInWays> signInWays();

  /// Puts [grant] in place of this device's session: its person is signed
  /// in. An anonymous account left behind is deleted, as nobody could sign
  /// into it again (as switching to GitHub does).
  Future<void> useSession(SessionGrant grant);

  /// The signed-in person was made identified on the instance (a password
  /// and address set, ADR 0017): this device's copy of their session
  /// follows.
  Future<void> markIdentified();
}