Skip to content

docs: clarify next ownership checks during transition #3065

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jbeckwith-oai merged 1 commit into from
Oct 27, 2026
Merged

docs: clarify next ownership checks during transition #3065

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions .github/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,8 +93,10 @@ Handwritten edits to generated output are overwritten, not carried forward.
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 currently relies on contributor guidance and code review, without a
dedicated generated-file edit check or required gate. Fix violations in the
ownership will rely on contributor guidance and code review after canonical
regeneration removes the legacy reporting tooling. Until then, the retained
strict ownership checker can reject generated-file mismatches; preserve its
checks and satisfy any required statuses. Fix violations in the
generation inputs/compiler and regenerate; do not edit inventory hashes to
accept a handwritten patch.

Expand Down
6 changes: 4 additions & 2 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,8 +86,10 @@ Regeneration replaces generator-owned files and deletes retired generated paths.
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. Generated-file ownership currently relies on contributor guidance and
code review; there is no dedicated generated-file edit check or required gate.
together. After canonical regeneration removes the legacy reporting tooling,
generated-file ownership relies on contributor guidance and code review. Until
then, the retained strict ownership checker can reject generated-file mismatches;
preserve its checks and satisfy any required statuses.
Fix violations in the inputs/compiler and regenerate; never update inventory
hashes to accept a handwritten patch.

Expand Down
13 changes: 7 additions & 6 deletions docs/architecture/security-model.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,10 +25,11 @@ in external scan configuration. It records reusable architecture and
trust-boundary context; the scenarios below are hypotheses and calibration
examples, not findings.

Generated-file ownership currently relies on `AGENTS.md`, contributor guidance,
and ordinary SDK code review. There is no dedicated generated-file edit check or
required gate. Review generated output and inventory changes together; fix
violations in the inputs/compiler and regenerate.
After canonical regeneration removes the legacy reporting tooling, generated-file
ownership relies on `AGENTS.md`, contributor guidance, and SDK code review. This
revision still retains the strict ownership checker, which can reject generated-file
mismatches. Preserve its checks and satisfy any required statuses. Review output
and inventory changes together; fix violations in the inputs/compiler and regenerate.

## 1. Overview

Expand Down Expand Up @@ -363,7 +364,7 @@ read-only token permissions remain in place (`.github/workflows/ci.yml`).
- **Dependencies to build execution:** frozen lockfiles and workspace dependency
policy reduce supply-chain risk, but dependency lifecycle behavior remains a
real boundary when independently mutable artifacts can reach a trusted build
(`.github/CONTRIBUTING.md:96-110`, `pnpm-workspace.yaml:7-37`).
(`.github/CONTRIBUTING.md:130-142`, `pnpm-workspace.yaml:7-37`).

## 3. Attack Surface, Mitigations, and Attacker Stories

Expand All @@ -374,7 +375,7 @@ read-only token permissions remain in place (`.github/workflows/ci.yml`).
| High | Untrusted API, stream, WebSocket, or model output crosses parser state into prototype pollution, tenant confusion, or an unintended privileged callback. | Attacker controls a real protocol payload or model/tool argument, not merely trusted callback code. | Cross-request state corruption, unauthorized callback effects, or sensitive data exposure. | Structured validators, parser checks, WebSocket event dispatch boundaries, and callback allowlisting; callbacks are supplied by the application. | Preserve own-property validation, schema boundaries, iteration limits, event cleanup, and application-level authorization inside callbacks. | `src/internal/parse.ts:17-93`, `src/resources/responses/ws-base.ts:194-611`, `src/resources/beta/responses/ws-base.ts:198-615`, `src/lib/parser.ts:162-184`, `src/helpers/standard-schema.ts:703-805`, `src/lib/AbstractChatCompletionRunner.ts:446-499` |
| Medium | Malformed or very large legitimate response, stream, upload, WebSocket, pagination, or embedding data causes disproportionate CPU, memory, retention, or cancellation failure. | Lower-trust runtime data reaches a parser, accumulator, decoder, polling loop, pagination loop, or base64 expansion used by a long-lived process. | Worker availability degradation without credential compromise. | Ordinary HTTP retry hints are bounded; shared streams own cancellation cleanup; uploads support incremental encoding and typed-multipart cleanup; polling and pagination expose caller cancellation but commonly lack overall deadlines. | Prefer incremental, amortized-linear processing and timely cleanup; callers impose service-level budgets where needed. Do not add arbitrary limits that reject supported large API payloads. | `src/internal/parse.ts:17-93`, `src/core/streaming.ts:88-456`, `src/client.ts:1549-1667`, `src/lib/polling.ts:94-144`, `src/core/pagination.ts:29-61`, `src/core/pagination.ts:155-328`, `src/lib/embeddings.ts:17-65`, `src/internal/utils/base64.ts:45-61`, `src/helpers/audio.ts:35-73`, `src/helpers/audio.ts:119-281`, `src/internal/to-file.ts:93-208`, `src/internal/uploads.ts:203-640`, `src/internal/multipart-encoding.ts:7-53` |
| High | An external PR or mutable artifact reaches main-only API keys, release GitHub App credentials, or npm OIDC publication authority. | Protected branch/environment or immutable artifact binding is bypassed; ordinary read-only PR CI is insufficient. | Credential theft or publication of attacker-controlled official packages. | PR jobs use read-only contents; releases are main-only; release SHA and artifacts are verified; publisher script is preserved from trusted workflow code. | Keep privileged workflows bound to protected, immutable revisions and maintain least-privilege permissions. | `.github/workflows/ci.yml:18-154`, `.github/workflows/ci.yml:260-313`, `.github/workflows/create-releases.yml:41-80`, `.github/workflows/create-releases.yml:106-164`, `.github/workflows/create-releases.yml:288-346` |
| Not a boundary by itself | A contributor changes a tracked test, fixture, example, build script, or workflow-invoked helper and that repository code executes during its normal build or test workflow. | The same actor already controls the tracked executable code being run. | No new capability solely from execution of code already entrusted with repository-code authority. | Code review and the workflow's existing permission boundary. | Re-evaluate only if independently mutable input or a protected credential transition is present. | `.github/workflows/ci.yml:18-154`, `scripts/test:43-172`, `.github/CONTRIBUTING.md:122-136` |
| Not a boundary by itself | A contributor changes a tracked test, fixture, example, build script, or workflow-invoked helper and that repository code executes during its normal build or test workflow. | The same actor already controls the tracked executable code being run. | No new capability solely from execution of code already entrusted with repository-code authority. | Code review and the workflow's existing permission boundary. | Re-evaluate only if independently mutable input or a protected credential transition is present. | `.github/workflows/ci.yml:18-154`, `scripts/test:43-172`, `.github/CONTRIBUTING.md:130-142` |
| High | Lower-trust workflow metadata, candidate artifacts, or automation output controls a privileged status, PR-comment, repository-write, or draft-PR action. | A trusted workflow fails to bind its write to validated event, repository, revision, identity, or allowed paths. | Attacker-controlled statuses, comments, or repository changes. | Monthly Node review is main-only and constrained to draft PR paths; required human review and branch protection are external assumptions. | Preserve immutable trusted-code, event identity, freshness, path, and externally enforced review gates. | `.github/workflows/node-version-review.yml:17-55`, `.github/workflows/node-version-review.yml:90-111` |

## 4. Severity Calibration
Expand Down
Loading