86 lines
3.4 KiB
Markdown
86 lines
3.4 KiB
Markdown
# 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`
|