---
id: SMH-PLAN-VOETK_DD
type: plan
title: "Auth Store and Provider Selection"
spec: SMH-SPEC-SPEC0001
status: approved
depends_on: [SMH-PLAN-AIAG0001]
---

# Auth Store and Provider Selection

## Outcome

Credentials resolve deterministically from the Smith auth store or environment variables.
Eval and RPC run against any supported vendor with no implicit provider default.
Unresolved credentials fail before dispatch with every source tried named.

## Scope

Auth data persistence, `smith auth` commands, provider and model selection flags, the shared flag surface, and removal of hard-coded OpenAI defaults.
Provider plugins, catalogs, aliases, KDL configuration files, and credential refresh beyond existing behavior remain out of scope.
Builds on the SMH-SPEC-SPEC0001 environment configuration layer.

## Behaviors

Ordered by delivery value.

1. **Auth store**: `smith auth add` persists one credential per provider under XDG `smith/auth` as plaintext files with user-only permissions.
2. **Inspection**: `smith auth list` reports providers and credential provenance without printing secrets; `smith auth remove` deletes one entry.
3. **Pre-dispatch check**: `smith auth check` resolves a provider's credential without a model request and prints the winning source.
4. **Flag surface**: each option is declared once with a command-line flag and a `SMITH_`-prefixed environment name; eval and RPC expose `--provider`, `--model`, `--base-url`; the command line wins over the environment, and resolved values report their source.
Capabilities stay in the catalog; request options such as thinking levels arrive with catalog levels, not as flags.
5. **Resolution orders**: options resolve command line, then environment, then configuration; credentials resolve auth store, then environment variable. First hit wins in each domain.
6. **Explicit failure**: with no provider flag, no stored credential, and no environment variable, commands fail naming the vendor, the missing credential, and every source tried.
7. **Hygiene**: credential plaintext never enters logs, session traces, replay output, or diagnostics.

## Resolution model

```mermaid
flowchart LR
  subgraph options [options: provider, model, base-url]
    OF["--flag value"] --> OE["SMITH_ env value"] --> OC["configuration value"] --> OD["default"]
  end
  subgraph creds [credentials]
    CA["auth store entry"] --> CE["vendor env variable"] --> CX["fail: vendor + sources tried"]
  end
  OD --> R["resolve before dispatch"]
  CE --> R
  CX --> R
```

## Plan dependencies

```mermaid
flowchart LR
  AIAG1["AIAG0001<br/>agent loop, env auth"] --> THIS["VOETK_DD<br/>auth store, selection"]
  THIS --> PLUG["PLUG0001<br/>provider plugins, catalogs"]
```

## Interfaces

- `smith::config`: XDG auth paths.
- `smith-ai::auth`: store-backed credential registry; resolution order; provenance.
- `smith-harness::runtime`: provider assembly from explicit selection; removal of vendor defaults.
- `smith-cli`: `auth` subcommand group; eval and RPC selection flags.

## Verification

- `smith auth add` then `list` then `remove` round-trips one provider entry; file permissions are user-only.
- `smith auth check` succeeds and fails without any network activity.
- Options resolve cli > env > configuration; credentials resolve store > env, deterministically per vendor.
- Eval without any credential source fails with vendor and all sources named; no OpenAI endpoint or model is implied.
- Every option resolves from one declaration; the command-line value overrides the environment value.
- Diagnostics report which surface supplied each resolved option; undeclared environment prefixes are ignored.
- Each vendor (OpenAI-compatible, Anthropic, Google) completes one eval round using a stored credential.
- Logs, traces, and replay output contain no credential plaintext.

## Stop conditions

- Store format cannot preserve user-only permissions portably.
- Provider selection cannot resolve a vendor without network access.
- A diagnostics path would require printing secret material.