Harden Keryx architecture, runtime, and public repository

[vladimirperovic]

Summary

Full architecture, runtime, security, and public-repository hardening for Keryx while preserving the shared ToolRegistry design and existing MCP/OpenAPI/REST/Siri functionality.

Architecture review

The central registry remains the correct core abstraction: one source of truth for tool metadata, Zod validation, authentication mode, REST/OpenAPI exposure, and MCP registration. Application construction now creates an isolated registry per Express app, eliminating duplicate registration during tests or embedded use.

Security changes

• fail-closed production configuration: HTTPS public URL and a gateway token of at least 32 characters
• MCP Origin validation and explicit browser-origin allow-lists
• strict bearer parsing and generic client errors with request IDs
• CSP, HSTS, frame denial, MIME-sniffing protection, restrictive referrer/permissions policies, rate/body limits, and proxy-hop configuration
• bounded upstream JSON reads, timeout, content-type checks, parameter limits, and redirect blocking while forwarding credentials
• HTTPS-only Shortcut targets outside localhost development
• random, TTL-limited, bounded, memory-only, single-use Shortcut downloads
• hardened non-root/read-only Docker Compose defaults with dropped capabilities and loopback binding

Repository and supply-chain changes

• Node 22/24 CI and Node 24 production image
• Docker/Compose validation and production dependency audit
• refreshed lockfile removing the high-severity transitive advisories
• CodeQL, dependency review with an npm-audit fallback, Dependabot, and CODEOWNERS
• security regression tests
• structured issue forms and a stronger PR checklist

Documentation

Adds or expands README, architecture, security architecture, threat model, deployment, tool-development, roadmap, governance, support, design system, contribution, security, and changelog documentation.

Validation results

• Node 22: typecheck, build, 11 tests, and production audit passed
• Node 24: typecheck, build, 11 tests, and production audit passed
• Docker Compose validation passed
• Docker image build passed
• Dependency Review passed
• CodeQL JavaScript/TypeScript analysis passed

Residual tracked risk

The legacy scpl-macos-updated compiler still pulls uuid@3, which has a moderate advisory and no compatible upstream fix. High-severity production advisories are blocked in CI. Follow-up is tracked in #6 to replace or isolate the legacy compiler.

Compatibility notes

Production deployments must provide an HTTPS PUBLIC_BASE_URL and a strong KERYX_API_TOKEN. Docker Compose now binds to 127.0.0.1 by default; set KERYX_BIND_ADDRESS=0.0.0.0 only for intentional direct network exposure.

[github-advanced-security]

You are seeing this message because GitHub Code Scanning has recently been set up for this repository, or this pull request contains the workflow file for the Code Scanning tool.

What Enabling Code Scanning Means:

• The 'Security' tab will display more code scanning analysis results (e.g., for the default branch).
• Depending on your configuration and choice of analysis tool, future pull requests will be annotated with code scanning analysis results.
• You will be able to see the analysis results for the pull request's branch on this overview once the scans have completed and the checks have passed.

For more information about GitHub Code Scanning, check out the documentation.