Frontend changes to enable faster upstream to internal repo

frontends/ui/.env.example

@@ -36,6 +36,17 @@
 # Optional: Explicit cookie security override (rarely needed)
 # SECURE_COOKIES=true
 
+# Session and token lifetime tuning (optional)
+#
+# Session max age in hours (applies to both NextAuth session and idToken cookie).
+# Default: 24. Both MUST stay aligned to prevent stale-credential bugs.
+# SESSION_MAX_AGE_HOURS=24
+#
+# Minutes before token expiry to trigger proactive refresh.
+# Default: 5. For deployments with long-running jobs (deep research runs
+# 20-40+ minutes), set to 30 to prevent mid-job 401 errors.
+# TOKEN_REFRESH_BUFFER_MINUTES=5
+
 # =============================================================================
 # OAuth Provider (required when REQUIRE_AUTH=true)
 # =============================================================================

frontends/ui/README.md

@@ -297,20 +297,16 @@ All environment variables are **runtime configurable** - no container rebuild ne
 | `REQUIRE_AUTH` | `false` | Set to `true` to require OAuth login |
 | `NEXTAUTH_SECRET` | - | Session encryption secret (required if auth enabled) |
 | `NEXTAUTH_URL` | - | Public URL where app is hosted (required if auth enabled) |
+| `SESSION_MAX_AGE_HOURS` | `24` | Session and idToken cookie lifetime in hours |
+| `TOKEN_REFRESH_BUFFER_MINUTES` | `5` | Minutes before token expiry to trigger refresh (set to 30 for long-running jobs) |
 
 > **Cookie Security:** `NEXTAUTH_URL` determines cookie security:
 > - `http://...` -> non-secure cookies (local dev over HTTP)
 > - `https://...` -> secure cookies (production over HTTPS)
 
 ### OAuth (required when `REQUIRE_AUTH=true`)
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `OAUTH_CLIENT_ID` | - | OAuth client ID from your OIDC provider |
-| `OAUTH_CLIENT_SECRET` | - | OAuth client secret |
-| `OAUTH_ISSUER` | - | OIDC issuer URL (enables auto-discovery of endpoints) |
-
-> **Note:** When `OAUTH_ISSUER` is set, the app uses OIDC auto-discovery to resolve authorization, token, and userinfo endpoints automatically. No additional endpoint URLs are needed for standard OIDC providers.
+Provider-specific env vars depend on your provider implementation. See `src/adapters/auth/providers/auth-example.ts` for a template/checklist and the [Authentication](#authentication) section for setup steps.
 
 
 ## API Communication
@@ -325,7 +321,7 @@ OpenAI-compatible chat completions via `/chat/stream`:
 import { streamChat } from '@/adapters/api'
 
 await streamChat(
-  { messages, sessionId, workflowId },
+  { messages, sessionId },
   {
     onChunk: (content) => console.log(content),
     onComplete: () => console.log('Done'),
@@ -343,7 +339,6 @@ import { createWebSocketClient } from '@/adapters/api'
 
 const ws = createWebSocketClient({
   sessionId: 'abc123',
-  workflowId: 'researcher',
   callbacks: {
     onAgentText: (content, isFinal) => {},
     onStatus: (status, message) => {},
@@ -358,23 +353,133 @@ ws.sendMessage('Hello!')
 
 ## Authentication
 
-Authentication is **disabled by default**. All users are assigned a "Default User" identity with no login required.
+Authentication is **disabled by default**. All users are assigned a "Default User" identity with no login required. The auth system uses a **plugin architecture** where `src/adapters/auth/providers/index.ts` is the sole file that controls whether auth is enabled and which provider is active.
+
+### Architecture
+
+```
+src/adapters/auth/
+├── providers/
+│   ├── types.ts           # AuthProviderConfig interface (contract)
+│   ├── index.ts           # SWAP-POINT: returns null (disabled) or a real provider
+│   └── auth-example.ts    # Provider template/checklist (not imported by default)
+├── config.ts              # NextAuth config (provider-agnostic, never needs editing)
+├── session.ts             # useAuth() hook (provider-agnostic)
+├── types.ts               # NextAuth type extensions
+└── index.ts               # Re-exports
+```
+
+- `providers/index.ts` exports `getAuthProviderConfig()` which returns the active provider configuration. By default it returns `{ provider: null }` (auth disabled).
+- `config.ts` imports from `providers/index.ts` and wires the provider into NextAuth. It never needs to be edited when adding a new provider.
+- `session.ts` provides the `useAuth()` hook that components use. It reads `authProviderId` from `AppConfig` and adapts dynamically.
+
+### Provider Contract
+
+Every auth provider must conform to the `AuthProviderConfig` interface defined in `providers/types.ts`:
+
+```typescript
+interface AuthProviderConfig {
+  provider: Record<string, unknown> | null  // NextAuth-compatible provider object, or null
+  providerId: string                        // ID used in signIn(providerId) -- must match provider.id
+  refreshToken: (refreshToken: string) => Promise<TokenRefreshResult>
+}
+
+interface TokenRefreshResult {
+  access_token: string
+  id_token?: string
+  expires_in: number
+  refresh_token?: string
+}
+```
+
+### Enabling Authentication (step-by-step)
+
+To enable OAuth/OIDC authentication, follow these steps:
+
+#### Step 1: Create a provider file
+
+Create a new file in `src/adapters/auth/providers/` (e.g. `my-sso.ts`). See `auth-example.ts` in the same directory for a template/checklist. Your file should export:
+
+1. A NextAuth-compatible provider object (OAuth/OIDC config)
+2. A token refresh function matching the `TokenRefreshResult` return type
+
+Example minimal provider:
 
-To enable OAuth authentication:
+```typescript
+// src/adapters/auth/providers/my-sso.ts
+import type { TokenRefreshResult } from './types'
+
+export const MySSOProvider = {
+  id: 'my-sso',
+  name: 'My SSO',
+  type: 'oauth' as const,
+  wellKnown: `${process.env.MY_SSO_ISSUER}/.well-known/openid-configuration`,
+  authorization: {
+    params: { scope: 'openid profile email', response_type: 'code' },
+  },
+  clientId: process.env.MY_SSO_CLIENT_ID,
+  clientSecret: process.env.MY_SSO_CLIENT_SECRET || '',
+  checks: ['pkce', 'state'] as ('pkce' | 'state' | 'nonce')[],
+  idToken: true,
+  profile(profile: { sub: string; email: string; name: string; picture?: string }) {
+    return { id: profile.sub, email: profile.email, name: profile.name, image: profile.picture }
+  },
+}
+
+export const refreshMySSOToken = async (refreshToken: string): Promise<TokenRefreshResult> => {
+  const response = await fetch(process.env.MY_SSO_TOKEN_URL!, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+      grant_type: 'refresh_token',
+      refresh_token: refreshToken,
+      client_id: process.env.MY_SSO_CLIENT_ID || '',
+    }),
+  })
+  const tokens = await response.json()
+  if (!response.ok) throw tokens
+  return tokens
+}
+```
+
+#### Step 2: Wire it into providers/index.ts
+
+Replace the default `getAuthProviderConfig()` to return your provider:
+
+```typescript
+// src/adapters/auth/providers/index.ts
+import type { AuthProviderConfig } from './types'
+import { MySSOProvider, refreshMySSOToken } from './my-sso'
+
+export type { AuthProviderConfig, TokenRefreshResult } from './types'
+
+export const getAuthProviderConfig = (): AuthProviderConfig => ({
+  provider: MySSOProvider,
+  providerId: 'my-sso',
+  refreshToken: refreshMySSOToken,
+})
+```
 
-1. Set `REQUIRE_AUTH=true`
-2. Configure your OIDC provider credentials:
+#### Step 3: Set environment variables
 
 ```bash
-# .env
 REQUIRE_AUTH=true
 NEXTAUTH_SECRET=<generate-with-openssl-rand-base64-32>
 NEXTAUTH_URL=http://localhost:3000
-OAUTH_CLIENT_ID=<your-client-id>
-OAUTH_CLIENT_SECRET=<your-client-secret>
-OAUTH_ISSUER=<your-oidc-issuer-url>
+
+# Provider-specific (names depend on your provider file)
+MY_SSO_ISSUER=https://sso.example.com
+MY_SSO_CLIENT_ID=<your-client-id>
+MY_SSO_CLIENT_SECRET=<your-client-secret>
+MY_SSO_TOKEN_URL=https://sso.example.com/token
 ```
 
+That's it. No other files need to change -- `config.ts`, `session.ts`, `proxy.ts`, and all components automatically adapt to the new provider via `getAuthProviderConfig()`.
+
+### Disabling Authentication
+
+To disable auth (the default), ensure `providers/index.ts` returns `{ provider: null }` and either unset `REQUIRE_AUTH` or set `REQUIRE_AUTH=false`. The app will use a "Default User" identity with no login required.
+
 ### Using the Auth Hook
 
 ```typescript
@@ -386,16 +491,11 @@ const MyComponent = () => {
   if (isLoading) return <Spinner />
   if (!isAuthenticated) return <Button onClick={signIn}>Sign In</Button>
 
-  // Use idToken for backend API calls
-  await fetch('/api/data', {
-    headers: { 'Authorization': `Bearer ${idToken}` }
-  })
-
   return <Text>Welcome, {user?.name}</Text>
 }
 ```
 
->**NOTE:** Above Authentication docs are reference only and implementation depends on environment specifics.
+When auth is disabled, `useAuth()` returns `isAuthenticated: true` with a default user -- no sign-in flow is triggered.
 
 
 ## Development

frontends/ui/config/vitest/mocks/server-only.ts

@@ -0,0 +1,2 @@
+// Test-only shim for Next.js server boundary marker.
+export {}

frontends/ui/server.js

@@ -119,7 +119,14 @@ const startServer = async () => {
     req.socket.setKeepAlive?.(true, 15000)
     req.socket.setTimeout?.(0)
 
-    const parsedUrl = parse(req.url, true)
+    let parsedUrl
+    try {
+      parsedUrl = parse(req.url, true)
+    } catch {
+      res.writeHead(400, { 'Content-Type': 'text/plain' })
+      res.end('Bad Request')
+      return
+    }
 
     if (dev) {
       // Development: proxy everything to Next.js dev server
@@ -141,7 +148,13 @@ const startServer = async () => {
     socket.setKeepAlive?.(true, 15000)
     socket.setTimeout?.(0)
 
-    const parsedUrl = parse(req.url, true)
+    let parsedUrl
+    try {
+      parsedUrl = parse(req.url, true)
+    } catch {
+      socket.destroy()
+      return
+    }
     const pathname = parsedUrl.pathname || '/'
 
     // Proxy /websocket to backend

frontends/ui/src/adapters/api/chat-client.ts

@@ -19,7 +19,6 @@ import {
 
 export interface StreamChatOptions {
   messages: Message[]
-  workflowId?: string
   sessionId?: string
   model?: string
   temperature?: number
@@ -45,14 +44,13 @@ export const streamChat = async (
   options: StreamChatOptions,
   callbacks: StreamCallbacks
 ): Promise<void> => {
-  const { messages, workflowId, sessionId, model, temperature, maxTokens, signal, authToken } =
+  const { messages, sessionId, model, temperature, maxTokens, signal, authToken } =
     options
   const { onChunk, onComplete, onError } = callbacks
 
   const requestBody: ChatCompletionRequest = {
     messages,
     stream: true,
-    workflow_id: workflowId,
     session_id: sessionId,
     model,
     temperature,
@@ -221,8 +219,6 @@ export interface GenerateStreamMessage {
 export interface StreamGenerateOptions {
   /** User's input message */
   inputMessage: string
-  /** Workflow ID for the backend */
-  workflowId?: string
   /** Session ID for conversation tracking */
   sessionId?: string
   /** Abort signal */
@@ -299,12 +295,11 @@ export const streamGenerate = async (
   options: StreamGenerateOptions,
   callbacks: GenerateStreamCallbacks
 ): Promise<void> => {
-  const { inputMessage, workflowId, sessionId, signal, authToken } = options
+  const { inputMessage, sessionId, signal, authToken } = options
   const { onThinking, onStatus, onPrompt, onReport, onComplete, onError } = callbacks
 
   const requestBody = {
     input_message: inputMessage,
-    workflow_id: workflowId,
     session_id: sessionId,
     stream: true,
   }

frontends/ui/src/adapters/api/schemas.ts

@@ -26,7 +26,6 @@ export const ChatCompletionRequestSchema = z.object({
   temperature: z.number().optional(),
   max_tokens: z.number().optional(),
   stream: z.boolean().optional(),
-  workflow_id: z.string().optional(),
   session_id: z.string().optional(),
 })
 
@@ -256,7 +255,6 @@ export const NATIncomingMessageSchema = z.discriminatedUnion('type', [
 export const WebSocketConnectMessageSchema = z.object({
   type: z.literal('connect'),
   session_id: z.string(),
-  workflow_id: z.string(),
   /** Auth token for backend authentication */
   auth_token: z.string().optional(),
 })