azaion/satellite-provider
1
0
Fork 0
mirror of https://github.com/azaion/satellite-provider.git synced 2026-06-21 22:51:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

[AZ-495] [AZ-496] Cycle 3 batch 1: doc convention + AspNetCore 8.0.25
ci/woodpecker/push/01-test Pipeline was successful
Details
ci/woodpecker/push/02-build-push Pipeline was successful
Details

Browse Source 
AZ-495 (1 SP): formalize the modules-only documentation convention for
the WebApi component. _docs/02_document/module-layout.md now carries an
explicit Documentation Layout section anchoring WebApi docs at
modules/api_program.md; the components/06_web_api/ folder is
intentionally absent. .cursor/skills/new-task/SKILL.md Step 4 directs
future agents at the correct path. Cycle-1 + cycle-2 F1 findings in the
two batch-review files are marked RESOLVED with back-reference to
AZ-495. Cycle-2 retrospective decision-item list F1 updated.

AZ-496 (2 SP): bump Microsoft.AspNetCore.OpenApi and JwtBearer in
SatelliteProvider.Api.csproj from 8.0.21 to 8.0.25, closing CVE-
2026-26130 (SignalR DoS - not reachable in this app, but the runtime
patch is the recommended hardening per cycle-1 D1 + cycle-2 D3).
SatelliteProvider.Tests.csproj has no direct JwtBearer reference - it
consumes JwtBearer transitively via ProjectReference to Api, so no
edit needed there. Dockerfiles use floating mcr.microsoft.com/
dotnet/aspnet:8.0 / sdk:8.0 / runtime:8.0 tags which auto-resolve to
>= 8.0.25 on rebuild. Security artifacts (dependency_scan.md,
security_report.md) and current-state docs (module-layout.md,
architecture.md, modules/api_program.md, modules/tests_unit.md)
updated to reflect 8.0.25.

Batch report + code review report (verdict PASS_WITH_WARNINGS with 2
Low findings, neither blocking) written under _docs/03_implementation.

Test suite gate deferred to Step 16 (Final Test Run) per implement
skill convention. Patch-level bump within .NET 8 LTS; regression risk
very low.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-12 01:24:48 +03:00
parent 76076cbd90
commit 9cfd80babe
15 changed files with 140 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
_docs/02_tasks/done/AZ-495_doc_folder_convention.md
+119
View File
@@ -0,0 +1,119 @@
# Doc-folder convention for WebApi component
**Task**: AZ-495_doc_folder_convention
**Name**: Resolve doc-folder convention for WebApi
**Description**: Settle the recurring F1 code-review finding (cycle 1 AZ-487 + cycle 2 AZ-488) where task specs reference `_docs/02_document/components/01_web_api/description.md` which does not exist. Pick one: (a) create the stub folder, or (b) formalize the "WebApi lives in `modules/api_program.md`" convention. Update task-spec templates accordingly so the finding stops recurring.
**Complexity**: 1 point
**Dependencies**: None
**Component**: Documentation conventions (`_docs/02_document/`) + task-spec templates (`.cursor/skills/decompose/templates/task.md`)
**Tracker**: AZ-495
**Epic**: none (process / quality)
## Problem
The cycle-1 (AZ-487) and cycle-2 (AZ-488) code reviews each surfaced an identical F1 finding (Low / Style): the task spec referenced `_docs/02_document/components/01_web_api/description.md`, a folder that has never existed in the codebase. The existing component-doc folders are:
```
_docs/02_document/components/
01_common/
02_data_access/
03_tile_downloader/
04_region_processing/
05_route_management/
```
The WebApi component's documentation lives in `_docs/02_document/modules/api_program.md`. Each cycle's batch worked around the missing folder by updating `modules/api_program.md` instead. The decision item — create the stub folder OR formalize the modules-only convention — was carried as an open item but never settled.
The cycle-2 retrospective (`_docs/06_metrics/retro_2026-05-11_cycle2.md` § 9) lists this as a decision item carried over. Until it's settled, every future cycle that touches WebApi will repeat the same finding and the same workaround.
## Outcome
- The decision is made and reflected in `_docs/02_document/module-layout.md` (canonical convention).
- Task-spec templates and any decompose-skill prompts that auto-generate task docs no longer reference a nonexistent path.
- The cycle 1 + cycle 2 code-review findings (F1) are explicitly resolved with a back-reference to this PBI's tracker ID.
## Scope
### Included
Option **A — Create stub folder** (matches the layout convention of other components):
- Create `_docs/02_document/components/01_web_api/description.md` as a brief stub that:
- Documents the WebApi component at a level consistent with the other 5 component descriptions (purpose, architectural pattern, upstream/downstream).
- Either inlines the full content (preferred for consistency) or includes a single "for module-level detail, see `_docs/02_document/modules/api_program.md`" pointer.
- Renumber existing components if needed (e.g., 01_common stays, WebApi becomes 06_web_api at the layer-4 position — implementer's call based on architecture layering).
- Update task-spec templates to point at the new path.
Option **B — Formalize modules-only convention for WebApi**:
- Update `_docs/02_document/module-layout.md` § "Documentation layout" with an explicit note: "The WebApi component (`SatelliteProvider.Api`) has no `components/*` folder — its documentation lives in `_docs/02_document/modules/api_program.md` because the API layer is documented at module-level rather than component-level."
- Update task-spec templates and any decompose-skill scaffolds to reference `modules/api_program.md` instead of a nonexistent `components/01_web_api/description.md` path.
- Add a checklist row to `.cursor/skills/new-task/SKILL.md` Step 4 (Codebase Analysis): "WebApi documentation is in `modules/api_program.md`, not `components/`."
Either option:
- Update `_docs/03_implementation/reviews/batch_01_cycle2_review.md` and `batch_02_cycle2_review.md` with a one-line resolution note pointing at this PBI.
- Update the cycle-2 retrospective decision-item list (§ 9) to mark F1 resolved.
### Excluded
- Rewriting any existing module documentation. The module-level `api_program.md` stays where it is; this PBI is about the convention, not the content.
- Restructuring the other 5 component folders.
- Changing the layout of `modules/` vs `components/` — that's a much larger decision.
## Acceptance Criteria
**AC-1: One option chosen and documented**
Given the post-PBI repository
When `_docs/02_document/module-layout.md` is read
Then either (a) a `components/01_web_api/description.md` (or its renumbered equivalent) exists with non-trivial content, OR (b) an explicit "WebApi has no components/* folder" convention is documented with rationale.
**AC-2: Templates updated**
Given a fresh `/new-task` invocation that touches WebApi
When the skill generates a task spec
Then the spec references the correct documentation location (Option A: the new component folder; Option B: `modules/api_program.md`) — never the nonexistent path.
**AC-3: Code-review findings explicitly resolved**
Given the post-PBI repository
When `_docs/03_implementation/reviews/batch_01_cycle2_review.md` and `batch_02_cycle2_review.md` are read
Then their F1 finding sections include a resolution note pointing at this PBI.
**AC-4: Regression check**
Given a hypothetical next cycle's code review
When the review runs Phase 6 (Cross-Task Consistency)
Then no F1-shaped finding fires because either the path now exists OR the convention is documented and templates were updated.
## Non-Functional Requirements
**Compatibility**
- Must not break links from any existing documentation file. If Option A introduces a new path, run a grep for `01_web_api` across all `_docs/` files and confirm none reference a path that hasn't been created.
- Must not break the existing `monorepo-document` skill workflow (which reads component descriptions).
## Unit Tests
| AC Ref | What to Test | Required Outcome |
|--------|-------------|-----------------|
| (none) | This is a documentation / convention PBI; no code paths to unit-test | — |
## Blackbox Tests
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|------------------------|-------------|-------------------|----------------|
| AC-2 | Fresh `/new-task` invocation touching a WebApi-side change | The generated task spec's Documentation section | References the correct path; no reference to nonexistent path | — |
## Constraints
- The decision is binary — pick A or B, not "both" or "neither".
- If Option A is chosen, the new file's content must be substantive enough to justify its existence (≥ 30 lines), not a one-line redirect placeholder.
- If Option B is chosen, the convention note in `module-layout.md` must include the rationale, not just the rule.
## Risks & Mitigation
**Risk 1: Decision deferred again**
- *Risk*: This PBI ends up "let's revisit later" without picking A or B, and the F1 finding recurs in cycle 3.
- *Mitigation*: The PBI is explicitly a forced decision. Implementer or operator picks A or B during the kickoff conversation; no third "deferred" option is acceptable.
**Risk 2: Renumbering ripples (Option A)**
- *Risk*: If Option A inserts `01_web_api` and renumbers existing folders, all existing component-doc links across `_docs/` break.
- *Mitigation*: Prefer appending (e.g., `06_web_api`) rather than renumbering. Run a grep for `components/0` references before/after to catch any broken link.
**Risk 3: Convention drift (Option B)**
- *Risk*: Future developers see 5 `components/` folders and 1 module file and instinctively create a 6th `components/` folder for WebApi.
- *Mitigation*: The note in `module-layout.md` is canonical. Add a checklist line to `new-task` skill so the agent surfaces the convention at task-creation time.
_docs/02_tasks/done/AZ-496_bump_aspnetcore_8025.md
+119
View File
@@ -0,0 +1,119 @@
# Bump AspNetCore.OpenApi + JwtBearer to 8.0.25
**Task**: AZ-496_bump_aspnetcore_8025
**Name**: Bump AspNetCore 8.0.21 → 8.0.25
**Description**: Bump both `Microsoft.AspNetCore.OpenApi` (cycle-1 finding D1) and `Microsoft.AspNetCore.Authentication.JwtBearer` (cycle-2 finding D3) from `8.0.21` to the latest `8.0.x` patch (`8.0.25`) in a single coordinated commit. Closes CVE-2026-26130 (SignalR DoS — not reachable in this app, but the runtime patch is the recommended hardening).
**Complexity**: 2 points
**Dependencies**: None
**Component**: WebApi (`SatelliteProvider.Api`) — dependency upgrade only
**Tracker**: AZ-496
**Epic**: none (cycle-3 security hardening)
## Problem
The cycle-1 security audit (`_docs/05_security/dependency_scan.md` finding D1) flagged `Microsoft.AspNetCore.OpenApi 8.0.21` as one patch behind 8.0.25 due to CVE-2026-26130 (SignalR DoS via unbounded buffer). Disposition was "not exploitable in this app — no SignalR use", but the recommended hardening is still to bump the package.
The cycle-2 security audit added finding D3: `Microsoft.AspNetCore.Authentication.JwtBearer 8.0.21` (added by AZ-487) shares the same 8.0.21 patch line. Pinning a second 8.0.21 package raises the cost of not doing the bump — every additional package implicitly hardcodes the runtime expectation.
Cycle-2 security report explicitly recommends bumping **both** packages in a single coordinated commit so the project's ASP.NET Core 8 LTS footprint stays uniform.
Pre-public-network exposure is the trigger for actually executing this hardening (per `_docs/05_security/security_report.md`). Cycle 3 is a good time because no high-risk new code is shipping concurrently, so the bump can be exercised against the full test suite as a standalone change.
## Outcome
- Both `Microsoft.AspNetCore.OpenApi` and `Microsoft.AspNetCore.Authentication.JwtBearer` are pinned to `8.0.25` (or the latest available 8.0.x patch at implementation time, whichever is higher).
- All unit + integration tests pass against the bumped packages.
- Container image build succeeds (Dockerfile is still pinned to a runtime image ≥ 8.0.25 so the deployed binary actually picks up the patched ASP.NET Core runtime).
- `_docs/05_security/dependency_scan.md` D1 + D3 entries are marked Resolved with a reference to this PBI's tracker ID.
- `_docs/05_security/security_report.md` D1/D3 row moves from Open to Resolved.
## Scope
### Included
- Edit `SatelliteProvider.Api/SatelliteProvider.Api.csproj`:
- `<PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="8.0.21" />` → `Version="8.0.25"`
- `<PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="8.0.21" />` → `Version="8.0.25"`
- Edit `SatelliteProvider.Tests/SatelliteProvider.Tests.csproj`:
- `<PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="8.0.21" />` → `Version="8.0.25"`
- Verify the runtime image in `SatelliteProvider.Api/Dockerfile` (or wherever the runtime base image is pinned) is at ≥ 8.0.25. Bump if not.
- Run the full test suite (`./scripts/run-tests.sh --full`) — all green required for this PBI to land.
- Update `_docs/05_security/dependency_scan.md`: mark D1 and D3 Resolved with a one-line note pointing at this PBI's tracker ID.
- Update `_docs/05_security/security_report.md` summary table: D1/D3 status Open → Resolved.
- Verify version consistency: any other 8.0.x ASP.NET Core packages (if any) are bumped to the same patch line to keep `coderule.mdc`'s "consistent package versions" rule satisfied.
### Excluded
- Bumping to ASP.NET Core 9.x or 10.x — this is a patch-level bump only.
- Bumping unrelated packages (Dapper, Npgsql, ImageSharp) — separate decisions.
- Updating `Microsoft.NET.Test.Sdk` (finding D2) — that's a test-only Low and a separate PBI if/when it lands. Mention it in the batch report as the next dep-bump candidate.
- Any production code change.
## Acceptance Criteria
**AC-1: Both packages pinned to 8.0.25**
Given the post-PBI `*.csproj` files
When `grep "Microsoft.AspNetCore" SatelliteProvider.Api/SatelliteProvider.Api.csproj SatelliteProvider.Tests/SatelliteProvider.Tests.csproj` is run
Then both `Microsoft.AspNetCore.OpenApi` AND `Microsoft.AspNetCore.Authentication.JwtBearer` resolve to `Version="8.0.25"`.
**AC-2: Runtime image at or above 8.0.25**
Given the post-PBI `SatelliteProvider.Api/Dockerfile`
When the runtime base image is inspected
Then it pins (or transitively resolves to) ≥ 8.0.25.
**AC-3: All tests pass against the bumped packages**
Given the bumped repository
When `./scripts/run-tests.sh --full` is run
Then all unit + integration tests pass with no new failures vs. the pre-bump baseline.
**AC-4: Security findings updated**
Given the post-PBI repository
When `_docs/05_security/dependency_scan.md` is read
Then D1 and D3 status is Resolved with a reference to this PBI's tracker ID, AND the summary table in `_docs/05_security/security_report.md` reflects the same.
**AC-5: Image build succeeds**
Given the bumped repository
When `docker-compose build` is run
Then the API image builds successfully without warnings about package downgrade or framework conflict.
## Non-Functional Requirements
**Compatibility**
- 8.0.21 → 8.0.25 is a patch-level bump within the 8 LTS line; no public API change expected. If any API drift is observed, STOP and document — this would be unusual and worth investigating.
- The bump must not change `TokenValidationParameters` semantics (cycle-2 JWT validation behavior preserved).
**Security**
- The bump's primary security benefit (CVE-2026-26130) is in code paths NOT reachable from this app. The bump is "hygiene" rather than "active CVE closure", but D1's disposition already explained this and the cycle-2 audit reiterated.
## Unit Tests
| AC Ref | What to Test | Required Outcome |
|--------|-------------|-----------------|
| AC-3 | All existing unit tests | Pass unchanged |
## Blackbox Tests
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|------------------------|-------------|-------------------|----------------|
| AC-3 | Bumped repo | `./scripts/run-tests.sh --full` | All green | Compatibility |
| AC-5 | Bumped repo | `docker-compose build` | Successful image build | — |
## Constraints
- This is a coordinated bump: BOTH packages move together. Do not bump only one.
- The chosen target version MUST be the same across `Api.csproj` and `Tests.csproj` for `JwtBearer` (no version-drift between projects).
- If a higher 8.0.x patch is available at implementation time (e.g., 8.0.27), use that and document the choice in the batch report.
## Risks & Mitigation
**Risk 1: Latent API drift between 8.0.21 and 8.0.25**
- *Risk*: A behavioral change in the JWT bearer middleware between patch versions affects existing test fixtures or production behavior.
- *Mitigation*: AC-3 (full test suite green) is the gate. The Microsoft.AspNetCore patch notes between 8.0.21 and 8.0.25 are short and well-scoped (mostly hotfixes); a behavior drift is unlikely but the test suite would catch it.
**Risk 2: Runtime image upgrade required**
- *Risk*: The Dockerfile base image may still be at 8.0.21; bumping only NuGet packages doesn't help if the runtime is stale.
- *Mitigation*: AC-2 covers this explicitly. Bump the Dockerfile base image in the same commit if needed.
**Risk 3: Cascade bumps**
- *Risk*: Bumping these two packages may pull in transitive dependency updates that conflict with `Microsoft.Extensions.*` (currently at 9.0.10).
- *Mitigation*: A `dotnet restore` (run by the user, not the agent — per AGENTS.md) will surface any conflict immediately. If it occurs, document the cascade and decide whether to fold the cascade in or scope-cut.