browser/openspec/changes/polish-ai-provider-onboarding/specs/ai-provider-management/spec.md

MODIFIED Requirements

Requirement: AI provider management preserves secret boundaries

AI provider management SHALL reject raw key material in request fields and SHALL never expose raw API keys in API responses or frontend-visible types.

Scenario: Raw key is submitted during update

• WHEN a create or update request includes raw key material instead of a secret reference in apiKeyRef
• THEN the platform MUST reject the request with a validation error and MUST NOT persist the provider

Scenario: Provider is returned to UI

• WHEN the backend or frontend API client returns provider data
• THEN the response/type MUST include apiKeyRef only and MUST NOT include apiKey, rawApiKey, or equivalent raw credential fields

Scenario: Provider management route is accessed without platform admin

• WHEN a client creates, lists, reads, updates, tests, changes status, or lists models for AI providers without a platform administrator bearer session
• THEN the platform MUST reject the request with a stable JSON authorization error

Requirement: AI provider console page is functional

The management console SHALL provide a functional operational view for configured providers while keeping normal setup focused on provider kind and platform-owned secret references.

Scenario: Operator opens AI provider page

• WHEN the AI provider page renders
• THEN it MUST show provider counts, status distribution, configured model counts, and a provider table

Scenario: Operator creates provider from normal form

• WHEN an operator creates a provider through the normal form
• THEN the page MUST generate the provider ID and apply provider-specific defaults for Base URL, model list, relay mode, timeout, and redaction policy before submitting named API requests

Scenario: Operator edits advanced provider metadata

• WHEN an operator opens advanced settings
• THEN the page MAY allow editing Base URL, model list, default model, relay mode, timeout, and redaction policy without requiring the operator to manually edit the provider ID

Scenario: Operator uses provider actions

• WHEN an operator triggers enable/disable, test, or model-list actions
• THEN the page MUST call the matching API client methods and display the redacted result state