From ef46bb8ceb21b99dc3b4f7573ccae94417f80b97 Mon Sep 17 00:00:00 2001 From: Justin Beckwith Date: Tue, 27 Oct 2026 15:26:52 -0700 Subject: [PATCH 1/2] docs: clarify next tooling retirement across revisions --- AGENTS.md | 8 +++++--- CONTRIBUTING.md | 23 ++++++++++++----------- 2 files changed, 17 insertions(+), 14 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index de90f9bd8..cbc062644 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,9 +21,11 @@ Handwritten edits to generated files are overwritten; they are never replayed or merged into new output. Preserve separately owned handwritten files and resolve ownership collisions explicitly. Follow this AGENTS.md rule and review generated output and inventory changes together. The simplified workflow relies on contributor guidance and code review. -This intermediate revision retains the legacy strict generated-file checker, -which rejects manifest mismatches when invoked. Respect retained checks and any -currently required statuses until canonical regeneration removes the tooling. +Canonical regeneration retires the legacy strict generated-file checker and +reporting tooling. While those files remain in a checkout, preserve their checks +and satisfy required statuses. After removal, do not recreate the retired tooling. +Repository rules and hosted workflow settings are separate: inspect their actual +state rather than assuming file removal disables a required check. Fix violations in the inputs/compiler and regenerate; never update inventory hashes to accept a handwritten patch. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 494415ec5..f6aa9dad1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,17 +38,18 @@ Separately owned handwritten files are preserved. Resolve ownership conflicts explicitly before regeneration. Follow the ownership rules in `AGENTS.md` and review generated output and inventory changes together. Generated-file ownership under the simplified workflow relies on contributor guidance and code -review. This revision still contains the legacy strict generated-file checker, -which rejects manifest mismatches when invoked; inspect live workflow settings -and required statuses separately until canonical regeneration removes it. Fix violations in the -generation inputs/compiler and regenerate; do not edit inventory hashes to -accept a handwritten patch. - -This `next` guidance precedes canonical regeneration: the legacy reporting -workflow definitions and tools still exist in this revision. Preserve their -security checks until removal, and inspect actual workflow settings and results -rather than assuming this document disables them. Do not start new budget -changes or bypass required checks. +review. Fix violations in the generation inputs/compiler and regenerate; do not +edit inventory hashes to accept a handwritten patch. + +Canonical regeneration retires the legacy strict checker, reporting workflows, +and associated tools. The files present depend on the revision: while they +remain in a checkout, preserve their security checks and satisfy required +statuses. After removal, do not recreate them or introduce a replacement budget +system. + +Repository rules and hosted workflow settings are configured separately from +these files. Inspect the actual settings and check results before merging; +this guidance neither disables workflows nor bypasses a required check. ## Security expectations From 52b2d1e9c0088f9bd1ae63ef6273159986c02c1e Mon Sep 17 00:00:00 2001 From: Justin Beckwith Date: Tue, 27 Oct 2026 15:33:48 -0700 Subject: [PATCH 2/2] docs: preserve transition rules and refresh evidence ranges --- CONTRIBUTING.md | 4 ++-- docs/architecture/security-model.md | 12 ++++++------ 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f6aa9dad1..e73b89f25 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -44,8 +44,8 @@ edit inventory hashes to accept a handwritten patch. Canonical regeneration retires the legacy strict checker, reporting workflows, and associated tools. The files present depend on the revision: while they remain in a checkout, preserve their security checks and satisfy required -statuses. After removal, do not recreate them or introduce a replacement budget -system. +statuses. Do not start new budget changes. After removal, do not recreate the +retired tools or introduce a replacement budget system. Repository rules and hosted workflow settings are configured separately from these files. Inspect the actual settings and check results before merging; diff --git a/docs/architecture/security-model.md b/docs/architecture/security-model.md index 046644440..6dfae53ec 100644 --- a/docs/architecture/security-model.md +++ b/docs/architecture/security-model.md @@ -30,10 +30,10 @@ repository. | Component | Purpose and important flow | Evidence | | --- | --- | --- | -| openai-java-core | Transport-neutral client, generated services and models, request construction, authentication headers, retry/logging wrappers, JSON/SSE parsing, and webhook verification. | CONTRIBUTING.md:78-81; openai-java-core/src/main/kotlin/com/openai/client/OpenAIClientImpl.kt:57-140; openai-java-core/src/main/kotlin/com/openai/core/ClientOptions.kt:747-808 | -| openai-java-client-okhttp | Default HTTP transport, caller-configurable proxy, redirects, timeouts, TLS, and hostname verification. | CONTRIBUTING.md:82-84; openai-java-client-okhttp/src/main/kotlin/com/openai/client/okhttp/OpenAIOkHttpClient.kt:54-65; openai-java-client-okhttp/src/main/kotlin/com/openai/client/okhttp/OkHttpClient.kt:180-242 | -| openai-java | Umbrella artifact exposing core and OkHttp APIs without its own logic. | CONTRIBUTING.md:85-87; openai-java/build.gradle.kts:1-8 | -| openai-java-bedrock | Optional Bedrock endpoint selection and bearer or AWS SigV4 authentication. | CONTRIBUTING.md:88-89; openai-java-bedrock/src/main/kotlin/com/openai/bedrock/BedrockAuth.kt:64-215 | +| openai-java-core | Transport-neutral client, generated services and models, request construction, authentication headers, retry/logging wrappers, JSON/SSE parsing, and webhook verification. | CONTRIBUTING.md:79-82; openai-java-core/src/main/kotlin/com/openai/client/OpenAIClientImpl.kt:57-140; openai-java-core/src/main/kotlin/com/openai/core/ClientOptions.kt:747-808 | +| openai-java-client-okhttp | Default HTTP transport, caller-configurable proxy, redirects, timeouts, TLS, and hostname verification. | CONTRIBUTING.md:83-85; openai-java-client-okhttp/src/main/kotlin/com/openai/client/okhttp/OpenAIOkHttpClient.kt:54-65; openai-java-client-okhttp/src/main/kotlin/com/openai/client/okhttp/OkHttpClient.kt:180-242 | +| openai-java | Umbrella artifact exposing core and OkHttp APIs without its own logic. | CONTRIBUTING.md:86-88; openai-java/build.gradle.kts:1-8 | +| openai-java-bedrock | Optional Bedrock endpoint selection and bearer or AWS SigV4 authentication. | CONTRIBUTING.md:89-90; openai-java-bedrock/src/main/kotlin/com/openai/bedrock/BedrockAuth.kt:64-215 | | openai-java-vertex | Optional Vertex endpoint selection and Google bearer authentication. | openai-java-vertex/README.md; openai-java-vertex/src/main/kotlin/com/openai/client/okhttp/VertexOpenAIOkHttpClient.kt | | Build and release workflows | Unprivileged PR validation and separately gated main-only release/publish jobs. | .github/workflows/ci.yml:3-24; .github/workflows/create-releases.yml:3-25 | @@ -89,7 +89,7 @@ not exposed to the attestation action. application's responsibility. - Large JSON bodies and streaming events are supported API contracts. Reviews should prefer incremental processing, cleanup, and cancellation; a large - payload is not by itself hostile or malformed. (AGENTS.md:59-76) + payload is not by itself hostile or malformed. (AGENTS.md:61-78) - Main-branch integrity, protected release credentials, GPG signing material, OIDC attestation authority, artifact/source binding, and Gradle cache isolation must remain unreachable from unmerged PR code. @@ -179,7 +179,7 @@ These are review hypotheses, not confirmed findings. | --- | --- | --- | --- | --- | --- | --- | | High | PR-controlled code reaches protected release credentials or signing/attestation authority before merge/release governance. | A workflow trigger, checkout ref, artifact restore, or environment gate is weakened. | Credential theft or forged official artifacts. | Release is main/schedule/manual only, selects/verifies source, gates runtime compatibility, uses protected publish, and disables release cache reuse. | Preserve source binding, least permissions, environment protection, and no PR artifact/cache import. | .github/workflows/create-releases.yml:3-25; .github/workflows/create-releases.yml:90-164; .github/workflows/create-releases.yml:241-290; .github/workflows/create-releases.yml:426-469 | | High | Untrusted webhook bytes are parsed or acted on without valid signature/freshness checks. | Embedding application exposes webhook ingress and relies on SDK verification. | Forged event acceptance. | Required headers, bounded timestamp tolerance, HMAC-SHA256, timing-safe compare, then parse; no replay deduplication. | Preserve verify-before-parse ordering and focused regression tests; embedding applications must deduplicate accepted webhook IDs when replay matters. | openai-java-core/src/main/kotlin/com/openai/services/WebhookVerification.kt:19-99; openai-java-core/src/main/kotlin/com/openai/services/blocking/WebhookServiceImpl.kt:33-41 | -| Medium | Independently mutable API/SSE JSON crosses a parser boundary and causes unsafe interpretation, resource exhaustion, or sensitive exception/log output. | Attacker controls an API/network response or configured proxy; sink is reachable in caller deployment. | Client failure, data exposure, or downstream misuse. | Strict mapper defaults, typed parsing, stream iteration, and explicit DEBUG diagnostics. | Keep parsing robust and large-payload-compatible; avoid treating model output as executable authority without caller controls. | openai-java-core/src/main/kotlin/com/openai/core/ObjectMappers.kt:34-116; openai-java-core/src/main/kotlin/com/openai/core/handlers/SseHandler.kt:19-60; AGENTS.md:59-76 | +| Medium | Independently mutable API/SSE JSON crosses a parser boundary and causes unsafe interpretation, resource exhaustion, or sensitive exception/log output. | Attacker controls an API/network response or configured proxy; sink is reachable in caller deployment. | Client failure, data exposure, or downstream misuse. | Strict mapper defaults, typed parsing, stream iteration, and explicit DEBUG diagnostics. | Keep parsing robust and large-payload-compatible; avoid treating model output as executable authority without caller controls. | openai-java-core/src/main/kotlin/com/openai/core/ObjectMappers.kt:34-116; openai-java-core/src/main/kotlin/com/openai/core/handlers/SseHandler.kt:19-60; AGENTS.md:61-78 | | Medium | Credentials or customer payloads reach an unintended destination or uncontrolled log. | Lower-trust actor independently controls base URL/proxy/TLS/log sink, or diagnostics are enabled in an unsafe deployment. | Secret or customer-data disclosure. | Production URL default, caller-owned configuration, auth wrappers, and default sensitive-header redaction; DEBUG is explicit. | Preserve redaction and destination/TLS controls; document caller obligations. | openai-java-core/src/main/kotlin/com/openai/core/ClientOptions.kt:151-172; openai-java-core/src/main/kotlin/com/openai/core/ClientOptions.kt:601-665; openai-java-core/src/main/kotlin/com/openai/core/http/LoggingHttpClient.kt:24-48; openai-java-core/src/main/kotlin/com/openai/core/http/LoggingHttpClient.kt:91-142 | | Medium | A separately privileged evaluator consumes mutable PR Git objects, artifacts, or cache entries as trusted code/data. | Privileged workflow reads candidate state without binding/ref validation. | Privilege crossing beyond ordinary PR CI. | Custom-code workflow checks out main, uses current PR objects, and freshness-checks exact head; PR cache scope remains isolated. | Preserve trusted checkout and exact-head/digest binding. | .github/workflows/castiron-custom-code-comment.yml:34-57; .github/workflows/castiron-custom-code-comment.yml:128-181; .github/workflows/ci.yml:120-129 | | Low / not a boundary by itself | A PR changes a checked-in example, test, fixture, build script, or generated source and ordinary PR CI executes it. | The same PR author already controls the tracked executable checkout. | No new capability beyond the unprivileged PR job. | PR CI has read-only contents and no release credentials; cache scope is enforced outside PR code. | Investigate only if execution crosses an independent input or protected-authority boundary. | .github/workflows/ci.yml:8-20; .github/workflows/ci.yml:33-48; .github/workflows/ci.yml:92-107 |