saqib mirandClaude Sonnet 5
55253287b3
Implements tasks T026-T032 from specs/002-saas-integration/tasks.md (User Story 3, P3 - the final piece of this feature) plus Polish. - New bespoke Redis fixed-window counter (checkRateLimit, src/infrastructure/cache/rate-limiter.ts) rather than @fastify/rate-limit's default onRequest-stage hook -- that hook runs before this feature's preHandler-based auth resolves the integration/user identity the limit needs to key on. A second preHandler (checkIntegrationRateLimit) runs after authenticateProductIntegration on the inbound route, checking the integration-level limit then the per-user limit independently, each throwing the existing RateLimitError (429 RATE_LIMIT_EXCEEDED) on breach. - New integration test (inbound-rate-limit.test.ts) verifies both limits are enforced independently against a real Postgres/Redis: a throttled user doesn't affect others, and the integration cap throttles even when no individual user has hit their own limit. - Docs: contracts/quickstart updated from the placeholder "RATE_LIMITED" code to the actual reused RATE_LIMIT_EXCEEDED code; cleaned up a duplicated paragraph in the admin endpoints section; added a "SaaS Integration" section to README.md documenting the inbound contract, admin routes (and their known auth-stub limitation), and how rate limits are configured. All 32 tasks in tasks.md are now complete -- all three user stories (P1 trust boundary, P2 admin lifecycle, P3 rate limiting) are implemented and covered by integration tests verified against a live database, in addition to unit tests for the crypto/token primitives. Full quality gate (typecheck/lint/format/architecture/ unit tests) passes. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Development
docker compose --env-file .env.development -f docker-compose.development.yml up -d --build
Test
docker compose --env-file .env.test -f docker-compose.test.yml up --build
Production
docker compose --env-file .env.prod -f docker-compose.prod.yml up --build -d
Stop
docker compose -f docker-compose.prod.yml down
Local environment setup
.env.development, .env.test, and .env.prod are gitignored (they hold real credentials) —
copy .env.example to the one you need and fill in real values before running any command above.
CI/CD
Every push/PR triggers the Jenkins pipeline defined in Jenkinsfile. Stage order:
checkout → install → environment validation → typecheck → lint → format check → unit test →
integration test → E2E test → build → Docker build → publish → deploy. Publish/deploy only run
on branches with a configured deploy target (main → prod, develop/test → test); other
branches validate and build only. Pipeline run status and per-stage logs are visible in the
Jenkins UI for the relevant job — see specs/001-ci-pipeline/quickstart.md for how to validate
the pipeline itself, and specs/001-ci-pipeline/contracts/pipeline-stage-contract.md for the
guarantees each stage makes.
Required Jenkins credentials (see the header comment in Jenkinsfile for exact IDs): per target
environment (test, prod) a Postgres password, Redis password, JWT secret, and AWS access
key/secret, plus one shared Docker registry username/password. None of these are ever read from
a file in this repository.
SaaS Integration
POST /v1/support/requests is the trust boundary a registered SaaS product calls through — every
request must carry a Authorization: Bearer <signed-token> header (HMAC-SHA256, signed with the
integration's own secret) and a body matching the inbound contract. See
specs/002-saas-integration/contracts/inbound-request-contract.md for the full validation order
and error codes, and specs/002-saas-integration/quickstart.md for runnable scenarios.
Admins manage integrations under /admin/products/:externalProductId/integration (register) and
/admin/integrations/:integrationId/{rotate,revoke,status,audit-trail}. These admin routes are
not yet actually access-controlled — fastify.authenticate is a stub pending the identity/auth
module; don't expose them outside a trusted network until that's implemented.
Rate limits (rateLimitPerMinute, rateLimitPerUserPerMinute) are set per integration at
registration time and enforced via a Redis-backed fixed-window counter, independent of the
global @fastify/rate-limit floor already applied to every route.