| # Auth Credential Semantics |
|
|
| This document defines the canonical credential eligibility and resolution semantics used across: |
|
|
| - `resolveAuthProfileOrder` |
| - `resolveApiKeyForProfile` |
| - `models status --probe` |
| - `doctor-auth` |
|
|
| The goal is to keep selection-time and runtime behavior aligned. |
|
|
| ## Stable Reason Codes |
|
|
| - `ok` |
| - `missing_credential` |
| - `invalid_expires` |
| - `expired` |
| - `unresolved_ref` |
|
|
| ## Token Credentials |
|
|
| Token credentials (`type: "token"`) support inline `token` and/or `tokenRef`. |
|
|
| ### Eligibility rules |
|
|
| 1. A token profile is ineligible when both `token` and `tokenRef` are absent. |
| 2. `expires` is optional. |
| 3. If `expires` is present, it must be a finite number greater than `0`. |
| 4. If `expires` is invalid (`NaN`, `0`, negative, non-finite, or wrong type), the profile is ineligible with `invalid_expires`. |
| 5. If `expires` is in the past, the profile is ineligible with `expired`. |
| 6. `tokenRef` does not bypass `expires` validation. |
|
|
| ### Resolution rules |
|
|
| 1. Resolver semantics match eligibility semantics for `expires`. |
| 2. For eligible profiles, token material may be resolved from inline value or `tokenRef`. |
| 3. Unresolvable refs produce `unresolved_ref` in `models status --probe` output. |
|
|
| ## Legacy-Compatible Messaging |
|
|
| For script compatibility, probe errors keep this first line unchanged: |
|
|
| `Auth profile credentials are missing or expired.` |
|
|
| Human-friendly detail and stable reason codes may be added on subsequent lines. |
|
|
