CSRF middleware planned before introducing any cookie-based auth

[kilodesodiq-arch]

Problem Statement. security.module.ts carries an explicit comment:

/**
 * WARNING:
 * If cookie-based session management or any browser-managed credentials are introduced
 * in the future, CSRF protection middleware MUST be implemented.
 */

There is no ticket tracking that future obligation. Re-introducing a cookie or
SameSite=None; Secure flow without realising the gap is a one-line PR away from a regression.

Why it matters. CSRF defences are only as good as their visibility. Embedding the
expectation into the source-of-truth PR queue prevents regressions.

Technical Context. Today the API is API-key-authenticated, custom-header-based, so
browsers do not auto-attach the credential. Adding cookie-parser (not currently
installed) would silently change the threat model.

Expected Outcome. An informational PR is opened that documents the existing CSRF
posture, the conditions under which it would break, and a CsrfMiddleware skeleton guarded
behind a feature flag.

Acceptance Criteria.

• A new src/common/security/csrf.middleware.ts is registered only when
  CSRF_PROTECTION_ENABLED=true.
• A CI test verifies CSRF is bypassed (current posture) and a second test verifies it
  blocks a forged POST when enabled.
• A short docs/security/csrf-posture.md covers the contract.

Implementation Notes. Use csurf/csrf-csrf packages only if still maintained; else
build a 30-line double-submit-cookie middleware to keep the dependency surface small.

Files or modules likely to be affected. src/common/security/csrf.middleware.ts,
docs/security/csrf-posture.md.

Difficulty. Medium
Estimated effort. S

---

---

Backlog item #9 from `docs/maintainer-issue-backlog.md.

[Jumongweb]

Hi maintainer, i will like to solve this issue

[Clement-coder]

Hi,

I’m a full-stack software and blockchain engineer with hands-on experience delivering production-ready solutions across frontend, backend, and blockchain systems.

I’d like to take ownership of this issue. I’ve reviewed the requirements and can implement a scalable, maintainable, and well-tested solution that fully satisfies the acceptance criteria.

Ready to start immediately and keep the team updated throughout the process.

[YAustinXYZ]

Good morning, I wanna make this issue, i have experiencie working with this type of technologies.

[ZionApprove]

assign me this.

[grantfox-oss]

🦊 GrantFox — @ZionApprove has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #217)
2. Your PR will be reviewed by the ChainForgee maintainers

Good luck! Track your progress on GrantFox.