Skip to content

Security: aolus-software/clean-fastify

Security

.github/SECURITY.md

Security Policy

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.

Supported versions

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.

Reporting a vulnerability

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:line if 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.

Scope

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 in src/services/auth.service.ts, and the type claim that separates the two,
  • the cached UserInformation lookup and its invalidation in src/services/session.service.ts — stale permissions or a deleted or suspended user keeping access,
  • the RBAC layer: PermissionGuard and RoleGuard in src/libs/fastify/guards/, the superuser bypass, 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 (Hash in @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 /docs exposing 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=true in 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.

Known hardening notes

These are deliberate properties of the template, documented so nobody reports them as surprises:

  • .env holds every secret and is never committed. JWT_SECRET and JWT_REFRESH_SECRET are 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_HOST feeds 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 when ENABLE_API_DOCS=true. It defaults to false and is independent of NODE_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 on X-Forwarded-For; behind a proxy, configure Fastify's trustProxy for that proxy.
  • Request bodies are capped at 100 KB (bodyLimit in src/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/ create superuser@example.com and admin@example.com with a published password. Change or remove them before exposing any environment.
  • The Husky pre-commit hook runs bunx drizzle-kit migrate against the DATABASE_URL in your .env. Do not point a development checkout at a shared database.

There aren't any published security advisories