From 0a40666884fd669ef88fbf3557449c3ca33e0e74 Mon Sep 17 00:00:00 2001 From: Justin Beckwith Date: Tue, 27 Oct 2026 12:13:35 -0700 Subject: [PATCH] docs: clarify next ownership checks during transition --- .github/CONTRIBUTING.md | 6 ++++-- AGENTS.md | 6 ++++-- docs/architecture/security-model.md | 13 +++++++------ 3 files changed, 15 insertions(+), 10 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index eca95b635..9558fbc3a 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -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. diff --git a/AGENTS.md b/AGENTS.md index 00baa2876..de812a045 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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. diff --git a/docs/architecture/security-model.md b/docs/architecture/security-model.md index 2e353278c..d5f9c86a2 100644 --- a/docs/architecture/security-model.md +++ b/docs/architecture/security-model.md @@ -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 @@ -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 @@ -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