feat(plugin-auth): expose the configured better-auth basePath as one definition

`AuthManager.config` was private and nothing else exposed the base path
better-auth is configured with, so an HTTP adapter mounting this service had
no way to ask where its routes live. `getBasePath()` answers that, and is
now the single definition of the value: `createAuthInstance` hands better-auth
exactly this string and `betterAuthEndpointPath` reads the same call.

The two sites previously normalised independently and disagreed on a
configured value written without a leading slash — `api/v1/auth` reached
better-auth verbatim while the route-ownership walk tested `/api/v1/auth`.

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

Author: claude

packages/plugins/plugin-auth/src/auth-manager-base-path.test.ts

@@ -0,0 +1,70 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// #16025 — `AuthManager.getBasePath()`, the one definition of "where does
+// better-auth serve".
+//
+// ## Why this member is public, and why a rename is a breaking change
+//
+// An HTTP adapter that mounts this service has to know where its routes live.
+// Until this accessor existed it could not ask — `config` is private and
+// nothing exposed the value — so `@objectstack/hono`'s `createHonoApp` mounted
+// the auth surface under its OWN `prefix` option, whose default (`/api`) does
+// not compose with this one (`/api/v1/auth`). Measured on a real boot with the
+// documented embed `createHonoApp({ kernel })`, before the fix:
+//
+//     POST /api/auth/sign-in/email  (valid shape, wrong password)  ->  200 {}
+//
+// `createHonoApp` now derives the mount from this method, by name, through a
+// structural interface (the adapter does not depend on this package). ⇒ A
+// rename or removal here silently returns that adapter to the mount above.
+//
+// ⛔ The behaviour that matters most is NOT assertable from this package: that
+// better-auth is really configured with the string this returns. It is one
+// expression — `createAuthInstance` passes `this.getBasePath()` and
+// `betterAuthEndpointPath` reads the same call — so the two cannot disagree by
+// construction rather than by two sites happening to agree. The observable
+// proof runs on a real boot in `@objectstack/verify`
+// (`auth-base-path-contract.test.ts`), which is the nearest package that can
+// hold a live better-auth and this manager at once.
+
+import { describe, it, expect } from 'vitest';
+import { AuthManager } from './auth-manager';
+import type { AuthManagerOptions } from './auth-manager';
+
+const managerWith = (basePath?: unknown) =>
+  new AuthManager({ ...(basePath === undefined ? {} : { basePath }) } as unknown as AuthManagerOptions);
+
+describe('#16025 AuthManager.getBasePath', () => {
+  it('is a public member — the surface @objectstack/hono reads by name', () => {
+    expect(typeof managerWith().getBasePath).toBe('function');
+  });
+
+  it('defaults to the shipped base path when nothing is configured', () => {
+    expect(managerWith().getBasePath()).toBe('/api/v1/auth');
+  });
+
+  it('answers the CONFIGURED base path, which is the point of asking', () => {
+    expect(managerWith('/api/v9/identity').getBasePath()).toBe('/api/v9/identity');
+  });
+
+  it('normalises the spellings that used to reach better-auth and the ownership walk differently', () => {
+    // Before this method there were two normalising sites and they disagreed:
+    // a configured `api/v1/auth` reached better-auth WITHOUT its leading slash
+    // while `betterAuthEndpointPath` tested against `/api/v1/auth`.
+    expect(managerWith('api/v1/auth').getBasePath()).toBe('/api/v1/auth');
+    expect(managerWith('/api/v1/auth/').getBasePath()).toBe('/api/v1/auth');
+    expect(managerWith('/api/v1/auth///').getBasePath()).toBe('/api/v1/auth');
+    expect(managerWith('api/v1/auth/').getBasePath()).toBe('/api/v1/auth');
+  });
+
+  it('treats an empty configured value as unset, exactly as the pre-#16025 readers did', () => {
+    expect(managerWith('').getBasePath()).toBe('/api/v1/auth');
+  });
+
+  it('leaves a configured root as the empty base — unchanged behaviour, pinned so it is a decision', () => {
+    // `'/'` normalises to `''`, which is what `betterAuthEndpointPath` has
+    // always computed for it. The hono adapter rejects that answer as unusable
+    // and keeps its previous mount rather than mounting at the app root.
+    expect(managerWith('/').getBasePath()).toBe('');
+  });
+});

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

@@ -1249,7 +1249,7 @@ export class AuthManager {
       // bare host) so the reset-password / verify-email / magic-link URLs
       // better-auth derives from baseURL are always clickable links.
       baseURL: this.getCanonicalOrigin(),
-      basePath: this.config.basePath || '/api/v1/auth',
+      basePath: this.getBasePath(),
 
       // Database adapter configuration
       database: this.createDatabaseConfig(),
@@ -5445,6 +5445,40 @@ export class AuthManager {
     return response;
   }
 
+  /**
+   * [#16025] The path prefix better-auth matches its routes under — the SAME
+   * string this manager hands better-auth as its `basePath`, normalised once.
+   *
+   * ## Why this is public, and why it is the ONLY definition
+   *
+   * An HTTP adapter that mounts this service has to know where its routes
+   * live, and until this method existed it could not ask: `config` is private
+   * and nothing else exposed the value. `@objectstack/hono`'s `createHonoApp`
+   * therefore mounted the auth surface under its OWN `prefix` option, whose
+   * default (`/api`) does not compose with this one (`/api/v1/auth`), so on
+   * the documented embed better-auth was never reached at all — measured, on a
+   * real boot:
+   *
+   *     POST /api/auth/sign-in/email  (valid shape, wrong password)  ->  200 {}
+   *     POST /api/v1/auth/delete-user                                ->  401 {"message":"Unauthorized","code":"UNAUTHORIZED"}
+   *
+   * ⛔ The value must not be re-derived by any caller, here or in an adapter.
+   * Two readers already existed inside this file — the `basePath` handed to
+   * better-auth and `betterAuthEndpointPath`'s own normalising copy — and they
+   * normalised DIFFERENTLY: a configured `'api/v1/auth'` reached better-auth
+   * without its leading slash while the ownership walk tested against
+   * `'/api/v1/auth'`. Both now read this method, so "where better-auth serves"
+   * has one answer by construction rather than by three sites agreeing.
+   *
+   * Normalisation is exactly what `betterAuthEndpointPath` always applied: a
+   * leading slash is added when absent, trailing slashes are stripped. A
+   * configured `'/'` still normalises to `''`, unchanged from before.
+   */
+  getBasePath(): string {
+    const configured = this.config.basePath || '/api/v1/auth';
+    return (configured.startsWith('/') ? configured : `/${configured}`).replace(/\/+$/, '');
+  }
+
   /**
    * [#15417] Does better-auth ROUTE this request — i.e. is the path one its own
    * router owns, whatever it then answers?
@@ -5499,8 +5533,7 @@ export class AuthManager {
     } catch {
       return undefined;
     }
-    const configured = this.config.basePath || '/api/v1/auth';
-    const base = (configured.startsWith('/') ? configured : `/${configured}`).replace(/\/+$/, '');
+    const base = this.getBasePath();
     if (!pathname.startsWith(base)) return undefined;
     const endpoint = pathname.slice(base.length).replace(/\/+$/, '');
     return endpoint.startsWith('/') ? endpoint : undefined;