Module auth 

Credential storage for torii — both the gitorii.com cloud API key and the per-platform tokens (GitHub, GitLab, Gitea, Forgejo, Codeberg, crates.io) that the HTTPS transport and platform APIs use.

Storage layout (~/.config/torii/auth.toml, chmod 600 on Unix):

[cloud]
key = "gitorii_sk_…"
endpoint = "https://api.gitorii.com"

[tokens]
github = "ghp_…"
gitlab = "glpat-…"
gitea = "…"
forgejo = "…"
codeberg = "…"
cargo = "cio_…"

For backwards compatibility we also read the legacy formats:

• auth.toml with key = … / endpoint = … at the top level (the pre-0.7.1 cloud-only format) — auto-rewrites to the new sectioned format on the next save.
• config.toml’s [auth] block (where platform tokens used to live) — also auto-migrated to auth.toml [tokens] on the next mutating call.

Token precedence (resolved by resolve_token):

1. Provider-specific env var (GITHUB_TOKEN/GH_TOKEN, GITLAB_TOKEN, CARGO_REGISTRY_TOKEN, …)
2. Generic env var TORII_HTTPS_TOKEN
3. Local repo config (<repo>/.torii/auth.toml, same schema as global)
4. Global config (~/.config/torii/auth.toml)

Env var TORII_API_KEY overrides the cloud key the same way.

Structs

ApiKey

AuthStore

Every credential torii knows about, in one struct. tokens is a map rather than fixed fields so auth.toml can keep older or newer entries without parser breakage when we add providers.

ResolvedToken

Enums

TokenSource

Where a token came from, surfaced by torii auth doctor.

Constants

PROVIDERS

Recognised provider names. The CLI accepts these; readers ask by the same string. Add new entries here only — every other module looks them up by name.

Functions

default_endpoint

delete

Delete just the cloud entry (preserves platform tokens).

drop_token_cache

Public variant used by callers that mutated auth.toml out-of-band (e.g. the TUI’s auth ops spawn a child process via torii auth oauth … — the child invalidates its own cache when it calls set_token, but the parent TUI has no way of knowing that without an explicit cue). Call this after any operation that could have changed a token outside this process.

load

Read the cloud API key (env wins).

load_global

Read the whole global store from disk (no env override applied — that’s load / resolve_token’s job).

load_local_raw

Read a local (per-repo) store. Returns empty if the repo has no .torii/auth.toml. Never falls back to global — that’s the merge step’s job (resolve_token).

normalise_provider

Validate the provider name against the known list. Case-insensitive match; returns the canonical lowercase form.

refresh_if_needed

0.7.39 — best-effort auto-refresh. Returns Ok(true) if a refresh actually happened (new access token persisted, cache cleared), Ok(false) if nothing was due, Err on real errors. Safe to call from any path; failures are non-fatal (the caller still sees the stale token and the platform will return 401 if it’s expired, at which point a manual re-auth is the answer).

remove_token

resolve_token

repo_path is the path to the repo (. is usually fine); pass it even when you don’t expect a local override, the local lookup is cheap when the file doesn’t exist.

save_cloud

Persist a cloud key — kept as a back-compat shim for torii auth login callers that don’t know about the wider store yet.

save_global

save_local

set_token

set_token_with_expiry

Same as set_token, plus an optional ISO-8601 expiration timestamp. Stored under [token_expires] and surfaced by torii auth doctor as a “rotate before X” warning. Passing None clears any existing expiration entry for the provider (e.g. switching from a TTL-managed PAT to a stable bot token).

set_token_with_refresh

0.7.39 — store access_token + refresh_token + an expires_at derived from expires_in. Called by the OAuth worker so the next resolve_token can auto-refresh transparently. local is always None here because refresh tokens are user-scoped, not repo- scoped.

token_expires_at

Return the recorded expiration timestamp for provider, if any. Reads global only — the same precedence as resolve_token would be misleading for expirations (a local override of the token usually means the local one has its own TTL semantics).