@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.5

package/docs/contracts/environment-vocabulary.md

@@ -0,0 +1,195 @@
+# Environment vocabulary
+
+**Authority:** `agentsam-sdk`  
+**Companion:** [`docs/AUTH_IDENTITY_CONTRACT.md`](../AUTH_IDENTITY_CONTRACT.md) · `packages/identity/src/contracts/auth-config.js`  
+**Rule:** names and classification only. Never log or document secret values. Do not remove aliases until call-site audit clears them.
+
+This document is the law for env naming across AgentSam CLI, Local Studio, Identity, and Vault. It exists so sessions stop inventing tribal aliases.
+
+**Portable Local Studio rule:** the packaged UI is portable, while storage authority is installation policy. Official connected AgentSam builds use the configured identity service/main DB for account truth, local SQLite for device state, and the OS secure store for credentials. `IAM_*` variables are optional remote-adapter/deployment configuration and must never turn a company host into intrinsic APP identity. Explicit standalone products may choose the SQLite identity adapter.
+
+---
+
+## Three lanes (do not flatten)
+
+| Lane | Variables | Who it authenticates | Used by |
+| --- | --- | --- | --- |
+| **Account / platform** | `AGENTSAM_API_KEY` | The human (or delegated account) using AgentSam | CLI, SDK, Local Studio user work |
+| **Machine / bridge** | `AGENTSAM_BRIDGE_KEY` | A worker, VM, ExecOS front-door, or CI host talking to AgentSam infrastructure | Workers, iam-tunnel agents, CAD/build services |
+| **OAuth app (Identity)** | `IAM_CLIENT_ID`, `IAM_CLIENT_SECRET`, `IAM_OAUTH_ISSUER` (+ compat `IAM_ORIGIN`) | An installation as a client of an explicitly configured remote identity authority | Hosted/customer Worker or other remote-identity adapter; **not required by portable Local Studio desktop** |
+
+Provider API keys (`OPENAI_*`, `CLOUDFLARE_API_TOKEN`, …) are a **fourth** lane: external vendor credentials managed by vault/Connections — never aliases of the three lanes above.
+
+### Customer mental model
+
+```text
+User 123 is accredited by Inner Animal Media (company/platform Identity)
+     ↓
+On User 123's machine:
+  source ~/.agentsam/load-agent-env.sh
+    → eval "$(agentsam env shell --profile default)"
+    → loads THEIR AGENTSAM_API_KEY + IAM_CLIENT_ID + IAM_OAUTH_ISSUER
+       from THEIR keychain/vault (never another user's home)
+     ↓
+User 123 runs `agentsam terminal enroll … --pair`
+     → AGENTSAM_BRIDGE_KEY written for ONE terminal_connection
+       into ~/.execos/profiles/<instance_id>.env on THAT machine
+     ↓
+User 123 connects Cloudflare / GitHub / GCP / models as Provider Connections
+```
+
+`AGENTSAM_API_KEY` = “what can *this account* do on AgentSam.”  
+`AGENTSAM_BRIDGE_KEY` = “what can *this enrolled machine connection* prove to ExecOS/IAM” (one `terminal_connection`; `IAM_CONNECTION_KEY` retired).  
+`IAM_CLIENT_ID` + `IAM_OAUTH_ISSUER` = platform Identity wiring so User 123’s CLI/app can talk to our issuer (plus `IAM_CLIENT_SECRET` only on server/workers).
+
+#### `load-agent-env.sh` vs `env.d/inneranimalmedia.env`
+
+| Path | Role |
+| --- | --- |
+| `source ~/.agentsam/load-agent-env.sh` | **Canonical customer path.** Resolves `--profile default` from that user’s keychain/vault. This is where account accreditation belongs. |
+| `~/.agentsam/env.d/inneranimalmedia.env` | **Per-machine compat file** written by `agentsam env init/export` under **that user’s** `$HOME`. Not a shared template of anyone else’s secrets. User 123 never receives Sam’s `env.d` file — they get their own after *their* `api-key create` / `env init`. |
+
+Do not copy another operator’s `~/.agentsam/env.d/*.env` between machines. Mint or export on the destination account.
+
+---
+
+## AgentSam keys vs Google Cloud service-account keys
+
+These are **parallel authority systems**. Do not rename Google `KEY_ORIGIN` fields in place.
+
+| Concept | Issuer | Lives in | Authenticates | Google `KEY_ORIGIN` analogy (AgentSam overlay only) |
+| --- | --- | --- | --- | --- |
+| `AGENTSAM_API_KEY` (`aak_*`) | Inner Animal Media / AgentSam | vault / keychain | Human/account on AgentSam platform | `USER_MANAGED` + `INNERANIMALMEDIA_PROVIDED` |
+| `AGENTSAM_BRIDGE_KEY` | Inner Animal Media (machine mint) | Worker secret / vault | Machine↔ExecOS/Worker to AgentSam APIs | `SYSTEM_MANAGED` + `INNERANIMALMEDIA_PROVIDED` |
+| Google user ADC / `gcloud auth` | Google user OAuth | gcloud / ADC | Human operating GCP | n/a (user session, not SA key) |
+| GCP SA `SYSTEM_MANAGED` key | Google | Google IAM | Google runtime for that SA | stays `GOOGLE_PROVIDED` |
+| GCP SA `USER_MANAGED` JSON key | Google (operator-downloaded) | whoever stored the JSON | That SA via private key file | stays `GOOGLE_PROVIDED` — prefer delete/rotate |
+
+**Product UI may show a unified inventory table** with an AgentSam overlay column (`agentsam_origin_label`).  
+**Google’s API metadata must remain truthful** (`GOOGLE_PROVIDED`). We never claim Google minted an InnerAnimalMedia key.
+
+How Local Studio Connections compose:
+
+```text
+Local Studio
+  ├── Identity login          → IAM_CLIENT_* + browser session
+  ├── Account API             → AGENTSAM_API_KEY
+  ├── This Mac / ExecOS       → AGENTSAM_BRIDGE_KEY (+ local device provider)
+  └── Google Cloud connection → user's Google OAuth + discovered projects/VMs/SAs/billing
+```
+
+`agentsam google-cloud iam service-accounts list` discovers **customer GCP** workload identities.  
+It does **not** mint `AGENTSAM_*` keys into Google IAM.
+
+See also: [`docs/contracts/google-cloud-oauth-setup.md`](./google-cloud-oauth-setup.md) for Path A (`agentsam gcloud auth login`) vs Path B (hosted `agentsam.inneranimalmedia.com` Google OAuth).
+
+---
+
+## Classification legend
+
+| Class | Meaning |
+| --- | --- |
+| `canonical` | Prefer in new code |
+| `compatibility_alias` | Keep until zero call sites |
+| `provider_native` | Owned by external CLI/SDK |
+| `application_config` | Non-secret wiring |
+| `user_credential` | Human/account delegated secret |
+| `machine_credential` | Host/integration secret |
+| `server_secret` | Worker/server only — never browser |
+| `browser_safe` | Public by OAuth design |
+| `deprecated` | Stop using |
+| `unknown` | Needs owner decision |
+
+---
+
+## Normalization table
+
+| current name | canonical name | owner | secret? | class | migration |
+| --- | --- | --- | --- | --- | --- |
+| `AGENTSAM_API_KEY` | same | AgentSam account | yes | user_credential / canonical | vault + keychain via `agentsam env` |
+| `IAM_API_KEY` | `AGENTSAM_API_KEY` | legacy | yes | compatibility_alias | rewrite call sites |
+| `AGENTSAM_SDK_TOKEN` / `AGENTSAM_SDK_KEY` | `AGENTSAM_API_KEY` | retired docs | yes | deprecated | docs scrub only |
+| `AGENTSAM_BRIDGE_KEY` | same | ExecOS / Worker bridge | yes | machine_credential / canonical | never alias to API key |
+| `EXECOS_KEY` | `AGENTSAM_BRIDGE_KEY` | IAM worker envs | yes | compatibility_alias | dual-read then single |
+| `IAM_OAUTH_ISSUER` | same | Identity protocol | no | application_config / canonical | preferred issuer |
+| `IAM_ORIGIN` | `IAM_OAUTH_ISSUER` | Identity | no | compatibility_alias | fallback only |
+| `IAM_CLIENT_ID` | same | Identity OAuth client | no* | browser_safe | minted at install/build |
+| `IAM_CLIENT_SECRET` | same | Identity OAuth client | yes | server_secret | wrangler secret / vault |
+| `CLOUDFLARE_API_TOKEN` | same | Cloudflare | yes | user/machine credential | product: OAuth Connection first |
+| `CLOUDFLARE_ACCOUNT_ID` | same | Cloudflare | no | application_config | discover via whoami when possible |
+| `CLOUDFLARE_OAUTH_CLIENT_ID` | same | Identity CF login | no* | browser_safe | Connections + login |
+| `CLOUDFLARE_OAUTH_CLIENT_SECRET` | same | Identity CF login | yes | server_secret | optional for PKCE-only |
+| `GITHUB_TOKEN` / `GH_TOKEN` | prefer `gh` keyring / GitHub App | GitHub | yes | provider_native | unset stale shell tokens |
+| `GITHUB_CLIENT_ID` / `SECRET` | same | Identity login | mixed | OAuth app | BYOK login lane |
+| `GOOGLE_CLIENT_ID` / `SECRET` | same | Identity login | mixed | OAuth app | BYOK login lane |
+| `GEMINI_API_KEY` | same | Google AI | yes | user_credential | vault |
+| `GOOGLE_API_KEY` / `GOOGLE_AI_API_KEY` / `GOOGLE_KEY` | `GEMINI_API_KEY` | drift | yes | compatibility_alias | dual-read in resolver |
+| `OPENAI_API_KEY` | same | OpenAI | yes | user_credential | vault |
+| `ANTHROPIC_API_KEY` | same | Anthropic | yes | user_credential | vault |
+| `CURSOR_API_KEY` | same | Cursor | yes | user_credential | vault |
+| `XAI_API_KEY` | same | xAI | yes | user_credential | optional |
+| `GCP_PROJECT_ID` / `GCP_ZONE` / `GCP_VM_NAME` | same | ops / Connections | no | application_config | prefer discovery over hardcode |
+
+\*OAuth client IDs are public-by-design; still do not log them next to secrets.
+
+---
+
+## Storage expectations
+
+| Credential | Expected storage |
+| --- | --- |
+| `AGENTSAM_API_KEY` | That user’s macOS Keychain / vault via `agentsam api-key create --store keychain --activate`; loaded by `source ~/.agentsam/load-agent-env.sh` |
+| `IAM_CLIENT_ID` / `IAM_OAUTH_ISSUER` | Same account profile (`--profile default` / InnerAnimalMedia provider) — platform accreditation, not shared across users |
+| `AGENTSAM_BRIDGE_KEY` | That machine’s `~/.execos/profiles/<instance_id>.env` via `agentsam terminal enroll … --pair` |
+| Provider API keys | Encrypted vault + OS keychain (`agentsam providers` / `agentsam env`) |
+| OAuth client secrets | Wrangler secrets / vault — never frontend bundles |
+| `gcloud` user session | gcloud ADC (outside AgentSam until GCP Connection ships) |
+| `gh` | macOS keyring (`gh auth`) |
+| Compat plaintext | `~/.agentsam/env.d/*.env` only via `agentsam env export` — opt-in per-user fallback under **their** home |
+
+### macOS Keychain prompt
+
+AgentSam uses the **macOS Keychain** (Keychain Access / Security framework), not a separate “keychainos.” When a credential is stored with `--store keychain`, later reads may prompt for your Mac login password or Touch ID depending on the item’s ACL.
+
+Useful flows:
+
+```bash
+agentsam api-key create --name "$(hostname)" --store keychain --activate
+agentsam providers   # interactive vault/keychain setup
+eval "$(agentsam env shell --profile default)"
+```
+
+If nothing prompts, the item may already be unlocked for this login session, or the value is still coming from process environment (ambient `export`). Prefer keychain/vault over shell exports for the customer path.
+
+---
+
+## Failure → next-step protocol (product law)
+
+When auth/capability fails, AgentSam must not stop at “denied.” Mirror gcloud’s deterministic help:
+
+1. **What failed** (provider, operation, reason code)
+2. **What is configured** (names only — never values)
+3. **Exact next command** (`agentsam login`, `agentsam providers`, `gcloud auth login`, …)
+4. **Optional browser path** — “Press Enter to open …” for OAuth/consent/scopes
+5. **Cheatsheet link** — `agentsam cheat-sheet` / docs URL
+
+Target CLI surface (proposal):
+
+```text
+agentsam                  top-level groups (gcloud-like)
+agentsam cheat-sheet      common flows
+agentsam credentials audit [--json --names-only --verify --drift]
+agentsam connections      provider connections (CF / GH / GCP / local)
+agentsam compute          GCP/VM helpers (wrap gcloud safely)
+agentsam billing          cost/billing discovery (not --billing-project)
+```
+
+`--billing-project` on gcloud is **API quota/billing attribution for that CLI call**, not a cost dashboard. Cost monitoring is `gcloud billing` / Cloud Console Billing — AgentSam should wrap *that*, not overclaim `--billing-project`.
+
+---
+
+## Related audits
+
+Local machine audits (not committed; may contain fingerprint metadata):
+
+- `~/.agentsam/audits/AUTH-ENV-AUDIT-2026-09-25.md`

package/docs/contracts/google-cloud-oauth-setup.md

@@ -0,0 +1,199 @@
+# Google Cloud OAuth setup for AgentSam
+
+Two different Google login paths. Do not conflate them.
+
+## Path A — CLI operator auth
+
+### Default: Agent Sam hosted Google (`agentsam gcloud auth login`)
+
+```bash
+agentsam gcloud auth login
+```
+
+**Desktop PKCE (`--desktop`):** loopback using `GOOGLE_DESKTOP_CLIENT_ID` (Console type
+**Desktop app**, no secret). Some Google Auth Platform Desktop clients still return
+`client_secret is missing` on token exchange even though Console shows Type=Desktop —
+that is a Google classification quirk, not something AgentSam can invent a secret for.
+
+**Default CLI path (recommended):** Studio Web OAuth broker — uses `GOOGLE_CLIENT_ID` +
+Worker `GOOGLE_CLIENT_SECRET`, then hands tokens to the CLI over loopback.
+
+Uses the **same** Authorized redirect URI as Studio login (no extra Console URI):
+
+```text
+https://agentsam.inneranimalmedia.com/api/oauth/google/callback
+```
+
+CLI broker states are prefixed `cli_` so the Worker can share that path with identity login.
+
+```bash
+agentsam gcloud auth login              # Studio Web broker (default)
+agentsam gcloud auth login --desktop    # native Desktop PKCE
+```
+
+### Hosted identity (`agentsam gcloud auth login --web`)
+
+Shows the live start URL and waits for **Enter** to open the system browser:
+
+```text
+https://agentsam.inneranimalmedia.com/api/oauth/google/start
+```
+
+Consent branding: **Continue to Agent Sam** (your `GOOGLE_CLIENT_ID`).
+
+| Piece | Value |
+| --- | --- |
+| Consent UI | Your OAuth app name (Agent Sam / Local Studio) |
+| OAuth client | Your Web client (`GOOGLE_CLIENT_ID` + Worker `GOOGLE_CLIENT_SECRET`) |
+| Redirect | `https://agentsam.inneranimalmedia.com/api/oauth/google/callback` |
+
+### Optional: Google Cloud SDK (`agentsam gcloud auth login --sdk`)
+
+Wraps native **Google Cloud SDK** OAuth when you need ADC / `gcloud` CLI identity on the machine:
+
+```bash
+agentsam gcloud auth login --sdk
+# same engine as:
+gcloud auth login
+```
+
+| Piece | Value |
+| --- | --- |
+| Consent UI | Google’s “Google Cloud SDK wants to access your Google Account” |
+| OAuth client | Google’s public SDK client (`*.apps.googleusercontent.com`) |
+| Redirect | `http://localhost:8085/` (Google-controlled — **not** AgentSam) |
+| Stores | gcloud user credentials / ADC on the machine |
+
+**You do not create a Client ID for the `--sdk` path.** Installing `gcloud` is enough.
+
+---
+
+## Path B — AgentSam-hosted Google connection (web / Local Studio)
+
+For **Identity login** and **provider Connections** in Local Studio / AgentSam web, use an OAuth client **you** own, with HTTPS redirects on the **AgentSam** host.
+
+### Primary redirect (AgentSam)
+
+```text
+https://agentsam.inneranimalmedia.com/api/oauth/google/callback
+```
+
+Start / authorize:
+
+```text
+https://agentsam.inneranimalmedia.com/api/oauth/google/start
+```
+
+### Secondary (InnerAnimalMedia dashboard only)
+
+`https://inneranimalmedia.com/api/oauth/google/callback` is the **IAM worker/app** Google login — not AgentSam Local Studio. Register it only if the dashboard product still needs Google Connect there. Do **not** point AgentSam Connections at the IAM callback.
+
+| Product surface | Callback |
+| --- | --- |
+| AgentSam / Local Studio | `https://agentsam.inneranimalmedia.com/api/oauth/google/callback` |
+| InnerAnimalMedia dashboard | `https://inneranimalmedia.com/api/oauth/google/callback` |
+| AgentSam CLI (`agentsam login`) | Loopback `http://127.0.0.1:<port>/callback` (RFC 8252) |
+| `agentsam gcloud auth login` | Google SDK `http://localhost:8085/` (Path A) |
+
+Loopback remains correct for **native AgentSam CLI** login when the shell
+has the same OAuth client the Worker uses (`IAM_CLIENT_ID=iam_agentsam_sdk_web`
+on Local Studio Production) — RFC 8252 PKCE. Do not invent alternate client ids.
+Hosted HTTPS redirects are for browser apps and Local Studio.
+
+---
+
+## Setup checklist (Path B — your Google Cloud Console)
+
+Project: prefer `gen-lang-client-0684066529` (InnerAnimalMedia) once billing ownership is clear.
+
+### 1. Enable APIs
+
+APIs & Services → Enable APIs:
+
+- Cloud Resource Manager API  
+- IAM API  
+- Compute Engine API  
+- (optional) Vertex AI, BigQuery, Cloud Billing API — as needed for Connections discovery  
+
+### 2. Configure OAuth consent screen
+
+APIs & Services → OAuth consent screen:
+
+- User type: **External** (or Internal if Workspace-only)
+- App name: `Agent Sam`
+- Support email / developer contact: your IAM email
+- Scopes (start minimal for login; expand for Cloud Connections):
+  - `openid`
+  - `email`
+  - `profile`
+  - For Cloud resource discovery later: add Cloud Platform scopes only when Connections needs them (`https://www.googleapis.com/auth/cloud-platform` is powerful — prefer incremental scopes)
+
+Publishing status: **Testing** while iterating; add test users (you, Connor).
+
+### 3. Create OAuth client
+
+APIs & Services → Credentials → Create credentials → **OAuth client ID**:
+
+- Application type: **Web application**
+- Name: `Agent Sam Local Studio / Identity`
+- Authorized JavaScript origins (if needed):
+  - `https://agentsam.inneranimalmedia.com`
+  - `https://inneranimalmedia.com` (only if IAM dashboard shares the client)
+- Authorized redirect URIs (AgentSam-first):
+  - `https://agentsam.inneranimalmedia.com/api/oauth/google/callback` ← **required for AgentSam**
+  - `https://inneranimalmedia.com/api/oauth/google/callback` ← optional IAM dashboard only
+
+Copy:
+
+- Client ID → `GOOGLE_CLIENT_ID`
+- Client secret → `GOOGLE_CLIENT_SECRET` (Wrangler **secret**, never frontend)
+
+### 4. Install on AgentSam hosts
+
+```bash
+# example — production worker secrets
+npx wrangler secret put GOOGLE_CLIENT_SECRET
+# GOOGLE_CLIENT_ID may already be a plain var in wrangler.jsonc
+```
+
+Local Studio / SDK `.env` (server only):
+
+```bash
+GOOGLE_CLIENT_ID=....apps.googleusercontent.com
+GOOGLE_CLIENT_SECRET=...   # server-only
+```
+
+### 5. Prove it
+
+```bash
+# Operator CLI (Path A) — Google Cloud SDK consent
+agentsam gcloud auth login
+agentsam google-cloud doctor
+
+# Hosted Identity (Path B) — browser
+open "https://agentsam.inneranimalmedia.com/api/oauth/google/start"
+# or Local Studio Connections → Google
+```
+
+### 6. Service accounts (workload) vs your user OAuth
+
+| Kind | Purpose |
+| --- | --- |
+| Your user via `gcloud auth login` | Operator / discovery / admin on the Mac |
+| `agent-sam-vertex@…` etc. | Workload SAs inside the GCP project |
+| `AGENTSAM_API_KEY` / `AGENTSAM_BRIDGE_KEY` | AgentSam platform — **not** Google keys |
+
+See also: `docs/contracts/environment-vocabulary.md` and `~/.agentsam/audits/GCP-SA-DISPOSITION-2026-09-25.md`.
+
+---
+
+## What “agentsam.inneranimalmedia.com instead of localhost” means
+
+| Flow | Redirect host |
+| --- | --- |
+| `gcloud auth login` / `agentsam gcloud auth login` | Google’s `localhost` (immutable without custom client + custom token broker) |
+| `agentsam login` (InnerAnimalMedia account) | Loopback `127.0.0.1` for CLI; authorize already on `inneranimalmedia.com` |
+| AgentSam / Local Studio Google connect | **`https://agentsam.inneranimalmedia.com/api/oauth/google/callback`** |
+| IAM dashboard Google connect | `https://inneranimalmedia.com/api/oauth/google/callback` (separate product) |
+
+Building a fully custom “AgentSam Google Cloud SDK” that uses only `agentsam.inneranimalmedia.com` redirects (no gcloud client) is a larger Connections product — token relay, refresh, and API wrappers — tracked separately from wrapping `gcloud auth login`.

package/docs/local-studio/WORKMODE_DONOR_NOTES.md

@@ -100,7 +100,7 @@ Worker secrets (vault + app)
 openssl rand -base64 32 | npx wrangler secret put VAULT_MASTER_KEY
 
 # optional aliases used by platform workers
-npx wrangler secret put VAULT_KEY          # same value if you keep one master
+npx wrangler secret put VAULT_MASTER_KEY  # Worker AES-256-GCM master key (not a personal BYOK)
 npx wrangler secret put BETTER_AUTH_SECRET
 npx wrangler secret put XAI_API_KEY        # server-only model calls
 Deploy this Worker (vault API — live)