# 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`