This document is the vulnerability disclosure policy for this repository — how to report a security problem in the starter itself.
It is not the API security guide. For how authentication, RBAC, password handling, token lifecycle,
rate limiting, validation, and security headers actually work in this template, read
docs/SECURITY.md.
This is a starter template rather than a versioned library. Security fixes land on main, and
projects built from the template are expected to pull them forward themselves. Only the current
main branch is supported.
Do not open a public issue for a security vulnerability.
Report it privately through GitHub Security Advisories:
https://github.com/aolus-software/clean-fastify/security/advisories/new
That creates a private thread visible only to the maintainers. If you cannot use GitHub Advisories, open a regular issue that says only "security report, please provide a private contact" with no technical detail, and a maintainer will follow up.
Please include, as far as you can determine it:
- the affected component (plugin, guard, route, service, repository, config) and
file:lineif you have it, - the conditions required to reach it — authenticated or not, which role or permission, which data,
- a proof-of-concept request or sequence,
- the impact you believe it has.
We aim to acknowledge a report within a few working days and to agree a disclosure timeline with you once the issue is confirmed.
In scope — anything in this repository's own code, in particular:
- authentication and token handling:
src/libs/fastify/plugins/app/auth.plugin.ts, access and refresh JWT signing and verification insrc/services/auth.service.ts, and thetypeclaim that separates the two, - the cached
UserInformationlookup and its invalidation insrc/services/session.service.ts— stale permissions or a deleted or suspended user keeping access, - the RBAC layer:
PermissionGuardandRoleGuardinsrc/libs/fastify/guards/, thesuperuserbypass, and any authenticated route that is missing a guard, - verification and password-reset tokens: expiry, single use (
used_at), and revoke-on-issue, - soft delete: reads that forget
isNull(usersTable.deleted_at)and let deleted users be read back or log in, - secret handling: bcrypt password hashing (
Hashin@utils),APP_KEY,JWT_SECRET,JWT_REFRESH_SECRET, and anything that could leak them into logs, responses, or the OpenAPI spec, - the external plugins in
src/libs/fastify/plugins/externals/: CORS, the Helmet CSP, and the rate limiter, - Zod validation gaps that let unvalidated input reach a service or a query,
- SQL injection or query-shape problems in
src/libs/database/postgres/repositories/— including sort or filter values that bypass the allow-lists, - BullMQ job payloads that carry secrets, or workers that can be driven by attacker-controlled data,
- the OpenAPI surface at
/docsexposing schemas or examples it should not, - dependency vulnerabilities that are reachable through code in this repo.
Out of scope:
- vulnerabilities in a project built from this template that come from that project's own code,
- anything requiring a misconfiguration the docs tell you not to ship — for example
ENABLE_API_DOCS=truein production, or the placeholder JWT secrets from.env.example, - missing hardening that is documented as the deployer's responsibility (TLS termination, database network exposure, Redis authentication),
- reports generated by an automated scanner with no demonstrated exploit path.
These are deliberate properties of the template, documented so nobody reports them as surprises:
.envholds every secret and is never committed.JWT_SECRETandJWT_REFRESH_SECRETare the only variables with no default; the process refuses to boot without them, with a value shorter than 32 characters, with a known placeholder (including the ones in.env.example), or with the same value for both. Use two different random values (openssl rand -base64 48).ALLOWED_HOSTfeeds the CORS origin list. Empty means every origin is allowed, which is a development convenience; set it to your real front-end origins everywhere else.- The Scalar reference at
/docs(and/docs/openapi.json) is served only whenENABLE_API_DOCS=true. It defaults tofalseand is independent ofNODE_ENV. - The rate limiter is global at 100 requests per minute per client IP, stored in Redis. It keys on
the socket address (
request.ip), not onX-Forwarded-For; behind a proxy, configure Fastify'strustProxyfor that proxy. - Request bodies are capped at 100 KB (
bodyLimitinsrc/app.ts); larger bodies get 413. - Redis (
REDIS_PASSWORD) backs the user cache, the refresh-token ids, the rate limiter and BullMQ. Anything that can write to that Redis can impersonate cached users and revoke sessions. - The seeders in
src/libs/database/seed/createsuperuser@example.comandadmin@example.comwith a published password. Change or remove them before exposing any environment. - The Husky
pre-commithook runsbunx drizzle-kit migrateagainst theDATABASE_URLin your.env. Do not point a development checkout at a shared database.