Auto-detect auth baseUrl at runtime

Detect and apply the actual server port for the Auth plugin at runtime.

- Add optional getPort() to IHttpServer so code can query the bound port.
- Add AuthManager.setRuntimeBaseUrl(url) to allow updating baseUrl before the auth instance is created; emits a warning and is a no-op if called after initialization.
- Update AuthPlugin to auto-detect the server port (when available) and call setRuntimeBaseUrl if the configured origin differs from the actual server URL; logs the update.
- Add unit tests covering setRuntimeBaseUrl behavior and the plugin's auto-detection logic.
- Tweak objectstack.config.ts comment to note baseUrl is auto-detected at runtime.

These changes ensure the auth instance uses the real server URL (useful when the runtime port differs from config) while preserving backward compatibility and emitting a warning if runtime updates are attempted after initialization.

Author: hotlong

objectstack.config.ts

@@ -32,7 +32,7 @@ export default defineStack({
     }),
     new AuthPlugin({
       secret: 'dev-secret-please-change-in-production-min-32-chars',
-      baseUrl: 'http://localhost:3000',
+      // baseUrl is auto-detected from the running server port at runtime.
       // Optional: Enable OAuth providers
       // providers: [
       //   {

packages/core/src/contracts/http-server.ts

@@ -135,6 +135,13 @@ export interface IHttpServer {
      * @returns Promise that resolves when server is ready
      */
     listen(port: number): Promise<void>;
+
+    /**
+     * Get the port the server is listening on.
+     * Returns the actual bound port after `listen()` resolves, or the
+     * configured port before that.
+     */
+    getPort?(): number;
 
     /**
      * Stop the HTTP server

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

@@ -472,6 +472,73 @@ describe('AuthManager', () => {
     });
   });
 
+  describe('setRuntimeBaseUrl', () => {
+    it('should update baseURL before auth instance is created', () => {
+      let capturedConfig: any;
+      (betterAuth as any).mockImplementation((config: any) => {
+        capturedConfig = config;
+        return { handler: vi.fn(), api: {} };
+      });
+
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const manager = new AuthManager({
+        secret: 'test-secret-at-least-32-chars-long',
+        baseUrl: 'http://localhost:3000',
+      });
+
+      manager.setRuntimeBaseUrl('http://localhost:3002');
+      manager.getAuthInstance();
+      warnSpy.mockRestore();
+
+      expect(capturedConfig.baseURL).toBe('http://localhost:3002');
+    });
+
+    it('should be a no-op and warn when called after auth instance is created', () => {
+      let capturedConfig: any;
+      (betterAuth as any).mockImplementation((config: any) => {
+        capturedConfig = config;
+        return { handler: vi.fn(), api: {} };
+      });
+
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const manager = new AuthManager({
+        secret: 'test-secret-at-least-32-chars-long',
+        baseUrl: 'http://localhost:3000',
+      });
+
+      // Force auth instance creation
+      manager.getAuthInstance();
+      expect(capturedConfig.baseURL).toBe('http://localhost:3000');
+
+      // Now try to change — should warn and not affect the already-created instance
+      manager.setRuntimeBaseUrl('http://localhost:4000');
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('setRuntimeBaseUrl() called after the auth instance was already created'),
+      );
+      warnSpy.mockRestore();
+    });
+
+    it('should override the default fallback (localhost:3000) when no baseUrl was configured', () => {
+      let capturedConfig: any;
+      (betterAuth as any).mockImplementation((config: any) => {
+        capturedConfig = config;
+        return { handler: vi.fn(), api: {} };
+      });
+
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const manager = new AuthManager({
+        secret: 'test-secret-at-least-32-chars-long',
+      });
+
+      manager.setRuntimeBaseUrl('http://localhost:3002');
+      manager.getAuthInstance();
+      warnSpy.mockRestore();
+
+      expect(capturedConfig.baseURL).toBe('http://localhost:3002');
+    });
+  });
+
   describe('socialProviders passthrough', () => {
     it('should forward socialProviders to betterAuth when provided', () => {
       let capturedConfig: any;

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

@@ -272,6 +272,27 @@ export class AuthManager {
     return envSecret;
   }
 
+  /**
+   * Update the base URL at runtime.
+   *
+   * This **must** be called before the first request triggers lazy
+   * initialisation of the better-auth instance — typically from a
+   * `kernel:ready` hook where the actual server port is known.
+   *
+   * If the auth instance has already been created this is a no-op and
+   * a warning is emitted.
+   */
+  setRuntimeBaseUrl(url: string): void {
+    if (this.auth) {
+      console.warn(
+        '[AuthManager] setRuntimeBaseUrl() called after the auth instance was already created — ignoring. ' +
+        'Ensure this method is called before the first request.',
+      );
+      return;
+    }
+    this.config = { ...this.config, baseUrl: url };
+  }
+
   /**
    * Get the underlying better-auth instance
    * Useful for advanced use cases

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

@@ -265,6 +265,95 @@ describe('AuthPlugin', () => {
       // Should NOT throw
     });
 
+    it('should auto-detect baseUrl from http-server port when port differs', async () => {
+      const mockRawApp = { all: vi.fn() };
+      const mockHttpServer = {
+        post: vi.fn(), get: vi.fn(), put: vi.fn(), delete: vi.fn(),
+        patch: vi.fn(), use: vi.fn(),
+        getRawApp: vi.fn(() => mockRawApp),
+        getPort: vi.fn(() => 3002),
+      };
+
+      mockContext.getService = vi.fn((name: string) => {
+        if (name === 'http-server') return mockHttpServer;
+        throw new Error(`Service not found: ${name}`);
+      });
+
+      // AuthPlugin configured with default port 3000, but server will be on 3002
+      const registeredAuthManager = (mockContext.registerService as any).mock.calls[0][1];
+      const setRuntimeSpy = vi.spyOn(registeredAuthManager, 'setRuntimeBaseUrl');
+
+      await authPlugin.start(mockContext);
+      await hookCapture.trigger('kernel:ready');
+
+      expect(setRuntimeSpy).toHaveBeenCalledWith('http://localhost:3002');
+      expect(mockContext.logger.info).toHaveBeenCalledWith(
+        expect.stringContaining('Auth baseUrl auto-updated to http://localhost:3002'),
+      );
+    });
+
+    it('should NOT update baseUrl when port matches configured value', async () => {
+      const localHookCapture = createHookCapture();
+      const localPlugin = new AuthPlugin({
+        secret: 'test-secret-at-least-32-chars-long',
+        baseUrl: 'http://localhost:3000',
+      });
+      mockContext.hook = localHookCapture.hookFn;
+      await localPlugin.init(mockContext);
+
+      const mockRawApp = { all: vi.fn() };
+      const mockHttpServer = {
+        post: vi.fn(), get: vi.fn(), put: vi.fn(), delete: vi.fn(),
+        patch: vi.fn(), use: vi.fn(),
+        getRawApp: vi.fn(() => mockRawApp),
+        getPort: vi.fn(() => 3000),
+      };
+
+      mockContext.getService = vi.fn((name: string) => {
+        if (name === 'http-server') return mockHttpServer;
+        throw new Error(`Service not found: ${name}`);
+      });
+
+      const registeredAuthManager = (mockContext.registerService as any).mock.calls.at(-1)[1];
+      const setRuntimeSpy = vi.spyOn(registeredAuthManager, 'setRuntimeBaseUrl');
+
+      await localPlugin.start(mockContext);
+      await localHookCapture.trigger('kernel:ready');
+
+      expect(setRuntimeSpy).not.toHaveBeenCalled();
+    });
+
+    it('should auto-detect baseUrl when no baseUrl configured (uses default fallback)', async () => {
+      const localHookCapture = createHookCapture();
+      // No baseUrl — defaults to http://localhost:3000 internally
+      const localPlugin = new AuthPlugin({
+        secret: 'test-secret-at-least-32-chars-long',
+      });
+      mockContext.hook = localHookCapture.hookFn;
+      await localPlugin.init(mockContext);
+
+      const mockRawApp = { all: vi.fn() };
+      const mockHttpServer = {
+        post: vi.fn(), get: vi.fn(), put: vi.fn(), delete: vi.fn(),
+        patch: vi.fn(), use: vi.fn(),
+        getRawApp: vi.fn(() => mockRawApp),
+        getPort: vi.fn(() => 3002),
+      };
+
+      mockContext.getService = vi.fn((name: string) => {
+        if (name === 'http-server') return mockHttpServer;
+        throw new Error(`Service not found: ${name}`);
+      });
+
+      const registeredAuthManager = (mockContext.registerService as any).mock.calls.at(-1)[1];
+      const setRuntimeSpy = vi.spyOn(registeredAuthManager, 'setRuntimeBaseUrl');
+
+      await localPlugin.start(mockContext);
+      await localHookCapture.trigger('kernel:ready');
+
+      expect(setRuntimeSpy).toHaveBeenCalledWith('http://localhost:3002');
+    });
+
     it('should throw error if auth not initialized', async () => {
       const uninitializedPlugin = new AuthPlugin({
         secret: 'test-secret',

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

@@ -114,6 +114,27 @@ export class AuthPlugin implements Plugin {
         }
 
         if (httpServer) {
+          // Auto-detect the actual server URL when no explicit baseUrl was
+          // configured, or when the configured baseUrl uses a different port
+          // than the running server (e.g. port 3000 configured but 3002 bound).
+          // getPort() is optional on IHttpServer; duck-type check for it.
+          const serverWithPort = httpServer as IHttpServer & { getPort?: () => number };
+          if (this.authManager && typeof serverWithPort.getPort === 'function') {
+            const actualPort = serverWithPort.getPort();
+            if (actualPort) {
+              const configuredUrl = this.options.baseUrl || 'http://localhost:3000';
+              const configuredOrigin = new URL(configuredUrl).origin;
+              const actualUrl = `http://localhost:${actualPort}`;
+
+              if (configuredOrigin !== actualUrl) {
+                this.authManager.setRuntimeBaseUrl(actualUrl);
+                ctx.logger.info(
+                  `Auth baseUrl auto-updated to ${actualUrl} (configured: ${configuredUrl})`,
+                );
+              }
+            }
+          }
+
           // Route registration errors should propagate (server misconfiguration)
           this.registerAuthRoutes(httpServer, ctx);
           ctx.logger.info(`Auth routes registered at ${this.options.basePath}`);