Metadata-Version: 2.4
Name: arkclaw-webchat-cli
Version: 0.1.0
Summary: CLI to chat with an ArkClaw EE space's Claw over enterprise SSO — zero permanent AK/SK.
Author: ArkClaw Team
Keywords: arkclaw,cli,ee,openclaw,sso,sts
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: typer>=0.12.0
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# ee-claw

A tiny CLI to chat with a **Claw** in an **ArkClaw EE** space from your terminal —
authenticated by your existing **enterprise SSO** session, with **zero permanent
AK/SK** ever stored.

```bash
pip install ee-claw

arkclaw login https://<space>.arkclaw-enterprise-bj.volceapi.com/
arkclaw chat
```

That's it. `login` reuses the SSO session your browser already holds for the
space; `chat` talks to the Claw you last had open there.

## How it works

```
Chrome login (id_token)  →  STS AssumeRoleWithOIDC  →  temporary creds
                         →  GetClawInstanceChatToken →  ChatToken
                         →  OpenClaw WebSocket        →  chat
```

- **`login <space-url>`** reads the `id_token` Chrome already holds for the space
  (you must be logged in there), validates it by exchanging it for **temporary**
  credentials via Volcengine STS, and caches the session in
  `~/.arkclaw/ee_login.json` (mode `0600`). No browser is opened, nothing is
  pasted, **no permanent AK/SK is ever written**.
- **`chat`** uses the cached login to mint a one-time `ChatToken`
  (`GetClawInstanceChatToken`) and opens an OpenClaw WebSocket. Without
  `--clawid` it uses the claw you most recently opened in the browser (read from
  Chrome history); pass `--clawid ci-...` to target a specific one.

## Admin setup (once per space)

The CLI needs one piece of space-level configuration: the **STS role** whose
trust policy accepts the space's enterprise-SSO identity pool and whose
permission policy allows `arkclaw:GetClawInstanceChatToken`. Provide it via
(highest precedence first):

1. `--role-trn trn:iam::<account>:role/<name>`
2. `ARKCLAW_ROLE_TRN` environment variable
3. the space serving `GET <space-url>/.well-known/arkclaw-cli` →
   `{"region": ..., "role_trn": ..., "provider_trn": ...}` (then the user types
   only the URL)

Nothing is hardcoded per space. Region is derived from the URL (override with
`--region`); the OIDC provider is inferred from the token issuer (override with
`--provider-trn`). If no role can be resolved, `login` fails with
`ARKCLAW_E_UNCONFIGURED`.

## Security

The role is a least-privilege bridge: enterprise SSO identity → **1-hour**
temporary credentials that can do exactly **one** thing
(`GetClawInstanceChatToken`) and nothing else in the account. See the error
codes (`ARKCLAW_E_NOLOGIN`, `ARKCLAW_E_STS`, `ARKCLAW_E_UNCONFIGURED`, …) for
clear diagnostics.

## Scope

- Platform: **Chrome on macOS/Linux** (reads Chrome's Local Storage + history).
- This is the ArkClaw EE companion CLI; the general-purpose public SDK is
  `arkclaw-sdk` (standard OIDC login + a2a chat) and lives separately.
