feat(auth): harden X.509 lifecycle and add end-to-end validation

[jbeckwith-oai]

Summary

• introduce a single retry/authentication orchestrator for X.509 requests while preserving the ordinary-client retry path unchanged
• cache exchanged bearer tokens with expiry skew, single-flight refresh, rejected-generation invalidation, and one bounded 401 replay
• propagate request deadlines, cancellation, stream close, and client close through authentication, backoff, transport calls, request bodies, responses, parsing, and logging
• preserve exact client/pipeline ownership across sync/async views, reusable builders, generated Unit endpoints, and raw-response continuations
• add installed-JAR documentation, a runnable example/runtime probe, and a protected opt-in live X.509 smoke workflow

Compatibility and security boundaries

• ordinary non-X.509 construction and retry/completion behavior remains on the pre-existing code path
• X.509 remains fixed to the attested transport and fixed auth/API origins introduced by the earlier stack layers
• credentials remain bearer-only at the API boundary and are never added to logs, fixtures, examples, or default test output
• cleanup helpers act only on internal pipeline-owned markers; ordinary raw-response ownership remains unchanged
• public/source compatibility was verified against both baseline and proposed API manifests

Validation

• focused sync/async X.509 lifecycle matrix: passed, including token races, cancellation, deadlines, retries, 401 replay, builder/view ownership, request/response cleanup, logging, parsing, streams, and ordinary-client regressions
• repository lint: passed
• full scripts/test graph with Steady: passed, including R8 and ProGuard artifacts
• Java 21 runtime compatibility probe: passed for core, OkHttp, Bedrock, and runtime providers
• API/source breaking-change detector: passed for baseline and proposed public APIs
• staged secret-pattern scan and git diff --check: passed
• Castiron custom-code budget: 1668 of 2000 lines, 332 lines headroom; ratchet unchanged
• first review cycle: two independent agents clean after all findings were fixed; mandatory thermo-nuclear review clean
• second clean-room review cycle: two fresh independent agents clean on the exact frozen 49-file diff (1e5bba26e91a638915bfa509e87adee10b598c5d92bd23ae54a98a504a4e9fe6)

Stack

1. test: define X.509 workload identity wire contract #929 — executable raw-wire oracle (merged)
2. feat(auth): add fixed-alias X.509 transport capability #934 — fixed-alias direct mTLS transport capability
3. feat(auth): add X.509 workload token exchange #935 — identity metadata and exact token exchange
4. feat(auth): integrate X.509 SDK clients #936 — minimal sync/async client integration with fixed origins and exclusive auth
5. this PR — lifecycle, cache/single-flight, 401 rotation, deadline/cancellation ownership, installed-JAR docs, and protected live E2E

Stacked on #936.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-08-26T00:27:20.378256Z	54f37cd	New commits
🔒 Security Review	✅ Completed 2026-08-26T00:27:57.571428Z	54f37cd	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[github-actions]

Castiron custom code

✅ No new custom-code files detected.

63 mixed files remain; 0 existing customizations changed.

Compared 9a3ac279fa8a → 54f37cdf251f. Generated baselines verified.

63 existing customizations unchanged

• openai-java-core/src/main/kotlin/com/openai/client/OpenAIClientAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/client/OpenAIClientImpl.kt
• openai-java-core/src/main/kotlin/com/openai/models/audio/AudioResponseFormat.kt
• openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionCreateParams.kt
• openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionMessageFunctionToolCall.kt
• openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionToolMessageParam.kt
• openai-java-core/src/main/kotlin/com/openai/models/embeddings/Embedding.kt
• openai-java-core/src/main/kotlin/com/openai/models/embeddings/EmbeddingCreateParams.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseCreateParams.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseFunctionToolCall.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseFunctionWebSearch.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseInputItem.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseTextConfig.kt
• openai-java-core/src/main/kotlin/com/openai/models/videos/Video.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/BetaServiceAsync.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/BetaServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/ContainerServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/ResponseServiceAsync.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/ResponseServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/WebhookServiceAsync.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/WebhookServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/audio/TranscriptionServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/beta/ResponseServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/chat/ChatCompletionServiceAsync.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/containers/FileServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/finetuning/checkpoints/PermissionServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/realtime/CallServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/BetaService.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/BetaServiceImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/ContainerServiceImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/ResponseService.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/ResponseServiceImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/WebhookService.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/WebhookServiceImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/audio/TranscriptionServiceImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/beta/ResponseServiceImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/chat/ChatCompletionService.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/containers/FileServiceImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/finetuning/checkpoints/PermissionServiceImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/realtime/CallServiceImpl.kt

23 more in the full report.

A changed generated baseline means this report cannot reliably identify which handwritten lines changed.

Inspect the custom-code diff

Download the exact patch produced by this run (requires repository access):

gh run download 32915067605 --repo openai/openai-java \
  --name castiron-custom-code-32915067605-1 --dir /tmp/castiron-custom-code-32915067605-1
git apply --stat /tmp/castiron-custom-code-32915067605-1/custom-code.patch
cat /tmp/castiron-custom-code-32915067605-1/custom-code.patch

Or reproduce it from an SDK checkout containing the vendored reporter:

git fetch --no-tags origin 9a3ac279fa8a56edc9df884f923c777707c105c7 54f37cdf251ffdebf447cc4295203c1a30c75097
python3 scripts/castiron/custom_code_report.py report \
  --base 9a3ac279fa8a56edc9df884f923c777707c105c7 \
  --head 54f37cdf251ffdebf447cc4295203c1a30c75097 --fetch --require-head-hash --public \
  --out /tmp/castiron-custom-code-54f37cdf251f
cat /tmp/castiron-custom-code-54f37cdf251f/custom-code.patch

This is the current full custom patch for mixed files, not an attribution of only the handwritten lines changed by this PR.

Full report and patch

[HAYDEN-OAI]

Found two actionable issues in the new X.509 lifecycle: permanent issuer TLS failures can be masked by cached-token fallback, and repeatable request bodies are closed before 401 replay/retries. Details are inline.