CS-11264 follow-up: validate via registry, no per-row cold-mount

Routing every permission row through `reconciler.lookupOrMount` made
`_realm-auth` correct for the user's own non-pinned realms but
introduced a cold-mount-storm hazard: `fetchUserPermissions` is
called with `onlyOwnRealms: false`, so the result includes every
`'*'`-readable realm in addition to the user's owned/writable
realms. The host login flow and `boxel realm list` both hit
`/_realm-auth` and expect a JWT for every accessible realm; on a
fresh process that's an unbounded series of sequential
`realm.start()` calls against the entire public-readable set.

A JWT does not actually require a mounted realm. The token encodes
the URL, the user's permissions, the session room, and the realm
server URL; the realm itself is only used when the holder later
hits a per-realm endpoint, and `findOrMountRealm` /
`reconciler.lookupOrMount` handle the on-demand mount there.

Switch the handler to:

- Validate each accessible URL against `reconciler.knownByUrl` (the
  in-memory mirror of `realm_registry`), with a single batched
  probe against `realm_registry` for URLs not yet reflected in
  this process. Mirrors `multiRealmAuthorization` (CS-11238).
- Resolve the session room once per request (it is keyed by
  matrixUserId in the DB, not by realm). For the create branch,
  use the realm-server's matrix client to call `createDM`,
  matching how `_server-session` creates session rooms — the
  caller has already exchanged an OpenID token via
  `_server-session` to get the JWT they're presenting here, so
  the server client is already logged in.
- Issue the JWT for every URL that resolved against the registry,
  with no mount. Mount stays deferred to the next per-realm
  request.

Strengthen the regression test: `testingOnlyEvictRealmFromRealmsList`
now also removes the realm from `reconciler.mounted`, so the test
proves the handler issues a JWT for a realm absent from both
`realms[]` and `mounted` (i.e. would have needed a cold mount
under the previous follow-up's behavior). Adds preconditions and
a post-call assertion that `reconciler.mounted` is still empty
for the URL — the handler did NOT cold-mount.

Author: lukemelia

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

@@ -2,9 +2,14 @@ import type Koa from 'koa';
 
 import type { CreateRoutesArgs } from '../routes';
 import {
-  SupportedMimeType,
+  fetchSessionRoom,
   fetchUserPermissions,
-  type Realm,
+  param,
+  query,
+  separatedByCommas,
+  SupportedMimeType,
+  upsertSessionRoom,
+  type Expression,
 } from '@cardstack/runtime-common';
 import type { RealmServerTokenClaim } from 'utils/jwt';
 import { getUserByMatrixUserId } from '@cardstack/billing/billing-queries';
@@ -14,6 +19,7 @@ import * as Sentry from '@sentry/node';
 
 export default function handleRealmAuth({
   dbAdapter,
+  matrixClient,
   realmSecretSeed,
   reconciler,
   serverURL,
@@ -37,32 +43,88 @@ export default function handleRealmAuth({
       userId: matrixUserId,
       onlyOwnRealms: false,
     });
+    let accessibleRealmUrls = Object.keys(permissionsForAllRealms);
 
-    let sessions: { [realm: string]: string } = {};
-    for (let [realmUrl, permissions] of Object.entries(
-      permissionsForAllRealms,
-    )) {
-      let realm: Realm | undefined;
+    // Validate each accessible realm URL against the registry WITHOUT
+    // mounting it. fetchUserPermissions with onlyOwnRealms:false returns
+    // every '*'-readable realm in addition to the user's own; routing
+    // each row through reconciler.lookupOrMount would cold-mount every
+    // public-readable realm on the server on the first post-restart
+    // _realm-auth call (boxel realm list, host login). Phase 3's lazy-
+    // mount contract is "mount on first per-realm request" — the per-
+    // realm JWT itself is fine to issue from registry presence alone;
+    // the mount happens later, when the holder actually hits a realm
+    // endpoint and findOrMountRealm/lookupOrMount runs there.
+    //
+    // Same lookup order as multiRealmAuthorization (CS-11238): in-memory
+    // reconciler.knownByUrl first, then a single batched probe against
+    // realm_registry for any URLs not yet reflected in this process
+    // (e.g. a freshly-published row from a peer instance between NOTIFY
+    // and the next reconcile pass).
+    let registeredUrls = new Set<string>();
+    let urlsToProbe: string[] = [];
+    for (let realmUrl of accessibleRealmUrls) {
+      if (reconciler.knownByUrl.has(realmUrl)) {
+        registeredUrls.add(realmUrl);
+      } else {
+        urlsToProbe.push(realmUrl);
+      }
+    }
+    if (urlsToProbe.length > 0) {
+      let rows = (await query(dbAdapter, [
+        'SELECT url FROM realm_registry WHERE url IN (',
+        ...separatedByCommas(urlsToProbe.map((url) => [param(url)])),
+        ')',
+      ] as Expression)) as { url: string }[];
+      for (let { url } of rows) {
+        registeredUrls.add(url);
+      }
+    }
+
+    // Resolve the user's session room ONCE per request. The session room
+    // is keyed by matrixUserId in the DB, not by realm, so calling
+    // realm.ensureSessionRoom() per accessible realm (as this handler
+    // used to) was N redundant DB reads on the fast path and forced us
+    // to materialize each realm as a `Realm` instance on the cold path.
+    // For the create branch we use the realm-server's matrix client,
+    // matching how _server-session creates session rooms — at this
+    // point in the request lifecycle the caller has already exchanged
+    // an OpenID token via _server-session, so the server client is
+    // already logged in. login() is idempotent (cached promise).
+    let sessionRoom: string | null = await fetchSessionRoom(
+      dbAdapter,
+      matrixUserId,
+    );
+    if (!sessionRoom) {
       try {
-        realm = await reconciler.lookupOrMount(realmUrl);
+        await matrixClient.login();
+        sessionRoom = await matrixClient.createDM(matrixUserId);
+        await upsertSessionRoom(dbAdapter, matrixUserId, sessionRoom);
       } catch (error) {
         Sentry.withScope((scope) => {
-          scope.setExtra('realmUrl', realmUrl);
           scope.setExtra('matrixUserId', matrixUserId);
-          scope.setExtra('permissionsForAllRealms', permissionsForAllRealms);
           Sentry.captureException(error);
         });
-        continue;
+        await sendResponseForError(
+          ctxt,
+          500,
+          'Internal Server Error',
+          'Failed to ensure session room',
+        );
+        return;
       }
-      if (!realm) {
+    }
+
+    let sessions: { [realm: string]: string } = {};
+    for (let realmUrl of accessibleRealmUrls) {
+      if (!registeredUrls.has(realmUrl)) {
         console.error(
           `Permissions found pointing to unknown realm ${realmUrl}`,
         );
         continue;
       }
-
+      let permissions = permissionsForAllRealms[realmUrl];
       try {
-        let sessionRoom = await realm.ensureSessionRoom(matrixUserId);
         sessions[realmUrl] = createJWT(
           {
             user: matrixUserId,
@@ -79,10 +141,8 @@ export default function handleRealmAuth({
           scope.setExtra('realmUrl', realmUrl);
           scope.setExtra('matrixUserId', matrixUserId);
           scope.setExtra('permissionsForAllRealms', permissionsForAllRealms);
-
           Sentry.captureException(error);
         });
-
         continue;
       }
     }

packages/realm-server/server.ts

@@ -537,23 +537,34 @@ export class RealmServer {
     return [...this.realms];
   }
 
+  // Test-only accessor for the reconciler. Exposed so realm-auth-test
+  // can inspect knownByUrl / mounted as preconditions and assert that
+  // _realm-auth does not cold-mount during request handling.
+  get testingOnlyReconciler() {
+    return this.reconciler;
+  }
+
   testingOnlyUnmountRealms() {
     for (let realm of this.realms) {
       this.virtualNetwork.unmount(realm.handle);
     }
   }
 
-  // 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.
+  // Simulate the post-restart "this realm has a registry row but no
+  // active Realm instance on this process" state without tearing down
+  // its disk mount, indexer, or matrix client. realm-auth-test uses
+  // this to prove _realm-auth issues a JWT for a realm that is absent
+  // from both realms[] and reconciler.mounted — i.e. one that would
+  // need a cold lookupOrMount to be materialized. The registry row
+  // (and reconciler.knownByUrl entry) is left in place; the next
+  // request that actually needs the realm will lazy-mount it via the
+  // normal request path.
   testingOnlyEvictRealmFromRealmsList(url: string): void {
     let idx = this.realms.findIndex((r) => r.url === url);
     if (idx !== -1) {
       this.realms.splice(idx, 1);
     }
+    this.reconciler.mounted.delete(url);
   }
 
   // Test-only accessor for the request-path realm resolver. Exposed so

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

@@ -95,16 +95,22 @@ module(basename(__filename), function () {
     });
 
     // 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) {
+    // realm has a row in realm_registry but no active Realm instance
+    // on this process 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 validates against reconciler.knownByUrl
+    // (with a registry probe fallback) and issues a JWT without
+    // mounting; the mount happens later via the normal request path
+    // when the holder of the JWT actually hits a realm endpoint.
+    //
+    // Mounting per row inside _realm-auth was rejected because
+    // fetchUserPermissions(onlyOwnRealms:false) returns every
+    // '*'-readable realm, so a single boxel realm list / host login
+    // would cold-mount the entire accessible set after a restart.
+    test('POST /_realm-auth issues a token for a realm absent from realms[] and reconciler.mounted (post-restart)', async function (assert) {
       sinon
         .stub(MatrixClient.prototype, 'createDM')
         .resolves('!post-restart-session-room:localhost');
@@ -114,11 +120,26 @@ module(basename(__filename), function () {
       });
       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.
+      // Simulate the post-restart state: registry row + knownByUrl
+      // entry are present (reconciler boot has reflected the registry),
+      // but neither realms[] nor reconciler.mounted holds an active
+      // Realm. The handler must NOT attempt to cold-mount; it must
+      // issue a JWT from the registry presence alone.
       testRealmServer.testingOnlyEvictRealmFromRealmsList(testRealmHref);
+      assert.false(
+        testRealmServer.testingOnlyRealms.some(
+          (r) => r.url === testRealmHref,
+        ),
+        'precondition: realm is absent from realms[]',
+      );
+      assert.false(
+        testRealmServer.testingOnlyReconciler.mounted.has(testRealmHref),
+        'precondition: realm is absent from reconciler.mounted',
+      );
+      assert.true(
+        testRealmServer.testingOnlyReconciler.knownByUrl.has(testRealmHref),
+        'precondition: registry row is still reflected in reconciler.knownByUrl',
+      );
 
       let response = await request
         .post('/_realm-auth')
@@ -136,7 +157,11 @@ module(basename(__filename), function () {
       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[]',
+        'response includes a JWT for the realm even though it was absent from realms[] and reconciler.mounted',
+      );
+      assert.false(
+        testRealmServer.testingOnlyReconciler.mounted.has(testRealmHref),
+        'the handler did NOT cold-mount the realm — mount remains deferred to the next per-realm request',
       );
     });
   });