diff --git a/‎.changeset/20861-host-sign-in-handoff.md‎
Lines changed: 36 additions & 0 deletions b/‎.changeset/20861-host-sign-in-handoff.md‎
Lines changed: 36 additions & 0 deletions
diff --git a/‎content/docs/deployment/self-hosting.mdx‎
Lines changed: 11 additions & 0 deletions b/‎content/docs/deployment/self-hosting.mdx‎
Lines changed: 11 additions & 0 deletions
diff --git a/‎packages/plugins/plugin-auth/src/auth-plugin.ts‎
Lines changed: 29 additions & 1 deletion b/‎packages/plugins/plugin-auth/src/auth-plugin.ts‎
Lines changed: 29 additions & 1 deletion
diff --git a/‎packages/plugins/plugin-auth/src/boot-sign-in-reachability.sso-gate.test.ts‎
Lines changed: 100 additions & 0 deletions b/‎packages/plugins/plugin-auth/src/boot-sign-in-reachability.sso-gate.test.ts‎
Lines changed: 100 additions & 0 deletions
diff --git a/‎packages/plugins/plugin-auth/src/boot-sign-in-reachability.ts‎
Lines changed: 65 additions & 4 deletions b/‎packages/plugins/plugin-auth/src/boot-sign-in-reachability.ts‎
Lines changed: 65 additions & 4 deletions
@@ -0,0 +1,36 @@
+---
+'@objectstack/plugin-auth': minor
+---
+
+feat(plugin-auth): a host declares its own sign-in handoff route with `hostSignInHandoff`, and the `no_sign_in_account_at_boot` boot report stops calling that deployment a dead end (#20861)
+
+Clause-②: yes (widening)
+
+`AuthPluginOptions` gains one option, `hostSignInHandoff?: boolean` (default
+`false`). The HOST that constructs the plugin sets it when it signs people in
+through a handoff route of its own: a route that is not a login-page provider
+and that creates the session without writing a `sys_account` row. A hosted
+kernel whose owner signs in through the control plane is the case it is for.
+That owner can still sign in when the login page shows no platform sign-in
+button:
+
+```ts
+new AuthPlugin({ /* … */ hostSignInHandoff: true });
+```
+
+With it declared, human `sys_user` rows and zero `sys_account` rows are that
+deployment's normal state. The boot report then logs the shape at `debug` and
+names `hostSignInHandoff` as the reason. It no longer logs an `error` saying
+nobody can sign in. The option's only reader is that boot report.
+
+- It is a declaration, not a detection. The option is the only way to set it:
+  there is no environment variable or setting. Nothing infers it from an
+  environment's name, from a control plane's platform-SSO flag, or from missing
+  rows.
+- The login page is not changed. `getPublicConfig()` returns the same value with
+  or without the option, and no provider is registered.
+- Set it only where the host really serves such a route. On a deployment with
+  no such route, the option turns the error for a deployment nobody can sign in
+  to into a quiet `debug` line.
+- A deployment that does not declare it gets the same report as before. That
+  includes every self-hosted deployment with no delegated sign-in path.
@@ -540,6 +540,17 @@ first thing to look for — and note that it asks only whether *an* account row
 exists, so a row you wrote yourself silences it whether or not anyone can
 actually authenticate with it.
 
+The same shape is logged at **debug** instead, under the same token and naming
+the reason, when the deployment has a sign-in path that needs no `sys_account`
+row of its own: SSO-only mode (`OS_AUTH_SSO_ONLY` or `ssoOnlyMode`), a
+configured social or OIDC provider, enterprise SSO with at least one registered
+identity provider, or a host that constructs `AuthPlugin` with
+`hostSignInHandoff: true` because it signs people in through a handoff route of
+its own. A deployment with none of these still reports at **error**.
+`hostSignInHandoff` is a statement by the code that serves such a route, not a
+way to quiet the report: set on a deployment without one, it hides exactly the
+dead end this section describes.
+
 **The recovery is out of band, and it is one row.** Write a pending invitation
 directly against the store the deployment reads, then have that person register
 through the ordinary sign-up endpoint — the invitation carve-out admits that
 
@@ -225,6 +225,31 @@ export interface AuthPluginOptions extends Partial<AuthConfig> {
    * `AuthManagerOptions.databaseHooks` for the hop-by-hop correction (#4802).
    */
   databaseHooks?: BetterAuthOptions['databaseHooks'];
+
+  /**
+   * [#20861] The HOST declares that it signs humans into this deployment
+   * through a handoff route of its OWN — a sign-in path that is not a
+   * login-page provider, and that mints the session without writing a
+   * `sys_account` row. A hosted kernel whose owner enters through the control
+   * plane's handoff is the case this exists for: that owner signs in whether or
+   * not the login page shows any platform sign-in button.
+   *
+   * It has ONE reader, the `no_sign_in_account_at_boot` boot report
+   * (`boot-sign-in-reachability.ts`): with it declared, "human `sys_user` rows,
+   * zero `sys_account` rows" is this deployment's healthy state rather than an
+   * unrecoverable dead end, and the shape is recorded at `debug`, naming this
+   * declaration, instead of at `error`.
+   *
+   * ⛔ A declaration, never an inference and never a silencer. Set it only where
+   * the host really mounts such a route; declared without one, it turns the loud
+   * report of a deployment nobody can sign in to into a quiet one. It changes
+   * nothing the login page is told — `getPublicConfig()` returns the same with
+   * or without it, and no provider is registered. It is read from this option
+   * alone (no env var, no setting), so the code that wires the handoff is the
+   * one place it can be stated.
+   * @default false
+   */
+  hostSignInHandoff?: boolean;
 }
 
 /**
@@ -1052,7 +1077,10 @@ export class AuthPlugin implements Plugin {
       // pays for its bounded provider read only when the answer can change what
       // is reported; a deployment with no delegated path is untouched and still
       // reports at `error`.
-      const signInPath = await probeSignInPathWiring(reachability, pub, ql);
+      // [#20861] The plugin's own options ride along as the fourth fact: a
+      // handoff route the HOST owns never appears in `pub`, so the host's
+      // `hostSignInHandoff` declaration is the only place the gate can read it.
+      const signInPath = await probeSignInPathWiring(reachability, pub, ql, this.options);
       const deadEnd = reportIfNoSignInAccountExists(reachability, ctx.logger, signInPath);
 
       let ownerAccountState: WalledOwnerAccountState = 'unknown';
 
@@ -53,6 +53,7 @@ import type {
   SignInReachabilityFacts,
 } from './boot-sign-in-reachability';
 import { WALLED_OWNER_NO_VERIFICATION_PATH } from './walled-owner-verification-path';
+import type { AuthManager } from './auth-manager';
 import type { PluginContext } from '@objectstack/core';
 
 /** The store shape this report speaks about: humans SEEN, accounts SEEN ABSENT. */
@@ -61,6 +62,7 @@ const NOTHING_WIRED: SignInPathWiring = {
   ssoOnlyMode: false,
   socialSignIn: false,
   enterpriseSso: false,
+  hostSignInHandoff: false,
 };
 
 const ENV_KEYS = [
@@ -174,9 +176,14 @@ const bootWith = async (
   await plugin.start(ctx);
   await runKernelReady(hooks);
   const said = (fn: { mock: { calls: unknown[][] } }) => fn.mock.calls.map((c) => String(c[0]));
+  // The live manager `init()` registered — what the login page is told comes
+  // from ITS `getPublicConfig()`, so that is what the #20861 pin compares.
+  const registered = (ctx.registerService as unknown as { mock: { calls: unknown[][] } }).mock.calls;
+  const authManager = registered.find((c) => c[0] === 'auth')?.[1] as AuthManager | undefined;
   return {
     logger,
     reads,
+    publicConfig: authManager?.getPublicConfig(),
     errors: said(logger.error).filter((m) => m.includes(NO_SIGN_IN_ACCOUNT_AT_BOOT)),
     warnings: said(logger.warn).filter((m) => m.includes(NO_SIGN_IN_ACCOUNT_AT_BOOT)),
     debugs: said(logger.debug).filter((m) => m.includes(NO_SIGN_IN_ACCOUNT_AT_BOOT)),
@@ -454,3 +461,96 @@ describe('#15074 — the `sys_sso_provider` probe is bounded, silent and cheap',
     await expect(probeSignInPathWiring(DEAD_END, undefined, engine)).resolves.toEqual(NOTHING_WIRED);
   });
 });
+
+// ---------------------------------------------------------------------------
+// [#20861] A sign-in path the HOST owns, which no login-page provider shows.
+//
+// A hosted kernel whose owner hid the platform sign-in button wires no
+// `oidcProviders`, yet its owner still enters through the host's own handoff
+// route — which writes no `sys_account` row. None of the three facts above can
+// see that path, because each is read off what the LOGIN PAGE is told. So the
+// host states it: `new AuthPlugin({ hostSignInHandoff: true })`. The pins below
+// hold both directions and the one thing the declaration must never touch.
+// ---------------------------------------------------------------------------
+
+describe('#20861 — a host-declared sign-in handoff is a delegated path', () => {
+  it('declared, humans and ZERO `sys_account` rows — NO error, NO warning', async () => {
+    const { errors, warnings } = await bootWith(
+      { users: HUMANS, accounts: [] },
+      {},
+      { hostSignInHandoff: true },
+    );
+    expect(errors).toHaveLength(0);
+    expect(warnings).toHaveLength(0);
+  });
+
+  it('CONTROL — the same boot WITHOUT the declaration still reports the error', async () => {
+    const { errors } = await bootWith({ users: HUMANS, accounts: [] });
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toContain('NOBODY CAN SIGN IN');
+  });
+
+  it('the suppressed shape is still recorded at `debug`, naming the declaration', async () => {
+    const { debugs } = await bootWith(
+      { users: HUMANS, accounts: [] },
+      {},
+      { hostSignInHandoff: true },
+    );
+    expect(debugs).toHaveLength(1);
+    expect(debugs[0]).toMatch(/hostSignInHandoff/);
+  });
+
+  it('declaring it changes NOTHING `getPublicConfig()` returns — the login page is not lied to', async () => {
+    const without = await bootWith({ users: HUMANS, accounts: [] });
+    const declared = await bootWith(
+      { users: HUMANS, accounts: [] },
+      {},
+      { hostSignInHandoff: true },
+    );
+    expect(without.publicConfig).toBeDefined();
+    expect(declared.publicConfig).toEqual(without.publicConfig);
+    // Spelled out, because these are the fields the other three facts read:
+    // no provider is registered and no SSO mode is claimed on the host's behalf.
+    expect(declared.publicConfig?.socialProviders).toEqual([]);
+    expect(declared.publicConfig?.features.sso).toBe(false);
+    expect(declared.publicConfig?.features.ssoEnforced).toBe(false);
+  });
+});
+
+describe('#20861 — the fact comes from the host declaration, and from nothing else', () => {
+  it('declared alone ⇒ no report, and the reason NAMES the declaration', () => {
+    const wiring: SignInPathWiring = { ...NOTHING_WIRED, hostSignInHandoff: true };
+    expect(resolveNoSignInAccountReport(DEAD_END, wiring)).toBeNull();
+    expect(resolveDelegatedSignInPath(wiring)).toMatch(/hostSignInHandoff/);
+  });
+
+  it('the resolver carries the declaration through, and defaults to NOT declared', async () => {
+    const { engine } = engineOver({});
+    const declared = await probeSignInPathWiring(DEAD_END, undefined, engine, {
+      hostSignInHandoff: true,
+    });
+    expect(declared).toEqual({ ...NOTHING_WIRED, hostSignInHandoff: true });
+    await expect(probeSignInPathWiring(DEAD_END, undefined, engine, {})).resolves.toEqual(
+      NOTHING_WIRED,
+    );
+  });
+
+  it('only a literal `true` declares it — anything else keeps the report LOUD', async () => {
+    const { engine } = engineOver({});
+    for (const value of ['true', 1, 'yes', null]) {
+      const wiring = await probeSignInPathWiring(DEAD_END, undefined, engine, {
+        hostSignInHandoff: value as unknown as boolean,
+      });
+      expect(wiring.hostSignInHandoff).toBe(false);
+      expect(resolveNoSignInAccountReport(DEAD_END, wiring)).toContain(NO_SIGN_IN_ACCOUNT_AT_BOOT);
+    }
+  });
+
+  it('a declared handoff spares the `sys_sso_provider` read, like any path proven without the store', async () => {
+    const { engine, reads } = engineOver({ ssoProviders: [{ id: 'ssop_1' }] });
+    await probeSignInPathWiring(DEAD_END, { features: { sso: true } }, engine, {
+      hostSignInHandoff: true,
+    });
+    expect(reads).toEqual([]);
+  });
+});
@@ -195,6 +195,38 @@
  * When the gate suppresses the report the shape is still recorded — at `debug`,
  * under the same grep token, naming which configuration answered for it — so
  * "why is this deployment quiet" has an answer in the log and not only here.
+ *
+ * ## [#20861] A path the HOST owns, which the login page does not show
+ *
+ * The three facts above are read off `getPublicConfig()` — what the login page
+ * is told — plus one store row behind the SSO flag. A sign-in path that is
+ * deliberately NOT on the login page is invisible to all three. Measured on the
+ * card: a hosted kernel whose owner hid the platform sign-in button wires no
+ * `oidcProviders`, yet that owner still enters through the host's own handoff
+ * route, which mints the session without writing a `sys_account` row — and
+ * every kernel rebuild logged this report at `error` while the owner signed in
+ * normally.
+ *
+ * So there is a FOURTH fact, `hostSignInHandoff`, and it is the one the gate
+ * does not derive: the host that constructs the plugin STATES it
+ * (`AuthPluginOptions.hostSignInHandoff`), because the host is the one party
+ * that knows it mounted such a route. Three things it deliberately is not:
+ *
+ *   - ⛔ **an inference** — not from an environment's name, not from a control
+ *     plane's "platform SSO enabled" flag, not from the absence of rows. Each
+ *     would silence a deployment on a guess about wiring nobody stated;
+ *   - ⛔ **a login-page provider** — declaring it registers nothing and moves
+ *     no field `getPublicConfig()` returns, so the public config keeps telling
+ *     the truth about what the login page offers. Re-registering a hidden
+ *     provider just to satisfy this gate would make it lie;
+ *   - ⛔ **a remedy** — the `error` text does not name it, and must not: the
+ *     operator of a locked-out self-hosted deployment reads that line, and a
+ *     one-word switch that makes it go quiet is the one "fix" that turns a loud
+ *     dead end into a silent one. A host with no handoff route never sets it,
+ *     and the report stays loud there.
+ *
+ * Only a literal `true` declares it; any other value reads as NOT declared,
+ * which is the loud direction.
  */
 
 import { SystemObjectName } from '@objectstack/spec/system';
@@ -363,6 +395,13 @@ export interface SignInPathWiring {
   socialSignIn: boolean;
   /** Enterprise SSO is wired AND at least one `sys_sso_provider` row exists. */
   enterpriseSso: boolean;
+  /**
+   * [#20861] The HOST declared a sign-in handoff route of its own
+   * (`AuthPluginOptions.hostSignInHandoff`): a path no login-page provider
+   * shows, which mints a session without a `sys_account` row. The one member
+   * that is STATED rather than derived — see the module doc.
+   */
+  hostSignInHandoff: boolean;
 }
 
 /**
@@ -375,32 +414,45 @@ export interface SignInPathConfigView {
   features?: { sso?: boolean; ssoEnforced?: boolean };
 }
 
+/**
+ * [#20861] The subset of `AuthPluginOptions` this gate reads — what the HOST
+ * declared, as opposed to {@link SignInPathConfigView}, what the login page is
+ * told. Structural for the same reason: the plugin hands its own options
+ * straight over, and nothing here depends on the rest of them.
+ */
+export interface SignInPathHostView {
+  hostSignInHandoff?: boolean;
+}
+
 /**
  * [#15074] Resolve the wiring facts for a boot, paying for the provider probe
  * only when the answer can change what is reported.
  *
  * Two short-circuits, both deliberate: a boot that is not in the dead-end shape
  * cannot report whatever the wiring says, and a deployment that already has a
- * delegated path proven from config needs no store read to confirm a second
- * one. Every other boot pays exactly one bounded row read, and only when
- * enterprise SSO is switched on.
+ * delegated path — proven from config, or [#20861] declared by the host — needs
+ * no store read to confirm a second one. Every other boot pays exactly one
+ * bounded row read, and only when enterprise SSO is switched on.
  */
 export async function probeSignInPathWiring(
   facts: SignInReachabilityFacts,
   config: SignInPathConfigView | undefined,
   engine: BootProbeEngine | undefined,
+  host?: SignInPathHostView,
 ): Promise<SignInPathWiring> {
   const ssoOnlyMode = config?.features?.ssoEnforced === true;
   const socialSignIn = (config?.socialProviders?.length ?? 0) > 0;
+  const hostSignInHandoff = host?.hostSignInHandoff === true;
   const needsProviderProbe =
     config?.features?.sso === true &&
     !ssoOnlyMode &&
     !socialSignIn &&
+    !hostSignInHandoff &&
     isNoSignInAccountShape(facts);
   const enterpriseSso = needsProviderProbe
     ? (await probeSsoProvidersPresence(engine)) === 'present'
     : false;
-  return { ssoOnlyMode, socialSignIn, enterpriseSso };
+  return { ssoOnlyMode, socialSignIn, enterpriseSso, hostSignInHandoff };
 }
 
 /**
@@ -431,6 +483,13 @@ export function resolveDelegatedSignInPath(wiring?: SignInPathWiring): string |
       'registered, so a human signs in through it without holding a credential row here'
     );
   }
+  if (wiring.hostSignInHandoff) {
+    return (
+      'the host running this deployment declared a sign-in handoff route of its own ' +
+      '(hostSignInHandoff), so its humans enter through that route, not through a login-page ' +
+      `provider, and hold no '${SystemObjectName.ACCOUNT}' row`
+    );
+  }
   return null;
 }
 
@@ -455,6 +514,8 @@ export function resolveDelegatedSignInPath(wiring?: SignInPathWiring): string |
  *     accounts" is its healthy resting state and not a dead end. Omitting
  *     `wiring` answers as if nothing were configured, which keeps every
  *     pre-#15074 caller (and the self-hosted deployment they describe) loud.
+ *     [#20861] A host-declared handoff route is one such path, the one the
+ *     host states rather than the config shows.
  */
 export function resolveNoSignInAccountReport(
   facts: SignInReachabilityFacts,