objectstack-ai · os-sales · Sep 3, 2026 · Sep 3, 2026 · Sep 3, 2026 · Sep 3, 2026
diff --git a/.changeset/auth-bindings-off-registerroutes.md b/.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.
diff --git a/content/docs/permissions/system-context.mdx b/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` |

diff --git a/packages/plugins/plugin-auth/src/auth-plugin.test.ts b/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();
+ }
+ });
  });
  });
 

diff --git a/.changeset/auth-bindings-off-registerroutes.md b/.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.
diff --git a/content/docs/permissions/system-context.mdx b/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` |

diff --git a/packages/plugins/plugin-auth/src/auth-plugin.test.ts b/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();
+ }
+ });
  });
  });
 

diff --git a/.changeset/auth-bindings-off-registerroutes.md b/.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.
diff --git a/content/docs/permissions/system-context.mdx b/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` |

diff --git a/packages/plugins/plugin-auth/src/auth-plugin.test.ts b/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();
+ }
+ });
  });
  });
 

diff --git a/.changeset/auth-bindings-off-registerroutes.md b/.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.
diff --git a/content/docs/permissions/system-context.mdx b/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` |

diff --git a/packages/plugins/plugin-auth/src/auth-plugin.test.ts b/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();
+ }
+ });
  });
  });
 

diff --git a/.changeset/auth-bindings-off-registerroutes.md b/.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.
diff --git a/content/docs/permissions/system-context.mdx b/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` |

diff --git a/packages/plugins/plugin-auth/src/auth-plugin.test.ts b/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();
+ }
+ });
  });
  });
 

diff --git a/.changeset/auth-bindings-off-registerroutes.md b/.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.
diff --git a/content/docs/permissions/system-context.mdx b/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` |

diff --git a/packages/plugins/plugin-auth/src/auth-plugin.test.ts b/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();
+ }
+ });
  });
  });
 

diff --git a/.changeset/auth-bindings-off-registerroutes.md b/.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.
diff --git a/content/docs/permissions/system-context.mdx b/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` |

diff --git a/packages/plugins/plugin-auth/src/auth-plugin.test.ts b/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();
+ }
+ });
  });
  });
 

diff --git a/.changeset/auth-bindings-off-registerroutes.md b/.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.
diff --git a/content/docs/permissions/system-context.mdx b/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` |

diff --git a/packages/plugins/plugin-auth/src/auth-plugin.test.ts b/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();
+ }
+ });
  });
  });