fix: address all review comments — browser-safe UUID, selective error handling, fix Studio build, update docs

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

apps/studio/package.json

@@ -22,7 +22,6 @@
     "@objectstack/driver-memory": "workspace:*",
     "@objectstack/metadata": "workspace:*",
     "@objectstack/objectql": "workspace:*",
-    "@objectstack/plugin-auth": "workspace:*",
     "@objectstack/plugin-msw": "workspace:*",
     "@objectstack/runtime": "workspace:*",
     "@objectstack/spec": "workspace:*",

apps/studio/src/mocks/createKernel.ts

@@ -4,7 +4,6 @@ import { ObjectKernel, DriverPlugin, AppPlugin } from '@objectstack/runtime';
 import { ObjectQLPlugin, SchemaRegistry } from '@objectstack/objectql';
 import { InMemoryDriver } from '@objectstack/driver-memory';
 import { MSWPlugin } from '@objectstack/plugin-msw';
-import { AuthPlugin } from '@objectstack/plugin-auth';
 
 export interface KernelOptions {
     appConfigs?: any[];      // Multiple app configs
@@ -43,13 +42,6 @@ export async function createKernel(options: KernelOptions) {
     // ObjectQLPlugin's ctx.registerService('protocol', ...) during bootstrap.
     console.log('[KernelFactory] Protocol service will be registered by ObjectQLPlugin');
 
-    // Register AuthPlugin for MSW/mock mode (gracefully skips HTTP route registration)
-    // WARNING: This secret is for local development only — never use in production
-    await kernel.use(new AuthPlugin({
-        secret: 'INSECURE_DEV_ONLY_mock_secret_do_not_use_in_production',
-        baseUrl: 'http://localhost:5173',
-    }));
-
     // --- BROKER SHIM (MUST be registered BEFORE MSWPlugin) ---
     // HttpDispatcher requires a broker to function. We inject a shim.
     (kernel as any).broker = {

content/docs/guides/authentication.mdx

@@ -626,7 +626,7 @@ await kernel.bootstrap();
 
 ### Mock Fallback Endpoints
 
-When no auth service handler or broker is available, `HttpDispatcher.handleAuth()` automatically provides mock responses for:
+When no auth service handler is registered and the legacy broker login is unavailable, `HttpDispatcher.handleAuth()` automatically provides mock responses for:
 
 | Endpoint | Method | Description |
 |:---|:---:|:---|
@@ -639,17 +639,21 @@ When no auth service handler or broker is available, `HttpDispatcher.handleAuth(
 
 This ensures that registration and sign-in flows do not return 404 errors in MSW/browser-only environments.
 
+> **Note:** In server mode with AuthPlugin loaded, the auth service handler takes priority and the mock fallback is never reached. The mock fallback only activates when AuthPlugin is not loaded (e.g. browser-only Studio builds where `better-auth` is unavailable).
+
 ### Studio Kernel Factory
 
-The Studio app's `createKernel()` factory includes AuthPlugin by default:
+The Studio app runs in the browser, where the Node-only `better-auth` library cannot be bundled. Instead of loading `AuthPlugin` directly, Studio relies on `HttpDispatcher`'s built-in mock fallback to handle auth endpoints in MSW mode:
 
 ```typescript
 // apps/studio/src/mocks/createKernel.ts
-// WARNING: This secret is for local development only
-await kernel.use(new AuthPlugin({
-  secret: 'INSECURE_DEV_ONLY_mock_secret_do_not_use_in_production',
-  baseUrl: 'http://localhost:5173',
-}));
+// No AuthPlugin needed — HttpDispatcher provides mock auth endpoints automatically
+const kernel = new ObjectKernel();
+await kernel.use(new ObjectQLPlugin());
+await kernel.use(new DriverPlugin(driver, 'memory'));
+// ...
+await kernel.use(new MSWPlugin({ /* ... */ }));
+await kernel.bootstrap();
 ```
 
 ---

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

@@ -169,8 +169,7 @@ describe('AuthPlugin', () => {
       await authPlugin.start(mockContext);
 
       expect(mockContext.logger.warn).toHaveBeenCalledWith(
-        expect.stringContaining('HTTP server not available'),
-        expect.any(String)
+        expect.stringContaining('No HTTP server available')
       );
       // Should NOT throw
     });

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

@@ -101,21 +101,22 @@ export class AuthPlugin implements Plugin {
 
     // Register HTTP routes if enabled and HTTP server is available
     if (this.options.registerRoutes) {
+      let httpServer: IHttpServer | null = null;
       try {
-        const httpServer = ctx.getService<IHttpServer>('http-server');
-        if (httpServer) {
-          this.registerAuthRoutes(httpServer, ctx);
-          ctx.logger.info(`Auth routes registered at ${this.options.basePath}`);
-        } else {
-          ctx.logger.warn(
-            'No HTTP server available — auth routes not registered. ' +
-            'Auth service is still available for MSW/mock environments via HttpDispatcher.'
-          );
-        }
-      } catch (error) {
-        // Gracefully handle missing HTTP server (e.g. MSW/mock mode)
-        const err = error instanceof Error ? error : new Error(String(error));
-        ctx.logger.warn('HTTP server not available, skipping auth route registration', { error: err.message });
+        httpServer = ctx.getService<IHttpServer>('http-server');
+      } catch {
+        // Service not found — expected in MSW/mock mode
+      }
+
+      if (httpServer) {
+        // Route registration errors should propagate (server misconfiguration)
+        this.registerAuthRoutes(httpServer, ctx);
+        ctx.logger.info(`Auth routes registered at ${this.options.basePath}`);
+      } else {
+        ctx.logger.warn(
+          'No HTTP server available — auth routes not registered. ' +
+          'Auth service is still available for MSW/mock environments via HttpDispatcher.'
+        );
       }
     }
 

packages/runtime/src/http-dispatcher.ts

@@ -2,7 +2,19 @@
 
 import { ObjectKernel, getEnv } from '@objectstack/core';
 import { CoreServiceName } from '@objectstack/spec/system';
-import { randomUUID } from 'crypto';
+
+/** Browser-safe UUID generator — prefers Web Crypto, falls back to RFC 4122 v4 */
+function randomUUID(): string {
+    const cryptoObj = typeof globalThis !== 'undefined' ? (globalThis as any).crypto : undefined;
+    if (cryptoObj && typeof cryptoObj.randomUUID === 'function') {
+        return cryptoObj.randomUUID();
+    }
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, c => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
 
 export interface HttpProtocolContext {
     request: any;
@@ -187,8 +199,20 @@ export class HttpDispatcher {
                 const broker = this.ensureBroker();
                 const data = await broker.call('auth.login', body, { request: context.request });
                 return { handled: true, response: { status: 200, body: data } };
-            } catch {
-                // Broker not available — fall through to mock fallback
+            } catch (error: any) {
+                // Only fall through to mock when the broker is truly unavailable.
+                const msg = error?.message || '';
+                const statusCode = error?.statusCode ?? error?.status;
+                const isBrokerUnavailable =
+                    msg.includes('not available') ||
+                    msg.includes('not found') ||
+                    msg.includes('not registered') ||
+                    statusCode === 503;
+
+                if (!isBrokerUnavailable) {
+                    // Propagate real auth failures so callers see the correct error
+                    throw error;
+                }
             }
         }