fix(plugin-auth): register the auth service-composition bindings independently of registerRoutes (#14810)

* fix(plugin-auth): register the auth service-composition bindings independently of registerRoutes

`AuthPlugin` bound the outbound mail transport, the SMS transport, the
deployment email locale, the brand name and the SMS locale inside the same
`kernel:ready` hook that mounts `/api/v1/auth/*`, and that hook was gated on
`registerRoutes`.

`registerRoutes` answers a transport-mounting question. The bindings are
service composition and are true of an embedding regardless of who serves the
routes, so every routes-less embedding came up with no mail transport, no
locale on either channel and no brand binding — silently, because the
`logger.info` lines that would have reported the wiring sat inside the same
skipped block.

Split the hook: the composition block moves verbatim into its own
unconditional `ctx.hook('kernel:ready', …)`, registered before the route hook
so the ordering a routing host had is preserved. Route registration itself
stays under `if (this.options.registerRoutes)`.

This is the shape the sibling hooks in this file already use and already name
("Registered independently of `registerRoutes` so an embedding that serves no
auth routes still gets the diagnosis") — the file applied the distinction to
the diagnosis hook and not to the wiring the diagnosis exists to report on.

The `#14319` describe block now runs against both values of `registerRoutes`
rather than only the default, and pins both acceptance criteria: the
composition completes either way, and a `registerRoutes: false` kernel still
mounts no auth routes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AUF1NoViznQK32gqpK8wS8

* chore(auth): add the changeset and re-anchor the system-context census row

The census row for `plugin-auth`'s session-resolution middleware anchors a
LINE NUMBER in `auth-plugin.ts`; the hook split moved that read site from
:1353 to :1380 without changing a character of it. Re-anchored with the gate's
own `--fix`, which is the repair it prescribes for pure line rot.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AUF1NoViznQK32gqpK8wS8

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

.changeset/auth-bindings-off-registerroutes.md

@@ -0,0 +1,42 @@
+---
+"@objectstack/plugin-auth": patch
+---
+
+fix(plugin-auth): the mail transport, brand and locale bindings no longer depend on `registerRoutes`
+
+`AuthPlugin` bound five things to the live kernel on `kernel:ready` — the
+outbound mail transport (`setEmailService`), the SMS transport
+(`setSmsService`), the deployment email locale (`setDefaultEmailLocale`), the
+brand name (`setAppName`) and the SMS locale (`setDefaultSmsLocale`) — from
+inside the same hook that mounts `/api/v1/auth/*`, and that hook was gated on
+`registerRoutes`.
+
+`registerRoutes` answers a transport-mounting question: should this plugin put
+its own routes on the kernel's `http-server`. The bindings are service
+composition, and they are true of an embedding regardless of who serves the
+routes. So an embedding that serves auth routes itself — the whole point of
+`registerRoutes: false` — came up with no mail transport, no locale on either
+channel and no brand binding. Silently: the `logger.info` lines that report the
+wiring were inside the same skipped block, and the `localization` settings
+namespace was not even read. One visible consequence was that the workspace
+language could not reach auth mail on such a host at all, and
+`/api/v1/auth/config` answered `requireEmailVerification: false` because
+`resolveRequireEmailVerification()` saw no transport.
+
+The composition block now registers as its own unconditional
+`ctx.hook('kernel:ready', …)` — the shape the sibling diagnosis and dev-seed
+hooks in this plugin already use — placed before the route hook so a routing
+host keeps the ordering the single combined hook gave it.
+
+Route registration itself stays gated: a `registerRoutes: false` kernel still
+mounts no auth routes.
+
+**Behaviour change for `registerRoutes: false` embeddings.** They now resolve
+the `email`, `sms`, `i18n` and `settings` services at `kernel:ready`, apply
+`branding.workspace_name` and `localization.locale` (subscribing to both), seed
+the built-in auth SMS templates when phone sign-in is enabled, and emit the
+four wiring `info` lines. Hosts that had compensated by wiring these by hand
+should expect the plugin's own binding to run as well; both paths are
+idempotent setters, and an explicit workspace setting keeps outranking a
+manifest default exactly as it does on a routing host. Nothing changes for a
+host that leaves `registerRoutes` at its default.

content/docs/permissions/system-context.mdx

@@ -97,7 +97,7 @@ that silently does not happen.
 | 8 | `explain()` may target a principal other than the caller | plugin-security | Get: no `manage_users` / delegated-admin check | `security-plugin.ts:3857` |
 | 9 | Anonymous-deny treats the caller as authenticated | core | Get: passes the 401 seam with no `userId` | `anonymous-deny.ts:154` |
 | 10 | Permission-set projection middleware skipped | plugin-security | Lose: projection of permission-set-derived columns | `permission-set-projection.ts:1015` |
-| 11 | Session-resolution middleware skipped | plugin-auth | Get: no session lookup attempted | `auth-plugin.ts:1353` |
+| 11 | Session-resolution middleware skipped | plugin-auth | Get: no session lookup attempted | `auth-plugin.ts:1380` |
 | 12 | Per-request performance timings disclosed | observability | Get: timing headers a normal caller cannot pull | `perf-timing.ts:474` |
 | 13 | Permission-set **overlay discard** skips the tenant-admin assertion | plugin-security | Get: an overlay can be discarded with no authenticated tenant administrator | `permission-set-overlay-discard.ts:142` |
 | 14 | MCP stdio bridge skips the object API-exposure gate | mcp | Get: the bridge reaches objects whose `apiEnabled` / `apiMethods` would refuse an external caller | `stdio-data-bridge.ts:246` |

packages/plugins/plugin-auth/src/auth-plugin.test.ts

@@ -541,6 +541,9 @@ describe('AuthPlugin', () => {
     let hookCapture: ReturnType<typeof createHookCapture>;
     let setEmailLocaleSpy: ReturnType<typeof vi.spyOn>;
     let setSmsLocaleSpy: ReturnType<typeof vi.spyOn>;
+    let setEmailServiceSpy: ReturnType<typeof vi.spyOn>;
+    let rawApp: { all: ReturnType<typeof vi.fn>; get: ReturnType<typeof vi.fn>; post: ReturnType<typeof vi.fn>; use: ReturnType<typeof vi.fn> };
+    let httpServer: { getRawApp: ReturnType<typeof vi.fn>; use: ReturnType<typeof vi.fn> };
 
     type Resolved = { value: unknown; source: string };
 
@@ -576,17 +579,38 @@ describe('AuthPlugin', () => {
      * `i18n` is passed as `null` to mean "no such service" — `getService`
      * THROWS for an unregistered service, which is the shape the plugin
      * probes for, not a falsy return.
+     *
+     * `registerRoutes` is threaded through on purpose (#14724). It answers a
+     * TRANSPORT-MOUNTING question — "does this plugin mount its own
+     * `/api/v1/auth/*` routes" — and must not decide any of the SERVICE
+     * COMPOSITION this block is about. A routes-less embedding (every cloud
+     * tenant environment kernel is one) has the same mail transport, brand
+     * and locale needs as a routing one; before #14724 all of it hung off the
+     * routing flag, so a `registerRoutes: false` kernel did not even READ the
+     * `localization` namespace.
      */
-    const boot = async (opts: { settings?: unknown; i18nDefault?: string | null }) => {
+    const boot = async (opts: {
+      settings?: unknown;
+      i18nDefault?: string | null;
+      registerRoutes?: boolean;
+      email?: unknown;
+    }) => {
       hookCapture = createHookCapture();
       mockContext.hook = hookCapture.hookFn;
+      rawApp = { all: vi.fn(), get: vi.fn(), post: vi.fn(), use: vi.fn() };
+      httpServer = { getRawApp: vi.fn(() => rawApp), use: vi.fn() };
       // `: any` on the RETURN, not a cast on the assignment: `getService` is
       // generic (`<T>(name: string) => T`), so an inferred union return is a
       // TS2322 — the exact debt `check:test-typecheck` ledgers for the older
       // doubles in this file. That ledger only ratchets down, so this one
       // states its shape instead of adding to it.
       mockContext.getService = vi.fn((name: string): any => {
         if (name === 'manifest') return { register: vi.fn() };
+        if (name === 'http-server') return httpServer;
+        if (name === 'email') {
+          if (opts.email === undefined) throw new Error('Service not found: email');
+          return opts.email;
+        }
         if (name === 'settings') {
           if (opts.settings === undefined) throw new Error('Service not found: settings');
           return opts.settings;
@@ -599,9 +623,11 @@ describe('AuthPlugin', () => {
       });
       setEmailLocaleSpy = vi.spyOn(AuthManager.prototype, 'setDefaultEmailLocale');
       setSmsLocaleSpy = vi.spyOn(AuthManager.prototype, 'setDefaultSmsLocale');
+      setEmailServiceSpy = vi.spyOn(AuthManager.prototype, 'setEmailService');
       authPlugin = new AuthPlugin({
         secret: 'test-secret-at-least-32-chars-long',
         baseUrl: 'http://localhost:3000',
+        ...(opts.registerRoutes === undefined ? {} : { registerRoutes: opts.registerRoutes }),
       });
       await authPlugin.init(mockContext);
       await authPlugin.start(mockContext);
@@ -611,72 +637,138 @@ describe('AuthPlugin', () => {
     afterEach(() => {
       setEmailLocaleSpy?.mockRestore();
       setSmsLocaleSpy?.mockRestore();
-    });
+      setEmailServiceSpy?.mockRestore();
+    });
+
+    // #14724 — run the whole block against BOTH values of the routing flag.
+    // Covering only the default is how the split defect survived: a test that
+    // exercises one branch of a flag cannot see the other.
+    describe.each([
+      ['registerRoutes: true (default)', true],
+      ['registerRoutes: false (routes-less embedding)', false],
+    ] as const)('%s', (_label, registerRoutes) => {
+      it('a zh-CN workspace binds zh-CN on the EMAIL channel, not just on SMS', async () => {
+        const settings = makeSettings({ value: 'zh-CN', source: 'tenant' });
+        await boot({ settings, i18nDefault: 'en', registerRoutes });
+
+        expect(settings.get).toHaveBeenCalledWith('localization', 'locale', {});
+        // The regression, stated as the two channels agreeing. Before #14319 the
+        // SMS assertion passed and the email one read 'en'.
+        expect(setSmsLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+        expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+      });
 
-    it('a zh-CN workspace binds zh-CN on the EMAIL channel, not just on SMS', async () => {
-      const settings = makeSettings({ value: 'zh-CN', source: 'tenant' });
-      await boot({ settings, i18nDefault: 'en' });
+      it.each(['ja-JP', 'es-ES'])('and the same for a %s workspace', async (locale) => {
+        await boot({
+          settings: makeSettings({ value: locale, source: 'global' }),
+          i18nDefault: 'en',
+          registerRoutes,
+        });
+        expect(setEmailLocaleSpy).toHaveBeenLastCalledWith(locale);
+      });
 
-      expect(settings.get).toHaveBeenCalledWith('localization', 'locale', {});
-      // The regression, stated as the two channels agreeing. Before #14319 the
-      // SMS assertion passed and the email one read 'en'.
-      expect(setSmsLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
-      expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
-    });
+      it('a workspace that never chose a language keeps the app build-time default', async () => {
+        // `get` answers the manifest default ('en-US') for an untouched
+        // workspace, so taking `value` unconditionally would demote every
+        // deployment that declared `i18n.defaultLocale` — the #8195 behaviour
+        // this change must not regress.
+        await boot({
+          settings: makeSettings({ value: 'en-US', source: 'default' }),
+          i18nDefault: 'zh-CN',
+          registerRoutes,
+        });
+        expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+      });
 
-    it.each(['ja-JP', 'es-ES'])('and the same for a %s workspace', async (locale) => {
-      await boot({ settings: makeSettings({ value: locale, source: 'global' }), i18nDefault: 'en' });
-      expect(setEmailLocaleSpy).toHaveBeenLastCalledWith(locale);
-    });
+      it('names NO locale when neither producer speaks — the documented en-US fallback', async () => {
+        // The issue's second acceptance criterion: absent language ⇒ English.
+        // Spelled as an ABSENT locale rather than 'en-US', because that is what
+        // `EmailService`'s ladder contract ("no locale means the DOCUMENTED
+        // default") is written against.
+        await boot({
+          settings: makeSettings({ value: 'en-US', source: 'default' }),
+          registerRoutes,
+        });
+        expect(setEmailLocaleSpy).toHaveBeenLastCalledWith(undefined);
+      });
 
-    it('a workspace that never chose a language keeps the app build-time default', async () => {
-      // `get` answers the manifest default ('en-US') for an untouched
-      // workspace, so taking `value` unconditionally would demote every
-      // deployment that declared `i18n.defaultLocale` — the #8195 behaviour
-      // this change must not regress.
-      await boot({
-        settings: makeSettings({ value: 'en-US', source: 'default' }),
-        i18nDefault: 'zh-CN',
+      it('binds the build-time default when there is no settings service at all', async () => {
+        await boot({ i18nDefault: 'ja-JP', registerRoutes });
+        expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('ja-JP');
       });
-      expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
-    });
 
-    it('names NO locale when neither producer speaks — the documented en-US fallback', async () => {
-      // The issue's second acceptance criterion: absent language ⇒ English.
-      // Spelled as an ABSENT locale rather than 'en-US', because that is what
-      // `EmailService`'s ladder contract ("no locale means the DOCUMENTED
-      // default") is written against.
-      await boot({ settings: makeSettings({ value: 'en-US', source: 'default' }) });
-      expect(setEmailLocaleSpy).toHaveBeenLastCalledWith(undefined);
-    });
+      it('re-binds live when the workspace switches language', async () => {
+        const settings = makeSettings({ value: 'en-US', source: 'default' });
+        await boot({ settings, i18nDefault: 'en', registerRoutes });
+        expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('en');
 
-    it('binds the build-time default when there is no settings service at all', async () => {
-      await boot({ i18nDefault: 'ja-JP' });
-      expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('ja-JP');
-    });
+        expect(settings.subscribe).toHaveBeenCalledWith('localization', expect.any(Function));
+        settings.set({ value: 'zh-CN', source: 'tenant' });
+        for (const handler of settings.handlers) handler();
+        // The subscribe handler is fire-and-forget (`void`); flush its promise.
+        await new Promise((resolve) => setImmediate(resolve));
 
-    it('re-binds live when the workspace switches language', async () => {
-      const settings = makeSettings({ value: 'en-US', source: 'default' });
-      await boot({ settings, i18nDefault: 'en' });
-      expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('en');
+        expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+        expect(setSmsLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+      });
 
-      expect(settings.subscribe).toHaveBeenCalledWith('localization', expect.any(Function));
-      settings.set({ value: 'zh-CN', source: 'tenant' });
-      for (const handler of settings.handlers) handler();
-      // The subscribe handler is fire-and-forget (`void`); flush its promise.
-      await new Promise((resolve) => setImmediate(resolve));
+      it('leaves the build-time default standing when the settings read fails', async () => {
+        const settings = makeSettings(new Error('boom'));
+        await expect(
+          boot({ settings, i18nDefault: 'zh-CN', registerRoutes }),
+        ).resolves.toBeUndefined();
+        expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+        expect(mockContext.logger.warn).toHaveBeenCalledWith(
+          expect.stringContaining('failed to apply localization.locale'),
+        );
+      });
 
-      expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
-      expect(setSmsLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
-    });
+      // ── #14724 acceptance criterion 1 ──────────────────────────────────
+      // The service composition is complete at the end of `kernel:ready`
+      // whichever way the routing flag is set. Measured before the split with
+      // `registerRoutes: false`: settingsRead [], emailLocaleCalls [],
+      // smsLocaleCalls [], emailServiceCalls [] — the namespace was not even
+      // read.
+      it('ends kernel:ready with the transport wired and BOTH locales bound', async () => {
+        const settings = makeSettings({ value: 'zh-CN', source: 'tenant' });
+        const email = { send: vi.fn() };
+        await boot({ settings, email, i18nDefault: 'en', registerRoutes });
+
+        expect(mockContext.getService).toHaveBeenCalledWith('email');
+        expect(setEmailServiceSpy).toHaveBeenCalledWith(email);
+        expect(settings.get).toHaveBeenCalledWith('localization', 'locale', {});
+        expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+        expect(setSmsLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+      });
 
-    it('leaves the build-time default standing when the settings read fails', async () => {
-      const settings = makeSettings(new Error('boom'));
-      await expect(boot({ settings, i18nDefault: 'zh-CN' })).resolves.toBeUndefined();
-      expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
-      expect(mockContext.logger.warn).toHaveBeenCalledWith(
-        expect.stringContaining('failed to apply localization.locale'),
-      );
+      // ── #14724 acceptance criterion 2 — the regression guard ───────────
+      // Route registration itself stays gated. This is the half that must
+      // NOT move: `registerRoutes: false` mounts no auth routes, and it is
+      // pinned here rather than left to prose.
+      it(`${registerRoutes ? 'mounts' : 'mounts NO'} auth routes`, async () => {
+        await boot({
+          settings: makeSettings({ value: 'zh-CN', source: 'tenant' }),
+          email: { send: vi.fn() },
+          i18nDefault: 'en',
+          registerRoutes,
+        });
+
+        const httpServerLookups = (mockContext.getService as ReturnType<typeof vi.fn>).mock.calls
+          .filter((args: unknown[]) => args[0] === 'http-server');
+
+        if (registerRoutes) {
+          expect(httpServerLookups.length).toBeGreaterThan(0);
+          expect(httpServer.getRawApp).toHaveBeenCalled();
+          expect(rawApp.all).toHaveBeenCalledWith('/api/v1/auth/*', expect.any(Function));
+        } else {
+          // The `http-server` service is present in this harness, so a zero
+          // lookup count is a statement about the gate and not about the
+          // service being absent.
+          expect(httpServerLookups.length).toBe(0);
+          expect(httpServer.getRawApp).not.toHaveBeenCalled();
+          expect(rawApp.all).not.toHaveBeenCalled();
+        }
+      });
     });
   });