feat(accounts): one account across an instance's services (ADR 0016)

halkyon_base runs as the instance's register or as one of its members.
The register keeps the ways in, handles and profiles; members ask it
over HTTP with the instance's shared secret (instanceSecret), and open
sessions of their own for its accounts, under the same account ID.

- AccountsMode from the environment: INSTANCE_MEMBERS on the register,
  ACCOUNT_REGISTER_URL on a member. Learn always holds the register
  (Explore joins the profiles); Todo is a member where it is set.
- AccountRegister: LocalRegister, RemoteRegister, an in-memory one in
  tests. Calls between services on the web server, refused without the
  secret (constant-time compare); a server needing it doesn't start
  without it.
- Deleting an account deletes it everywhere: notices per member kept in
  the deletion's transaction (account_deletion_notice), told at once and
  hourly until confirmed; members prune daily whom the register no longer
  knows, never while it knows none of them or can't be reached.
- Deploy: INSTANCE_SECRET and INSTANCE_MEMBERS in compose and .env.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Tizian 「ティツィアーン」 <raisondetredev@pm.me>

apps/learn/halkyon_learn_server/lib/server.dart

@@ -17,7 +17,9 @@ Future<void> run(List<String> args) async {
   final pod = Serverpod(args);
   // What every Halkyon server has (ADR 0014): sign-in, the account and its
   // deletion, the pruning, the instance's basics, set up for Learn.
-  HalkyonBase.configure(pod, learnBase());
+  // Learn holds the instance's register of accounts (ADR 0016), telling the
+  // instance's other services when one goes.
+  HalkyonBase.configure(pod, learnBase(accounts: learnAccounts()));
   pod
     // Token managers validate and issue authentication keys; identity
     // providers are the ways people can sign in (halkyon_base's
@@ -30,6 +32,9 @@ Future<void> run(List<String> args) async {
     ..addCloudStorage(DatabaseCloudStorage('private'))
     ..addCloudStorage(DatabaseCloudStorage('public'));
 
+  // The calls of the instance's other services, on the web server
+  // (ADR 0016); Caddy never forwards them.
+  addInstanceRoutes(pod);
   // The assistant connector, on the web server (ADR 0006).
   addConnectorRoutes(pod);
   // Profile pages, `/@handle`, which profile links link back to (ADR 0011),
@@ -63,6 +68,15 @@ Future<void> run(List<String> args) async {
       .pruning
       .forgetSignUpAttempts();
 
+  // The deletions the instance's members haven't confirmed yet, hourly
+  // (ADR 0016).
+  await pod.futureCalls.cancel(_deletionNotices);
+  await pod.futureCalls
+      .callRecurring(identifier: _deletionNotices)
+      .cron('52 * * * *')
+      .pruning
+      .tellMembersOfDeletions();
+
   // The assistant connector's expired codes and tokens (ADR 0006, rule 5).
   await pod.futureCalls.cancel(_connectorPruning);
   await pod.futureCalls
@@ -121,6 +135,9 @@ const _pruning = 'prune-abandoned-anonymous-people';
 /// The identifier of the hourly forgetting of sign-up attempts.
 const _attemptPruning = 'forget-sign-up-attempts';
 
+/// The identifier of the hourly telling of the members of deleted accounts.
+const _deletionNotices = 'tell-members-of-deletions';
+
 /// The identifier of the daily forgetting of the connector's expired secrets.
 const _connectorPruning = 'forget-connector-secrets';
 

apps/learn/halkyon_learn_server/lib/src/auth/learn_base.dart

@@ -15,18 +15,38 @@ const upstreamSourceCodeUrl =
 /// serves `learn` (the app accepts only such an instance; never change it),
 /// sign-in mails name the app, the instance names this project's source,
 /// works with apps from [minimumAppBuild] on, deletes Learn's own data of a
-/// person who goes ([deleteLearnData]), and profile pages name the app at
-/// their foot. The server sets it up before it starts (`server.dart`), and so
-/// do tests that delete people or read profiles.
-HalkyonBase learnBase() => HalkyonBase(
-  app: 'learn',
-  appName: 'Halkyon Learn',
-  upstreamSourceCodeUrl: upstreamSourceCodeUrl,
-  minimumAppBuild: minimumAppBuild,
-  deletePersonData: const [deleteLearnData],
-  profilePageNote: (
-    english: 'On Halkyon Learn, a spaced-repetition learning app:',
-    german: 'Auf Halkyon Learn, einer Lern-App mit verteilter Wiederholung:',
-    link: Uri.parse('https://halkyon.app/learn'),
-  ),
-);
+/// person who goes ([deleteLearnData]), profile pages name the app at their
+/// foot, and it holds the instance's register with [accounts]' members
+/// ([learnAccounts]). The server sets it up before it starts (`server.dart`),
+/// and so do tests that delete people or read profiles.
+HalkyonBase learnBase({HoldsRegister accounts = const HoldsRegister()}) =>
+    HalkyonBase(
+      app: 'learn',
+      appName: 'Halkyon Learn',
+      upstreamSourceCodeUrl: upstreamSourceCodeUrl,
+      minimumAppBuild: minimumAppBuild,
+      deletePersonData: const [deleteLearnData],
+      profilePageNote: (
+        english: 'On Halkyon Learn, a spaced-repetition learning app:',
+        german:
+            'Auf Halkyon Learn, einer Lern-App mit verteilter Wiederholung:',
+        link: Uri.parse('https://halkyon.app/learn'),
+      ),
+      accounts: accounts,
+    );
+
+/// Learn's part in the instance's accounts (ADR 0016), from the operator's
+/// [environment]: it holds the register, telling the members
+/// `INSTANCE_MEMBERS` names when an account goes. Never a member: Explore
+/// searches studysets by their authors' handles in the same query as the
+/// releases (`explore_endpoint.dart`), so the profiles must be in Learn's
+/// own database. An `ACCOUNT_REGISTER_URL` stops the server as it starts.
+HoldsRegister learnAccounts([Map<String, String>? environment]) =>
+    switch (AccountsMode.fromEnvironment(environment)) {
+      final HoldsRegister accounts => accounts,
+      MemberOfRegister() => throw StateError(
+        "Halkyon Learn holds its instance's register (ADR 0016) and is "
+        "never a member of another's: unset ACCOUNT_REGISTER_URL, and name "
+        'the other services in INSTANCE_MEMBERS.',
+      ),
+    };

apps/learn/halkyon_learn_server/lib/src/auth/pruning_future_call.dart

@@ -5,11 +5,11 @@ import 'package:serverpod/serverpod.dart';
 
 /// Deletes the anonymous people nobody can return to, daily, the IP
 /// addresses of sign-up attempts the rate limit is done with and the email
-/// sign-in codes past their time, hourly, and
-/// the assistant connector's expired secrets, daily; the server schedules
-/// them when it starts (`server.dart`). All but the last are halkyon_base's
-/// (ADR 0014), and people go through its `deletePerson`, so Learn's own data
-/// of theirs goes too.
+/// sign-in codes past their time, hourly, the deletions the instance's
+/// members haven't confirmed, hourly, and the assistant connector's expired
+/// secrets, daily; the server schedules them when it starts (`server.dart`).
+/// All but the last are halkyon_base's (ADR 0014, ADR 0016), and people go
+/// through its `deletePerson`, so Learn's own data of theirs goes too.
 class PruningFutureCall extends FutureCall {
   /// Prunes one batch and logs how many people went.
   Future<void> pruneAnonymousPeople(Session session) async {
@@ -39,4 +39,11 @@ class PruningFutureCall extends FutureCall {
     final codes = await forgetExpiredEmailCodes(session, now: now);
     session.log('Forgot $forgotten sign-up attempts and $codes email codes.');
   }
+
+  /// Tells the instance's members again of the accounts gone that they
+  /// haven't confirmed yet (ADR 0016), and logs how many confirmed.
+  Future<void> tellMembersOfDeletions(Session session) async {
+    final confirmed = await deliverDeletionNotices(session);
+    session.log('Members confirmed $confirmed deleted accounts.');
+  }
 }

apps/learn/halkyon_learn_server/lib/src/generated/future_calls.dart

@@ -68,6 +68,8 @@ class FutureCalls extends _is.FutureCallDispatch<_FutureCallRef> {
           PruningForgetConnectorSecretsFutureCall(),
       'PruningForgetSignUpAttemptsFutureCall':
           PruningForgetSignUpAttemptsFutureCall(),
+      'PruningTellMembersOfDeletionsFutureCall':
+          PruningTellMembersOfDeletionsFutureCall(),
       'DictionaryReloadReloadDictionariesFutureCall':
           DictionaryReloadReloadDictionariesFutureCall(),
       'LearnerCountCountLearnersFutureCall':
@@ -243,6 +245,13 @@ class _PruningFutureCallDispatcher {
       null,
     );
   }
+
+  Future<void> tellMembersOfDeletions() {
+    return _invokeFutureCall(
+      'PruningTellMembersOfDeletionsFutureCall',
+      null,
+    );
+  }
 }
 
 class _DictionaryReloadFutureCallDispatcher {
@@ -322,6 +331,19 @@ class PruningForgetSignUpAttemptsFutureCall extends _is.FutureCall
   }
 }
 
+/// Tells the instance's members again of the accounts gone that they
+/// haven't confirmed yet (ADR 0016), and logs how many confirmed.
+class PruningTellMembersOfDeletionsFutureCall extends _is.FutureCall
+    implements _is.InvokableFutureCall {
+  @override
+  _ida.Future<void> invoke(
+    _is.Session session,
+    _is.SerializableModel? object,
+  ) async {
+    await _igevg04y.PruningFutureCall().tellMembersOfDeletions(session);
+  }
+}
+
 /// Loads the dictionary files that changed since they were loaded.
 class DictionaryReloadReloadDictionariesFutureCall extends _is.FutureCall
     implements _is.InvokableFutureCall {