pedwfrontend/GUARDRAILS.md

PEDW FrontEnd Guardrails

Purpose

This document is a fast pre-flight checklist to reduce regressions in high-risk areas. Use it before coding, before opening a PR, and before merge.

Non-Negotiable Guardrails

1. Auth/session integrity
   • Do not bypass next-auth flow in pages/api/auth/[...nextauth].js.
   • Preserve secure redirect behavior and cookie/session settings.
2. Security headers and CSP
   • Do not weaken middleware.js CSP/header behavior or next.config.js security headers without explicit rationale.
3. Data model safety
   • Treat prisma/schema.prisma as source-of-truth for auth/account persistence.
4. Bilingual parity (EN/CY)
   • Any user-facing route/content change must validate both locales.
   • Keep i18n.js, locales/, and next.config.js rewrites aligned.
5. Public-service reliability
   • Avoid breaking core flows: search, case, account, myportal, admin.

Sensitive Flow Protection

Apply extra checks for:

• pages/api/auth/**
• pages/api/file/**
• pages/api/email/**
• pages/api/endpoint/*_api.js handling account/user data

Relay Hash Integrity Rules (CRM-bound APIs)

Apply when changing relay-bound portal endpoints and helpers (notably pages/api/endpoint/** and actions/index.js):

1. Keep relay endpoint configuration sourced from API_ROOT.
2. Preserve path-hash generation behavior:
   • hash input must be request path/query (excluding domain),
   • appended hash parameter must remain compatible with relay expectations.
3. Do not change hash algorithm/key usage contract without coordinated relay change.
4. Treat hash validation failures as security-relevant negative paths; verify graceful rejection handling.
5. Never log hash key material or sensitive request payloads.

Required for sensitive changes:

• Negative-path validation (unauthorized, invalid input, malformed payload).
• Safe logging (no secrets/tokens/personal data in cleartext).
• Explicit rollback steps.

Relay Policy Change Guardrail (timeouts/retries/logging)

When changing shared relay forwarding policy (for example in pages/api/middleware/relayForwarding.js), treat this as an operationally sensitive change even if endpoint contracts are unchanged.

Minimum required before merge:

1. Complete the relay governance gate in context/runbook.md (Relay Hardening Rollout Playbook).
2. Attach non-prod smoke evidence for:
   • deterministic non-retry classes (400, 401, 403, 404)
   • transient retry classes (429, 503, timeout/network-transient)
3. Confirm structured redacted logging and duplicate-log suppression behavior.
4. Provide fast mitigation + rollback path (RELAY_RETRY_MAX=0 and commit-revert path).

Pre-PR Quick Checklist

• Ran npm run lint (or documented why unavailable)
• Verified changed routes/APIs manually
• Verified EN + CY behavior for impacted user-facing flow
• Performed accessibility smoke checks (keyboard, focus, labels, headings)
• Added risk notes (auth/data/i18n/a11y)
• Updated memory-bank/change-log.md for non-trivial changes

If Assumptions Are Unclear

1. Record assumptions in PR notes.
2. Add unresolved items to memory-bank/open-questions.md.
3. Choose the safer behavior and clearly mark as temporary.

Related Docs

• .clinerules
• CONTRIBUTING_AI.md
• context/implementation-governance.md
• context/maintainability-adoption-programme.md
• context/runbook.md
• context/integration-map.md
• memory-bank/README.md