refactor: address code review - use randomUUID, named constant, and improve JSDoc

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

Author: Copilot

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

@@ -27,6 +27,13 @@ export interface AuthPluginOptions extends Partial<AuthConfig> {
  * 
  * Provides authentication and identity services for ObjectStack applications.
  * 
+ * **Dual-Mode Operation:**
+ * - **Server mode** (HonoServerPlugin active): Registers HTTP routes at basePath,
+ *   forwarding all auth requests to better-auth's universal handler.
+ * - **MSW/Mock mode** (no HTTP server): Gracefully skips route registration but
+ *   still registers the `auth` service, allowing HttpDispatcher.handleAuth() to
+ *   simulate auth flows (sign-up, sign-in, etc.) for development and testing.
+ * 
  * Features:
  * - Session management
  * - User registration/login
@@ -35,8 +42,8 @@ export interface AuthPluginOptions extends Partial<AuthConfig> {
  * - 2FA, passkeys, magic links
  * 
  * This plugin registers:
- * - `auth` service (auth manager instance)
- * - HTTP routes for authentication endpoints
+ * - `auth` service (auth manager instance) — always
+ * - HTTP routes for authentication endpoints — only when HTTP server is available
  * 
  * Integrates with better-auth library to provide comprehensive
  * authentication capabilities including email/password, OAuth, 2FA,

packages/runtime/src/http-dispatcher.ts

@@ -2,6 +2,7 @@
 
 import { ObjectKernel, getEnv } from '@objectstack/core';
 import { CoreServiceName } from '@objectstack/spec/system';
+import { randomUUID } from 'crypto';
 
 export interface HttpProtocolContext {
     request: any;
@@ -202,32 +203,33 @@ export class HttpDispatcher {
      */
     private mockAuthFallback(path: string, method: string, body: any): HttpDispatcherResult {
         const m = method.toUpperCase();
+        const MOCK_SESSION_EXPIRY_MS = 86_400_000; // 24 hours
 
         // POST sign-up/email
         if ((path === 'sign-up/email' || path === 'register') && m === 'POST') {
-            const id = `mock_${Date.now()}`;
+            const id = `mock_${randomUUID()}`;
             return {
                 handled: true,
                 response: {
                     status: 200,
                     body: {
                         user: { id, name: body?.name || 'Mock User', email: body?.email || 'mock@test.local', emailVerified: false, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString() },
-                        session: { id: `session_${id}`, userId: id, token: `mock_token_${id}`, expiresAt: new Date(Date.now() + 86400000).toISOString() },
+                        session: { id: `session_${id}`, userId: id, token: `mock_token_${id}`, expiresAt: new Date(Date.now() + MOCK_SESSION_EXPIRY_MS).toISOString() },
                     },
                 },
             };
         }
 
         // POST sign-in/email or login
         if ((path === 'sign-in/email' || path === 'login') && m === 'POST') {
-            const id = `mock_${Date.now()}`;
+            const id = `mock_${randomUUID()}`;
             return {
                 handled: true,
                 response: {
                     status: 200,
                     body: {
                         user: { id, name: 'Mock User', email: body?.email || 'mock@test.local', emailVerified: true, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString() },
-                        session: { id: `session_${id}`, userId: id, token: `mock_token_${id}`, expiresAt: new Date(Date.now() + 86400000).toISOString() },
+                        session: { id: `session_${id}`, userId: id, token: `mock_token_${id}`, expiresAt: new Date(Date.now() + MOCK_SESSION_EXPIRY_MS).toISOString() },
                     },
                 },
             };