Decide: where patch API calls go when a token is set but the org slug can't be resolved

[mikolalysenko]

[agent] Filed by the scheduled architecture audit routine (CLI and core). Register: C07.

Kind: decision. Source: review Part 7.2 (URL builders), register C07.

Question

When SOCKET_API_TOKEN is set, no --org / SOCKET_ORG_SLUG is given and org auto-resolve fails (a network blip, a token without org scope, an unexpected /organizations answer), get_api_client_with_overrides only warns and still returns an authenticated, non-proxy client with org_slug = None (client.rs#L2169-L2193). Four URL builders then route that one client in two different ways. Which single route should every call take?

Options:

1. Fail fast (strict). No resolved org means a typed error before any patch-API call (for example org_unresolved: "could not determine your organization; pass --org or set SOCKET_ORG_SLUG"). It is predictable and never silently drops paid patches, but a transient blip on /organizations now fails the run.
2. Downgrade the whole client to the public proxy (recommended). Treat an unresolved org exactly like the stale-token fallback (#647): every call goes to the proxy anonymously (free patches only), with the existing api_auth_fallback warning. That matches what blob/diff/vendor/telemetry already do today, and stays consistent with Only scan, get <uuid> and vex fall back to the public proxy on 401/403; get search, apply, rollback, repair and vendor eject fail #647.
3. Use default everywhere. Extend today's JSON behavior (/v0/orgs/default/…) to blob, diff, vendor and telemetry. This only makes sense if the server gives the default slug a meaning. The code comment at client.rs#L724-L728 treats a 404 on that route as a typo'd slug.

Problem (verified on main 045d7ec)

• JSON calls use org_slug_or_default → /v0/orgs/default/patches/... with the bearer: client.rs#L636-L655.
• Blob and diff downloads require org_slug.is_some() and otherwise go to the public proxy without auth: binary_url, client.rs#L1034-L1061.
• Vendor package references do the same: vendor_package_url, client.rs#L1412-L1430.
• Telemetry has a fourth copy of the token+slug decision, and it also goes to the proxy: resolve_telemetry_endpoint, telemetry.rs#L225-L253.

Proof by execution: a temporary unit test (run twice, not committed) built ApiClient { api_token: Some(..), org_slug: None, use_public_proxy: false } and printed:

patches_path(view)  = /v0/orgs/default/patches/view/u1
patches_path(batch) = /v0/orgs/default/patches/batch
binary_url(blob)    = ("https://patches-api.socket.dev/patch/blob/h1", false)
binary_url(diff)    = ("https://patches-api.socket.dev/patch/diff/u1", false)
vendor_package_url  = ("https://patches-api.socket.dev/patch/package", false)
telemetry endpoint  = ("https://patches-api.socket.dev/patch/telemetry", false)

So one run queries patch metadata as org default with the user's token, then downloads the blobs anonymously from the proxy. That only works when the patch is free, and scan's batch call against default errors with "unknown org slug" in the first place.

Proposed change (any option)

Resolve the route once, at client construction, into one value (for example enum Route { Org { slug }, Proxy }), and have all four builders read it:

• delete org_slug_or_default and the three api_token.is_some() && org_slug.is_some() && !use_public_proxy re-derivations;
• telemetry takes its route from the client (or the shared resolver) rather than re-deciding it.

Size and scope

• Files: api/client.rs, telemetry.rs. Estimated ~150 production lines.
• Out of scope: the 401/403 fallback itself (Only scan, get <uuid> and vex fall back to the public proxy on 401/403; get search, apply, rollback, repair and vendor eject fail #647) and the per-call org_slug override of fetch_registry_references_for_org, which stays as it is.

Acceptance criteria

• One route value decides JSON, blob, diff, vendor and telemetry URLs, and a unit test asserts all five agree for each of: token+slug, token without slug (the chosen option), no token, proxy override.
• CLI_CONTRACT.md documents the unresolved-org behavior.
• The existing binary_url_*, vendor_package_tests and authenticated_batch_tests stay green (their expectations change only for the no-slug case).

Dependencies

• Pairs with Only scan, get <uuid> and vex fall back to the public proxy on 401/403; get search, apply, rollback, repair and vendor eject fail #647: option 2 reuses its downgrade.
• api/client.rs is also changed by open PRs Stream patch blob and diff downloads to disk (#571) #607 and Retry patch API connections reset mid-handshake #610.

[mikolalysenko]

[agent] Triaged as priority:p3. This is a design decision, so it stays agent:needs-human. Related: #647 (proxy fallback on 401/403 for every API consumer).

---

Generated by Claude Code