{
  "version": 2,
  "description": "The CLI login `tonbo login` (and `yield login`) saves from @tonbo/cli 0.12 and @tonbo/yield 0.4 (ADR-0018): one session of the person per computer, tied to the computer's device id, that reaches every account the person belongs to only through per-account access tokens exchanged at POST /api/iam/token (contracts/iam/access-token-v1.json `cli_session`). It is a new file beside credentials-v1.json's, not a version 2 of it, so a reader of version 1 never sees it and never overwrites it. @tonbo/cli-core writes and reads it; the Tonbo SDK (contracts/sdk/v1.json) reads it before the legacy file.",
  "path": {
    "description": "`${XDG_CONFIG_HOME}/tonbo/login.json` when XDG_CONFIG_HOME is set and not empty, else `${HOME}/.config/tonbo/login.json`.",
    "base_env": "XDG_CONFIG_HOME",
    "fallback_base": [
      "$HOME",
      ".config"
    ],
    "relative": [
      "tonbo",
      "login.json"
    ]
  },
  "permissions": {
    "description": "POSIX only; a reader on Windows skips the mode checks. The same rules as credentials-v1.json.",
    "directory_mode": "0700",
    "file_mode": "0600",
    "writer": "The writer creates the directory 0700, writes a temporary file 0600 beside the target, syncs it and renames it over the target, so a crash never leaves a partial login. It refuses to replace or remove a symlink or anything that is not a regular file."
  },
  "key_sources": {
    "description": "Where a client takes its credential, first match wins. A library takes an explicit option first; the CLIs have none. `env` is an API key of one account (TONBO_API_KEY, contracts/iam/access-token-v1.json `personal_key`), which binds the client to the key's account. `file` is this login, then the legacy file of credentials-v1.json, which a client reads only when this file is missing.",
    "order": [
      "option",
      "env",
      "file"
    ],
    "env": "TONBO_API_KEY",
    "files": [
      "login.json",
      "credentials.json"
    ]
  },
  "account": {
    "description": "Which account a client acts in with this login. A session reaches no account by itself: every request names one, and the exchange checks the person's role there at that moment.",
    "order": [
      "option",
      "env",
      "default_account_id",
      "personal_account_id"
    ],
    "option": "The command's `--account <name|id>` or the library's `account` option.",
    "env": "TONBO_ACCOUNT",
    "env_description": "An account's name or id. Beside TONBO_API_KEY it must name the key's own account, or the client refuses before it calls anything.",
    "names": "A name is resolved through `accounts`; when it misses, or the exchange answers account_not_found, the client refreshes `accounts` from GET /api/iam/session and tries once more. `accounts` is a cache for names and offline display, never authority."
  },
  "device_file": {
    "description": "The computer's device id (ADR-0015's device id), kept in the state directory and never written to login.json, which holds only its SHA-256 (`device_id_sha256`). So a login.json copied without the state directory (a synced or published `~/.config`, a backup restored onto another computer) carries no device id, and an exchange that presents any other id is refused with cli_session_device_mismatch. @tonbo/cli-core makes it at the first login of either CLI and re-makes it when the saved hash of the operating system's machine id differs from the machine's (a cloned disk). A reader that only reads it (the SDK) takes `device_id` and never writes the file.",
    "base_env": "XDG_STATE_HOME",
    "fallback_base": [
      "$HOME",
      ".local",
      "state"
    ],
    "relative": [
      "tonbo-yield",
      "device.json"
    ],
    "schema": {
      "type": "object",
      "required": [
        "version",
        "device_id",
        "machine_id_sha256"
      ],
      "additionalProperties": true,
      "properties": {
        "version": {
          "const": 1
        },
        "device_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
          "description": "A random UUID made at the first run."
        },
        "machine_id_sha256": {
          "type": [
            "string",
            "null"
          ],
          "pattern": "^[0-9a-f]{64}$",
          "description": "The SHA-256 of the operating system's machine id (macOS IOPlatformUUID, Linux /etc/machine-id), or null when it could not be read."
        }
      }
    },
    "missing": "No file, or one that does not match `schema`: a reader that does not make it treats the login as unusable on this computer and asks the person to run `tonbo login`."
  },
  "reader": {
    "missing": "No file: read credentials.json under credentials-v1.json; with neither, ask the person to run `tonbo login`.",
    "refuse_symlink": true,
    "refuse_non_regular_file": true,
    "refuse_mode_bits": "0077",
    "refused": "A symlink, a non-regular file, or a file any group or other permission bit is set on is an error and is never read; do not fall back to another source.",
    "unknown_version": "A `version` other than `current_version`, or content that does not match `schema`, is unusable: ask the person to run `tonbo login`. It is never migrated, and the legacy file is not read in its place.",
    "expired": "A login whose `session.expires_at` is at or before now is expired: ask the person to run `tonbo login`. The server also ends a session 30 days after its last use and whenever it is revoked; a client learns that from a 401 at the exchange.",
    "device": "Every exchange sends the `device_id` of the computer's device file (`device_file`), and only when its SHA-256 (lowercase hex of the id's UTF-8 text) equals the login's `device_id_sha256`. Without a usable device file, or with another device's, the login is unusable on this computer: ask the person to run `tonbo login`, never send a mismatched id. A writer never puts the device id itself in login.json.",
    "login_hint": "tonbo login"
  },
  "current_version": 2,
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://tonbo.dev/contracts/cli/credentials-v2.json",
    "title": "Tonbo CLI login session",
    "type": "object",
    "required": [
      "version",
      "session",
      "user_id",
      "device_id_sha256",
      "personal_account_id"
    ],
    "additionalProperties": true,
    "properties": {
      "version": {
        "const": 2
      },
      "session": {
        "type": "object",
        "required": [
          "id",
          "secret",
          "expires_at"
        ],
        "additionalProperties": true,
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "description": "The session's id (a UUID)."
          },
          "secret": {
            "type": "string",
            "pattern": "^tbs_",
            "description": "The session's secret (contracts/iam/access-token-v1.json `cli_session.format`). It is presented only to POST /api/iam/token and /api/iam/session, never to a resource server."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "The session's absolute expiry, ISO 8601."
          }
        }
      },
      "user_id": {
        "type": "string",
        "minLength": 1,
        "description": "The person the session belongs to (a UUID)."
      },
      "device_id_sha256": {
        "type": "string",
        "pattern": "^[0-9a-f]{64}$",
        "description": "The SHA-256 (lowercase hex) of the device id the session is tied to. The id itself stays in the device file (`device_file`), so this file alone cannot be presented from another computer."
      },
      "personal_account_id": {
        "type": "string",
        "minLength": 1,
        "description": "The person's personal account (a UUID): the account of a command without --account, TONBO_ACCOUNT or a default."
      },
      "default_account_id": {
        "type": [
          "string",
          "null"
        ],
        "minLength": 1,
        "description": "The account commands act in without --account or TONBO_ACCOUNT (`tonbo account use`); null or absent for the personal account."
      },
      "accounts": {
        "type": "object",
        "description": "The person's accounts as GET /api/iam/session last answered them, keyed by account id: a cache of names, never authority.",
        "additionalProperties": {
          "type": "object",
          "required": [
            "name",
            "kind"
          ],
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1,
              "description": "The account's name, which --account and TONBO_ACCOUNT take."
            },
            "kind": {
              "type": "string",
              "pattern": "^(user|organization)$",
              "description": "`user` for the personal account."
            },
            "role": {
              "type": [
                "string",
                "null"
              ],
              "description": "The person's role when the cache was written; display only."
            }
          }
        }
      }
    }
  },
  "examples": {
    "usable": [
      {
        "version": 2,
        "session": {
          "id": "30000000-0000-4000-8000-000000000003",
          "secret": "tbs_secret",
          "expires_at": "2027-05-02T00:00:00.000Z"
        },
        "user_id": "40000000-0000-4000-8000-000000000004",
        "device_id_sha256": "342ace7df588b4b741e10d57aeab9d9a79dab7cc931ddc50204c5bf381c96415",
        "personal_account_id": "10000000-0000-4000-8000-000000000001"
      },
      {
        "version": 2,
        "session": {
          "id": "30000000-0000-4000-8000-000000000003",
          "secret": "tbs_secret",
          "expires_at": "2027-05-02T00:00:00.000Z"
        },
        "user_id": "40000000-0000-4000-8000-000000000004",
        "device_id_sha256": "342ace7df588b4b741e10d57aeab9d9a79dab7cc931ddc50204c5bf381c96415",
        "personal_account_id": "10000000-0000-4000-8000-000000000001",
        "default_account_id": "10000000-0000-4000-8000-0000000000a1",
        "accounts": {
          "10000000-0000-4000-8000-000000000001": {
            "name": "sam",
            "kind": "user",
            "role": "owner"
          },
          "10000000-0000-4000-8000-0000000000a1": {
            "name": "acme",
            "kind": "organization",
            "role": "member"
          }
        }
      }
    ],
    "unusable": [
      {
        "version": 1,
        "account_id": "10000000-0000-4000-8000-000000000001",
        "key_id": "20000000-0000-4000-8000-000000000002",
        "key": "tbo_secret",
        "expires_at": null
      },
      {
        "version": 2,
        "session": {
          "id": "30000000-0000-4000-8000-000000000003",
          "secret": "tbo_secret",
          "expires_at": "2027-05-02T00:00:00.000Z"
        },
        "user_id": "40000000-0000-4000-8000-000000000004",
        "device_id_sha256": "342ace7df588b4b741e10d57aeab9d9a79dab7cc931ddc50204c5bf381c96415",
        "personal_account_id": "10000000-0000-4000-8000-000000000001"
      },
      {
        "version": 2,
        "session": {
          "id": "30000000-0000-4000-8000-000000000003",
          "secret": "tbs_secret",
          "expires_at": null
        },
        "user_id": "40000000-0000-4000-8000-000000000004",
        "device_id_sha256": "342ace7df588b4b741e10d57aeab9d9a79dab7cc931ddc50204c5bf381c96415",
        "personal_account_id": "10000000-0000-4000-8000-000000000001"
      },
      {
        "version": 2,
        "session": {
          "id": "30000000-0000-4000-8000-000000000003",
          "secret": "tbs_secret",
          "expires_at": "2027-05-02T00:00:00.000Z"
        },
        "user_id": "40000000-0000-4000-8000-000000000004",
        "personal_account_id": "10000000-0000-4000-8000-000000000001"
      },
      {
        "version": 2,
        "session": {
          "id": "30000000-0000-4000-8000-000000000003",
          "secret": "tbs_secret",
          "expires_at": "2027-05-02T00:00:00.000Z"
        },
        "user_id": "40000000-0000-4000-8000-000000000004",
        "device_id_sha256": "342ace7df588b4b741e10d57aeab9d9a79dab7cc931ddc50204c5bf381c96415",
        "personal_account_id": "10000000-0000-4000-8000-000000000001",
        "accounts": {
          "10000000-0000-4000-8000-0000000000a1": {
            "name": "acme",
            "kind": "team"
          }
        }
      },
      {
        "version": 3,
        "session": {
          "id": "30000000-0000-4000-8000-000000000003",
          "secret": "tbs_secret",
          "expires_at": "2027-05-02T00:00:00.000Z"
        },
        "user_id": "40000000-0000-4000-8000-000000000004",
        "device_id_sha256": "342ace7df588b4b741e10d57aeab9d9a79dab7cc931ddc50204c5bf381c96415",
        "personal_account_id": "10000000-0000-4000-8000-000000000001"
      }
    ]
  }
}
