@@ -0,0 +1,12 @@
+---
+'@objectstack/plugin-auth': patch
+---
+
+feat(plugin-auth): `answerOneTimeTokenHandoff` — a host that forwards `/api/v1/auth/*` to a kernel's `AuthManager` answers the mobile sign-in hand-off
+
+Clause-②: yes (widening)
+Metadata-protocol: none
+
+The package root now exports `answerOneTimeTokenHandoff(manager, request, serving)` with its input types `OneTimeTokenHandoffManager` and `OneTimeTokenHandoffServing`, and `HandoffAnswer` as a type beside them. It is the whole body of `GET /api/v1/auth/one-time-token/handoff`: AuthPlugin's own mount now calls it, and its answers do not change.
+
+A host that serves no AuthPlugin routes and forwards the auth routes to an `AuthManager` it did not mount (a per-environment kernel with no HTTP server, AuthPlugin with `registerRoutes: false`) used to answer the hand-off `404`, because the route existed only on AuthPlugin's own server and a token minted outside the hand-off is unredeemable by design. Such a host now answers it for the manager it forwards to: `answerOneTimeTokenHandoff(manager, { url, headers, queries }, { authMountPath: '/api/v1/auth', server, serverEnv, onUnserved })`. A `302` answer carries `headers` and no body; every other status carries `body` as JSON with `headers`. The sign-in page a signed-out navigation is sent to is the one `server` answers, and `Location` stays root-relative, so the browser stays on the host it arrived on. The seams the hand-off is built from (`runOneTimeTokenHandoff`, `withHandoffChallenge`, `resolveHandoffSignInEntry`, the token-store hasher) stay unexported, so no host can mint outside the challenge scope.
@@ -103,7 +103,7 @@ import { runSetInitialPassword } from './set-initial-password.js';
 import { runRegisterSsoProviderFromForm, runRegisterSamlProviderFromForm, runRequestDomainVerification, runVerifyDomain, type AuthRequestHandler } from './register-sso-provider.js';
 import { runResendVerificationEmail } from './send-verification-email.js';
 import { runSysSessionRevoke, sysSessionRevokeDepsFor } from './sys-session-revoke.js';
-import { resolveHandoffSignInEntry, runOneTimeTokenHandoff } from './one-time-token-handoff.js';
+import { answerOneTimeTokenHandoff } from './one-time-token-handoff.js';
 import { readJsonRequestBody } from './request-json-body.js';
 import {
   seedCreatedOrganizationCurrency,
@@ -4708,45 +4708,33 @@ export class AuthPlugin implements Plugin {
     // navigation is refused (ruling A). A page navigation without such a session
     // goes to this deployment's sign-in page and comes back, so the app opens this
     // route and never names the Console's. The reasons for every answer live in
-    // `one-time-token-handoff.ts`. Ledgered in auth-route-ledger.ts.
+    // `one-time-token-handoff.ts`, whose `answerOneTimeTokenHandoff` is this
+    // route's whole body and the package export a host that forwards the auth
+    // routes to a manager it did not mount calls. Ledgered in auth-route-ledger.ts.
     let reportedNoHandoffSignInPage = false;
     rawApp.get(`${basePath}/one-time-token/handoff`, async (c: any) => {
       try {
-        const manager = this.authManager!;
-        const answer = await runOneTimeTokenHandoff(
+        const answer = await answerOneTimeTokenHandoff(
+          this.authManager!,
           {
-            registeredSchemes: manager.getRegisteredAppSchemes(),
-            sessionCreatedAt: async (headers) => {
-              const api: any = await manager.getApi();
-              const live = await api.getSession({ headers });
-              const createdAt = live?.session?.createdAt;
-              return createdAt ? new Date(createdAt) : null;
-            },
-            generate: async (headers) => {
-              const api: any = await manager.getApi();
-              return api.generateOneTimeToken({ headers });
+            url: c.req.url,
+            headers: c.req.raw.headers,
+            queries: (c.req.queries() ?? {}) as Record<string, string[]>,
+          },
+          {
+            authMountPath: basePath,
+            server: rawApp,
+            serverEnv: c.env,
+            onUnserved: (path, reason) => {
+              if (reportedNoHandoffSignInPage) return;
+              reportedNoHandoffSignInPage = true;
+              ctx.logger.warn(
+                `[AuthPlugin] one-time-token/handoff: this server does not serve a sign-in page at ${path} (${reason}), ` +
+                  'so a signed-out browser that opens the mobile sign-in hand-off sees a JSON 401 instead of a sign-in form. ' +
+                  'Mount the Console, or set uiBasePath to where it is mounted. Reported once.',
+              );
             },
-            signInEntry: (headers) =>
-              resolveHandoffSignInEntry({
-                signInPageUrl: manager.getConsoleUrl('/login'),
-                authBaseUrl: manager.getAuthIssuer(),
-                authMountPath: basePath,
-                requestUrl: c.req.url,
-                requestHost: headers.get('host'),
-                server: rawApp,
-                serverEnv: c.env,
-                onUnserved: (path, reason) => {
-                  if (reportedNoHandoffSignInPage) return;
-                  reportedNoHandoffSignInPage = true;
-                  ctx.logger.warn(
-                    `[AuthPlugin] one-time-token/handoff: this server does not serve a sign-in page at ${path} (${reason}), ` +
-                      'so a signed-out browser that opens the mobile sign-in hand-off sees a JSON 401 instead of a sign-in form. ' +
-                      'Mount the Console, or set uiBasePath to where it is mounted. Reported once.',
-                  );
-                },
-              }),
           },
-          { queries: (c.req.queries() ?? {}) as Record<string, string[]>, headers: c.req.raw.headers },
         );
         if (answer.status === 302) {
           return new Response(null, { status: 302, headers: answer.headers });
 
@@ -312,7 +312,7 @@ export const AUTH_ROUTE_LEDGER: readonly AuthRouteLedgerEntry[] = [
   // `one-time-token-handoff.ts` carries the interception argument.
   { route: 'GET /api/v1/auth/one-time-token/generate', family: 'one-time-token', source: 'better-auth', disposition: 'server-only', requires: 'oneTimeToken', note: 'published by the catch-all and refused to every client request (disableClientRequest: 400 with a session, 401 without); the only caller is the in-process hand-off, which binds the token it mints to the app shell\'s PKCE challenge' },
   { route: 'POST /api/v1/auth/one-time-token/verify', family: 'one-time-token', source: 'better-auth', disposition: 'public', requires: 'oneTimeToken', note: 'no SDK method builds this URL — the mobile app shell (or the Console in its WebView) redeems a hand-off token here with no session: body { token: "T.code_verifier" }, answering the vendor { session, user } plus the session cookie, once, within one minute; a token without the verifier whose challenge started the hand-off (an intercepted callback) answers the vendor 400 and consumes nothing' },
-  { route: 'GET /api/v1/auth/one-time-token/handoff', family: 'one-time-token', source: 'objectstack', disposition: 'server-only', requires: 'oneTimeToken', note: 'no SDK method builds this URL — it is the entry the mobile app shell opens in the system browser. Closed query set { redirect_uri, code_challenge, code_challenge_method }: for a session signed in within five minutes it answers 302 to a redirect_uri whose scheme trustedAppSchemes registers, with a single-use one-minute token bound to the S256 code_challenge; an unregistered scheme answers 400 with no redirect. With no such session, a page navigation answers 302 to this deployment\'s Console sign-in page (root-relative, redirect naming the same request); any other caller, a navigation reporting Sec-Fetch-Site: same-origin (the sign-in page forwarding), and every caller on a deployment that serves no sign-in page answer 401. The mount is unconditional; with no registered scheme every target is refused' },
+  { route: 'GET /api/v1/auth/one-time-token/handoff', family: 'one-time-token', source: 'objectstack', disposition: 'server-only', requires: 'oneTimeToken', note: 'no SDK method builds this URL — it is the entry the mobile app shell opens in the system browser. Closed query set { redirect_uri, code_challenge, code_challenge_method }: for a session signed in within five minutes it answers 302 to a redirect_uri whose scheme trustedAppSchemes registers, with a single-use one-minute token bound to the S256 code_challenge; an unregistered scheme answers 400 with no redirect. With no such session, a page navigation answers 302 to this deployment\'s Console sign-in page (root-relative, redirect naming the same request); any other caller, a navigation reporting Sec-Fetch-Site: same-origin (the sign-in page forwarding), and every caller on a deployment that serves no sign-in page answer 401. The mount is unconditional; with no registered scheme every target is refused. A host that forwards the auth routes to an AuthManager it did not mount (a per-environment kernel with no HTTP server, so this mount never runs) answers this route through the package export answerOneTimeTokenHandoff, which is this mount\'s whole body: the token is still minted inside the challenge scope, and the hand-off\'s seams stay unexported' },
   { route: 'POST /api/v1/auth/two-factor/disable', family: 'two-factor', source: 'better-auth', disposition: 'sdk', client: 'auth.twoFactor.disable', requires: 'twoFactor' },
   { route: 'POST /api/v1/auth/two-factor/enable', family: 'two-factor', source: 'better-auth', disposition: 'sdk', client: 'auth.twoFactor.enable', requires: 'twoFactor' },
   { route: 'POST /api/v1/auth/two-factor/generate-backup-codes', family: 'two-factor', source: 'better-auth', disposition: 'sdk', client: 'auth.twoFactor.generateBackupCodes', requires: 'twoFactor' },
 
@@ -40,6 +40,18 @@ export {
 // kept; the call never throws. The pure steps of the rule stay unexported, so
 // the rule keeps one owner.
 export type { IdpLocaleClaim } from './idp-locale-claim.js';
+// The mobile sign-in hand-off, for a host that forwards `/api/v1/auth/*` to a
+// kernel's AuthManager it did not mount (a per-environment kernel with no HTTP
+// server): that host answers `GET /one-time-token/handoff` with this, the same
+// body AuthPlugin's own mount runs. Only the whole answer is published: the
+// token must be minted inside the hand-off's challenge scope, so the seams it
+// is built from stay unexported and no host can mint outside it.
+export {
+  answerOneTimeTokenHandoff,
+  type OneTimeTokenHandoffManager,
+  type OneTimeTokenHandoffServing,
+  type HandoffAnswer,
+} from './one-time-token-handoff.js';
 export * from './ensure-default-organization.js';
 // [ADR-0131 D3 / D10 fate 3] The Default Organization's boot invariant, for the
 // v18 organization-ownership ceremony (`os migrate organization-ownership
 
@@ -40,6 +40,13 @@ import {
   runOneTimeTokenHandoff,
   s256Challenge,
 } from './one-time-token-handoff';
+import * as packageRoot from './index';
+import {
+  answerOneTimeTokenHandoff,
+  type HandoffAnswer,
+  type OneTimeTokenHandoffManager,
+  type OneTimeTokenHandoffServing,
+} from './index';
 
 const SECRET = 'test-secret-at-least-32-chars-long!!';
 const PASSWORD = 'S3cure!Passw0rd-one-time-token';
@@ -732,3 +739,128 @@ describe('trustedAppSchemes — refused at construction, never dropped', () => {
     expect(manager.getRegisteredAppSchemes()).toEqual([APP_SCHEME]);
   });
 });
+
+// A host that forwards `/api/v1/auth/*` to a kernel's `AuthManager` it did not
+// mount (the cloud's per-environment kernels: no `http-server`, AuthPlugin with
+// `registerRoutes: false`) answers the hand-off through the package root's one
+// export, so the token is still minted inside the challenge scope and the
+// AuthPlugin route and every such host share one implementation.
+describe('one-time-token hand-off — a host that forwards the auth routes answers it through the package export', () => {
+  const query = { redirect_uri: CALLBACK, code_challenge: s256Challenge(VERIFIER), code_challenge_method: 'S256' };
+  const HOST_ORIGIN = 'https://env-42.hosted.example';
+
+  /**
+   * The host: a Hono app that is NOT AuthPlugin's. It serves its own sign-in
+   * page, answers the hand-off for the manager it was handed, and forwards every
+   * other auth path to that manager the way a forwarding host does. No
+   * AuthPlugin is constructed, so nothing here mounts `registerAuthRoutes`.
+   */
+  const arrangeHost = async () => {
+    const engine = createMemoryEngine();
+    for (const [name, rows] of await signedUpOnce()) engine.tables.set(name, structuredClone(rows));
+    const manager = makeManager(engine);
+    const unserved: string[] = [];
+    const host = new Hono();
+    servedConsole(host);
+    host.get(`${BASE}${ONE_TIME_TOKEN_HANDOFF_PATH}`, async (c) => {
+      const handedManager: OneTimeTokenHandoffManager = manager;
+      const serving: OneTimeTokenHandoffServing = {
+        authMountPath: BASE,
+        server: host,
+        serverEnv: c.env,
+        onUnserved: (path, reason) => unserved.push(`${path}: ${reason}`),
+      };
+      const answer: HandoffAnswer = await answerOneTimeTokenHandoff(
+        handedManager,
+        { url: c.req.url, headers: c.req.raw.headers, queries: c.req.queries() ?? {} },
+        serving,
+      );
+      if (answer.status === 302) return new Response(null, { status: 302, headers: answer.headers });
+      return c.json(answer.body, answer.status as any, answer.headers);
+    });
+    host.all(`${BASE}/*`, (c) => manager.handleRequest(c.req.raw));
+
+    const viaHost = (path: string, init: RequestInit = {}) => host.request(`${HOST_ORIGIN}${path}`, init);
+    const handoff = (cookie: string | undefined, extra: Record<string, string> = {}) =>
+      viaHost(`${BASE}${ONE_TIME_TOKEN_HANDOFF_PATH}?${new URLSearchParams(query)}`, {
+        headers: { ...(cookie ? { cookie } : {}), ...extra },
+      });
+    const signIn = async (): Promise<string> => {
+      const res = await viaHost(`${BASE}/sign-in/email`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', origin: ORIGIN },
+        body: JSON.stringify({ email: ALICE_EMAIL, password: PASSWORD }),
+      });
+      expect(res.status, `sign-in: ${await res.clone().text()}`).toBe(200);
+      return cookieFrom(res);
+    };
+    const redeem = (token: string) =>
+      viaHost(`${BASE}${ONE_TIME_TOKEN_VERIFY_PATH}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', origin: ORIGIN },
+        body: JSON.stringify({ token }),
+      });
+    return { engine, unserved, handoff, signIn, redeem };
+  };
+
+  it('answers the app\'s anonymous probe with 401 UNAUTHENTICATED and mints nothing', async () => {
+    const { engine, handoff } = await arrangeHost();
+    const before = verificationRows(engine).length;
+    const res = await handoff(undefined, { accept: 'application/json' });
+    expect(res.status).toBe(401);
+    expect(((await res.json()) as any).error.code).toBe('UNAUTHENTICATED');
+    expect(res.headers.get('location')).toBeNull();
+    expect(verificationRows(engine).length).toBe(before);
+  });
+
+  it('sends a signed-out navigation to the HOST\'s own sign-in page, root-relative, naming the same request', async () => {
+    const { handoff, unserved } = await arrangeHost();
+    const res = await handoff(undefined, NAVIGATION);
+    expect(res.status).toBe(302);
+    expect(res.headers.get('cache-control')).toBe('no-store');
+    const location = res.headers.get('location')!;
+    expect(location.startsWith('/')).toBe(true);
+    const target = new URL(location, HOST_ORIGIN);
+    expect(target.pathname).toBe('/_console/login');
+    expect(target.searchParams.get('redirect')).toBe(`${BASE}${ONE_TIME_TOKEN_HANDOFF_PATH}?${new URLSearchParams(query)}`);
+    expect(unserved).toEqual([]);
+  });
+
+  it('hands a fresh session to the app, the token redeems at /one-time-token/verify with the verifier once, and no log line carries it', async () => {
+    const streams = [process.stdout, process.stderr].map((stream) => vi.spyOn(stream, 'write'));
+    const consoles = (['log', 'info', 'debug', 'warn', 'error'] as const).map((level) =>
+      vi.spyOn(console, level).mockImplementation(() => {}),
+    );
+    const { engine, signIn, handoff, redeem, unserved } = await arrangeHost();
+    const cookie = await signIn();
+
+    const res = await handoff(cookie, NAVIGATION);
+    expect(res.status).toBe(302);
+    const location = new URL(res.headers.get('location')!);
+    expect(location.protocol).toBe(`${APP_SCHEME}:`);
+    const token = location.searchParams.get('token')!;
+    expect(token).toMatch(/^[A-Za-z0-9_-]{32}$/);
+
+    const redeemed = await redeem(`${token}.${VERIFIER}`);
+    expect(redeemed.status, await redeemed.clone().text()).toBe(200);
+    expect(((await redeemed.json()) as any).user.id).toBe(userRows(engine).find((r) => r.email === ALICE_EMAIL).id);
+    expect(cookieFrom(redeemed)).toContain('session_token=');
+
+    const replay = await redeem(`${token}.${VERIFIER}`);
+    expect(replay.status).toBe(400);
+    expect(((await replay.json()) as any).message).toBe('Invalid token');
+
+    const written = [...streams, ...consoles]
+      .flatMap((spy) => spy.mock.calls)
+      .map((args) => args.map((arg) => (typeof arg === 'string' ? arg : String(arg))).join(' '))
+      .concat(unserved);
+    expect(written.filter((line) => line.includes(token))).toEqual([]);
+  });
+
+  it('the package root publishes the one answer and none of the minting seams', () => {
+    expect(typeof packageRoot.answerOneTimeTokenHandoff).toBe('function');
+    for (const seam of ['runOneTimeTokenHandoff', 'withHandoffChallenge', 'resolveHandoffSignInEntry', 'oneTimeTokenStoreHasher']) {
+      expect(Object.keys(packageRoot), seam).not.toContain(seam);
+    }
+  });
+});