CS-11264: route _realm-auth through reconciler.lookupOrMount

Pre-Phase-3 (CS-10894), every realm in the registry was eagerly
mounted at boot, so iterating the in-memory `realms[]` to resolve
a permission row's URL was equivalent to consulting the registry.
After Phase 3 only `pinned=true` rows mount at boot; non-pinned
(source / published) rows wait for a request-path
`reconciler.lookupOrMount()` to bring them in. `_realm-auth` was
left calling `allRealms.find(...)` directly — so after a
realm-server restart, an owner's first `boxel-cli` push/publish
fails with `No realm token available` because the auth handler
silently skips the permission row whose URL isn't yet in
`realms[]`. The matching `realm_user_permissions` row is intact;
the gap is purely in this handler's view of mounted realms.

Restore the pre-Phase-3 contract that calling `/_realm-auth` is
sufficient to interact with any realm the user has permissions on
by routing through `reconciler.lookupOrMount(realmUrl)`. Pinned
rows resolve via the `mounted` fast-path (O(1)); non-pinned rows
pay one cold-mount cost on first hit, the same cost any other
first request would pay. Mount failures Sentry-capture-and-skip,
mirroring the existing `ensureSessionRoom` failure handling.

Adds a `testingOnlyEvictRealmFromRealmsList(url)` shim on
`RealmServer` so the regression test can simulate the post-
restart "row in DB, realm not yet in this process's realms[]"
state without re-running disk mount / matrix login.

Regression test in `realm-auth-test.ts` evicts the test realm
from `realms[]`, hits `/_realm-auth`, and asserts a JWT is
issued. Confirmed it fails on the pre-fix code path and passes
on the fix.

Author: lukemelia

packages/realm-server/handlers/handle-realm-auth.ts

@@ -4,6 +4,7 @@ import type { CreateRoutesArgs } from '../routes';
 import {
   SupportedMimeType,
   fetchUserPermissions,
+  type Realm,
 } from '@cardstack/runtime-common';
 import type { RealmServerTokenClaim } from 'utils/jwt';
 import { getUserByMatrixUserId } from '@cardstack/billing/billing-queries';
@@ -14,11 +15,10 @@ import * as Sentry from '@sentry/node';
 export default function handleRealmAuth({
   dbAdapter,
   realmSecretSeed,
-  realms,
+  reconciler,
   serverURL,
 }: CreateRoutesArgs): (ctxt: Koa.Context, next: Koa.Next) => Promise<void> {
   return async function (ctxt: Koa.Context, _next: Koa.Next) {
-    let allRealms = realms;
     let token = ctxt.state.token as RealmServerTokenClaim;
     let { user: matrixUserId } = token;
     let user = await getUserByMatrixUserId(dbAdapter, matrixUserId);
@@ -42,7 +42,18 @@ export default function handleRealmAuth({
     for (let [realmUrl, permissions] of Object.entries(
       permissionsForAllRealms,
     )) {
-      let realm = allRealms.find((r) => r.url === realmUrl);
+      let realm: Realm | undefined;
+      try {
+        realm = await reconciler.lookupOrMount(realmUrl);
+      } catch (error) {
+        Sentry.withScope((scope) => {
+          scope.setExtra('realmUrl', realmUrl);
+          scope.setExtra('matrixUserId', matrixUserId);
+          scope.setExtra('permissionsForAllRealms', permissionsForAllRealms);
+          Sentry.captureException(error);
+        });
+        continue;
+      }
       if (!realm) {
         console.error(
           `Permissions found pointing to unknown realm ${realmUrl}`,

packages/realm-server/server.ts

@@ -543,6 +543,19 @@ export class RealmServer {
     }
   }
 
+  // Simulate the post-restart "this realm isn't in this process's
+  // realms[] yet" state without tearing down its disk mount, indexer,
+  // or matrix client. realm-auth-test uses this to prove
+  // _realm-auth resolves through the reconciler instead of realms[].
+  // The realm stays in reconciler.mounted so lookupOrMount() returns
+  // it via the fast path.
+  testingOnlyEvictRealmFromRealmsList(url: string): void {
+    let idx = this.realms.findIndex((r) => r.url === url);
+    if (idx !== -1) {
+      this.realms.splice(idx, 1);
+    }
+  }
+
   // Test-only accessor for the request-path realm resolver. Exposed so
   // lazy-mount integration tests can drive findOrMountRealm directly
   // without spinning up an HTTP listener + mocked Koa context.

packages/realm-server/tests/realm-auth-test.ts

@@ -13,11 +13,13 @@ import {
   testRealmHref,
 } from './helpers';
 import { createJWT as createRealmServerJWT } from '../utils/jwt';
+import type { RealmServer } from '../server';
 
 module(basename(__filename), function () {
   module('realm auth handler', function (hooks) {
     let dbAdapter: PgAdapter;
     let request: SuperTest<SupertestTest>;
+    let testRealmServer: RealmServer;
     const matrixUserId = '@firsttimer:localhost';
 
     setupPermissionedRealmCached(hooks, {
@@ -27,9 +29,14 @@ module(basename(__filename), function () {
         [matrixUserId]: ['read', 'write'],
         '@node-test_realm:localhost': ['read', 'realm-owner'],
       },
-      onRealmSetup: ({ dbAdapter: adapter, request: req }) => {
+      onRealmSetup: ({
+        dbAdapter: adapter,
+        request: req,
+        testRealmServer: server,
+      }) => {
         dbAdapter = adapter;
         request = req;
+        testRealmServer = server.testRealmServer;
       },
     });
 
@@ -86,5 +93,51 @@ module(basename(__filename), function () {
         'session room is persisted after the realm auth request',
       );
     });
+
+    // CS-11264 regression: after a realm-server restart, a non-pinned
+    // realm is not in this process's realms[] until something triggers a
+    // lazy mount via the request path. Pre-fix, _realm-auth iterated
+    // realms[] directly and silently skipped any realm not yet mounted on
+    // this instance — so an owner's first post-restart boxel-cli call
+    // (push/publish/sync) failed with "No realm token available". Post-
+    // fix, the handler routes through reconciler.lookupOrMount, so any
+    // realm the reconciler can resolve (already mounted, or registered
+    // via knownByUrl, or directly readable from realm_registry) yields a
+    // session token.
+    test('POST /_realm-auth issues a token for a realm reachable only via the reconciler (post-restart)', async function (assert) {
+      sinon
+        .stub(MatrixClient.prototype, 'createDM')
+        .resolves('!post-restart-session-room:localhost');
+      sinon.stub(MatrixClient.prototype, 'sendEvent').resolves();
+      sinon.stub(MatrixClient.prototype, 'getJoinedRooms').resolves({
+        joined_rooms: [],
+      });
+      sinon.stub(MatrixClient.prototype, 'joinRoom').resolves();
+
+      // Simulate the post-restart state where the realm is still
+      // mounted in the reconciler (which knows about it from boot or a
+      // prior lazy mount on another caller) but absent from this
+      // process's realms[] snapshot.
+      testRealmServer.testingOnlyEvictRealmFromRealmsList(testRealmHref);
+
+      let response = await request
+        .post('/_realm-auth')
+        .set('Accept', 'application/json')
+        .set('Content-Type', 'application/json')
+        .set(
+          'Authorization',
+          `Bearer ${createRealmServerJWT(
+            { user: matrixUserId, sessionRoom: 'server-session-room' },
+            realmSecretSeed,
+          )}`,
+        )
+        .send('{}');
+
+      assert.strictEqual(response.status, 200, 'HTTP 200 status');
+      assert.ok(
+        response.body[testRealmHref],
+        'response includes a JWT for the realm even though it was absent from realms[]',
+      );
+    });
   });
 });