{
  "version": 1,
  "hosts": {
    "<host-url>": { /* HostCredential — see below */ }
  }
}

interface HostCredential {
  /** Bearer token. Bearer-form is the only one supported today. */
  token: string

  /** Always "Bearer" today; reserved for future schemes. */
  tokenType: "Bearer"

  /** ISO-8601. May be in the past — callers must check `isExpired`. */
  expiresAt: string

  /** OAuth 2.0 refresh token. Present when the host issues one. */
  refreshToken?: string

  /** Space-separated scopes the token was issued with. */
  scope?: string

  /**
   * Human-readable subject — usually the user id. Surfaced by
   * `agentproto auth status`.
   */
  subject?: string

  /** ISO-8601 of when this credential was minted. */
  obtainedAt: string

  /**
   * Friendly device label shown on the host's "machine tokens" page,
   * if it has one. Sent to the host during the device-flow
   * authorization request.
   */
  deviceLabel?: string

  /**
   * Opaque revocation hint the host surfaced (typically a JTI). The
   * CLI passes it back on `agentproto auth logout` so the host can
   * revoke the right row server-side, not just delete the local copy.
   */
  revocationId?: string
}

function credentialsPath(): string

function normaliseHost(host: string): string
// Strips trailing slashes. Use before reading hosts[key].

async function loadCredentials(): Promise<CredentialsFile>
// Reads + parses the file. Returns
// { version: 1, hosts: {} } on ENOENT (file absent).

async function saveCredentials(file: CredentialsFile): Promise<void>
// Writes + chmods 0600. Skips chmod on Windows.

async function readHost(host: string): Promise<HostCredential | null>
async function writeHost(host: string, cred: HostCredential): Promise<void>
async function deleteHost(host: string): Promise<HostCredential | null>
// deleteHost unlinks the file when it removes the last host.

function isExpired(cred: HostCredential, gracePeriodMs?: number): boolean
// Default grace period 30s. Returns false for unparseable expiresAt
// (trust the host — don't refuse usable tokens because of a bad ISO).

function formatExpiry(cred: HostCredential): string
// "expires in 2h", "expired 5d ago", or "unknown".

{
  "version": 1,
  "hosts": {
    "https://guilde.work": {
      "token": "eyJhbGciOiJIUzI1NiIs…",
      "tokenType": "Bearer",
      "expiresAt": "2026-08-08T12:34:56.000Z",
      "refreshToken": "rt_v1_abc…",
      "scope": "tunnel:connect operator:run",
      "subject": "user_abc",
      "obtainedAt": "2026-05-10T08:21:11.000Z",
      "deviceLabel": "jeremy@laptop",
      "revocationId": "jti_xyz123"
    },
    "https://my-gateway.internal": {
      "token": "ghs_…",
      "tokenType": "Bearer",
      "expiresAt": "2026-09-01T00:00:00.000Z",
      "obtainedAt": "2026-05-15T17:00:00.000Z"
    }
  }
}