olares-shared

# 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](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.

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

| Skill | Owns | Reach for it when |
|---|---|---|
| [`olares-shared`](SKILL.md) | Profile / login / token refresh / auth-error recovery; hosts the platform model | logging in, switching Olares ID, any auth error |
| [`olares-market`](../olares-market/SKILL.md) | App-store lifecycle: install / uninstall / upgrade / clone / start / stop / cancel; `--mine`; chart upload | installing or managing an app's lifecycle |
| [`olares-settings`](../olares-settings/SKILL.md) | Post-install config (Settings SPA): app entrance / domain / env / policy, users, VPN, network, backup / restore, integrations | changing config of an installed app or the system |
| [`olares-cluster`](../olares-cluster/SKILL.md) | K8s runtime view: pods / workloads / jobs / cronjobs / nodes / namespaces; logs; scale / restart / delete | inspecting or operating running K8s objects |
| [`olares-dashboard`](../olares-dashboard/SKILL.md) | Resource metrics & health: CPU / memory / disk / network / pods / GPU / fan / ranking | "what's the usage / what's eating CPU" |
| [`olares-files`](../olares-files/SKILL.md) | Per-user file API: drive / sync / cache / external; upload / download; share; SMB; Seafile | browsing or moving files / drives |
| [`olares-chart`](../olares-chart/SKILL.md) | Local chart authoring: from-compose / lint / package, then publish | authoring or validating your own chart |

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

| Command | Purpose |
|---------|---------|
| `olares-cli profile login` | Mode A — password (+ TOTP if 2FA is on); auto-creates the profile on first run |
| `olares-cli profile import` | Mode B — bootstrap an access_token from an existing refresh_token |
| `olares-cli profile list` | List every profile (NAME / OLARES-ID / STATUS / VERSION), mark the current one, show login status; `--refresh-version` re-reads the current profile's cached backend version |
| `olares-cli profile use <name\|->` | Switch the current profile; `-` reverts to the previous one (like `cd -`) |
| `olares-cli profile remove <name>` | Delete a profile and its stored token in one shot |

> **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)

```bash
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

```bash
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 | Meaning | Recovery |
|--------|---------|----------|
| `logged-in` | Token valid — JWT exp is in the future, **or** the JWT carries no exp claim (can't verify