docs: canonical dependency-security consensus plan

docs/CLAUDE-DEPENDENCY-SECURITY-CONSENSUS-BRIEF.md

@@ -0,0 +1,188 @@
+> **SUPERSEDED 2026-08-29.** This document contains recommendations that were
+> revised during reconciliation and it is NOT internally consistent. Do not work
+> from it. The canonical agreed plan is
+> [`DEPENDENCY-SECURITY-PLAN.md`](DEPENDENCY-SECURITY-PLAN.md).
+> Retained for provenance only.
+
+---
+
+# RateMyPlace dependency-security decision brief
+
+**Audience:** Claude Project review, followed by a Codex/Claude consensus pass  
+**Prepared:** 2026-08-28  
+**Decision requested:** Choose the safest proportionate path for resolving the current npm dependency advisories without disguising framework-migration risk as routine maintenance.
+
+## How to use this brief
+
+Please review this as an independent technical adviser. Do not implement anything yet. Challenge the risk assessment, identify assumptions that are not adequately supported, and recommend a concrete sequence of work. The final section gives a response format so your advice can be returned to Codex for a point-by-point consensus pass.
+
+If the Project supports file attachments, also attach the current `AGENTS.md`, `package.json`, and `package-lock.json`. The repository rules in `AGENTS.md` are binding; in particular, `main` auto-deploys, Astro major upgrades trigger a CSRF re-audit, and completion requires check, test, build, and proportionate flow verification.
+
+## Project and release context
+
+RateMyPlace is an Astro 5 server-rendered tenant housing review platform deployed to Cloudflare Pages. It uses React islands, Cloudflare D1 and R2, Lucia authentication, Resend email, Turnstile, Vitest, and Playwright. It is a small production service maintained by one person, so the plan must reduce security risk without creating an oversized maintenance burden.
+
+Release-safety work was just completed and merged through PR #13. CI now checks types, tests, and the production build, and the release process can smoke-test the immutable Cloudflare Pages deployment for the exact commit before separately verifying the custom domain. The dependency work should use those gates rather than bypassing them.
+
+## Confirmed audit snapshot
+
+The following was verified on 2026-08-28 against the checked-in dependency graph and source. No package or source files were changed during the audit.
+
+| Check | Result |
+|---|---|
+| `npm audit --json` | 29 advisories: 1 critical, 15 high, 12 moderate, 1 low |
+| `npm audit --omit=dev --json` | 27 advisories: 0 critical, 14 high, 12 moderate, 1 low |
+| Non-major dependency-resolution simulation | 10 advisories: 0 critical, 6 high, 4 moderate, 0 low |
+| Coordinated Astro 7 dependency-resolution simulation | 1 low advisory, in the esbuild/tooling family |
+
+The `--omit=dev` result must not be confused with the deployed attack surface. Several build and Cloudflare-development packages are declared as production dependencies even though they are not necessarily reachable in the deployed Worker. Conversely, being present in a bundled file is not by itself proof that the application calls the vulnerable operation.
+
+### Current direct versions
+
+- Astro 5.16.11; current compatible Astro 5 release resolved in simulation: 5.18.2
+- `@astrojs/cloudflare` 12.6.13
+- `@astrojs/react` 3.6.3
+- Vitest 4.0.18; patched current release resolved in simulation: 4.1.11
+- happy-dom 20.5.1; compatible update resolved in simulation: 20.11.13
+- Resend 6.9.2; compatible update resolved in simulation: 6.25.0
+- `@astrojs/check` 0.9.6; compatible update resolved in simulation: 0.9.10
+- React and React DOM 18.3.1
+
+### Evidence limits
+
+Both upgrade simulations ran in temporary directories and proved dependency resolution and the resulting audit counts only. They did not prove that the upgraded application passes type-checking, tests, build, E2E, or runtime smoke checks. Those are implementation gates, not facts already established by this brief.
+
+## Exposure assessment
+
+### 1. Critical Vitest advisory
+
+The critical advisory is [GHSA-5xrq-8626-4rwp](https://github.com/advisories/GHSA-5xrq-8626-4rwp), affecting Vitest versions from 4.0.0 through versions before 4.1.0. Its exploit conditions involve an exposed Vitest UI/API or Browser Mode on Windows or a network-accessible test service.
+
+This repository runs `vitest run` with `happy-dom`. `vitest.config.ts` does not enable the UI, Browser Mode, or an API host. Vitest is not deployed as an application service. The current evidence therefore does **not** indicate a critical production exploit path, but the package should still be patched promptly because the fix is compatible and low-cost.
+
+### 2. Astro advisory aggregate
+
+Astro 5.16.11 is associated with multiple advisories, which causes npm to aggregate several findings under the direct Astro dependency. A source sweep found no use of `define:vars`, Astro spread attributes, dynamic slot names, or Astro transition directives in the application.
+
+The Host-header SSRF advisory [GHSA-2pvr-wf23-7pc7](https://github.com/withastro/astro/security/advisories/GHSA-2pvr-wf23-7pc7) explicitly says the Cloudflare adapter is not affected. The dynamic-slot XSS advisory [GHSA-8hv8-536x-4wqp](https://github.com/withastro/astro/security/advisories/GHSA-8hv8-536x-4wqp) requires attacker-controlled dynamic slot names, which the source sweep did not find. This lowers current exploitability; it does not make the outdated framework line a permanent acceptable state.
+
+### 3. Cloudflare adapter image SSRF
+
+`@astrojs/cloudflare` 12.6.13 is below the fixed line for [GHSA-88gm-j2wx-58h6](https://github.com/advisories/GHSA-88gm-j2wx-58h6), an SSRF involving remote-image allowlist bypass through redirects. The built Worker contains the Astro image route, but its generated configuration has no allowed remote domains or patterns. The application source does not import `astro:assets` or render Astro `Image` or `Picture` components.
+
+The current evidence therefore suggests that the vulnerable operation is not reachable through an application-configured remote-image source. Fixing the adapter still matters, but the compatible fixed adapter requires a coordinated Astro major upgrade rather than a simple patch.
+
+### 4. Resend transitive chain
+
+Resend 6.9.2 brings in `svix`, which brings in a vulnerable `uuid` version. The application uses `new Resend(...).emails.send(...)` in `src/lib/email.ts`; it does not use Resend webhook/Svix processing or the affected UUID buffer APIs. A Resend update to 6.25.0 removed the `svix`/`uuid` advisory chain in the simulation without requiring an application API change.
+
+### 5. Development and build tools
+
+The remaining Vite/esbuild findings concern development-server or file-serving behavior. Repository scripts do not expose the development server with `--host`. Wrangler, Miniflare, undici, and ws are used in local/build/deployment tooling; the audit did not find those modules as application runtime dependencies in the deployed Worker. Sharp is related to the image path described above.
+
+### Overall assessment
+
+**Codex's provisional rating is medium maintenance risk, not an active critical production incident.** The critical label is real at the package level, but the known exploit preconditions are absent from the deployed application. The correct response is prompt, controlled remediation with release verification, not an emergency unreviewed framework migration.
+
+## Options
+
+### Option A: Patch only the obviously reachable or critical packages
+
+Update Vitest and Resend, leave the rest alone, and defer framework work.
+
+**Advantage:** smallest diff and fastest execution.  
+**Problem:** leaves avoidable compatible updates undone, retains most audit noise, and makes future critical findings harder to distinguish from known debt. This is not the recommended option.
+
+### Option B: Two-stage remediation
+
+First perform a non-major dependency refresh within the current architecture. Then handle Astro and its adapters as a separately reviewed framework migration.
+
+**Advantage:** removes the critical finding and most total findings quickly while keeping the behavioral diff narrow. It also gives the Astro major upgrade the CSRF, adapter, build, and release scrutiny required by the repository rules.  
+**Problem:** the repository temporarily retains 10 known advisories after Stage 1, including the Cloudflare adapter advisory, so the second stage must be scheduled rather than allowed to disappear into a backlog.
+
+**This is Codex's recommendation.**
+
+### Option C: Upgrade directly to Astro 7 in one change
+
+Perform the compatible updates and framework/adapter migration together.
+
+**Advantage:** the simulation reduced the graph to one low advisory in one project.  
+**Problem:** it mixes low-risk package maintenance with a framework major upgrade, expands the regression surface, and triggers a required CSRF re-audit. A successful install and build would not by themselves prove that authentication, origin checking, SSR behavior, middleware, and Cloudflare bindings retained their semantics.
+
+## Proposed staged path
+
+### Stage 1: compatible security refresh
+
+Work on a feature branch such as `codex/dependency-security-refresh`. Do not use `npm audit fix --force`.
+
+The expected intended changes are:
+
+- raise the minimum compatible versions for Astro 5, Vitest, happy-dom, Resend, and `@astrojs/check` to the tested versions listed above;
+- refresh compatible transitive dependencies in `package-lock.json`;
+- review every direct and transitive lockfile change rather than accepting an opaque forced rewrite;
+- add a CI critical-advisory gate after the critical finding is removed, so it cannot silently return;
+- add weekly Dependabot updates with a low-noise grouping policy, if the maintenance burden is acceptable.
+
+The simulation also updated compatible transitive packages including Vite, PostCSS, nanoid, js-yaml, fast-uri, defu, and devalue. The actual branch should record the final resolved versions and explain any difference from the simulation.
+
+Expected audit result, based on the resolution simulation: 29 advisories become 10, with no critical or low findings. The real branch must reproduce that result.
+
+No product behavior is intended to change. This stage should not alter application features, design, copy, scoring, database data or migrations, Cloudflare settings, environment variables, authentication policy, moderation behavior, or privacy rules. Because dependency updates can still cause regressions, “no intended behavior change” is not the same as “no risk.”
+
+Required evidence before merge:
+
+1. clean install from the committed lockfile;
+2. `npm run check`;
+3. full Vitest suite;
+4. production build;
+5. full local Playwright suite because build/runtime libraries changed;
+6. before/after audit output and a reviewed lockfile diff;
+7. immutable preview smoke tied to the exact branch SHA;
+8. separate user approval before merge;
+9. post-merge exact-SHA production smoke and custom-domain verification.
+
+### Stage 2: coordinated Astro major migration
+
+Use a separate feature branch and review. The dependency-resolution simulation used:
+
+- Astro 7.2.9;
+- `@astrojs/cloudflare` 14.2.5;
+- `@astrojs/react` 6.0.4;
+- `@cloudflare/workers-types` 5.20260828.1;
+- React and React DOM remaining on 18.3.1.
+
+Compatibility observations from package metadata:
+
+- Astro 7.2.9 requires Node 22.12 or newer; the release-safety baseline pins Node 22.16;
+- Cloudflare adapter 14.2.5 peers with Astro 7.2 and a current Wrangler 4 line;
+- React adapter 6.0.4 supports React 18;
+- stopping at Cloudflare adapter 13.1.10 would still require Astro 6, so there is no adapter-only patch on the current Astro 5 architecture.
+
+This stage must include the repository-required CSRF re-audit. It should re-check `security.checkOrigin`, authenticated and unauthenticated POST behavior, middleware/session cookies, JSON-route protections, Cloudflare runtime bindings, SSR output, image endpoint exposure, and error behavior. Preview limitations for Turnstile and Maps remain expected; those integrations require production verification.
+
+Expected audit result from the dependency simulation: one low esbuild/tooling advisory. Any source or configuration changes needed for Astro 7 must be reviewed as functional changes, not hidden inside the package update.
+
+## Questions Claude should resolve
+
+1. Do you agree that there is no evidence of a currently reachable critical production exploit? If not, name the exact application path and advisory preconditions that make it reachable.
+2. Does the Cloudflare adapter image SSRF justify skipping directly to Astro 7 despite the absent remote-image configuration and component usage?
+3. Is the proposed Stage 1 package set complete and appropriately constrained? Should any package be excluded or added?
+4. Should Stage 1 change both `package.json` minimums and the lockfile, or only refresh the lockfile within existing ranges? Explain the maintenance and reproducibility implications.
+5. Is a full-graph `npm audit --audit-level=critical` CI gate the right first ratchet, or should the gate use production-only dependencies or a documented allowlist? How should it avoid normalizing permanent exceptions?
+6. Should Dependabot be enabled in Stage 1, and how should updates be grouped to keep a single-maintainer repository manageable?
+7. What additional tests or manual checks are necessary for the Astro 7 migration beyond the listed CSRF, auth, SSR, Cloudflare-binding, E2E, preview, and production checks?
+8. Are there safer supported mitigations for the 10 interim advisories that do not require unsupported overrides or `--force`?
+
+## Requested response format
+
+Please return:
+
+1. **Verdict:** concur, concur with changes, or reject the two-stage recommendation.
+2. **Risk assessment:** active incident vs maintenance risk, with the strongest evidence.
+3. **Agreement table:** each major Codex claim, agree/disagree/uncertain, and why.
+4. **Recommended Stage 1:** exact dependency and CI changes, verification, and rollback criteria.
+5. **Recommended Stage 2:** exact migration boundary, required audits, and verification.
+6. **Missing evidence:** anything that must be checked before implementation.
+7. **Consensus candidate:** a short proposed plan that both Claude and Codex could adopt.
+
+Do not recommend an implementation solely because it produces a lower `npm audit` count. Optimize for actual production risk reduction, supported upgrade paths, reproducibility, and confidence that RateMyPlace's privacy and security behavior remains intact.