fix(upstreams): distinguish upstream credentials by subject

Author: masterkain

docs-site/src/content/_docs-contract.md

@@ -16,7 +16,7 @@ Use only these hosts in public examples:
 - `https://codex-pooler.example.com`, for deployed product examples
 - `https://docs.codex-pooler.com`, for the public docs site canonical URL
 
-Do not use private hostnames, cluster names, pod names, tenant names, real account identifiers, real repository evidence paths, or private service URLs in public docs.
+Do not use private hostnames, cluster names, pod names, tenant names, real account identifiers, raw OpenAI user subjects, real repository evidence paths, or private service URLs in public docs.
 
 ## Route Vocabulary
 
@@ -99,6 +99,7 @@ Allowed public claims:
 - `upstream`: A Codex account identity or assignment that Codex Pooler can route eligible work to
 - `Pool API key`: A bearer credential used by runtime clients for `/backend-api` and `/v1` requests. It represents a Pool, not one upstream account
 - `MCP token`: An operator-owned bearer credential used only for `/mcp`. It is separate from Pool API keys and browser sessions
+- `subject reference`: A sanitized fingerprint of an upstream OpenAI user subject. Public docs may describe this reference, but must never include raw subject values
 - `backend API`: The Codex backend compatibility surface rooted at `/backend-api`, especially `/backend-api/codex/*`
 - `/v1`: The narrow OpenAI-compatible SDK surface rooted at `/v1`. It is compatibility over Codex routing, not full OpenAI parity
 - `metadata-only logging`: Request, route, accounting, audit, and MCP records may keep identifiers, route names, counts, statuses, timings, model names, safe error codes, and sanitized summaries. They must not store or show raw payloads or credentials
@@ -114,7 +115,7 @@ Use placeholders that are clearly fake and generic:
 - Email-like examples: `operator@example.com`
 - Model ids: use documented sample ids only when the surrounding page explains that the Pool must expose them
 
-Never include raw tokens, raw prompts, request bodies, response bodies, file bodies, audio bodies, image bodies, cookies, `auth.json`, access tokens, refresh tokens, raw idempotency keys, raw upload URLs, internal evidence snippets, internal logs, private hostnames, real account ids, or real user identifiers.
+Never include raw tokens, raw prompts, request bodies, response bodies, file bodies, audio bodies, image bodies, cookies, `auth.json`, access tokens, refresh tokens, raw idempotency keys, raw upload URLs, internal evidence snippets, internal logs, private hostnames, callback URLs, real account ids, raw OpenAI user subjects, or real user identifiers.
 
 If a docs example needs an Authorization header, write `Authorization: Bearer <pool-api-key>` for runtime routes or `Authorization: Bearer <operator-mcp-token>` for `/mcp`.
 
@@ -142,6 +143,7 @@ Safe fields to mention:
 - HTTP method and status class
 - Pool label or placeholder
 - Upstream label or placeholder
+- Sanitized upstream subject reference or fingerprint
 - Model name
 - Request-log id only when synthetic
 - Error code, retry count, duration, token count, and timestamp examples
@@ -151,7 +153,7 @@ Forbidden fields and examples:
 - Raw prompts and completions
 - Request bodies, response bodies, multipart bodies, websocket frames, file bytes, audio bytes, image bytes, data URLs, and transcripts
 - Bearer tokens, Pool API keys, MCP tokens, cookies, access tokens, refresh tokens, `auth.json`, TOTP secrets, SMTP secrets, signing secrets, and raw idempotency keys
-- Internal incident procedures, cluster names, pod names, private hostnames, real account identifiers, raw emails, and private IP addresses
+- Internal incident procedures, cluster names, pod names, private hostnames, real account identifiers, raw OpenAI user subjects, raw emails, and private IP addresses
 
 ## Source Map For Public Route Claims
 
@@ -167,6 +169,7 @@ Use these tracked sources as the source of truth for public route claims. Do not
 | Unsupported `/v1` routes | `lib/codex_pooler_web/controllers/v1/unsupported_routes.ex`, `test/support/compatibility_matrix.ex`, `test/codex_pooler_web/controllers/v1/route_auth_test.exs`, `test/codex_pooler_web/controllers/runtime/compatibility_contract_test.exs` | Explicit unsupported `/v1` routes return deterministic OpenAI-shaped unsupported endpoint errors before gateway dispatch |
 | Realtime exclusion | `lib/codex_pooler_web/router.ex`, `test/support/compatibility_matrix.ex`, `test/codex_pooler_web/route_surface_test.exs`, `test/codex_pooler_web/controllers/v1/route_auth_test.exs` | `/v1/realtime` and OpenAI Realtime SDK websocket or session routes are not supported |
 | MCP endpoint | `lib/codex_pooler_web/router.ex`, `test/codex_pooler_web/route_surface_test.exs`, `test/codex_pooler_web/controllers/mcp_contract_test.exs`, `test/codex_pooler_web/controllers/mcp_controller_test.exs` | `/mcp` is a root metadata-only, read-only operator endpoint using operator MCP bearer tokens, not Pool API keys or browser sessions |
+| Upstream identity linking | `lib/codex_pooler/upstreams/lifecycle/identity_lifecycle.ex`, `lib/codex_pooler/upstreams/token_linking.ex`, `lib/codex_pooler/upstreams/auth/codex_auth.ex`, `lib/codex_pooler/upstreams/auth/codex_auth_json.ex`, `lib/codex_pooler_web/live/admin/read_models/upstream_accounts_read_model.ex`, `lib/codex_pooler_web/live/admin/read_models/upstream_cockpit_read_model.ex`, `test/codex_pooler/upstreams/oauth_browser_linking_test.exs`, `test/codex_pooler/upstreams/oauth_device_linking_test.exs`, `test/codex_pooler/upstreams/oauth_relink_test.exs`, `test/codex_pooler/upstreams_test.exs`, `test/codex_pooler_web/live/admin/pages/upstreams_live_test.exs`, `test/codex_pooler_web/live/admin/pages/upstream_cockpit_live_test.exs` | OAuth links, relinks, and auth.json imports can use an OpenAI user subject, when returned, to separate same-account and same-workspace upstream credentials. Public docs may mention only sanitized subject references or fingerprints, never raw subjects |
 | Privacy and redaction | `README.md`, `test/codex_pooler_web/controllers/runtime/compatibility_contract_test.exs`, `test/codex_pooler_web/controllers/mcp_contract_test.exs`, `test/codex_pooler_web/controllers/mcp_controller_test.exs` | Public docs must keep prompts, bodies, bearer tokens, cookies, `auth.json`, upstream secrets, and private identifiers out of examples and evidence |
 
 ## Author Checklist
@@ -178,5 +181,5 @@ Before publishing or editing a public page:
 3. Include narrow `/v1` compatibility language when mentioning OpenAI SDKs
 4. Keep Codex app-server helper routes outside the supported runtime surface
 5. Keep `/mcp` token language separate from Pool API key language
-6. Remove raw payloads, secrets, private hosts, and internal evidence from examples
+6. Remove raw payloads, secrets, callback URLs, raw OpenAI user subjects, private hosts, and internal evidence from examples
 7. If the route claim isn't in the tracked sources above, don't publish it yet

docs-site/src/content/docs/operators/upstreams.mdx

@@ -14,7 +14,7 @@ Use this page when you need to answer:
 5. how recent token usage compares with observed quota windows
 6. which account actions are available without exposing raw credentials
 
-The page is metadata-only after linking or import. It shows operator labels, workspace and plan badges, safe status labels, quota-window evidence, token counters, assignment counts, and links to related logs. It does not show prompts, responses, files, websocket frames, bearer tokens, refresh tokens, provider cookies, OAuth provider payloads, or stored Codex `auth.json` contents.
+The page is metadata-only after linking or import. It shows operator labels, workspace and plan badges, safe status labels, quota-window evidence, token counters, assignment counts, sanitized subject references when needed, and links to related logs. It does not show prompts, responses, files, websocket frames, bearer tokens, refresh tokens, provider cookies, OAuth provider payloads, raw OpenAI user subjects, or stored Codex `auth.json` contents.
 
 ![Upstreams page overview](/operators/upstreams/upstreams-overview.png)
 
@@ -167,6 +167,8 @@ The upload accepts small auth files only. The current UI states a 64 KB limit.
 
 After import, Codex Pooler becomes the refresh-token authority for that account lineage. Do not keep using the same `auth.json` from another Codex install, machine, or automation. Provider refresh-token rotation can invalidate one copy and move the account into `reauth_required`.
 
+Export `auth.json` from the intended signed-in account, then import each user lineage separately. When the auth file returns an OpenAI user subject, Codex Pooler uses it with the account and workspace identifiers to separate multiple credentials from the same account and workspace. The admin UI may show a sanitized subject reference so operators can distinguish those rows, but it never renders the raw subject.
+
 The dialog footer keeps docs on the left and the submit actions on the right. `Cancel` closes without importing. `Import auth.json` stores the credential material through encrypted upstream secret storage.
 
 ## OpenAI OAuth Upstream Linking
@@ -175,28 +177,36 @@ OpenAI OAuth upstream linking is an authenticated admin workflow. Use
 `OAuth` on `/admin/upstreams` to link a new OpenAI upstream account to a selected Pool. Use
 `/admin/upstreams/:id` to relink or reconnect the exact upstream identity shown
 in the cockpit. Relink checks the returned account and workspace claims against
-the target identity before replacing encrypted credential material.
+the target identity before replacing encrypted credential material. When OpenAI
+returns a user subject, Codex Pooler also uses that subject to keep same-account,
+same-workspace upstream credentials distinct.
+
+Browser account choice is controlled by the active OpenAI or Google browser
+session. Codex Pooler can start the authorization flow, but it cannot force the
+provider account chooser by itself. Sign in to the intended provider account, or
+use a separate browser profile, before completing the link or relink.
 
 The browser manual callback workflow is:
 
 1. open the OAuth link or relink dialog
 2. choose `Browser`
 3. open the generated OpenAI authorization URL
 4. complete OpenAI authorization in the browser
-5. paste the resulting local callback URL back into the admin dialog
+5. paste the resulting returned browser URL back into the admin dialog
 6. submit the callback form and wait for the success or safe error state
 7. use `Close` after the dialog reports that the account was linked or relinked
 
-The local callback URL is consumed only by the already-authenticated admin page,
-and there is no hosted OAuth callback route, no public `/auth/callback`, and no
+The returned browser URL is consumed only by the already-authenticated admin page,
+and there is no hosted OAuth callback route, no public callback endpoint, and no
 `/api/admin/*` or dashboard JSON API for this workflow.
 
 Use the device-code fallback when browser authorization is not practical. The
 dialog shows the user code and verification URL while the flow is pending, and
 the page polls only while the operator keeps the dialog open. Device-code
-authorization must be enabled for Codex on the OpenAI account or workspace. If
-device authorization is unavailable or denied, use the browser workflow or ask
-the workspace admin to enable Codex device-code login.
+authorization must be enabled for Codex on the OpenAI account or workspace. It
+may be unavailable or denied by account or workspace policy. If device
+authorization is unavailable or denied, use the browser workflow or ask the
+workspace admin to enable Codex device-code login.
 
 Immediately after a successful link, the new account is not guaranteed to route
 traffic. Codex Pooler creates the initial Pool assignment and enqueues account
@@ -206,7 +216,7 @@ before any user request is routed, and runtime routing excludes it until token
 refresh succeeds or the credentials are relinked.
 
 Operators should never paste callback URLs, authorization codes, tokens, cookies,
-raw auth.json, OpenAI provider payloads, or local credential files into docs,
+returned browser URLs, raw auth.json, OpenAI provider payloads, raw user subjects, or local credential files into docs,
 tickets, logs, or evidence. The admin UI may show the one-time authorization URL
 or device user code during a pending flow, but persisted flow summaries, audit
 metadata, request logs, tests, and docs stay metadata-only.
@@ -227,7 +237,7 @@ Safe OAuth troubleshooting codes:
     </tr>
     <tr>
       <td><code>invalid_callback_origin</code></td>
-      <td>Use only the <code>http://localhost:1455/auth/callback</code> URL produced by the OpenAI flow.</td>
+      <td>Use only the local browser URL produced by the OpenAI flow.</td>
     </tr>
     <tr>
       <td><code>missing_state</code></td>
@@ -267,7 +277,7 @@ Safe OAuth troubleshooting codes:
     </tr>
     <tr>
       <td><code>identity_mismatch</code></td>
-      <td>Relink with the same OpenAI account and workspace shown in the cockpit.</td>
+      <td>Relink with the same OpenAI account, workspace, and sanitized subject reference shown in the cockpit. If a different person in the same workspace should be added, link or import that user lineage as a separate upstream identity.</td>
     </tr>
     <tr>
       <td><code>identity_conflict</code></td>

lib/codex_pooler/upstreams/auth/codex_auth_json.ex

@@ -19,6 +19,7 @@ defmodule CodexPooler.Upstreams.Auth.CodexAuthJson do
   @type import_attrs :: %{
           required(:account_identifier) => String.t(),
           required(:account_email) => String.t() | nil,
+          required(:chatgpt_user_id) => String.t() | nil,
           required(:account_label) => String.t(),
           required(:workspace_id) => String.t() | nil,
           required(:workspace_label) => String.t() | nil,
@@ -47,6 +48,7 @@ defmodule CodexPooler.Upstreams.Auth.CodexAuthJson do
        %{
          account_identifier: account_identifier,
          account_email: account_email(id_claims),
+         chatgpt_user_id: auth_claim(id_claims, "chatgpt_user_id"),
          account_label: account_label(id_claims),
          workspace_id: workspace_id(id_claims),
          workspace_label: workspace_label(id_claims),

lib/codex_pooler/upstreams/import.ex

@@ -76,6 +76,7 @@ defmodule CodexPooler.Upstreams.Import do
       chatgpt_account_id: chatgpt_account_id,
       account_identifier: chatgpt_account_id || account_email,
       account_email: account_email,
+      chatgpt_user_id: attrs |> import_value(:chatgpt_user_id) |> present_string(),
       account_label: attrs |> import_value(:account_label) |> present_string(),
       workspace_id: attrs |> import_value(:workspace_id) |> present_string(),
       workspace_label: attrs |> import_value(:workspace_label) |> present_string(),

lib/codex_pooler/upstreams/lifecycle/identity_lifecycle.ex

@@ -58,10 +58,11 @@ defmodule CodexPooler.Upstreams.Lifecycle.IdentityLifecycle do
     attrs = atomize_attrs(attrs)
     chatgpt_account_id = attrs |> Map.get(:chatgpt_account_id) |> present_string()
     workspace_id = attrs |> Map.get(:workspace_id) |> present_string()
+    chatgpt_user_id = attrs |> Map.get(:chatgpt_user_id) |> present_string()
 
     case chatgpt_account_id do
       nil -> select_email_fallback_identity(attrs, workspace_id)
-      account_id -> select_account_slot_identity(account_id, workspace_id)
+      account_id -> select_account_slot_identity(account_id, workspace_id, chatgpt_user_id, attrs)
     end
   end
 
@@ -181,25 +182,57 @@ defmodule CodexPooler.Upstreams.Lifecycle.IdentityLifecycle do
   defp concrete_workspace?(%UpstreamIdentity{} = identity),
     do: not is_nil(present_string(identity.workspace_id))
 
-  defp select_account_slot_identity(account_id, workspace_id) do
+  defp select_account_slot_identity(account_id, workspace_id, nil, attrs) do
     identities = identities_for_account(account_id)
 
-    case identity_for_workspace(identities, workspace_id) do
+    case subjectless_identity_for_workspace(identities, workspace_id) do
       %UpstreamIdentity{} = identity ->
         {:ok, identity}
 
       nil ->
-        legacy_identity = identity_for_workspace(identities, nil)
-        concrete_identities = Enum.reject(identities, &is_nil(&1.workspace_id))
+        select_subjectless_account_fallback(identities, workspace_id, attrs)
+    end
+  end
+
+  defp select_account_slot_identity(account_id, workspace_id, subject, _attrs) do
+    identities = identities_for_account(account_id)
+
+    with nil <- identity_for_workspace_and_subject(identities, workspace_id, subject),
+         nil <- subjectless_identity_for_workspace(identities, workspace_id) do
+      {:ok, claimable_subjectless_legacy_identity(identities, workspace_id)}
+    else
+      %UpstreamIdentity{} = identity -> {:ok, identity}
+    end
+  end
+
+  defp select_subjectless_account_fallback(identities, workspace_id, attrs) do
+    case claimable_subjectless_legacy_identity(identities, workspace_id) do
+      %UpstreamIdentity{} = identity ->
+        {:ok, identity}
+
+      nil ->
+        case subject_bound_identity_for_workspace(identities, workspace_id) do
+          %UpstreamIdentity{} = conflict -> {:error, identity_conflict(attrs, conflict)}
+          nil -> {:ok, nil}
+        end
+    end
+  end
 
-        if (is_binary(workspace_id) and legacy_identity) && concrete_identities == [] do
-          {:ok, legacy_identity}
-        else
-          {:ok, nil}
+  defp claimable_subjectless_legacy_identity(identities, workspace_id)
+       when is_binary(workspace_id) do
+    case subjectless_identity_for_workspace(identities, nil) do
+      %UpstreamIdentity{} = legacy_identity ->
+        if subjectless_concrete_identities(identities) == [] do
+          legacy_identity
         end
+
+      nil ->
+        nil
     end
   end
 
+  defp claimable_subjectless_legacy_identity(_identities, _workspace_id), do: nil
+
   defp select_email_fallback_identity(attrs, workspace_id) do
     account_email = attrs |> Map.get(:account_email) |> normalize_email()
 
@@ -331,8 +364,35 @@ defmodule CodexPooler.Upstreams.Lifecycle.IdentityLifecycle do
   defp where_workspace(query, workspace_id),
     do: where(query, [identity], identity.workspace_id == ^workspace_id)
 
-  defp identity_for_workspace(identities, workspace_id) do
-    Enum.find(identities, &(&1.workspace_id == workspace_id))
+  defp subjectless?(%UpstreamIdentity{} = identity) do
+    is_nil(present_string(identity.chatgpt_user_id))
+  end
+
+  defp subject_bound?(%UpstreamIdentity{} = identity), do: not subjectless?(identity)
+
+  defp identity_for_workspace_and_subject(identities, workspace_id, subject) do
+    Enum.find(identities, fn identity ->
+      identity.workspace_id == workspace_id and
+        present_string(identity.chatgpt_user_id) == subject
+    end)
+  end
+
+  defp subjectless_identity_for_workspace(identities, workspace_id) do
+    Enum.find(identities, fn identity ->
+      identity.workspace_id == workspace_id and subjectless?(identity)
+    end)
+  end
+
+  defp subjectless_concrete_identities(identities) do
+    Enum.filter(identities, fn identity ->
+      subjectless?(identity) and not is_nil(present_string(identity.workspace_id))
+    end)
+  end
+
+  defp subject_bound_identity_for_workspace(identities, workspace_id) do
+    Enum.find(identities, fn identity ->
+      identity.workspace_id == workspace_id and subject_bound?(identity)
+    end)
   end
 
   defp sibling_concrete_slot?(%UpstreamIdentity{chatgpt_account_id: nil}), do: false

lib/codex_pooler/upstreams/oauth_flows/completion.ex

@@ -249,6 +249,7 @@ defmodule CodexPooler.Upstreams.OAuthFlows.Completion do
   defp oauth_link_attrs(tokens, token_info, config) do
     %{
       chatgpt_account_id: token_info.chatgpt_account_id,
+      chatgpt_user_id: token_info.chatgpt_user_id,
       account_email: token_info.email,
       account_label: token_info.email || token_info.chatgpt_account_id || "Codex account",
       workspace_id: token_info.workspace_id,