fix(cli): use the app's account in a Superset terminal, so pages publish stops failing with "Not a member of organization"

Merged
KI
1mo ago
+376-10

Write-up with before/after evidence: https://app.superset.sh/page/pr-8274-cli-uses-the-app-s-account-in-a-superset-t-42wvyb

Summary

  1. The CLI in a Superset terminal uses the app's account. It asks the workspace's local host-service for an API token and uses it before its own stored login. superset pages publish (and every other org-scoped command) stops failing when the CLI is signed in to a different account than the app.
  2. The "Not a member of organization" error says who is signed in and what to do. This change is server side, so released CLIs show it without an update.

Why / Context

A user (maxk, Slack) tried to publish a Superset page from an agent and got Not a member of organization a1f3ff78…. The agent then fell back to a Claude artifact.

A Superset terminal sets SUPERSET_ORGANIZATION_ID to its workspace's organization. The CLI sends that org in x-superset-organization-id, but it authenticates with its own login (~/.superset/config.json), which is separate from the app's. If that login belongs to another account (an old personal login, or an API key from another account), every org-scoped call fails. superset organization switch cannot help, because the env var overrides it.

How It Works

Host-service (packages/host-service)

  • New host.apiToken query returns the API JWT the host already mints for the account that runs it (JwtApiAuthProvider). It is built on machineOnlyProcedure, so cloud sandboxes refuse it.
  • Expiry. A host started by superset start returns its stored OAuth access token as-is, expired or not. host.apiToken checks exp, invalidates and re-reads once when under five minutes remain, and refuses if the token is still short-lived, so the CLI falls back to refreshing its own login.
  • Relay guard. The tunnel adds the host secret to every request it forwards from the relay. Without a guard, any teammate who can reach the host could take the owner's credential. The changes:
    • The tunnel now stamps x-superset-relayed: 1 on every forwarded HTTP request, overwriting any value the client sent.
    • The HTTP tRPC context sets isLocalCaller only when that header is absent.
    • host.apiToken requires isLocalCaller === true, so it fails closed for any context that does not set it.

CLI (packages/cli)

  • resolveAuth calls readHostApiToken() when the CLI runs in a Superset terminal (SUPERSET_WORKSPACE_ID and SUPERSET_ORGANIZATION_ID set, not a sandbox).
    • It reads ~/.superset/host/<org>/manifest.json, the same file resolveHostTarget already uses.
    • It calls host.apiToken with a 5 s timeout, long enough for the host to refresh its token first (a dead host fails at once on the pid check or a refused connection).
    • On success it uses that token, with authSource: "host".
  • Precedence: --api-key / SUPERSET_API_KEY → host token → stored API key → stored OAuth.
  • Any failure (host down, older host without the procedure, timeout) falls back silently to the CLI's own login.
  • superset start opts out, because a host it spawns outlives the token's ~1 h lifetime.
  • whoami shows Superset app (the account that runs this terminal's workspace).

API (packages/trpc/src/trpc.ts)

  • notAMemberOfOrganization now appends (signed in as <email>) and says to run superset auth login with the account used in the app.

Manual QA (dev desktop over CDP, before/after)

Setup: this worktree's dev app (renderer :4785, CDP :9561), signed in as kiet@superset.sh in org a1b2c3d4…. The CLI config held an API key for a second local account, orgrepro-b@example.com, which is not in that org. I opened the workspace from the Workspaces board, clicked Open Terminal, and ran the desktop-bundled CLI from the shell. The desktop rebuilds that CLI from the checkout on each launch.

base 9e27e780this branch
superset auth whoamiError: Not a member of organization a1b2c3d4…, which was asked for in the x-superset-organization-id headerSigned in as Kiet Ho (kiet@superset.sh) · Auth: Superset app (…)
superset pages publish org-repro.htmlsame error (matches the user's report)Published "Org repro" v1 → /page/org-repro-w2dj8r, listed in the workspace org and created by the app's user
  • Explicit SUPERSET_API_KEY (account B) still wins and gets the new message naming orgrepro-b@example.com.
  • Live host-service, called directly: host.apiToken with the secret returns a token. With the secret plus x-superset-relayed: 1 it returns FORBIDDEN. Without the secret it returns UNAUTHORIZED.
  • Local R2 does not exist in a worktree, so an in-memory S3 stand-in received the page upload in the "after" run. The "before" run failed before any upload.

Testing

  • bun test packages/trpc/src/trpc.test.ts: new test that the error names the email and the fix. It fails on the old code.
  • bun test packages/host-service/src/trpc/router/host/host.test.ts: a local caller gets the token; relayed and unknown callers get FORBIDDEN; an expired token is refreshed before it is given out, and refused if still short-lived (both fail on the previous commit).
  • bun test packages/host-service/src/tunnel/tunnel-client.integration.test.ts: forwarded requests carry x-superset-relayed: 1. It fails with the stamp removed.
  • bun test packages/cli: 375 pass, including new resolve-auth cases (uses the host token, falls back when the host has none, start keeps its own login).
  • biome check is clean on changed files.
  • bun run typecheck in cli, host-service and trpc: the same 22 pre-existing better-auth inference errors as main in this checkout, none in changed lines.

Design Decisions

  • Why the host-service and not the terminal env: the terminal env already strips AUTH_TOKEN on purpose, and putting a session credential in every child process (agents, npm scripts) is a bigger exposure. The host secret in the manifest is already readable by the CLI and already grants full host control.
  • Why a header stamp and not a path deny-list in the tunnel: it holds against path tricks such as batching, encoding and duplicate slashes. Tunnel and route ship in the same binary.

Known Limitations

  • jwtProcedure's bearer branch has no email in the token, so its not-a-member error still omits the account (Greptile P2). page.publish and the other protectedProcedure calls include it.
  • Users need a desktop build with this host-service. Older hosts lack host.apiToken, and the CLI falls back to its own login.

Risks / Rollout / Rollback

  • Risk: credential exposure through the relay. Mitigated by the fail-closed isLocalCaller check and covered by tests and the live probe above. Cloud sandboxes are refused by machineOnlyProcedure, and their auth provider holds no token anyway.
  • Behavior change: in a terminal, the CLI now acts as the app's account even if the CLI is logged in as someone else. --api-key / SUPERSET_API_KEY remain the way to act as another account.
  • Rollback: revert the PR. The CLI falls back to its stored login when host.apiToken is missing, so mixed versions in either direction keep working.

Summary by cubic

Fixes superset pages publish (and other org-scoped commands) failing from a Superset terminal with "Not a member of organization" when the CLI is signed in to a different account than the app. The CLI now acts as the app's account, and the error names the signed-in account and suggests running superset auth login, so released CLIs show the fix without an update.

Behavior and security

  • Precedence: --api-key / SUPERSET_API_KEY → host token → stored API key → stored OAuth; any failure falls back silently.
  • superset start keeps the CLI's own login, since a spawned host outlives the token's ~1 h lifetime.
  • host.apiToken refuses a token that expires within five minutes, refreshing it once first; the CLI waits 5 s for the loopback host, then falls back to its stored login.
  • The tunnel stamps x-superset-relayed on every forwarded request, and host.apiToken refuses requests carrying it, so relay callers cannot obtain the host's credential.
  • The "Not a member of organization" error also hints at unsetting SUPERSET_API_KEY when it names another account.

Summary by CodeRabbit

  • New Features
    • The CLI can use the authentication of the Superset app running the current workspace, while retaining configured or stored credentials as fallbacks. The start command continues to use configured authentication.
    • The whoami command identifies when authentication comes from the Superset app account.
  • Improvements
    • Organization access errors can identify the signed-in account and include guidance for resolving account or API-key mismatches.