@authuser/nest 0.2.2 → 1.1.0

package/docs/production.md

@@ -0,0 +1,45 @@
+# Production checklist
+
+Use this list before exposing a service to untrusted traffic.
+
+## Application
+
+- Start from the `secure` preset and document every disabled control.
+- Authenticate and authorize sensitive routes with application guards.
+- Keep `Public()` usage explicit and covered by authorization tests.
+- Validate business rules, file uploads and data leaving persistence layers.
+- Use `nest.logger` and `observability.logger` intentionally.
+
+## Network and edge
+
+- Terminate TLS at a trusted edge and redirect plaintext traffic.
+- Configure `network.trustProxy` only for known proxy addresses or networks.
+- Apply an infrastructure-level request/body limit no larger than the application
+  limit where possible.
+- Tune connection, header, request and handler timeouts against production latency.
+- Use an upstream DDoS control for an internet-facing API.
+
+## Distributed operation
+
+- Configure Redis or another shared `@fastify/rate-limit` store for multiple replicas.
+- Give login, recovery and expensive routes stricter endpoint-specific limits.
+- Keep liveness independent of downstream dependencies.
+- Put database, queue and critical service checks in readiness.
+- Ensure the orchestrator removes a replica when readiness returns 503.
+
+## Exposure and data
+
+- Disable or protect Swagger UI and OpenAPI in production.
+- Do not return credentials or topology from health checks.
+- Keep secrets and personal data out of URLs and logs.
+- Keep JSON log redaction enabled and extend it for application-specific fields.
+- Add CSRF protection when browsers authenticate with ambient cookies.
+
+## Release
+
+- Run `npm run check`, `npm run test:coverage`, `npm run test:package`, and
+  `npm run smoke --prefix example`.
+- Review `npm audit --omit=dev` and dependency updates.
+- Load-test realistic payloads through the production proxy and TLS path.
+- Exercise shutdown while requests are active.
+- Monitor latency percentiles, error rate, event-loop utilization and memory.

package/docs/releasing.md

@@ -0,0 +1,28 @@
+# Release process
+
+## Preparation
+
+1. Ensure `main` is green and the worktree is clean.
+2. Update `CHANGELOG.md` and the package version using Semantic Versioning.
+3. Run `npm run check`, `npm run test:coverage`, `npm run test:package`, and
+   `npm run smoke --prefix example`.
+4. Commit the release and create an annotated `vX.Y.Z` tag at that commit.
+5. Push the commit and tag.
+
+## Trusted publishing
+
+Configure npm trusted publishing for:
+
+- Organization/user: `authuser-org`
+- Repository: `nest`
+- Workflow: `.github/workflows/release.yml`
+- Environment: `npm`
+
+Create a GitHub Release from the version tag. The release workflow verifies that the
+tag equals `package.json`, repeats all release checks, and publishes with npm
+provenance through GitHub OIDC. No long-lived npm token should be stored in GitHub.
+
+## Verification
+
+Confirm the npm version and provenance, install it into a clean project, and verify
+that the GitHub tag resolves to the same commit used by the release workflow.

package/docs/security.md

@@ -9,11 +9,17 @@ The secure preset establishes a baseline, not a complete application security mo
 - A one MiB default request-body limit.
 - Finite connection, request, handler and header timeouts.
 - Rate limiting by client IP.
-- Request IDs restricted to 128 safe characters before log propagation.
-- Generic internal errors; unexpected exceptions are logged server-side only.
+- `createApp` request IDs restricted to 128 safe characters before log propagation.
+- Correlation IDs returned to clients in a configurable response header.
+- Reserved HTTP framing, connection and authentication headers cannot be reused as
+  the correlation-response header.
+- Generic 5xx errors; unexpected exceptions are logged server-side only.
 - CORS disabled until an allowlist is configured.
 - Sensitive authentication and cookie log fields redacted by default.
+- Query strings excluded from default request logs and error response paths.
 - Optional pre-handler protection for documentation and health routes.
+- Dynamic readiness checks that fail closed without exposing dependency errors.
+- Runtime configuration validation for JavaScript and environment-derived options.
 
 ## Application responsibilities
 
@@ -26,11 +32,17 @@ The secure preset establishes a baseline, not a complete application security mo
 - Use TLS at the load balancer or application edge.
 - Keep Node and dependencies patched and review `npm audit` output.
 - Avoid exposing Swagger UI and detailed readiness data publicly.
+- Keep credentials, tokens and personal data out of URL query parameters.
+- Preserve the default request serializer, or redact equivalent data in a custom
+  Pino `serializers.req` implementation.
 - Add CSRF protection when authentication relies on ambient cookies or sessions.
 
 `Public()` and `Roles()` only attach metadata. They do nothing until an application
 guard reads that metadata and enforces the intended policy.
 
+Setting `errors: false` or providing a custom filter transfers responsibility for
+5xx redaction and safe error contracts to the consuming application.
+
 ## Reporting
 
 Follow the private disclosure instructions in [SECURITY.md](../SECURITY.md).

package/docs/threat-model.md

@@ -0,0 +1,41 @@
+# Threat model
+
+`@authuser/nest` hardens the HTTP process boundary for a Nest application. It does
+not establish user identity or decide whether a caller may access a business object.
+
+## Protected assets
+
+- Availability of the Node process and its event loop.
+- Confidentiality of request credentials and internal exception details.
+- Integrity of parsed JSON objects and request correlation identifiers.
+- Predictable application bootstrap and shutdown behavior.
+
+## Included mitigations
+
+- Bounded bodies, parameters, sockets and finite timeouts reduce common resource
+  exhaustion paths.
+- Prototype and constructor poisoning are rejected during JSON parsing.
+- Helmet establishes browser-facing security headers.
+- Strict DTO defaults reject unexpected properties.
+- CORS is closed until explicitly configured.
+- Rate limiting controls abusive clients per instance or shared store.
+- Incoming request IDs are validated by `createApp` before they reach logs.
+- Sensitive headers and query strings are excluded from default logs.
+- All 5xx details and health-check failures are hidden from clients.
+
+## Explicitly out of scope
+
+- Authentication, authorization, tenancy and object-level access control.
+- TLS termination, WAF, network policy and volumetric DDoS protection.
+- Database query construction, encryption, secret storage and key rotation.
+- CSRF defenses for cookie-authenticated applications.
+- Malware scanning, file validation and non-HTTP ingestion.
+
+## Trust assumptions
+
+- Nest, Fastify and direct dependencies are kept on supported patched versions.
+- `trustProxy` contains only infrastructure controlled by the operator.
+- A distributed deployment uses a shared rate-limit store.
+- Application code does not deliberately log or expose sensitive data.
+- Applications calling `configureHttpApp` directly configure equivalent request-ID
+  and network limits on their own Fastify adapter.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@authuser/nest",
-  "version": "0.2.2",
+  "version": "1.1.0",
   "description": "Secure, high-performance NestJS foundation powered by Fastify",
   "keywords": [
     "nestjs",
@@ -19,17 +19,23 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
+      "require": "./dist/index.js",
       "default": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
     "docs",
     "README.md",
     "CHANGELOG.md",
+    "SECURITY.md",
+    "SUPPORT.md",
     "LICENSE"
   ],
-  "sideEffects": false,
+  "sideEffects": [
+    "./dist/index.js"
+  ],
   "engines": {
     "node": ">=22.12"
   },
@@ -43,8 +49,10 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
+    "test:package": "npm run build && node scripts/verify-package.mjs",
     "benchmark": "npm run build && node benchmark/run.mjs",
     "prepack": "npm run clean && npm run build",
+    "prepublishOnly": "npm run check && npm run test:package",
     "check": "npm run typecheck && npm test && npm run build && npm pack --dry-run"
   },
   "dependencies": {