olares-shared

name: olares-shared version: 4.3.0 description: "Set up and manage the Olares login/identity that every other olares-cli skill depends on — one profile per Olares ID, keychain-stored tokens, transparent token refresh, and auth-error recovery. Use for Olares ID, profile, login, 2FA/TOTP, refresh token, keychain, and auth errors (token rejected / invalidated / not logged in)." compatibility: Requires olares-cli on PATH metadata: openclaw: requires: bins: - olares-cli

olares-cli shared rules

Foundation for every other olares-cli skill. Every business verb under cluster / files / market / settings / dashboard rides the active profile's token. Read this first.

This skill also hosts the cross-skill platform model in references/olares-platform.md — the userspace storage model, uid-1000 run identity, system-managed drive/Home dirs, app/namespace & networking, system middleware, and version/semver. files / chart / cluster link there (one hop) instead of re-describing it. That reference is pure platform model and needs no login.

It also hosts the application state machine in references/olares-platform-appstate.md — app-service's lifecycle states/transitions, per-state allowed operations, backend fail TTLs, single-download serialization, what running actually proves, and why progress is unreliable. market / chart / doctor link there instead of re-stating these backend facts. Also pure platform contract, no login.

Source of truth for flags & syntax is always olares-cli profile --help. This file only carries what --help cannot give: the profile mental model, agent-driven login flow, token-storage backends, refresh semantics, and the error → fix matrix.

When to use

• First time operating on an Olares / a given Olares ID (not logged in yet) — set up the profile
• Switching identity between several Olares IDs
• Any olares-cli command failed with an auth error (token invalidated / not logged in / 2FA required)
• Keywords: Olares ID, profile, login, 2FA/TOTP, refresh token, keychain, server rejected the access token, refresh token ... became invalid, no access token, already authenticated

Skill suite map (routing source of truth)

The olares-cli skills ship and install as one suite; each owns a distinct slice. This is the canonical intent->skill map — a skill's own ## When to use lists its scope and points here for everything else.

The four-skill develop->deploy->debug combo: porting and running your own app usually loads olares-chart (package + deploy + chart fixes), olares-market (lifecycle), this olares-shared (platform facts), and olares-doctor (runtime diagnosis) together. chart owns fixes that mean editing your chart; doctor owns figuring out the root cause regardless of who deployed the app.

Host-side maintenance (cluster install, node join, OS upgrade, GPU drivers) is NOT a skill — it's the kubeconfig-based olares-cli node / os / gpu trees, separate from this profile-based suite.

Profile model

One profile = one Olares instance + one user identity, keyed by olaresId (e.g. alice@olares.com). Each profile owns its own access_token / refresh_token pair, stored in the OS keychain.

There is no auth login / auth logout namespace and no per-invocation --profile override flag. Everything lives under profile. "Logout" is profile remove. Identity is whichever profile is currently selected; to target a different one, run olares-cli profile use <name> first.

Login modes

Mode A — password (+ optional TOTP)

olares-cli profile login --olares-id <olaresId>

• Interactive: prompts for password (echo disabled); prompts for TOTP if 2FA is enabled.
• Scripted: pipe via --password-stdin; if 2FA is on, you MUST also pass --totp <code> because there is no second prompt. (Passwords only ever go through the TTY or --password-stdin — see Security rules.)

Mode B — existing refresh_token

olares-cli profile import --olares-id <olaresId> --refresh-token "$OLARES_REFRESH_TOKEN"

Exchanges the refresh_token for an access_token once via /api/refresh and writes both to the keychain. Read the token from an env var or secret manager — never inline plaintext.

Agent-driven login (recommended)

When you (an AI agent) drive the login on the user's behalf, do NOT pass password / TOTP as command-line arguments. Spawn olares-cli profile login --olares-id <id> as a background process so it parks at the password prompt, forward the prompt to the user, and read its output after the command exits to confirm success.

Switching and inspecting profiles

profile list output:

   NAME             OLARES-ID              STATUS        VERSION
*  alice            alice@olares.com       logged-in     1.12.6
   bob              bob@olares.com         expired        1.12.5
   eve              eve@olares.com         invalidated   -
   frank            frank@olares.com       never         -

STATUS reflects only what the local token store can prove without a network call (no (Xh Ym) time-to-expiry is printed). The VERSION column is the cached Olares backend version (- until a login eager-fetch or a version-aware command populates it; --refresh-version re-reads it). The leading * marks the current profile; profile use accepts either the NAME alias or the olaresId.

Auth-readiness gate

The single rule every skill uses to decide "proceed, or stop for login?" — proceed by default. Other skills link here instead of re-deriving it; the STATUS table above is the source for what each value means.

• Pre-flight (you ran profile list first): proceed on logged-in and expired. An expired access token auto-refreshes on the first call (see Automatic token refresh), so it is NOT a reason to stop. Stop only when the CLI has no credential it can send or refresh: never (no profile) or invalidated (refresh grant dead). The rare corrupt states — unknown (token store unreadable) and logged-in (unparseable token) — also fail at command time and recover the same way (profile login).
• Reactive (a command came back with an auth error): don't pre-empt it — run the command and read the result. Only the typed errors ErrNotLoggedIn (no access token …) and ErrTokenInvalidated (refresh token … became invalid) mean "must log in" → profile login / import. A 401/403/459 is auto-refreshed and retried once for you; a network / 5xx error is transient — surface it, do not preemptively log in, and do not build retry loops on top of auth errors.

ResolveProfile hands even a stale JWT to the refreshing transport and no command pre-flights on the STATUS string, which is why expired never blocks. When the decision is stop, tell the user which command to run — never log in on their behalf without being asked (see the agent-driven login flow above).

Token storage

After login / import succeeds, the CLI prints token stored via <backend> (service "olares-cli", account "<id>"). If the backend resolves to file-fallback (sandboxed / CI environments), be aware the token now sits in a file with different security properties than the system keychain.

The plaintext ~/.olares-cli/tokens.json from older builds is deprecated — if a user upgraded and suddenly appears "logged out", profile login is the fix.

Re-authentication rules

profile login and profile import both reject the case "a still-valid token already exists for this olaresId" — to force-overwrite, run profile remove <id> first. Expired / invalidated / never-logged-in profiles get the new token written in place; this lets scripts call login after invalidated without an extra remove step.

Automatic token refresh

The CLI rotates expired access_tokens transparently. Users do NOT need to run profile login just because their access_token aged out — only when the refresh_token itself becomes invalid. This is why a profile list STATUS of expired is not a blocker: the very next business command swaps the stale token out and succeeds. For the proceed/stop decision built on this, see the Auth-readiness gate above.

• Replayable requests (every JSON verb, files cat, files download, files rm, market verbs, …): on 401/403/459 the transport calls /api/refresh and retries once with the new token. (459 is Olares' edge / Authelia "auth failed" status, treated like 401/403.)
• Streaming uploads (files upload chunks): pre-decode the JWT exp; if within 60s of expiry, refresh BEFORE sending, because once a *os.File chunk is consumed it can't be replayed on a 401.

Across goroutines AND across concurrent olares-cli processes, /api/refresh is hit at most once per stale token (in-process mutex + cross-process flock).

Do not implement custom retry/backoff loops on top of auth errors. Once you see ErrTokenInvalidated or ErrNotLoggedIn, only profile login / profile import will help.

Auth error recovery table

These auth errors are deterministic — pick the fix from the table above (see also the auto-refresh rules), don't loop.

Security rules

• Never invent a --password <plaintext> argument (it does not exist). Passwords go through the TTY or --password-stdin fed by a secret pipe.
• Never echo access_token / refresh_token to the terminal. When passing a refresh_token to profile import, source it from an environment variable: --refresh-token "$OLARES_REFRESH_TOKEN".
• Confirm intent before write/delete actions (profile remove, files rm, files upload --overwrite, cluster pod delete, …). Do not act unilaterally on the user's behalf.
• TOTP is not a password — it is single-use and short-lived, so the CLI echoes it to make manual entry less error-prone. Never persist a TOTP in a shared script.