Skip to main content

​
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.

​
OAuth SecretRef Policy Guard

  • SecretRef input is for static credentials only.
  • If a profile credential is type: "oauth", SecretRef objects are not supported for that profile credential material.
  • If auth.profiles.<id>.mode is "oauth", SecretRef-backed keyRef/tokenRef input for that profile is rejected.
  • Violations are hard failures in startup/reload auth resolution paths.

​
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.