truf-server/openspec/changes/stabilize-and-widen-scanner-coverage/specs/provider-key-validation/spec.md

ADDED Requirements

Requirement: PostgreSQL Candidate And Current-State Authority

Normal provider workers SHALL claim one fenced PostgreSQL candidate at a time and SHALL transactionally insert the result, update keycheck_current_state, complete that candidate, and create a projection job.

Scenario: Compatibility files lag or fail

• WHEN keycheck JSONL or status projection is delayed or quarantined
• THEN the committed PostgreSQL result and current state SHALL remain authoritative and unrelated candidates SHALL continue

Scenario: Explicit compatibility input

• WHEN an operator selects --input-mode jsonl
• THEN the bounded legacy JSONL reader MAY be used, but --input SHALL be rejected in normal PostgreSQL mode

Requirement: Provider Support Uses Detector And Keychecker Pair

New provider API key support SHALL include both detection and validation when a safe validation endpoint is available.

Scenario: Provider has safe validation endpoint

• WHEN support is added for a provider with a non-generating authentication or model-list endpoint
• THEN the change SHALL include a detector or detector routing rule and a keychecker for that provider

Scenario: Provider has no safe validation endpoint

• WHEN a provider does not have a safe validation endpoint
• THEN the detector MAY be added only with explicit documentation that validation is unavailable

Requirement: Ambiguous Key Formats Use Context Routing

The scanner SHALL use nearby provider-specific context to route ambiguous key formats to the correct keychecker when possible.

Scenario: Qwen context around generic key

• WHEN an sk-... key is found near Qwen or DashScope context
• THEN the key SHALL be routed away from unrelated generic sk-... checkers such as DeepSeek when the context does not also identify that provider

Scenario: Weak context around generic key

• WHEN an ambiguous key has no strong provider-specific context
• THEN the scanner SHALL avoid speculative rerouting that would suppress the existing detector result

Requirement: Keycheckers Avoid Token-Generating Probes By Default

Provider keycheckers SHALL prefer safe non-generating validation endpoints where available.

Scenario: Provider exposes model-list endpoint

• WHEN a provider exposes an authenticated model-list or account-status endpoint
• THEN the keychecker SHALL use that endpoint before considering any generation-style probe

Requirement: Keycheck Results Remain Linkable To Findings

Provider keycheckers SHALL emit detector names and result metadata that can be linked back to scanner findings.

Scenario: Custom detector result is validated

• WHEN a keychecker validates a key from a custom detector finding
• THEN the result SHALL include a stable detector name and source metadata sufficient for DB link repair