@eduwork/dsh-oidc 0.3.0-dev.2 → 0.3.0

package/lib/desktop-oidc.js

@@ -6,7 +6,7 @@ import { callbackLanguage, callbackPage } from './callback-page.js'
 const MAX_FLOWS = 32
 const MAX_HISTORY = 128
 const error = (code, message) => Object.assign(new Error(message), { code })
-const safeCodes = new Set(['oidc_callback_invalid', 'oidc_authorization_rejected', 'oidc_token_invalid', 'oidc_id_token_invalid', 'oidc_userinfo_invalid', 'gateway_token_invalid', 'gateway_scope_changed', 'gateway_identity_changed', 'gateway_callback_issuer_missing', 'gateway_callback_issuer_invalid'])
+const safeCodes = new Set(['oidc_id_token_time_invalid', 'oidc_callback_invalid', 'oidc_authorization_rejected', 'oidc_token_invalid', 'oidc_id_token_invalid', 'oidc_userinfo_invalid', 'gateway_token_invalid', 'gateway_scope_changed', 'gateway_identity_changed', 'gateway_callback_issuer_missing', 'gateway_callback_issuer_invalid'])
 
 function reply(response, status, profile, outcome, language) {
   const page = callbackPage(profile, outcome, language)
@@ -138,7 +138,7 @@ export class DesktopOidcBackend extends WebOidcBackend {
       this.ctx.logger.warn('Desktop OIDC host credentials are unavailable')
     })
     await attempt.processing
-    const failedOutcome = ['gateway_callback_issuer_missing', 'gateway_callback_issuer_invalid'].includes(attempt.errorCode) ? 'issuer-invalid' : 'failed'
+    const failedOutcome = ['gateway_callback_issuer_missing', 'gateway_callback_issuer_invalid'].includes(attempt.errorCode) ? 'issuer-invalid' : attempt.errorCode === 'oidc_id_token_time_invalid' ? 'time-invalid' : 'failed'
     if (!response.destroyed) reply(response, attempt.state === 'completed' ? 200 : 400, profile,
       attempt.state === 'completed' ? 'completed' : failedOutcome, language)
     await this.closeCallback(attempt)

package/lib/gateway-backend.js

@@ -6,6 +6,7 @@ import { gatewayJSON, liteLLMToken, protocolError, readGatewayJSON, registerLite
 import { detectGatewayProtocol } from './gateway-protocol.js'
 import { oidcLlmIdentity, oidcLlmToken } from './oidc-llm-protocol.js'
 import { bufferResourceResponse, validateResourceRead } from './model-resource-transport.js'
+import { accessTokenNeedsRefresh } from './token-lifetime.js'
 
 const seconds = backend => Math.floor(backend.now() / 1000)
 const fingerprint = (profile, descriptor) => createHash('sha256').update(JSON.stringify({ auth: profile.auth, descriptor })).digest('hex')
@@ -266,7 +267,7 @@ function withGatewayAuth(Base) {
       const epoch = this.accountEpoch(profile)
       const session = await this.loadSession(profile)
       if (!session) return undefined
-      if (session.expiresAt > seconds(this) + 90) return session
+      if (!accessTokenNeedsRefresh(session, this.now)) return session
       try { return await this.refresh(profile, session) }
       catch (cause) {
         // Brief outages must not discard a still-valid access token; expired tokens stop.
@@ -314,14 +315,26 @@ function withGatewayAuth(Base) {
       return account(profile, session, true, 'access_token')
     }
 
-    async authorizedFetch(profileID, endpoint, init = {}) {
+    async authorizedFetch(profileID, endpoint, init = {}, authorization = {}) {
+      const retryUnauthorized = authorization.retryUnauthorized === true
+      if (retryUnauthorized && init.body != null && typeof init.body !== 'string') throw new TypeError('Authorization retry requires a buffered text request body')
       const profile = this.profile(profileID)
       if (!profile.auth) return super.authorizedFetch(profileID, endpoint, init)
       const epoch = this.accountEpoch(profile), descriptor = await this.discover(profile)
       const target = new URL(endpoint)
       // Host-only model and own-account routes, never key administration or arbitrary origins.
       const modelBase = new URL(`${descriptor.baseURL}/`)
-      if (target.username || target.password || target.hash || target.origin !== modelBase.origin || !(target.href === descriptor.userInfoEndpoint || target.pathname.startsWith(modelBase.pathname))) throw protocolError('oidc_authorized_origin_denied', 'Gateway token destination is not an authorized resource')
+      // Trusted Host services can grant one exact issuer POST route for their
+      // own request. This option is never accepted through a renderer RPC or
+      // persisted as a broader model-resource allowlist.
+      const servicePath = authorization.issuerServicePath
+      const issuerService = typeof servicePath === 'string'
+        && /^\/(?:[a-zA-Z0-9_-]+\/)*[a-zA-Z0-9_-]+$/.test(servicePath)
+        && (init.method ?? 'GET').toUpperCase() === 'POST'
+        && target.href === new URL(descriptor.issuer).origin + servicePath
+      const modelResource = target.origin === modelBase.origin
+        && (target.href === descriptor.userInfoEndpoint || target.pathname.startsWith(modelBase.pathname))
+      if (target.username || target.password || target.hash || !(modelResource || issuerService)) throw protocolError('oidc_authorized_origin_denied', 'Gateway token destination is not an authorized resource')
       const scope = await this.createGatewayScope(profileID)
       const lease = scope.open(init.signal ?? AbortSignal.timeout(20_000))
       let response
@@ -331,8 +344,9 @@ function withGatewayAuth(Base) {
         if (!session) throw protocolError('oidc_login_required', 'Gateway sign-in is required')
         const request = current => this.fetch(target.href, { ...init, headers: { ...Object.fromEntries(new Headers(init.headers)), authorization: `Bearer ${current.accessToken}` }, redirect: 'error', signal: lease.signal })
         response = await request(session)
-        // Retry only safe reads. A generation (including SSE) is never replayed here.
-        if (response.status === 401 && ['GET', 'HEAD'].includes((init.method ?? 'GET').toUpperCase())) {
+        // Reads recover automatically. Trusted Host services may explicitly opt
+        // in for replayable calls; model generation does not opt in.
+        if (response.status === 401 && (retryUnauthorized || ['GET', 'HEAD'].includes((init.method ?? 'GET').toUpperCase()))) {
           await response.body?.cancel()
           session = await this.refresh(profile, session)
           lease.assertCurrent()
@@ -379,6 +393,7 @@ function withGatewayAuth(Base) {
         this.updateProvider(next)
         this.profiles.set(profileID, next)
         result.models = models
+        if (models.some(model => model.type === 'unknown')) result.issues.push('model_types_unresolved')
       } catch (cause) {
         if (cause.code === 'oidc_login_cancelled' || cause.code === 'oidc_login_required') throw cause
         result.issues.push('models_unavailable')

package/lib/index.js

@@ -45,7 +45,7 @@ export class OidcAccountService extends TypertRemoteService {
     })
     const backendOptions = {
           authorizedOrigins: config.authorizedOrigins,
-          accountChanged: status => this.notifyAccount(status),
+          accountChanged: status => this.notifyAccount(status, { force: true }),
           updateProvider: profile => {
             const profiles = new Map(this.profiles)
             profiles.set(profile.id, profile)
@@ -98,18 +98,20 @@ export class OidcAccountService extends TypertRemoteService {
     return { opened: true }
   }
 
-  notifyAccount(status) {
-    if (this.accountStates.get(status.profileID) !== status.state) {
+  notifyAccount(status, { force = false } = {}) {
+    // A completed sign-in replaces authorization even when both sessions are
+    // "connected". Consumers must reset work blocked by the previous session.
+    if (force || this.accountStates.get(status.profileID) !== status.state) {
       this.accountStates.set(status.profileID, status.state)
-      this.ctx.emit('oidc/accounts-changed', { profileID: status.profileID, state: status.state })
+      this.ctx.emit('oidc/accounts-changed', { profileID: status.profileID, state: status.state, ...(force ? { authorizationChanged: true } : {}) })
     }
     return status
   }
   async status(profileID) { return this.notifyAccount(await this.callBackend('status', profileID)) }
   resources(profileID) { return this.callBackend('resources', profileID) }
   // Host-only capability: deliberately absent from Remote markers and Typert.
-  authorizedFetch(profileID, endpoint, init) {
-    return this.callBackend('authorizedFetch', profileID, endpoint, init)
+  authorizedFetch(profileID, endpoint, init, authorization) {
+    return this.callBackend('authorizedFetch', profileID, endpoint, init, authorization)
   }
   modelResourceFetch(profileID, relativePath, options) {
     return this.callBackend('modelResourceFetch', profileID, relativePath, options)

package/lib/litellm-protocol.js

@@ -1,4 +1,5 @@
 import { serviceProtocolAllowed } from './transport.js'
+import { accessTokenTiming } from './token-lifetime.js'
 // LiteLLM v1.101.0, native CLI auth contract 1. This is OAuth, not OIDC.
 // Protocol-specific wire fields stay here; tokens never cross the renderer RPC.
 const MAX_BYTES = 1024 * 1024
@@ -99,7 +100,7 @@ export function liteLLMToken(raw, now, previous) {
     throw protocolError('gateway_token_invalid', 'LiteLLM token response is incomplete or invalid')
   }
   if (previous && (raw.user_id !== previous.identity.sub || raw.team_id !== previous.teamID)) throw protocolError('gateway_identity_changed', 'Gateway authorization identity changed during refresh; sign in again')
-  return { accessToken: raw.access_token, refreshToken: raw.refresh_token, expiresAt: Math.floor(now() / 1000) + raw.expires_in, teamID: raw.team_id, identity: { sub: raw.user_id, name: previous?.identity?.name || raw.user_id } }
+  return { accessToken: raw.access_token, refreshToken: raw.refresh_token, ...accessTokenTiming(raw.expires_in, now), teamID: raw.team_id, identity: { sub: raw.user_id, name: previous?.identity?.name || raw.user_id } }
 }
 
 export function tokenRequest(fetcher, descriptor, values) {

package/lib/model-types.js

@@ -0,0 +1,7 @@
+// Purpose is independent of input modalities: a vision LLM is still an LLM.
+// Unknown (including future server types) is never registered for conversation.
+export const MODEL_TYPES = Object.freeze(['llm', 'embedding', 'rerank', 'image', 'tts', 'unknown'])
+
+export function isLLM(model) {
+  return model.type === 'llm'
+}

package/lib/oidc-llm-protocol.js

@@ -1,4 +1,5 @@
 import { serviceProtocolAllowed } from './transport.js'
+import { accessTokenTiming } from './token-lifetime.js'
 // Experimental draft 0.1. These wire rules are not a published standard.
 import { protocolError } from './litellm-protocol.js'
 
@@ -30,9 +31,12 @@ export function detectOidcLlm(raw, profile) {
   const identityMode = profile.auth.identityMode
   includes(extension, 'identity_modes_supported', ['oauth', identityMode])
   includes(extension, 'client_registration_methods_supported', ['static'])
-  const scopes = identityMode === 'oidc'
+  const identityScopes = identityMode === 'oidc'
     ? ['openid', 'profile', 'offline_access', 'llm:models:read', 'llm:invoke']
     : ['llm:profile', 'llm:models:read', 'llm:invoke']
+  // Only request explicitly configured services; discovery is not consent to
+  // every capability advertised by the authorization server.
+  const scopes = [...new Set([...identityScopes, ...(profile.auth.additionalScopes ?? [])])]
   for (const [key, values] of Object.entries({
     response_types_supported: ['code'], grant_types_supported: ['authorization_code', 'refresh_token'],
     code_challenge_methods_supported: ['S256'], token_endpoint_auth_methods_supported: ['none'],
@@ -73,7 +77,7 @@ export function oidcLlmToken(raw, descriptor, now, previous) {
     throw protocolError('gateway_scope_changed', 'oidc-llm granted scopes do not match the requested authorization')
   }
   // No unapproved 15-minute ceiling: honor the actual advertised TTL.
-  return { accessToken: raw.access_token, refreshToken: raw.refresh_token, expiresAt: Math.floor(now() / 1000) + raw.expires_in, scopes, teamID: null }
+  return { accessToken: raw.access_token, refreshToken: raw.refresh_token, ...accessTokenTiming(raw.expires_in, now), scopes, teamID: null }
 }
 
 export function oidcLlmIdentity(raw) {

package/lib/oidc.js

@@ -1,11 +1,11 @@
 import { serviceProtocolAllowed } from './transport.js'
 import { createHash, createPublicKey, randomBytes, timingSafeEqual, verify as verifySignature } from 'node:crypto'
 import { emptyResources } from './resources.js'
+import { accessTokenNeedsRefresh, accessTokenTiming } from './token-lifetime.js'
 
 const FLOW_TTL_MS = 10 * 60 * 1000
 const MAX_PENDING_FLOWS = 32
 const CLOCK_SKEW_SECONDS = 60
-const ACCESS_REFRESH_SECONDS = 90
 const MAX_RESPONSE_BYTES = 1024 * 1024
 export const OIDC_CALLBACK_PATH = '/oauth/callback'
 
@@ -225,7 +225,7 @@ export class WebOidcBackend {
     let response
     try {
       response = await this.fetch(discoveryURL(profile.oidc.issuer), {
-        headers: { accept: 'application/json' }, signal: AbortSignal.timeout(20_000),
+        headers: { accept: 'application/json' }, redirect: 'error', signal: AbortSignal.timeout(20_000),
       })
     } catch (cause) {
       throw publicError('oidc_discovery_failed', 'unable to read OIDC discovery metadata', cause)
@@ -328,7 +328,7 @@ export class WebOidcBackend {
     })
     const response = await this.fetch(discovery.tokenEndpoint, {
       method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
-      body, signal: AbortSignal.timeout(20_000),
+      body, redirect: 'error', signal: AbortSignal.timeout(20_000),
     })
     const token = await responseJSON(response, 'oidc_token_request_failed')
     if (typeof token.access_token !== 'string' || typeof token.id_token !== 'string' || token.token_type?.toLowerCase() !== 'bearer') {
@@ -336,6 +336,7 @@ export class WebOidcBackend {
     }
     const expiresIn = token.expires_in === undefined ? 3600 : Number(token.expires_in)
     if (!Number.isFinite(expiresIn) || expiresIn <= 0) throw publicError('oidc_token_invalid', 'OIDC token expiry is invalid')
+    const timing = accessTokenTiming(expiresIn, this.now)
     const claims = await this.verifyIDToken(profile, discovery, token.id_token, nonce, token.access_token)
     const userInfo = await this.userInfo(discovery.userInfoEndpoint, token.access_token)
     if (!equalText(userInfo.sub, claims.sub)) throw publicError('oidc_userinfo_invalid', 'OIDC UserInfo subject does not match ID Token')
@@ -346,7 +347,7 @@ export class WebOidcBackend {
       clientId: profile.oidc.clientId,
       accessToken: token.access_token,
       refreshToken: typeof token.refresh_token === 'string' ? token.refresh_token : '',
-      expiresAt: nowSeconds(this.now) + Math.max(60, expiresIn),
+      ...timing,
       identity: {
         sub: claims.sub,
         name: userName,
@@ -387,9 +388,12 @@ export class WebOidcBackend {
       throw publicError('oidc_id_token_invalid', 'OIDC ID Token identity claims are invalid')
     }
     if (!Number.isFinite(claims.exp) || !Number.isFinite(claims.iat)
-      || claims.exp < now - CLOCK_SKEW_SECONDS || claims.iat > now + CLOCK_SKEW_SECONDS
-      || (claims.nbf !== undefined && (!Number.isFinite(claims.nbf) || claims.nbf > now + CLOCK_SKEW_SECONDS))) {
-      throw publicError('oidc_id_token_invalid', 'OIDC ID Token time claims are invalid')
+      || (claims.nbf !== undefined && !Number.isFinite(claims.nbf))) {
+      throw publicError('oidc_id_token_invalid', 'OIDC ID Token time claims are malformed')
+    }
+    if (claims.exp < now - CLOCK_SKEW_SECONDS || claims.iat > now + CLOCK_SKEW_SECONDS
+      || (claims.nbf !== undefined && claims.nbf > now + CLOCK_SKEW_SECONDS)) {
+      throw publicError('oidc_id_token_time_invalid', 'OIDC ID Token time claims are invalid')
     }
     if (claims.at_hash !== undefined && (typeof claims.at_hash !== 'string' || !verifyAccessTokenHash(accessToken, claims.at_hash))) {
       throw publicError('oidc_id_token_invalid', 'OIDC ID Token access-token hash is invalid')
@@ -399,7 +403,7 @@ export class WebOidcBackend {
 
   async userInfo(endpoint, accessToken) {
     const response = await this.fetch(endpoint, {
-      headers: { authorization: `Bearer ${accessToken}`, accept: 'application/json' }, signal: AbortSignal.timeout(20_000),
+      headers: { authorization: `Bearer ${accessToken}`, accept: 'application/json' }, redirect: 'error', signal: AbortSignal.timeout(20_000),
     })
     const result = await responseJSON(response, 'oidc_userinfo_failed')
     if (typeof result.sub !== 'string' || result.sub === '') throw publicError('oidc_userinfo_invalid', 'OIDC UserInfo has no subject')
@@ -459,13 +463,14 @@ export class WebOidcBackend {
     const epoch = this.accountEpoch(profile)
     const saved = await this.loadSession(profile)
     if (!saved) throw publicError('oidc_login_required', 'OIDC session is no longer available')
-    if (saved && saved.accessToken !== session.accessToken && saved.expiresAt > nowSeconds(this.now) + ACCESS_REFRESH_SECONDS) return saved
+    if (saved.accessToken !== session.accessToken && saved.expiresAt > nowSeconds(this.now)) return saved
+    session = saved
     if (!session.refreshToken) throw publicError('oidc_login_required', 'OIDC session cannot be refreshed')
     const discovery = await this.discover(profile)
     const response = await this.fetch(discovery.tokenEndpoint, {
       method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
       body: new URLSearchParams({ grant_type: 'refresh_token', client_id: profile.oidc.clientId, refresh_token: session.refreshToken }),
-      signal: AbortSignal.timeout(20_000),
+      redirect: 'error', signal: AbortSignal.timeout(20_000),
     })
     let token
     try { token = await responseJSON(response, 'oidc_refresh_failed') }
@@ -486,7 +491,7 @@ export class WebOidcBackend {
       ...session,
       accessToken: token.access_token,
       refreshToken: typeof token.refresh_token === 'string' ? token.refresh_token : session.refreshToken,
-      expiresAt: nowSeconds(this.now) + Math.max(60, expiresIn),
+      ...accessTokenTiming(expiresIn, this.now),
     }
     await this.saveSession(profile, next, epoch)
     return next
@@ -496,8 +501,9 @@ export class WebOidcBackend {
     const epoch = this.accountEpoch(profile)
     let session = await this.loadSession(profile)
     if (!session) return undefined
-    if (session.expiresAt <= nowSeconds(this.now) + ACCESS_REFRESH_SECONDS) {
+    if (accessTokenNeedsRefresh(session, this.now)) {
       if (!session.refreshToken) {
+        if (session.expiresAt > nowSeconds(this.now)) return session
         await this.clearCredentials(profile, epoch)
         this.accountChanged(account(profile, undefined, false))
         return undefined
@@ -595,7 +601,7 @@ export class WebOidcBackend {
           const token = session.refreshToken || session.accessToken
           await this.fetch(discovery.revocationEndpoint, {
             method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' },
-            body: new URLSearchParams({ token, client_id: profile.oidc.clientId }), signal: AbortSignal.timeout(10_000),
+            body: new URLSearchParams({ token, client_id: profile.oidc.clientId }), redirect: 'error', signal: AbortSignal.timeout(10_000),
           })
         }
       } catch (cause) { this.ctx.logger.warn(cause instanceof Error ? cause : new Error(String(cause))) }

package/lib/profile.js

@@ -1,4 +1,5 @@
 import { serviceProtocolAllowed } from './transport.js'
+import { MODEL_TYPES, isLLM } from './model-types.js'
 import { readFileSync } from 'node:fs'
 
 export const PROFILE_SCHEMA_VERSION = 'dsh-oidc/v1alpha1'
@@ -19,7 +20,7 @@ const allowedRootKeys = new Set([
 const allowedOidcKeys = new Set(['issuer', 'clientId', 'scopes'])
 const allowedBrandKeys = new Set([
   'productName', 'organizationName', 'mark', 'logoURL', 'primaryColor',
-  'loginTitle', 'loginDescription', 'supportURL',
+  'loginTitle', 'loginDescription', 'loginButtonLabel', 'supportURL', 'language',
 ])
 const allowedProviderKeys = new Set([
   'id', 'displayName', 'adapter', 'baseURL', 'reasoning', 'defaultContextWindow',
@@ -27,7 +28,7 @@ const allowedProviderKeys = new Set([
   'requestImageMaxBytes', 'streamIdleTimeoutMs', 'retryPolicy', 'compat', 'models', 'modelSource',
 ])
 const allowedModelKeys = new Set([
-  'id', 'name', 'input', 'contextWindow', 'maxTokens', 'reasoning',
+  'id', 'type', 'name', 'input', 'contextWindow', 'maxTokens', 'reasoning',
   'reasoningEfforts', 'defaultReasoningEffort', 'compat',
 ])
 const allowedCompatKeys = new Set([
@@ -114,10 +115,14 @@ function normalizeBrand(value = {}) {
     }
     result.logoURL = logo.startsWith('https://') ? safeHTTPSResource(logo, 'brand.logoURL', 128 * 1024) : logo
   }
-  for (const key of ['loginTitle', 'loginDescription']) {
-    if (source[key] !== undefined) result[key] = text(source[key], `brand.${key}`, key === 'loginTitle' ? 120 : 500)
+  for (const [key, max] of Object.entries({ loginTitle: 120, loginDescription: 500, loginButtonLabel: 40 })) {
+    if (source[key] !== undefined) result[key] = text(source[key], `brand.${key}`, max)
   }
   if (source.supportURL !== undefined) result.supportURL = exactURL(source.supportURL, 'brand.supportURL')
+  if (source.language !== undefined) {
+    if (!['auto', 'zh-CN', 'en'].includes(source.language)) throw new Error('brand.language must be auto, zh-CN or en')
+    result.language = source.language
+  }
   return Object.freeze(result)
 }
 
@@ -162,6 +167,8 @@ export function normalizeModels(models, providerID) {
     const model = object(raw, label)
     exactKeys(model, allowedModelKeys, label)
     const id = text(model.id, `${label}.id`, 256)
+    const type = model.type === undefined ? 'unknown' : model.type
+    if (!MODEL_TYPES.includes(type)) throw new Error(`${label}.type must be one of ${MODEL_TYPES.join(', ')}`)
     if (seen.has(id)) throw new Error(`${providerID} repeats model ${id}`)
     seen.add(id)
     const input = model.input ?? ['text']
@@ -184,6 +191,7 @@ export function normalizeModels(models, providerID) {
     }
     return Object.freeze({
       id,
+      type,
       name: model.name === undefined ? id : text(model.name, `${providerID}.${id}.name`, 256),
       input: Object.freeze([...new Set(input)]),
       ...(model.contextWindow === undefined ? {} : { contextWindow: positiveInteger(model.contextWindow, `${providerID}.${id}.contextWindow`) }),
@@ -258,15 +266,22 @@ export function normalizeEnterpriseProfile(raw) {
   let auth
   if (gateway) {
     const rawAuth = object(source.auth, 'profile.auth')
-    exactKeys(rawAuth, new Set(['discoveryUrl', 'expectedIssuer', 'experimentalOidcLlm', 'clientId', 'identityMode']), 'profile.auth')
+    exactKeys(rawAuth, new Set(['discoveryUrl', 'expectedIssuer', 'experimentalOidcLlm', 'clientId', 'identityMode', 'additionalScopes']), 'profile.auth')
     const experimental = rawAuth.experimentalOidcLlm === true
     if (rawAuth.experimentalOidcLlm !== undefined && typeof rawAuth.experimentalOidcLlm !== 'boolean') throw new Error('profile.auth.experimentalOidcLlm must be boolean')
-    if (!experimental && (rawAuth.clientId !== undefined || rawAuth.identityMode !== undefined)) throw new Error('profile.auth clientId and identityMode require experimentalOidcLlm=true')
+    if (!experimental && (rawAuth.clientId !== undefined || rawAuth.identityMode !== undefined || rawAuth.additionalScopes !== undefined)) throw new Error('profile.auth clientId, identityMode and additionalScopes require experimentalOidcLlm=true')
     if (experimental && !['oauth', 'oidc'].includes(rawAuth.identityMode)) throw new Error('profile.auth.identityMode must explicitly select oauth or oidc')
+    if (rawAuth.additionalScopes !== undefined && (!Array.isArray(rawAuth.additionalScopes)
+      || rawAuth.additionalScopes.length > 64
+      || rawAuth.additionalScopes.some(scope => typeof scope !== 'string' || scope.length > 128 || !/^[\x21\x23-\x5b\x5d-\x7e]+$/.test(scope))
+      || new Set(rawAuth.additionalScopes).size !== rawAuth.additionalScopes.length)) {
+      throw new Error('profile.auth.additionalScopes must contain at most 64 unique OAuth scope tokens, each at most 128 characters')
+    }
     auth = Object.freeze({
       discoveryUrl: issuerURL(rawAuth.discoveryUrl, 'profile.auth.discoveryUrl', allowInsecureDevelopment),
       ...(rawAuth.expectedIssuer === undefined ? {} : { expectedIssuer: issuerURL(rawAuth.expectedIssuer, 'profile.auth.expectedIssuer', allowInsecureDevelopment) }),
       ...(experimental ? { experimentalOidcLlm: true, clientId: text(rawAuth.clientId, 'profile.auth.clientId', 256), identityMode: rawAuth.identityMode } : {}),
+      ...(rawAuth.additionalScopes === undefined ? {} : { additionalScopes: Object.freeze([...rawAuth.additionalScopes]) }),
     })
     if (source.provider?.baseURL !== undefined) throw new Error('profile.auth derives provider.baseURL from validated discovery')
     if (source.provider?.modelSource !== undefined && source.provider.modelSource !== 'discovery') throw new Error('profile.auth requires discovery modelSource')
@@ -354,7 +369,7 @@ export function loadEnterpriseProfiles(raw = {}, environment = process.env) {
 
 export function enterpriseProviderConfig(profiles) {
   return {
-    providers: Object.fromEntries([...profiles.values()].filter(profile => profile.provider?.baseURL && profile.provider.models.length).map(profile => [profile.provider.id, {
+    providers: Object.fromEntries([...profiles.values()].filter(profile => profile.provider?.baseURL && profile.provider.models.some(isLLM)).map(profile => [profile.provider.id, {
       displayName: profile.provider.displayName,
       apiKeyEnv: `DSH_GATEWAY_${profile.id.toUpperCase().replace(/-/g, '_')}_ACCESS`,
       baseURL: profile.provider.baseURL,
@@ -368,7 +383,7 @@ export function enterpriseProviderConfig(profiles) {
       ...(profile.provider.streamIdleTimeoutMs === undefined ? {} : { streamIdleTimeoutMs: profile.provider.streamIdleTimeoutMs }),
       ...(profile.provider.retryPolicy === undefined ? {} : { retryPolicy: structuredClone(profile.provider.retryPolicy) }),
       ...(profile.provider.compat === undefined ? {} : { compat: { ...profile.provider.compat } }),
-      models: profile.provider.models.map(model => ({
+      models: profile.provider.models.filter(isLLM).map(({ type, ...model }) => ({
         ...model,
         input: [...model.input],
         ...(model.reasoningEfforts && typeof model.reasoningEfforts === 'object'
@@ -390,7 +405,7 @@ export function publicProfile(profile) {
     ...(profile.provider ? { provider: {
       id: profile.provider.id,
       displayName: profile.provider.displayName,
-      models: profile.provider.models.map(model => ({ id: model.id, name: model.name, input: model.input })),
+      models: profile.provider.models.filter(isLLM).map(model => ({ id: model.id, name: model.name, input: model.input })),
     } } : {}),
   }
 }

package/lib/provider/authorization-scope.js

@@ -9,6 +9,10 @@ export class AuthorizationScopedAdapter {
   providerInfo(provider) { return this.inner.providerInfo(provider) }
   providerRetryPolicy(provider) { return this.inner.providerRetryPolicy(provider) }
   imageRequestPricing(provider, model) { return this.inner.imageRequestPricing(provider, model) }
+  imageRequestTarget(provider, model, image) {
+    return this.inner.imageRequestTarget?.(provider, model, image)
+      ?? { width: image.width, height: image.height, maxBytes: image.bytes }
+  }
   listModels(provider) { return this.inner.listModels(provider) }
   resolveModel(provider, model, signal) { return this.inner.resolveModel(provider, model, signal) }
 

package/lib/provider/core.js

@@ -174,16 +174,16 @@ export function resolveEnterpriseProfiles(raw = {}) {
   })
 }
 
-export function configurableEntries(profiles) {
+export function configurableEntries(profiles, settingsNs = ENTERPRISE_SETTINGS_NAMESPACE) {
   return [...profiles.values()].map(profile => ({
     provider: profile.provider,
     displayName: profile.displayName,
-    settingsNs: ENTERPRISE_SETTINGS_NAMESPACE,
+    settingsNs,
     settingsPath: ['providers', profile.provider],
     declared: true,
   }))
 }
 
 export function settingsBase(rawConfig) {
-  return { providers: rawConfig.providers ?? {} }
+  return { providers: typeof rawConfig.providers?.get === 'function' ? rawConfig.providers.get() : rawConfig.providers ?? {} }
 }

package/lib/provider/index.js

@@ -16,9 +16,22 @@ import { AuthorizationScopedAdapter } from './authorization-scope.js'
 export const name = 'dsh-oidc-provider'
 export const inject = ['llm']
 export const SETTINGS_NAMESPACE = ENTERPRISE_SETTINGS_NAMESPACE
+export const Config = PiAiConfig
 
 function installEnterpriseSettings(ctx, rawConfig, hooks) {
   ctx.inject(['settings'], (settingsCtx) => {
+    if (typeof settingsCtx.settings.installSection !== 'function') {
+      // Account-managed routes come from the organization profile and its
+      // authorization lease. Never project them into editable API-key forms.
+      if (rawConfig.settingsEnabled !== true) return
+      if (typeof rawConfig.providers?.get !== 'function' || !ctx.fiber.entry) {
+        throw new Error('Editable enterprise providers require a DSH profile entry with live Config')
+      }
+      settingsCtx.effect(() => settingsCtx.settings.configure({ auto: false }, ctx.fiber))
+      hooks.setSource(() => settingsBase(rawConfig))
+      ctx.on('loader/volatile-update', () => hooks.onChange())
+      return
+    }
     settingsCtx.settings.installSection(
       ctx,
       SETTINGS_NAMESPACE,
@@ -147,14 +160,17 @@ export function apply(ctx, rawConfig = {}) {
     : transforming
   let registration
   let directory
+  const nativeSettings = typeof ctx.get('settings')?.installSection !== 'function'
+  const editableDirectory = !nativeSettings || rawConfig.settingsEnabled === true
+  const settingsNs = nativeSettings ? ctx.fiber.entry?.options.id ?? SETTINGS_NAMESPACE : SETTINGS_NAMESPACE
   const replaceProfiles = next => {
     const previous = profiles
     profiles = next
     try {
       if (registration) registration.replace([...next.keys()])
       else if (next.size) registration = ctx.llm.registerAdapter([...next.keys()], adapter)
-      if (directory) directory.replace(configurableEntries(next))
-      else if (next.size) directory = ctx.llm.registerConfigurableProviders(configurableEntries(next))
+      if (directory) directory.replace(configurableEntries(next, settingsNs))
+      else if (next.size && editableDirectory) directory = ctx.llm.registerConfigurableProviders(configurableEntries(next, settingsNs))
     } catch (error) {
       profiles = previous
       registration?.replace([...previous.keys()])

package/lib/provider/transform-adapter.js

@@ -37,6 +37,10 @@ export class TransformingEnterpriseAdapter {
   providerInfo(provider) { return this.inner.providerInfo(provider) }
   providerRetryPolicy(provider) { return this.inner.providerRetryPolicy(provider) }
   imageRequestPricing(provider, model) { return this.inner.imageRequestPricing(provider, model) }
+  imageRequestTarget(provider, model, image) {
+    return this.inner.imageRequestTarget?.(provider, model, image)
+      ?? { width: image.width, height: image.height, maxBytes: image.bytes }
+  }
 
   async listModels(provider) {
     const models = await this.inner.listModels(provider)

package/lib/resources.js

@@ -1,16 +1,24 @@
 import { normalizeModels } from './profile.js'
+import { MODEL_TYPES } from './model-types.js'
 
-// The public resource contract extends the deployed worker wire protocol. OIDC
-// access tokens remain on the management plane; these calls use the model key.
+// A gateway catalog may also contain embedding, ranking and media models.
+// Type metadata classifies authorized rows; it never grants model access.
 export function normalizeResourceModels(raw, profile) {
   if (!Array.isArray(raw?.data) || raw.data.length > 128) throw new Error('invalid model catalog')
   const reviewed = new Map(profile.provider.models.map(model => [model.id, model]))
   const models = raw.data.map(row => {
     const id = typeof row?.id === 'string' ? row.id.trim() : ''
+    const local = reviewed.get(id)
+    // The current server declaration wins. Local metadata fills an absent type,
+    // but cannot turn an explicit unknown/future server type into a chat model.
+    const type = row.type === undefined
+      ? local?.type ?? 'unknown'
+      : MODEL_TYPES.includes(row.type) ? row.type : 'unknown'
     // A plain /models response does not prove reasoning or vision support.
-    return reviewed.get(id) ?? { id, name: id, input: ['text'], reasoning: false }
+    return { ...(local ?? { id, name: id, input: ['text'], reasoning: false }), type }
   })
-  return normalizeModels(models, profile.provider.id)
+  // Keep the full typed catalog; only the DSH conversation projection uses LLMs.
+  return models.length === 0 ? Object.freeze([]) : normalizeModels(models, profile.provider.id)
 }
 
 export function emptyResources(profile) {

package/lib/token-lifetime.js

@@ -0,0 +1,15 @@
+const ACCESS_REFRESH_SECONDS = 30 * 60
+
+// Refresh early without repeatedly renewing tokens whose entire lifetime is
+// shorter than the normal margin. These timestamps stay in the Host vault.
+export function accessTokenTiming(expiresIn, now) {
+  const expiresAt = Math.floor(now() / 1000) + expiresIn
+  return { expiresAt, refreshAt: expiresAt - Math.min(ACCESS_REFRESH_SECONDS, expiresIn / 2) }
+}
+
+export function accessTokenNeedsRefresh(session, now) {
+  // Existing installations have only expiresAt. Their first refresh adds the
+  // lifetime-aware timestamp; no migration or new sign-in is required.
+  const refreshAt = Number.isFinite(session.refreshAt) ? session.refreshAt : session.expiresAt - ACCESS_REFRESH_SECONDS
+  return now() / 1000 >= Math.min(session.expiresAt, refreshAt)
+}

package/lib/typert-schemas.js

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { MODEL_TYPES } from './model-types.js'
 
 const pkg = '@eduwork/dsh-oidc'
 export const profileIdSchema = z.string().min(1).max(64)
@@ -8,11 +9,11 @@ export const baseURLSchema = z.string().min(1).max(2048)
 export const modelCatalogModeSchema = z.enum(['discovery', 'manual'])
 export const configurationTargetSchema = z.enum(['config', 'examples'])
 export const openConfigurationResult = Object.freeze({
-  mode: 'strict', typeSymbol: `${pkg}#OpenConfigurationResult`,
+  mode: 'strict', create() { return this.schema }, typeSymbol: `${pkg}#OpenConfigurationResult`,
   schema: z.object({ opened: z.literal(true) }).strict(),
 })
 export const enterpriseSelectionResult = Object.freeze({
-  mode: 'strict', typeSymbol: `${pkg}#EnterpriseSelectionResult`,
+  mode: 'strict', create() { return this.schema }, typeSymbol: `${pkg}#EnterpriseSelectionResult`,
   schema: z.object({ changed: z.boolean(), selection: z.object({ provider: z.string(), model: z.string(), reasoningEffort: z.string().optional() }).strict().optional() }).strict(),
 })
 export const enterpriseSelectionOptionsSchema = z.object({ onlyIfMissing: z.boolean().optional() }).strict()
@@ -20,7 +21,7 @@ export const enterpriseSelectionOptionsSchema = z.object({ onlyIfMissing: z.bool
 const brandSchema = z.object({
   productName: z.string().optional(), organizationName: z.string().optional(), mark: z.string().optional(),
   logoURL: z.string().optional(), primaryColor: z.string().optional(), loginTitle: z.string().optional(),
-  loginDescription: z.string().optional(), supportURL: z.string().optional(),
+  loginDescription: z.string().optional(), loginButtonLabel: z.string().min(1).max(40).optional(), supportURL: z.string().optional(), language: z.enum(['auto', 'zh-CN', 'en']).optional(),
 }).strict()
 
 const publicProfileSchema = z.object({
@@ -50,11 +51,12 @@ export const runtimeModelSchema = z.object({
 }).strict()
 
 export const runtimeModelsSchema = z.array(runtimeModelSchema).max(128)
+export const resourceModelSchema = runtimeModelSchema.extend({ type: z.enum(MODEL_TYPES) })
 
 export const resourcesResult = Object.freeze({
-  mode: 'strict', typeSymbol: `${pkg}#Resources`,
+  mode: 'strict', create() { return this.schema }, typeSymbol: `${pkg}#Resources`,
   schema: z.object({
-    profileID: z.string(), modelSource: z.string(), models: runtimeModelsSchema, issues: z.array(z.string()),
+    profileID: z.string(), modelSource: z.string(), models: z.array(resourceModelSchema).max(128), issues: z.array(z.string()),
   }).strict(),
 })
 
@@ -69,14 +71,14 @@ const managementProfileSchema = z.object({
 }).strict()
 
 export const configurationResult = Object.freeze({
-  mode: 'strict', typeSymbol: `${pkg}#Configuration`,
+  mode: 'strict', create() { return this.schema }, typeSymbol: `${pkg}#Configuration`,
   schema: z.object({ schemaVersion: z.literal('dsh-oidc/v1alpha1'), uiMode: z.enum(['standard', 'models-only', 'external']), profiles: z.array(publicProfileSchema),
     manageProductBrand: z.boolean().optional(), configFile: z.object({ path: z.string(), examplesPath: z.string(), canOpen: z.boolean() }).strict().optional(),
   }).strict(),
 })
 
 export const managementResult = Object.freeze({
-  mode: 'strict', typeSymbol: `${pkg}#ManagementConfiguration`,
+  mode: 'strict', create() { return this.schema }, typeSymbol: `${pkg}#ManagementConfiguration`,
   schema: z.object({
     schemaVersion: z.literal('dsh-oidc/management/v1alpha1'), mode: z.enum(['profile', 'native']),
     activeProfileID: z.string(), restartRequired: z.boolean(),
@@ -86,14 +88,14 @@ export const managementResult = Object.freeze({
 })
 
 export const restartResult = Object.freeze({
-  mode: 'strict', typeSymbol: `${pkg}#RestartResult`,
+  mode: 'strict', create() { return this.schema }, typeSymbol: `${pkg}#RestartResult`,
   schema: z.object({ restarting: z.literal(true) }).strict(),
 })
 
-export const accountResult = Object.freeze({ mode: 'strict', typeSymbol: `${pkg}#AccountStatus`, schema: accountSchema })
+export const accountResult = Object.freeze({ mode: 'strict', create() { return this.schema }, typeSymbol: `${pkg}#AccountStatus`, schema: accountSchema })
 
 export const beginResult = Object.freeze({
-  mode: 'strict', typeSymbol: `${pkg}#BeginResult`,
+  mode: 'strict', create() { return this.schema }, typeSymbol: `${pkg}#BeginResult`,
   schema: z.union([
     z.object({ mode: z.literal('redirect'), authorizationURL: z.string().url() }).strict(),
     z.object({ mode: z.literal('completed'), status: accountSchema }).strict(),
@@ -102,7 +104,7 @@ export const beginResult = Object.freeze({
 })
 
 export const loginResult = Object.freeze({
-  mode: 'strict', typeSymbol: `${pkg}#LoginResult`,
+  mode: 'strict', create() { return this.schema }, typeSymbol: `${pkg}#LoginResult`,
   schema: z.object({
     loginID: loginIdSchema, profileID: profileIdSchema, expiresAt: z.string().datetime(),
     state: z.enum(['pending', 'completed', 'cancelled', 'expired', 'failed']),
@@ -111,5 +113,5 @@ export const loginResult = Object.freeze({
 })
 
 export function jsonParameter(name, schema, typeSymbol) {
-  return Object.freeze({ name, wire: name, source: 'json', codec: Object.freeze({ mode: 'strict', typeSymbol, schema }) })
+  return Object.freeze({ name, wire: name, source: 'json', codec: Object.freeze({ mode: 'strict', create() { return this.schema }, typeSymbol, schema }) })
 }