#23410: Gateway: require prefixes for hook request session-key overrides

## Summary Describe the problem and fix in 2–5 bullets: - Problem: `hooks.allowRequestSessionKey=true` previously allowed startup without any session-key prefix constraints. - Why it matters: external `/hooks/agent` callers could choose arbitrary session-key shapes if misconfigured. - What changed: gateway startup now fails fast unless `hooks.allowedSessionKeyPrefixes` is non-empty whenever request overrides are enabled. - What did NOT change (scope boundary): request/mapping resolution semantics and hook routing behavior are unchanged beyond the new startup validation guard. ## Change Type (select all) - [x] Bug fix - [ ] Feature - [ ] Refactor - [x] Docs - [x] Security hardening - [ ] Chore/infra ## Scope (select all touched areas) - [x] Gateway / orchestration - [ ] Skills / tool execution - [x] Auth / tokens - [ ] Memory / storage - [ ] Integrations - [x] API / contracts - [ ] UI / DX - [ ] CI/CD / infra ## Linked Issue/PR - Closes # - Related # ## User-visible / Behavior Changes When `hooks.allowRequestSessionKey=true`, startup now requires non-empty `hooks.allowedSessionKeyPrefixes`; otherwise gateway config resolution throws. ## Security Impact (required) - New permissions/capabilities? (`No`) - Secrets/tokens handling changed? (`No`) - New/changed network calls? (`No`) - Command/tool execution surface changed? (`No`) - Data access scope changed? (`No`) - If any `Yes`, explain risk + mitigation: ## Repro + Verification ### Environment - OS: macOS - Runtime/container: Node 22 + pnpm - Model/provider: N/A - Integration/channel (if any): Hooks gateway ingress - Relevant config (redacted): `hooks.allowRequestSessionKey` + `hooks.allowedSessionKeyPrefixes` ### Steps 1. Configure hooks with `allowRequestSessionKey: true` and no `allowedSessionKeyPrefixes`. 2. Resolve hooks config/start gateway. 3. Observe startup validation error. ### Expected - Config is rejected with explicit error. ### Actual - Config is rejected with explicit error. ## Evidence Attach at least one: - [x] Failing test/log before + passing after - [ ] Trace/log snippets - [ ] Screenshot/recording - [ ] Perf numbers (if relevant) ## Human Verification (required) What you personally verified (not just CI), and how: - Verified scenarios: unit + e2e hooks tests for request sessionKey policy and normal hook requests. - Edge cases checked: `allowRequestSessionKey=true` with missing and empty prefix list; valid prefixed override still accepted. - What you did **not** verify: full docker live-gateway matrix. ## Compatibility / Migration - Backward compatible? (`No`) - Config/env changes? (`Yes`) - Migration needed? (`Yes`) - If yes, exact upgrade steps: - If `hooks.allowRequestSessionKey=true`, set `hooks.allowedSessionKeyPrefixes` (for example `['hook:']`) before upgrading. ## Failure Recovery (if this breaks) - How to disable/revert this change quickly: set `hooks.allowRequestSessionKey=false`. - Files/config to restore: hook policy block in gateway config. - Known bad symptoms reviewers should watch for: startup error mentioning missing `hooks.allowedSessionKeyPrefixes`. ## Risks and Mitigations - Risk: deployments that enabled request overrides without prefixes now fail at startup. - Mitigation: explicit migration guidance in docs + clear startup error message. <!-- greptile_comment --> <h3>Greptile Summary</h3> Added startup validation to enforce non-empty allowedSessionKeyPrefixes when allowRequestSessionKey is enabled, preventing misconfigurations where external callers could specify arbitrary session-key shapes. **Key changes:** - New validation check at startup throws error if request overrides enabled without prefix constraints - Test coverage added for both missing and empty prefix arrays - Documentation updated across webhook guides and configuration references to clarify the new requirement - Breaking change: deployments with request overrides enabled and no prefix list now fail at startup with clear error message The change is scoped to startup validation only - runtime resolution and hook routing behavior remain unchanged. <h3>Confidence Score: 5/5</h3> - This PR is safe to merge with minimal risk - The change adds a fail-fast validation guard at startup to enforce an existing security constraint. Implementation is straightforward, well-tested with both unit and e2e coverage including edge cases (missing vs empty arrays), and thoroughly documented. The breaking change is intentional and clearly communicated with migration guidance. - No files require special attention _{Last reviewed commit: 396a993} <!-- greptile_other_comments_section --> <!-- /greptile_comment -->