Merge pull request #14 from metabase/cli-oauth

cli oauth

Author: alxnddr

.claude/skills/add-e2e-test/SKILL.md

@@ -67,7 +67,7 @@ beforeAll(async () => {
 ```
 
 - The `Bootstrap` schema lives in `tests/e2e/bootstrap-data.ts`. **Never redeclare it.** If you need a new field, edit the schema there — the writer (`tests/e2e/setup/bootstrap.ts`) consumes the same type, so drift is mechanically prevented.
-- The seeded `bootstrap.adminApiKey` authenticates as a synthetic api-key user (email `api-key-user-…@api-key.invalid`). For tests that need a real human admin, use `auth login --email --password` with `bootstrap.admin.email` / `bootstrap.admin.password` and **explain in the test name why** — don't paper over it.
+- The seeded `bootstrap.adminApiKey` authenticates as a synthetic api-key user (email `api-key-user-…@api-key.invalid`). For tests that need a real human admin, run the in-process OAuth login harness (`tests/e2e/setup/oauth-harness.ts` — `consentingBrowser` with `bootstrap.admin`; OAuth-capable servers only, gate with `requireOAuthServer()`) and **explain in the test name why** — don't paper over it.
 - **Never invoke the setup wizard from a test.** That mutates global state. Bootstrap runs once per `bun run test:e2e` via `tests/e2e/setup/global-setup.ts`.
 - **Never hard-code an API key.** Always read from `bootstrap`.
 

CLAUDE.md

@@ -30,11 +30,11 @@ Metabase CLI. TypeScript ESM. citty + native `fetch` + Zod + @clack/prompts. oxl
 - `src/main.ts` — root citty command, lazy `subCommands`.
 - `src/commands/` — CLI shell only. No HTTP, no parsing, no formatting.
 - `src/core/` — pure logic, no CLI deps.
-  - `auth/` — storage + verify.
+  - `auth/` — credential storage + verify, plus the OAuth login flow: `credential.ts` (discriminated `Credential` union), `pkce.ts`, `callback-server.ts` (loopback redirect), `oauth-login.ts` (orchestration), `oauth-session.ts` (refresh/revoke).
   - `config.ts` — flag → env → stored resolver. Profile-aware (`resolveProfileName`, `resolveConfig`). All `METABASE_*` env-var reads live here.
   - `errors.ts` — `isNotFoundError`, `errorMessage` (Node error type guards used outside the HTTP boundary).
-  - `http/` — the HTTP boundary. `client.ts` wraps native `fetch` with `requestParsed(schema, path, opts)` (the ONLY typed-JSON path), `requestRaw`, `requestStream`. Retries are idempotency-aware: GET/HEAD/OPTIONS retry on retryable status codes by default; POST/PUT/PATCH/DELETE never retry on status (only on network/timeout). Callers may override via `RequestOptions.idempotent`. `errors.ts` owns the discriminated `MetabaseError` taxonomy and `toMetabaseError(unknown)`. `sanitize.ts` runs at `HttpError` construction — secret redaction is not optional. `retry.ts` is the backoff math; it is also the only `core/http/` site allowed to drive a `setTimeout`-based wait loop (via `node:timers/promises`) outside `src/runtime/poll.ts`. Nothing outside this directory may import a third-party HTTP library or call `fetch` directly; this is enforced by `tests/structure.test.ts`.
-  - `url.ts` — `normalizeUrl` and `originOnly`. The single permitted home for `new URL(...)` outside `src/core/http/**`; the URL helpers belong here, not at call sites.
+  - `http/` — the HTTP boundary. `client.ts` wraps native `fetch` with `requestParsed(schema, path, opts)` (the ONLY typed-JSON path), `requestRaw`, `requestStream`. Retries are idempotency-aware: GET/HEAD/OPTIONS retry on retryable status codes by default; POST/PUT/PATCH/DELETE never retry on status (only on network/timeout). Callers may override via `RequestOptions.idempotent`. `errors.ts` owns the discriminated `MetabaseError` taxonomy and `toMetabaseError(unknown)`. `sanitize.ts` runs at `HttpError` construction — secret redaction is not optional. `retry.ts` is the backoff math; it is also the only `core/http/` site allowed to drive a `setTimeout`-based wait loop (via `node:timers/promises`) outside `src/runtime/poll.ts`. `oauth.ts` is the OAuth protocol boundary (RFC 8414 discovery with same-origin endpoint pinning, dynamic client registration, token exchange/refresh/revocation); its schemas are protocol envelopes, not `src/domain/` resources. Nothing outside this directory may import a third-party HTTP library or call `fetch` directly; this is enforced by `tests/structure.test.ts`.
+  - `url.ts` — `normalizeUrl`, `displayUrl`, `assertEndpointOrigin`. The single permitted home for `new URL(...)` outside `src/core/http/**`; the URL helpers belong here, not at call sites. Base URLs may carry a subpath (`https://my.org.com/metabase`) — never reduce a stored instance URL to its origin, and always join request paths by concatenation, not `new URL(path, base)`.
 - `src/domain/` — one file per Metabase resource; Zod schema + inferred type co-located. See **Domain pattern**.
 - `src/output/` — presentation; takes typed values.
 - `src/runtime/` — platform glue (stdin, poll).
@@ -122,7 +122,7 @@ Lives under `tests/e2e/`. The whole point is to run the **built `dist/cli.mjs`**
 Adding a new e2e test for command `mb <noun> <verb>`:
 
 1. `tests/e2e/<noun>.e2e.test.ts` — drive the command via `runCli`, assert exit code, assert `--json` output through the schema imported from `src/commands/<noun>/<verb>.ts` or `src/domain/<noun>.ts`. Each test gets its own config home via `mkTempConfigHome()` (or a small `makeIsolatedConfigHome` closure inside the file that pushes onto a `tempDirs` array drained in `afterEach`).
-2. The seeded admin API key (`bootstrap.adminApiKey`) authenticates as a synthetic api-key user (`api-key-user-…@api-key.invalid`). For tests that need a real admin user, call `auth login` with admin email/password — but expose that need explicitly; don't paper over it.
+2. The seeded admin API key (`bootstrap.adminApiKey`) authenticates as a synthetic api-key user (`api-key-user-…@api-key.invalid`). For tests that need a real admin user, run the in-process OAuth login harness (`tests/e2e/setup/oauth-harness.ts` `consentingBrowser` with `bootstrap.admin`, OAuth-capable servers only — see `oauth.e2e.test.ts`) — but expose that need explicitly; don't paper over it. The harness is also the only sanctioned home for raw `fetch` against Metabase from the oauth suite.
 3. Never mutate snapshot state in tests. Snapshot/restore (`/api/testing/*`) is reserved for the bootstrap script.
 
 Adding a new field to `.bootstrap.json`:

README.md

@@ -1,6 +1,6 @@
 # metabase-cli
 
-Command-line client for Metabase. Authenticates against an instance with an API key and stores it securely on your machine.
+Command-line client for Metabase. Logs in to an instance in your browser (OAuth, Metabase v62+) or with an API key, and stores credentials securely on your machine.
 
 ## Supported Metabase versions
 
@@ -43,25 +43,34 @@ Credentials are stored per-profile. The default profile is named `default`. Use
 
 ### `mb auth login`
 
-Save credentials for a profile. On success the server is probed once — the rendered output shows the API-key user, role (`Admin`/`User`), and Metabase version, and the same values are cached in `<configDir>/profiles.json` so later commands skip re-probing. Failure of either the auth probe (`/api/user/current`) or the server probe (`/api/session/properties`) rejects the login; an existing profile keeps its last-known-good `apiKey`/`url`/`lastProbe` and gains a `lastFailure` entry.
+Log in to a Metabase instance and save the credential to a profile. Interactive login offers two methods:
 
-| Flag                     | Description                                                |
-| ------------------------ | ---------------------------------------------------------- |
-| `--url <url>`            | Metabase URL. Falls back to `METABASE_URL`, then prompts.  |
-| `--api-key <value>`      | API key. Visible in shell history — pipe on stdin instead. |
-| `--profile <name>`, `-p` | Profile to write to (default: `default`).                  |
-| `--skip-verify`          | Save without contacting the server (no probe, no cache).   |
+- **In your browser** (recommended; requires Metabase v62 or newer) — the CLI opens Metabase, you sign in with your password or SSO and approve the CLI, and a short-lived access token plus a rotating refresh token are stored. Tokens refresh automatically; you never paste a secret.
+- **With an API key** — paste a key from Admin settings → Authentication → API keys.
 
-Resolution order for the API key: `--api-key` → piped stdin → `METABASE_API_KEY` → interactive prompt. Stdin is auto-detected when not a TTY.
+Against a server older than v62 the CLI detects the missing OAuth support and falls back to the API key prompt automatically. Supplying an API key (flag, env, or stdin) always skips the browser flow, so CI and scripts behave exactly as before.
+
+On success the server is probed once — the rendered output shows the user, role (`Admin`/`User`), and Metabase version, and the same values are cached in `<configDir>/profiles.json` so later commands skip re-probing. Failure of either the auth probe (`/api/user/current`) or the server probe (`/api/session/properties`) rejects the login; an existing profile keeps its last-known-good credential and gains a `lastFailure` entry.
+
+| Flag                     | Description                                                                                                                                          |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--url <url>`            | Metabase URL, including any subpath if the instance is hosted under one (`https://my.org.com/metabase`). Falls back to `METABASE_URL`, then prompts. |
+| `--api-key <value>`      | API key. Skips the browser flow. Visible in shell history — pipe on stdin instead.                                                                   |
+| `--client-id <id>`       | Pre-registered OAuth client id (only needed when dynamic client registration is disabled on the server).                                             |
+| `--profile <name>`, `-p` | Profile to write to (default: `default`).                                                                                                            |
+| `--skip-verify`          | Save without contacting the server (no probe, no cache).                                                                                             |
+
+Non-interactive (non-TTY) login requires an API key; resolution order: `--api-key` → piped stdin → `METABASE_API_KEY` (first non-empty wins). Without one, non-interactive login fails rather than prompting.
 
 ```sh
+mb auth login                                            # interactive: browser or API key
 echo "$MB_KEY" | mb auth login --url https://m.example.com
 mb auth login --url https://m.example.com < key.txt
 ```
 
 ### `mb auth status`
 
-Show whether a profile is authenticated.
+Show whether a profile is authenticated. The output includes the auth method (`OAuth` or `API key`) alongside the cached user, role, and server version.
 
 ```sh
 mb auth status
@@ -76,9 +85,9 @@ mb auth status --profile staging
 
 ### `mb auth list`
 
-List configured authentication profiles. All profile metadata (URL, last successful probe, last failure) lives in `<configDir>/profiles.json` at mode `0600`; the API key sits in the OS keychain when available, or inline in the same file when the keychain is unavailable.
+List configured authentication profiles. All profile metadata (URL, auth method, last successful probe, last failure) lives in `<configDir>/profiles.json` at mode `0600`; the secrets (API key, or OAuth access/refresh tokens) sit in the OS keychain when available, or inline in the same file when the keychain is unavailable.
 
-`auth list` re-probes every profile in parallel — on success it refreshes `lastProbe` (Metabase version, token features, API-key user identity) and clears `lastFailure`; on failure it updates `lastFailure` and leaves the prior `lastProbe`/`url`/`apiKey` untouched. Rendered columns: `Profile | URL | Status | Role | Version | Last probed`. Failed rows append a one-line footer pointing at `mb auth login --profile <name>`.
+`auth list` re-probes every profile, one at a time — a probe can refresh and rewrite an expired OAuth token, so probes are serialized to avoid racing on the shared `profiles.json`. On success it refreshes `lastProbe` (Metabase version, token features, user identity) and clears `lastFailure`; on failure it updates `lastFailure` and leaves the prior `lastProbe`/`url`/credential untouched. Rendered columns: `Profile | URL | Auth | Status | Role | Version | Last probed`. Failed rows append a one-line footer pointing at `mb auth login --profile <name>`.
 
 ```sh
 mb auth list
@@ -91,7 +100,7 @@ mb auth list --json
 
 ### `mb auth logout`
 
-Clear stored credentials for a profile.
+Clear stored credentials for a profile. For an OAuth profile the refresh token is also revoked server-side, best-effort: local credentials are cleared first and a revocation failure only warns, so a slow or offline server never blocks the logout.
 
 ```sh
 mb auth logout --yes
@@ -1360,7 +1369,7 @@ Exit codes: `0` success, `2` `ConfigError` (missing name, unknown name, `MB_SKIL
 | Variable                      | Effect                                                                                                                                                                    |
 | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `METABASE_URL`                | Default URL for `auth login` and config resolution.                                                                                                                       |
-| `METABASE_API_KEY`            | Default API key (overrides interactive prompt; not stored).                                                                                                               |
+| `METABASE_API_KEY`            | Default API key (makes `auth login` non-interactive, skipping the browser flow; not stored).                                                                              |
 | `METABASE_PROFILE`            | Default profile when `--profile` is omitted. Falls back to `default`.                                                                                                     |
 | `METABASE_VERBOSE`            | When set to `1`, prints structured developer-detail JSON to stderr on failure.                                                                                            |
 | `METABASE_CLI_SKIP_PREFLIGHT` | When set to `1`, bypasses the per-command server version / token-feature preflight check. Escape hatch for patched Metabase builds; can mask real compatibility problems. |

src/commands/auth/list.test.ts

@@ -2,6 +2,7 @@ import { runCommand } from "citty";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { ZodType } from "zod";
 
+import type { Credential } from "../../core/auth/credential";
 import { parseJson } from "../../runtime/json";
 import type { Verification } from "../../core/auth/verify";
 
@@ -17,10 +18,11 @@ vi.mock("@napi-rs/keyring", async () => {
 });
 
 vi.mock("../../core/auth/verify", () => ({
-  verifyAndProbe: async (url: string, apiKey: string): Promise<Verification> => {
-    const result = hoisted.verify.results.get(apiKey);
+  verifyAndProbe: async (url: string, credential: Credential): Promise<Verification> => {
+    const key = credential.kind === "apiKey" ? credential.apiKey : credential.accessToken;
+    const result = hoisted.verify.results.get(key);
     if (result === undefined) {
-      throw new Error(`no verifyAndProbe result configured for apiKey "${apiKey}"`);
+      throw new Error(`no verifyAndProbe result configured for credential "${key}"`);
     }
     return result;
   },
@@ -108,7 +110,8 @@ describe("auth list command", () => {
     expect(envelope.returned).toBe(2);
     expect(envelope.data.map((entry) => entry.profile)).toEqual(["staging", "prod"]);
     expect(envelope.data.every((entry) => entry.status === "ok")).toBe(true);
-    expect(envelope.data[0]?.url).toBe("https://staging.example.com");
+    // The subpath survives (instances hosted under a path stay distinguishable); query is dropped.
+    expect(envelope.data[0]?.url).toBe("https://staging.example.com/path");
     expect(envelope.data[0]?.version).toEqual({
       tag: "v0.58.7",
       major: 58,