feat(apiproxy): settings/credentials/llm wire domains, frames, and write guard

Eight compiler-locked methods: settings.describe/update/replace serve redacted layered namespace views (secrets structurally absent from every layer, write-only in the update direction) and fold seam refusals into settings-rejected; credentials.describe/set/unset expose value-free views with credential-rejected on shadowed writes; llm.providers merges the configurable directory with live routes and llm.models claims the host-scoped catalog reservation through the buildModelCatalog extraction session.models now shares. Three HostFrame invalidations bridge the seam events (host/settings-changed, host/credentials-changed, host/models-changed), and the connection route generalizes the native- dialog check into a privileged-method set covering all four writes. The fixture and both fake clients grow the same face.
2026-07-30 00:13:12 +08:00
parent a5c8136cb3
commit 191067559e
30 changed files with 1349 additions and 102 deletions
--- a/packages/client/connection/src/client/api.ts
+++ b/packages/client/connection/src/client/api.ts
@@ -13,6 +13,8 @@ export type {
  ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
  ModelReasoningEffort, ModelTarget, SessionModels,
  GoalsApi, GoalRef,
+  SettingsApi, SettingsNamespaceView, SettingsSecretView,
+  CredentialsApi, CredentialView, ConfigurableProviderView, LlmApi,
 } from '@deepseek-ai/dsh-host-apiproxy/api'
 export type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools/presentation'
 export type {
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -28,7 +28,7 @@ import type {
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import type {
  ApiProxy, ClientRequest, ClientResponse, HistoryEntry, HostFrame, MuxFrame, RpcReceipt,
-  ModelTarget, RpcRequest, RpcResponse, RpcResult, ServerRequest, ServerResponse, SessionSummary,
+  ModelProviderGroup, ModelTarget, RpcRequest, RpcResponse, RpcResult, ServerRequest, ServerResponse, SessionSummary,
  ToolCallView, ToolEventView, ToolResultView, WorkspaceId, WorkspaceView,
 } from './api.ts'
 import type { RequestPayload, ResponseValue, RpcMethodMap } from '@deepseek-ai/dsh-host-apiproxy/api'
@@ -99,6 +99,35 @@ const OPENAI_REASONING = {
  defaultEffort: 'medium',
 }

+/** Catalog served by `session.models` and `llm.models` alike (fresh copies per call). */
+function fixtureModelGroups(): ModelProviderGroup[] {
+  return [
+    {
+      id: 'deepseek-official',
+      name: 'DeepSeek',
+      models: [
+        {
+          id: 'deepseek-v4-flash',
+          name: 'DeepSeek-V4-Flash',
+          description: '快速响应',
+          reasoning: DEEPSEEK_REASONING,
+        },
+        {
+          id: 'deepseek-v4-pro',
+          name: 'DeepSeek-V4-Pro',
+          description: '复杂任务',
+          reasoning: DEEPSEEK_REASONING,
+        },
+      ],
+    },
+    {
+      id: 'openai',
+      name: 'OpenAI',
+      models: [{ id: 'gpt-5', name: 'GPT-5', reasoning: OPENAI_REASONING }],
+    },
+  ]
+}
+
 function sid(id: string): SessionId {
  return id as SessionId
 }
@@ -558,6 +587,8 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
    session.sessionId,
    { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
  ]))
+  /** Credential store double: set/unset flip the describe badge, values never read back. */
+  const fixtureCredentials = new Map<string, string>()
  const nextTurn = new Map<SessionId, number>([[sid('fx-alpha'), 60]])
  let nextSession = 1
  let nextRpc = 1
@@ -879,31 +910,7 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
      models: request => ok(request, {
        current: modelTargets.get(request.payload.sessionId)
          ?? { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-        groups: [
-          {
-            id: 'deepseek-official',
-            name: 'DeepSeek',
-            models: [
-              {
-                id: 'deepseek-v4-flash',
-                name: 'DeepSeek-V4-Flash',
-                description: '快速响应',
-                reasoning: DEEPSEEK_REASONING,
-              },
-              {
-                id: 'deepseek-v4-pro',
-                name: 'DeepSeek-V4-Pro',
-                description: '复杂任务',
-                reasoning: DEEPSEEK_REASONING,
-              },
-            ],
-          },
-          {
-            id: 'openai',
-            name: 'OpenAI',
-            models: [{ id: 'gpt-5', name: 'GPT-5', reasoning: OPENAI_REASONING }],
-          },
-        ],
+        groups: fixtureModelGroups(),
        failures: [],
      }),
      selectModel: (request) => {
@@ -1276,6 +1283,50 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
        }
      },
    },
+    settings: {
+      // The fixture registers no namespaces yet: the Models surface renders
+      // its provider list from llm.providers alone, and a real settings form
+      // rides the HTTP transport (a hand-written schema envelope here would
+      // drift from schemastery's real serialization).
+      describe: request => ok(request, { writable: true, namespaces: [] }),
+      update: request => err(request, {
+        code: 'settings-rejected',
+        message: 'fixture: no settings namespaces are registered',
+        details: { ns: request.payload.ns },
+      }),
+      replace: request => err(request, {
+        code: 'settings-rejected',
+        message: 'fixture: no settings namespaces are registered',
+        details: { ns: request.payload.ns },
+      }),
+    },
+    credentials: {
+      describe: request => ok(request, {
+        credentials: Object.fromEntries(request.payload.refs.map(ref => [ref, {
+          configured: fixtureCredentials.has(ref),
+          ...fixtureCredentials.has(ref) ? { source: 'file' } : {},
+          writable: true,
+        }])),
+      }),
+      set: (request) => {
+        fixtureCredentials.set(request.payload.ref, request.payload.value)
+        return ok(request, {})
+      },
+      unset: (request) => {
+        fixtureCredentials.delete(request.payload.ref)
+        return ok(request, {})
+      },
+    },
+    llm: {
+      providers: request => ok(request, {
+        providers: [
+          { provider: 'deepseek-official', displayName: 'DeepSeek', settingsNs: 'llm-deepseek', settingsPath: [], active: true },
+          { provider: 'openai', displayName: 'openai', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'openai'], active: true },
+          { provider: 'anthropic', displayName: 'anthropic', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'anthropic'], active: false },
+        ],
+      }),
+      models: request => ok(request, { groups: fixtureModelGroups(), failures: [] }),
+    },
    respond(message: ClientResponse): Promise<RpcReceipt> {
      if (!questionPending || message.rpcId !== pendingQuestionRpcId) {
        return Promise.resolve({ accepted: false, reason: 'not-pending' })
@@ -1351,6 +1402,14 @@ export class FixtureApiClient extends AbstractApiClient {
      case 'goal.resume': return this.api.goals.resume(request)
      case 'goal.complete': return this.api.goals.complete(request)
      case 'goal.clear': return this.api.goals.clear(request)
+      case 'settings.describe': return this.api.settings.describe(request)
+      case 'settings.update': return this.api.settings.update(request)
+      case 'settings.replace': return this.api.settings.replace(request)
+      case 'credentials.describe': return this.api.credentials.describe(request)
+      case 'credentials.set': return this.api.credentials.set(request)
+      case 'credentials.unset': return this.api.credentials.unset(request)
+      case 'llm.providers': return this.api.llm.providers(request)
+      case 'llm.models': return this.api.llm.models(request)
    }
  }

--- a/packages/client/connection/src/client/index.ts
+++ b/packages/client/connection/src/client/index.ts
@@ -21,6 +21,8 @@ export type {
  ClientRequest, ServerResponse, ServerRequest, ClientResponse, RpcMessage, RpcReceipt,
  IApiClient, SessionId, SessionEvent, ContentBlock, StreamChunk,
  GoalsApi, GoalRef,
+  SettingsApi, SettingsNamespaceView, SettingsSecretView,
+  CredentialsApi, CredentialView, ConfigurableProviderView, LlmApi,
 } from './api.ts'
 export { RpcId, AbstractApiClient, transportError } from './api.ts'

--- a/packages/client/connection/src/index.ts
+++ b/packages/client/connection/src/index.ts
@@ -15,6 +15,22 @@ export const name = 'client-connection'
 /** Services required before mounting the route. */
 export const inject = ['httpServer', 'apiProxy']

+/**
+ * Methods gated on the trusted same-origin loopback check. Native dialogs act
+ * on the host machine; settings and credential writes mutate the user's
+ * configuration and secret store. Under `--host 0.0.0.0` every other method
+ * is reachable LAN-wide, but these stay browser-same-origin-on-loopback until
+ * a real authentication layer exists.
+ */
+const PRIVILEGED_METHODS = new Set([
+  'host.pickDirectory',
+  'host.openPath',
+  'settings.update',
+  'settings.replace',
+  'credentials.set',
+  'credentials.unset',
+])
+
 /**
 * Mounts the API gateway under the browser transport prefix.
 * @param ctx - Host plugin context.
@@ -26,8 +42,8 @@ export function apply(ctx: Context): void {
    path: API_PATH,
    handler: async (req, res) => {
      const pathname = new URL(req.url ?? '/', 'http://dsh.internal').pathname
-      if ((pathname === `${API_PATH}/host.pickDirectory`
-        || pathname === `${API_PATH}/host.openPath`)
+      if (pathname.startsWith(`${API_PATH}/`)
+        && PRIVILEGED_METHODS.has(pathname.slice(API_PATH.length + 1))
        && !isTrustedNativeDialogRequest(req)) {
        res.writeHead(403)
        res.end('forbidden')
--- a/packages/client/connection/tests/fake-api.ts
+++ b/packages/client/connection/tests/fake-api.ts
@@ -136,6 +136,23 @@ export class FakeApiClient implements IApiClient {
    clear: payload => this.record('goal.clear', payload, Promise.resolve(ok({ cleared: true as const }))),
  }

+  readonly settings: IApiClient['settings'] = {
+    describe: payload => this.record('settings.describe', payload, Promise.resolve(ok({ writable: true, namespaces: [] }))),
+    update: payload => this.record('settings.update', payload, Promise.resolve(ok({ ns: 'fake', schema: {}, value: {}, applies: 'live' as const, secrets: [] }))),
+    replace: payload => this.record('settings.replace', payload, Promise.resolve(ok({ ns: 'fake', schema: {}, value: {}, applies: 'live' as const, secrets: [] }))),
+  }
+
+  readonly credentials: IApiClient['credentials'] = {
+    describe: payload => this.record('credentials.describe', payload, Promise.resolve(ok({ credentials: {} }))),
+    set: payload => this.record('credentials.set', payload, Promise.resolve(ok({}))),
+    unset: payload => this.record('credentials.unset', payload, Promise.resolve(ok({}))),
+  }
+
+  readonly llm: IApiClient['llm'] = {
+    providers: payload => this.record('llm.providers', payload, Promise.resolve(ok({ providers: [] }))),
+    models: payload => this.record('llm.models', payload, Promise.resolve(ok({ groups: [], failures: [] }))),
+  }
+
  /** When true, streams never fire onOpen (misbehaving-carrier material for the handshake timeout guard). */
  suppressStreamOpen = false

--- a/packages/client/connection/tests/node-half.spec.ts
+++ b/packages/client/connection/tests/node-half.spec.ts
@@ -28,7 +28,13 @@ describe('connection node half', () => {
    expect(routes).toHaveLength(1)
    expect(routes[0]).toMatchObject({ kind: 'prefix', path: API_PATH })

-    for (const url of ['/api/host.pickDirectory', '/api/host.openPath']) {
+    // The privileged set: native dialogs plus every settings/credential write.
+    // A non-loopback peer is denied even with same-origin headers.
+    for (const url of [
+      '/api/host.pickDirectory', '/api/host.openPath',
+      '/api/settings.update', '/api/settings.replace',
+      '/api/credentials.set', '/api/credentials.unset',
+    ]) {
      let status: number | undefined
      let body: unknown
      const deniedRequest = {
@@ -50,4 +56,49 @@ describe('connection node half', () => {
    await fiber.dispose()
    expect(routes).toHaveLength(0)
  })
+
+  it('leaves reads and unprivileged methods to the bridge under the same untrusted peer', async () => {
+    const ctx = new Context()
+    const routes: WebRoute[] = []
+    const httpServer: Pick<HttpServerService, 'register' | 'tapIndex' | 'port'> = {
+      register(route) {
+        routes.push(route)
+        return () => { routes.splice(routes.indexOf(route), 1) }
+      },
+      tapIndex: () => () => {},
+      port: 0,
+    }
+    ctx.provide('httpServer', httpServer as HttpServerService)
+    // The bridge parses the request before the (empty) impl is consulted; a
+    // carrier-level 404/parse outcome proves the guard did not intercept.
+    ctx.provide('apiProxy', {} as unknown as ApiProxy)
+    const fiber = ctx.plugin({ inject: [...inject], apply })
+    await fiber.await()
+
+    let status: number | undefined
+    const request = {
+      url: '/api/settings.describe',
+      method: 'POST',
+      headers: {
+        host: 'harness.example', origin: 'http://harness.example', 'sec-fetch-site': 'same-origin',
+      },
+      socket: { remoteAddress: '192.168.1.8' },
+      // Minimal async-iterable face for the bridge's body assembly.
+      async *[Symbol.asyncIterator]() {
+        yield Buffer.from('not json')
+      },
+    } as unknown as IncomingMessage
+    const response = {
+      writeHead(value: number) { status = value; return this },
+      setHeader() { return this },
+      end() { return this },
+      write() { return true },
+      on() { return this },
+    } as unknown as ServerResponse
+    await routes[0]!.handler(request, response)
+    // 400 (body is not JSON) comes from the carrier, not the 403 guard: the
+    // read passed the privileged check and reached the fetch handler.
+    expect(status).toBe(400)
+    await fiber.dispose()
+  })
 })
--- a/packages/client/runtime/tests/fake-api.ts
+++ b/packages/client/runtime/tests/fake-api.ts
@@ -162,6 +162,23 @@ export class FakeApiClient implements IApiClient {
    clear: payload => this.record('goal.clear', payload, Promise.resolve(ok({ cleared: true as const }))),
  }

+  readonly settings: IApiClient['settings'] = {
+    describe: payload => this.record('settings.describe', payload, Promise.resolve(ok({ writable: true, namespaces: [] }))),
+    update: payload => this.record('settings.update', payload, Promise.resolve(ok({ ns: 'fake', schema: {}, value: {}, applies: 'live' as const, secrets: [] }))),
+    replace: payload => this.record('settings.replace', payload, Promise.resolve(ok({ ns: 'fake', schema: {}, value: {}, applies: 'live' as const, secrets: [] }))),
+  }
+
+  readonly credentials: IApiClient['credentials'] = {
+    describe: payload => this.record('credentials.describe', payload, Promise.resolve(ok({ credentials: {} }))),
+    set: payload => this.record('credentials.set', payload, Promise.resolve(ok({}))),
+    unset: payload => this.record('credentials.unset', payload, Promise.resolve(ok({}))),
+  }
+
+  readonly llm: IApiClient['llm'] = {
+    providers: payload => this.record('llm.providers', payload, Promise.resolve(ok({ providers: [] }))),
+    models: payload => this.record('llm.models', payload, Promise.resolve(ok({ groups: [], failures: [] }))),
+  }
+
  /** When true, streams never fire onOpen (misbehaving-carrier material for the handshake timeout guard). */
  suppressStreamOpen = false