Add Jurisdictional Token Flag to Auth Command

API Error: Unable to connect to API (FailedToOpenSocket)

The plan is written. Here's the summary:

Plan: add --jurisdiction to entire auth token

The key finding: the entire jurisdictional-token exchange pipeline already exists in cmd/entire/cli/auth/cell_data_api.go (exchangeJurisdictionToken, jurisdictionAudience, jurisdictionCoreURL, targetJurisdiction). It's consumed by NewEntireAPICellClient, which returns a wrapped *api.Client instead of the raw token. So this is mostly exposing existing, already-audited logic rather than writing new exchange/security code.

The change, in three parts:

1. Expose the token — a new auth.JurisdictionToken(ctx, insecureHTTP, jurisdiction) that runs the same discover → resolve-subject → RFC 8693 exchange flow but returns the token string (skipping the cell-URL resolution only a client needs). Honoring your two decisions: flag value is a slug (us, eu), and ENTIRE_TOKEN is used as the exchange subject_token when set. Minor refactors keep NewEntireAPICellClient's behavior identical.
2. Wire the flag — --jurisdiction on newAuthTokenCmd; when non-empty it mints & prints the jurisdictional token (stdout stays clean for $(...)), otherwise the current control-plane behavior is untouched.
3. Docs — CLAUDE.md auth bullet + CHANGELOG.md.

Result: curl -H "Authorization: Bearer $(entire auth token --jurisdiction us)" https://aws-us-east-2.api.entire.io/api/v1/... works.

Tests reuse the existing SetResolveContextForCellAPIForTest / SetCellExchangeTransportForTest httptest seams, covering both the stored-login and ENTIRE_TOKEN subject paths, plus a command-level test.

Confirmed. The home jurisdiction slug is fetched by auth status but never displayed anywhere non-interactively — the only place a slug surfaces to a user is the interactive mirror-create region picker (repo_mirror_create_wizard.go:190). So today there's no clean way to answer "what's my jurisdiction slug?" from the CLI. That shapes the first question.

I'll grill one question at a time, each with my recommendation.

Question 1 — Input contract & discoverability.

The token's aud is the jurisdiction host (https://us.entire.io), not the cell host. So the flag value is a jurisdiction slug like us, and that one token works against any cell in that jurisdiction (including your example aws-us-east-2.api.entire.io). But a user staring at aws-us-east-2.api.entire.io/api/v1 has no CLI-supported way to learn that its slug is us — auth status doesn't print it, and the only slug UI is the interactive mirror wizard.

So: how should a user discover the value, and should the flag accept anything beyond a bare slug?

My recommendation: Keep --jurisdiction accepting only a lowercase slug (crisp contract, matches the internal jurisdictionLabelPattern and the existing --region values). To close the discovery gap, also print the home jurisdiction in entire auth status (one line, e.g. Region: us) as part of this change — it's a one-line render of data already fetched. I'd not overload the flag to also accept cell/cluster hostnames (that pulls in a control-plane ListClusters call and two input shapes for marginal benefit).

Do you agree, or do you want the flag to also accept a cell host / cluster slug and resolve the jurisdiction for the user?

Question 2 — ENTIRE_TOKEN exchange: environment detection & the "must be a login JWT" limitation.

You chose to honor ENTIRE_TOKEN as the exchange subject_token. Tracing the exchange path surfaces two things worth nailing down:

1. Environment auto-detection. The shared helpers pick prod-vs-staging from environmentFamily(dataOrigin, discoveredCore), and dataOrigin defaults to https://entire.io (prod) unless ENTIRE_API_BASE_URL is set. A CI job that only exports ENTIRE_TOKEN (the common case) — especially a staging token — would otherwise get mis-templated to prod cores. The env token's own aud (via ParseEnvToken) unambiguously encodes its environment.

2. Exchange happens at the target jurisdiction's core (https://{j}.auth.<family>/oauth/token), not the token's home core — this is the existing cross-jurisdiction identity flow. It only works if ENTIRE_TOKEN is a login JWT (subject-capable); an already-exchanged cell/foreign token gets rejected (the server refuses chained exchanges).

My recommendation:

• In the ENTIRE_TOKEN path, derive the environment family (and loopback detection) from the env token's own aud core, so entire auth token --jurisdiction eu works with only ENTIRE_TOKEN set — no ENTIRE_API_BASE_URL needed — in prod, staging, or local dev.
• Keep the exchange target as jurisdictionCoreURL(...) (same audited templating as the stored path), so cross-jurisdiction minting behaves identically regardless of subject source.
• Document the limitation: ENTIRE_TOKEN must be a login JWT; on a rejected exchange, surface the server error verbatim rather than masking it.

Agree? Or would you rather the env-token path exchange at the token's own aud core (simpler, but then --jurisdiction <other-region> couldn't cross jurisdictions and would rely on the server to redirect)?

Question 3 — Slug normalization.

resolveJurisdiction validates the value against jurisdictionLabelPattern, which is lowercase-only ([a-z0-9-]). The existing --region flag on org/project passes its value verbatim to the server (no client normalization). But our path validates client-side, so entire auth token --jurisdiction US would fail with "US" is not a valid label — a jarring error for something that unambiguously means us.

My recommendation: normalize the explicit slug (strings.TrimSpace + strings.ToLower) inside resolveJurisdiction's override branch before the pattern check, so --jurisdiction US / " us " / us all work. Slugs are lowercase DNS labels — there's no valid uppercase variant that means something else — so lowercasing can't mask a real distinction, and the pattern still guards against injection. (The home-fallback branch reads an already-lowercase claim, so it's unaffected.)

Agree, or would you prefer strict rejection (verbatim value, clear "must be lowercase" error) to surface typos?

Agreed — normalize (trim + lowercase) the slug.

Question 4 — Should the flag have a "home jurisdiction" shortcut, or always require a slug?

JurisdictionToken already falls back to the subject token's home_jurisdiction claim when the slug is empty. That opens a design choice for the command surface:

• (A) Slug always required when using the flag: --jurisdiction eu. Bare entire auth token stays the control-plane path. Simple; detection is just "flag value non-empty".
• (B) Optional-value flag: entire auth token --jurisdiction (no value) mints for your home jurisdiction — the common "just give me a cell token" case — and --jurisdiction eu targets a specific one. Requires cobra NoOptDefVal + cmd.Flags().Changed(...) detection.

My recommendation: (A), slug always required. It matches your original ask ("specify the jurisdiction"), keeps the flag's contract unambiguous (a string flag that sometimes takes no value is a papercut), and the home case is no longer opaque now that auth status prints the slug. The home-fallback stays in the library function for internal reuse but isn't surfaced on the flag.

Agree, or do you want the --jurisdiction-with-no-value home shortcut?

Agreed — slug always required (A).

Question 5 — Any stderr diagnostics on success, or token-only?

The minted token goes to stdout. The token's aud (jurisdiction host, e.g. https://us.entire.io) differs from the cell URL the user curls (https://aws-us-east-2.api.entire.io/api/v1). We could echo the resolved audience/exchange-core to stderr as a debugging aid.

My recommendation: token-only, no success chatter. It matches today's auth token contract (only the token on stdout, only errors on stderr, so $(entire auth token --jurisdiction us) stays clean), and the user already knows the cell URL they're targeting. Diagnostics on failure still surface via the wrapped exchange error. If deeper tracing is ever needed, the existing --insecure-http-auth/debug-logging paths cover it.

Agree? That's the last open branch — after this I'll finalize the plan.

Done. Here's what shipped.

entire auth token --jurisdiction <slug>

Feature — entire auth token --jurisdiction us now mints and prints a jurisdictional identity token (RFC 8693 exchange, scope=openid, aud=<jurisdiction host>) for use against that jurisdiction's entire-api cells like https://aws-us-east-2.api.entire.io/api/v1, which reject the control-plane bearer. Bare entire auth token is unchanged.

Implementation (per the grilled plan):

• cmd/entire/cli/auth/cell_data_api.go — new exported JurisdictionToken, built by extracting a shared subject-resolution helper (cellSubject/resolveStoredCellSubject/resolveEnvTokenCellSubject/cellExchangeHTTPClient) out of NewEntireAPICellClient (whose behavior is unchanged — it still ignores ENTIRE_TOKEN). targetJurisdiction split into resolveJurisdiction, which trims + lowercases the slug.
• ENTIRE_TOKEN is honored as the exchange subject (exclusive, fail-closed), with the environment (prod/staging/loopback) derived from the token's own aud — so it works in CI with no ENTIRE_API_BASE_URL.
• cmd/entire/cli/auth.go — the --jurisdiction flag/branch (slug required, token-only stdout, clean not-logged-in hint) plus a new Jurisdiction: line in auth status so the slug is discoverable (labels widened to align).
• Docs: CLAUDE.md (= AGENTS.md) auth bullet and a CHANGELOG.md Unreleased entry.

Tests — JurisdictionToken stored-context + ENTIRE_TOKEN paths (asserting subject_token, scope=openid, audience), the --jurisdiction command path (env-token success + not-logged-in), and the auth status slug line. go build, go vet, mise run lint, and the two touched packages all pass.

One thing to flag

mise run test:ci fails only in cmd/entire/cli/strategy git-hook tests — this is a pre-existing environment issue, not this change: your global init.templateDir = ~/.git_template has active post-commit/post-rewrite hooks that leak into the tests' freshly-git init'd temp repos and break their fresh-install assertions. The strategy/ package is untouched by this work and fails the same way on main. I saved this to memory so it isn't re-diagnosed next time.

If you'd like, I can follow up separately by isolating the template dir inside the strategy tests (e.g. neutralizing it in testutil.InitRepo) so your local mise run check goes green. Nothing has been committed.

(Side note: .opencode/package-lock.json shows as modified in git status — that wasn't touched by me; it changed during test tooling runs.)

All green. Here's the /simplify summary.

Applied (2 fixes)

Altitude — collapsed a cross-function magic literal into one helper. The %-13s label width was a contract shared by writeProfileLines and runAuthStatus (they render into the same aligned column), yet my change had spread the bare literal across 6 call sites. Added a single writeAuthStatusLine(w, label, value) helper in auth.go that owns the indent/width/spacing, and routed all 6 sites through it. Now the next label ≥13 chars can't silently misalign the column.

Reuse — folded the duplicated test transport. My new captureExchangeRT in cell_data_api_test.go re-implemented the existing captureTransport (same auth test package, repo_token_test.go). Added an optional token field to captureTransport (defaulting to its existing "repo-scoped.jwt"), pointed the env-token test at it, and deleted captureExchangeRT plus its now-unused io/net/url imports.

Skipped (with reason)

• Unify stubExchangeRT (cli) with captureExchangeRT (auth) — both agents agreed: different packages, no existing cli helper, and a cross-package exported test util would be over-engineering for ~10 lines.
• Inline the targetJurisdiction nil-adapter wrapper — the simplification agent rated it a wash; it's self-documenting and has a dedicated test (TestTargetJurisdictionRejectsBadLabel).
• Trim the --jurisdiction help Long — intentional thoroughness for a secret-printing command; style, not a maintenance cost.
• Extract a notLoggedIn helper for the doubled block in the RunE — the "Not logged in. Run 'entire login'…" line is an inline idiom repeated across 4 sites in this package (authcmd.go, repo_mirror_create_wizard.go, and both branches here); DRYing only 2 of them would break with house style.

Efficiency review found nothing to fix (the env-token path correctly skips discovery, JurisdictionToken skips the cell-URL round-trip, and the login-provider closure isn't retained). Lint clean, both touched packages pass. Nothing committed.

Done. The commit and push succeeded; the branch already had an open PR, so my commit landed on it rather than creating a new one.

• Committed 2b08ff14d11 — cli/auth: add token --jurisdiction for jurisdictional identity tokens (8 files, +465/−77) and pushed to origin/chore/unhide-auth-token.
• PR: this branch already has an open PR — #1619 (https://github.com/entireio/cli/pull/1619) — which now includes this commit alongside the earlier entire auth token unhide work on the same branch.

Note: the branch chore/unhide-auth-token predates this session (it already carried the unhide commits), so the jurisdiction feature is stacked onto that existing PR rather than getting its own. If you'd prefer this feature in a separate PR off main, let me know and I'll move the commit to a fresh branch.