doc: update docs md to be inline with current code

Author: andrechristikan

.dockerignore

@@ -1,12 +1,3 @@
-# ---------------------------------------------------------------------------
-# Build context is intentionally minimal. Only what `pnpm install`, `db:generate`
-# and `nest build` (+ `pnpm typecheck`) need is shipped.
-#
-# KEPT (do NOT ignore): src/, test/, prisma/, package.json, pnpm-lock.yaml,
-#   pnpm-workspace.yaml, .npmrc, tsconfig.json, nest-cli.json, .swcrc
-#   (test/ is required: `build` runs `pnpm typecheck` and tsconfig includes test/**)
-# ---------------------------------------------------------------------------
-
 # Dependencies & build output (reinstalled / regenerated inside the image)
 node_modules/
 dist/

docs/authentication.md

@@ -428,13 +428,16 @@ Interface `IAuthJwtAccessTokenPayload`
 
 Interface `IAuthJwtRefreshTokenPayload`
 
+Derived as `Omit<IAuthJwtAccessTokenPayload, 'roleId' | 'username' | 'email'>` — the refresh payload drops `roleId`, `username`, and `email`, keeping the rest:
+
 ```typescript
 {
     loginAt: Date;
     loginFrom: EnumUserLoginFrom;
-    loginWith: EnumUserSignUpWith;
+    loginWith: EnumUserLoginWith;
     userId: string;
     sessionId: string;
+    deviceOwnershipId: string;
 
     // Standard JWT claims
     jti?: string;  // JWT ID - unique token identifier

docs/authorization.md

@@ -267,7 +267,7 @@ flowchart TD
 ### Important Notes
 
 - `@RoleProtected()` **requires** `@AuthJwtAccessProtected()` and `@UserProtected()` to be applied
-- `@AuthJwtAccessProtected()` must be placed at the bottom, followed by `@RoleProtected()`, then `@UserProtected()`. See [Authentication Documentation][ref-doc-authentication] for `@AuthJwtAccessProtected()` details
+- Decorators must be stacked in this order from top to bottom: `@RoleProtected()` → `@UserProtected()` → `@AuthJwtAccessProtected()`. See [Authentication Documentation][ref-doc-authentication] for `@AuthJwtAccessProtected()` details
 - This decorator stores role abilities via `RequestStoreService.set(RoleAbilityStoreKey, abilities)` (read back with `RequestStoreService.get(RoleAbilityStoreKey)`), which is required by policy guards
 - Incorrect ordering will result in runtime errors
 - Users with `superAdmin` role type have unrestricted access to all `@RoleProtected` routes, regardless of the specified required roles. The guard returns an empty abilities array for super admins, as they bypass ability checks.
@@ -416,7 +416,7 @@ The factory creates a CASL ability instance that can check if a user can perform
 ### Important Notes
 
 - `@PolicyAbilityProtected()` **requires** `@AuthJwtAccessProtected()`, `@RoleProtected()`, and `@UserProtected()` to be applied
-- Decorators must be stacked in this order from bottom to top: `@PolicyAbilityProtected()` → `@RoleProtected()` → `@UserProtected()` → `@AuthJwtAccessProtected()`. See [Authentication Documentation][ref-doc-authentication] for `@AuthJwtAccessProtected()` details
+- Decorators must be stacked in this order from top to bottom: `@PolicyAbilityProtected()` → `@RoleProtected()` → `@UserProtected()` → `@AuthJwtAccessProtected()`. See [Authentication Documentation][ref-doc-authentication] for `@AuthJwtAccessProtected()` details
 - Incorrect ordering will result in runtime errors
 - Users with `superAdmin` role type have unrestricted access to all `@PolicyAbilityProtected` routes, bypassing all ability checks.
 - All actions in a required ability must be present in the user's abilities. For example, if you require `[UPDATE, DELETE]` on `USER` subject, the user must have both actions, not just one.

docs/cache.md

@@ -150,7 +150,7 @@ export class SessionService {
 ```typescript
 {
     cache: {
-        url: process.env.CACHE_REDIS_URL ?? 'redis://localhost:6379',
+        url: process.env.CACHE_REDIS_URL!,
         namespace: 'Cache',
         ttlInMs: 5 * 60 * 1000  // Default TTL: 5 minutes
     }

docs/configuration.md

@@ -18,7 +18,6 @@ The project uses a modular configuration approach through the NestJS `ConfigModu
 
 - [Overview](#overview)
 - [Related Documents](#related-documents)
-- [Configuration Principles](#configuration-principles)
 - [Configuration Structure](#configuration-structure)
 - [App Configuration](#app-configuration)
 - [Auth Configuration](#auth-configuration)
@@ -39,7 +38,6 @@ The project uses a modular configuration approach through the NestJS `ConfigModu
 - [Feature Flag Configuration](#feature-flag-configuration)
 - [Response Configuration](#response-configuration)
 - [Firebase Configuration](#firebase-configuration)
-- [Conclusion](#conclusion)
 
 ## Configuration Structure
 
@@ -139,7 +137,7 @@ encryptionSecretKey: string     // Secret key used to derive AES-256 encryption
 **File**: `src/configs/auth.config.ts`
 **Interface**: `IConfigAuth`
 
-This configuration manages JWT authentication settings including token configuration, password policies, social authentication, dan two-factor authentication.
+This configuration manages JWT authentication settings including token configuration, password policies, social authentication, and two-factor authentication.
 
 > **Environment Variables**: See [Environment Documentation](environment.md) for detailed environment variable configuration.
 
@@ -341,7 +339,7 @@ enable: boolean                 // Turn logging on/off
 
 **`level`** - Log level configuration
 ```typescript
-level: string                   // Log levels: silent, trace, debug, info, warn, error, fatal
+level: string                   // Log level: error, warn, info, verbose, debug, silly
 ```
 
 **`intoFile`** - File logging option
@@ -409,11 +407,8 @@ timeoutInMs: number             // Request timeout in milliseconds (default: 300
 **`cors`** - CORS configuration
 ```typescript
 cors: {
-  allowedMethod: string[];        // Allowed HTTP methods (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)
-  allowedOrigin: string[] | string | boolean;  // Allowed origins (from CORS_ALLOWED_ORIGIN env variable)
-                                               // - string[]: Array of origins (e.g., ["*.example.com", "api.myapp.com"])
-                                               // - string: Single origin or wildcard (e.g., "*.example.com" or "*")
-                                               // - boolean: true=allow all, false=deny all
+  allowedMethod: string[];        // Allowed HTTP methods (GET, DELETE, PUT, PATCH, POST, HEAD, OPTIONS)
+  allowedOrigin: string[];        // Allowed origins, parsed from CORS_ALLOWED_ORIGIN (comma-separated into an array)
   allowedHeader: string[];        // Allowed headers for CORS requests
 }
 ```
@@ -431,8 +426,8 @@ cors: {
 **`throttle`** - Rate limiting configuration
 ```typescript
 throttle: {
-  ttlInMs: number;                // Time window in milliseconds (default: 500ms)
-  limit: number;                  // Maximum requests per time window (default: 10)
+  ttlInMs: number;                // Time window in milliseconds (default: 60000ms / 60s)
+  limit: number;                  // Maximum requests per time window (default: 100)
 }
 ```
 
@@ -488,6 +483,14 @@ usernamePattern: RegExp         // Regex pattern for valid usernames
 uploadPhotoProfilePath: string  // Path template for user profile photo uploads
 ```
 
+**`default`** - Default role and country assigned to new users
+```typescript
+default: {
+  role: string;                 // Default role name (default: 'user')
+  country: string;              // Default country code (default: 'ID')
+}
+```
+
 ### Documentation Configuration
 
 
@@ -505,11 +508,6 @@ This configuration manages API documentation settings for Swagger/OpenAPI.
 name: string                    // API documentation title
 ```
 
-**`description`** - Documentation description
-```typescript
-description: string             // API documentation description
-```
-
 **`prefix`** - Documentation URL prefix
 ```typescript
 prefix: string                  // URL prefix for API documentation (default: '/docs')
@@ -546,7 +544,7 @@ language: string                // Default application language
 **File**: `src/configs/email.config.ts`
 **Interface**: `IConfigEmail`
 
-This configuration manages default email addresses for system communications. Email addresses (`noreply`, `support`, `admin`) can be overridden via environment variables. If not set, they fall back to hardcoded default values.
+This configuration manages default email addresses for system communications. Email addresses (`noreply`, `support`, `admin`) come from environment variables and fall back to `null` when unset.
 
 > **Environment Variables**: See [Environment Documentation](environment.md) for detailed environment variable configuration.
 
@@ -705,11 +703,6 @@ uploadContentPath: string       // Path pattern for uploading policy content fil
 contentPublicPath: string       // Public path for accessing policy content
 ```
 
-**`filenamePattern`** - Filename pattern for policy files
-```typescript
-filenamePattern: string         // Pattern for policy file names
-```
-
 ### Feature Flag Configuration
 
 **File**: `src/configs/feature-flag.config.ts`
@@ -771,7 +764,7 @@ clientEmail?: string            // Firebase service account client email
 
 **`privateKey`** - Firebase service account private key
 ```typescript
-privateKey?: string             // Base64-encoded DER PKCS8 private key (from Firebase Console service account JSON)
+privateKey?: string             // Service account private key (PEM); escaped `\n` sequences are converted to real newlines at load
 ```
 
 > [!NOTE]

docs/environment.md

@@ -78,7 +78,7 @@ APP_NAME=ACKNestJs
 APP_ENV=local
 APP_LANGUAGE=en
 APP_TIMEZONE=Asia/Jakarta
-APP_ENCRYPTION_SECRET_KEY=<your-random-string>
+APP_ENCRYPTION_SECRET_KEY=<your_app_encryption_secret_key>
 
 # Home/Organization
 HOME_URL=https://example.com
@@ -112,21 +112,21 @@ AUTH_JWT_AUDIENCE=ACKNestJs
 
 # Access Token Configuration
 AUTH_JWT_ACCESS_TOKEN_JWKS_URI=http://localhost:3011/.well-known/access-jwks.json
-AUTH_JWT_ACCESS_TOKEN_KID=ack-access-2024-001
-AUTH_JWT_ACCESS_TOKEN_PRIVATE_KEY=<your-random-string>
-AUTH_JWT_ACCESS_TOKEN_PUBLIC_KEY=<your-random-string>
+AUTH_JWT_ACCESS_TOKEN_KID=<your_jwt_access_token_kid>
+AUTH_JWT_ACCESS_TOKEN_PRIVATE_KEY=<your_jwt_access_token_private_key>
+AUTH_JWT_ACCESS_TOKEN_PUBLIC_KEY=<your_jwt_access_token_public_key>
 AUTH_JWT_ACCESS_TOKEN_EXPIRED=1h
 
 # Refresh Token Configuration
 AUTH_JWT_REFRESH_TOKEN_JWKS_URI=http://localhost:3011/.well-known/refresh-jwks.json
-AUTH_JWT_REFRESH_TOKEN_KID=ack-refresh-2024-001
-AUTH_JWT_REFRESH_TOKEN_PRIVATE_KEY=<your-random-string>
-AUTH_JWT_REFRESH_TOKEN_PUBLIC_KEY=<your-random-string>
+AUTH_JWT_REFRESH_TOKEN_KID=<your_jwt_refresh_token_kid>
+AUTH_JWT_REFRESH_TOKEN_PRIVATE_KEY=<your_jwt_refresh_token_private_key>
+AUTH_JWT_REFRESH_TOKEN_PUBLIC_KEY=<your_jwt_refresh_token_public_key>
 AUTH_JWT_REFRESH_TOKEN_EXPIRED=30d
 
 # Two-Factor Authentication
 AUTH_TWO_FACTOR_ISSUER=ACKNestJsTwoFactor
-AUTH_TWO_FACTOR_ENCRYPTION_KEY=<your-random-string>
+AUTH_TWO_FACTOR_ENCRYPTION_KEY=<your_two_factor_encryption_key>
 
 # Social Authentication (Optional)
 AUTH_SOCIAL_GOOGLE_CLIENT_ID=
@@ -187,21 +187,21 @@ APP_ENV=local
 ```
 
 **`APP_LANGUAGE`** *(required)*  
-Default language for the application. Supported: `en`, `id`
+Default language for the application. Validated against `EnumMessageLanguage`; currently only `en` is supported.
 ```bash
 APP_LANGUAGE=en
 ```
 
 **`APP_TIMEZONE`** *(required)*  
-Default timezone for date operations. Example: `Asia/Jakarta`, `UTC`
+Default timezone for date operations. Validated against `EnumRequestTimezone`; currently only `Asia/Jakarta` is supported.
 ```bash
 APP_TIMEZONE=Asia/Jakarta
 ```
 
 **`APP_ENCRYPTION_SECRET_KEY`** *(required)*  
-Secret key used to derive an AES-256 encryption key for encrypting sensitive data (recommended 32+ characters). Empty by default — startup validation rejects an unset value. Generate a unique key per environment (`openssl rand -base64 32`); never reuse the example below.
+Secret key used to derive an AES-256 encryption key for encrypting sensitive data. Must be 32-64 characters (enforced by `@MinLength(32)` / `@MaxLength(64)`). Empty by default — startup validation rejects an unset value. Generate a unique key per environment (`openssl rand -base64 32`); never reuse the example below.
 ```bash
-APP_ENCRYPTION_SECRET_KEY=<your-random-string>
+APP_ENCRYPTION_SECRET_KEY=<your_app_encryption_secret_key>
 ```
 
 ### Home/Organization Settings
@@ -221,7 +221,7 @@ HOME_URL=https://example.com
 ### HTTP Server Settings
 
 **`HTTP_HOST`** *(required)*  
-Host/IP address for the HTTP server.
+Address to bind the HTTP server to. Accepts a hostname such as `localhost` or an IPv4 literal like `0.0.0.0` or `127.0.0.1`.
 ```bash
 HTTP_HOST=localhost
 ```
@@ -241,7 +241,7 @@ LOGGER_ENABLE=true
 ```
 
 **`LOGGER_LEVEL`** *(required)*  
-Logging level using Pino logger. Options: `silent`, `trace`, `debug`, `info`, `warn`, `error`, `fatal`
+Logging level. Validated against `EnumLoggerLevel`. Options: `error`, `warn`, `info`, `verbose`, `debug`, `silly`
 ```bash
 LOGGER_LEVEL=debug
 ```
@@ -374,19 +374,19 @@ AUTH_JWT_ACCESS_TOKEN_JWKS_URI=http://localhost:3011/.well-known/access-jwks.jso
 **`AUTH_JWT_ACCESS_TOKEN_KID`** *(required)*  
 Key ID for access token. Generated automatically by `pnpm generate:keys`.
 ```bash
-AUTH_JWT_ACCESS_TOKEN_KID=ack-access-2024-001
+AUTH_JWT_ACCESS_TOKEN_KID=<your_jwt_access_token_kid>
 ```
 
 **`AUTH_JWT_ACCESS_TOKEN_PRIVATE_KEY`** *(required)*  
 Private key content for signing access tokens.
 ```bash
-AUTH_JWT_ACCESS_TOKEN_PRIVATE_KEY=<your-random-string>
+AUTH_JWT_ACCESS_TOKEN_PRIVATE_KEY=<your_jwt_access_token_private_key>
 ```
 
 **`AUTH_JWT_ACCESS_TOKEN_PUBLIC_KEY`** *(required)*  
 Public key content for verifying access tokens.
 ```bash
-AUTH_JWT_ACCESS_TOKEN_PUBLIC_KEY=<your-random-string>
+AUTH_JWT_ACCESS_TOKEN_PUBLIC_KEY=<your_jwt_access_token_public_key>
 ```
 
 **`AUTH_JWT_ACCESS_TOKEN_EXPIRED`** *(required)*  
@@ -406,19 +406,19 @@ AUTH_JWT_REFRESH_TOKEN_JWKS_URI=http://localhost:3011/.well-known/refresh-jwks.j
 **`AUTH_JWT_REFRESH_TOKEN_KID`** *(required)*  
 Key ID for refresh token. Generated automatically by `pnpm generate:keys`.
 ```bash
-AUTH_JWT_REFRESH_TOKEN_KID=ack-refresh-2024-001
+AUTH_JWT_REFRESH_TOKEN_KID=<your_jwt_refresh_token_kid>
 ```
 
 **`AUTH_JWT_REFRESH_TOKEN_PRIVATE_KEY`** *(required)*  
 Private key content for signing refresh tokens.
 ```bash
-AUTH_JWT_REFRESH_TOKEN_PRIVATE_KEY=<your-random-string>
+AUTH_JWT_REFRESH_TOKEN_PRIVATE_KEY=<your_jwt_refresh_token_private_key>
 ```
 
 **`AUTH_JWT_REFRESH_TOKEN_PUBLIC_KEY`** *(required)*  
 Public key content for verifying refresh tokens.
 ```bash
-AUTH_JWT_REFRESH_TOKEN_PUBLIC_KEY=<your-random-string>
+AUTH_JWT_REFRESH_TOKEN_PUBLIC_KEY=<your_jwt_refresh_token_public_key>
 ```
 
 **`AUTH_JWT_REFRESH_TOKEN_EXPIRED`** *(required)*  
@@ -458,16 +458,16 @@ AUTH_SOCIAL_APPLE_SIGN_IN_CLIENT_ID=
 
 ### Two-Factor Authentication Settings
 
-**`AUTH_TWO_FACTOR_ISSUER`** *(optional)*  
-Issuer name displayed in authenticator apps.  
+**`AUTH_TWO_FACTOR_ISSUER`** *(required)*  
+Issuer name displayed in authenticator apps. Empty by default — startup validation rejects an unset value.  
 ```bash
 AUTH_TWO_FACTOR_ISSUER=ACKNestJsTwoFactor
 ```
 
-**`AUTH_TWO_FACTOR_ENCRYPTION_KEY`** *(required for 2FA)*  
+**`AUTH_TWO_FACTOR_ENCRYPTION_KEY`** *(required)*  
 Secret used to derive an AES-256 key for encrypting TOTP secrets (recommended 32+ chars). Empty by default — startup validation rejects an unset value. Generate a unique key per environment (`openssl rand -base64 32`); never reuse the example below.  
 ```bash
-AUTH_TWO_FACTOR_ENCRYPTION_KEY=<your-random-string>
+AUTH_TWO_FACTOR_ENCRYPTION_KEY=<your_two_factor_encryption_key>
 ```
 
 ### AWS Settings
@@ -489,8 +489,8 @@ AWS IAM secret access key for S3 bucket operations.
 AWS_S3_IAM_CREDENTIAL_SECRET=
 ```
 
-**`AWS_S3_IAM_ARN`** *(optional)*  
-AWS IAM Role ARN for S3 operations. Used for role-based access control and temporary credentials.
+**`AWS_S3_IAM_ARN`** *(required when S3 credentials are set)*  
+AWS IAM Role ARN for S3 operations. Used for role-based access control and temporary credentials. Validation requires it whenever `AWS_S3_IAM_CREDENTIAL_KEY` or `AWS_S3_IAM_CREDENTIAL_SECRET` is provided.
 ```bash
 AWS_S3_IAM_ARN=
 ```
@@ -548,8 +548,8 @@ AWS IAM secret access key for SES email service.
 AWS_SES_IAM_CREDENTIAL_SECRET=
 ```
 
-**`AWS_SES_IAM_ARN`** *(optional)*  
-AWS IAM Role ARN for SES operations. Used for role-based access control and temporary credentials.
+**`AWS_SES_IAM_ARN`** *(required when SES credentials are set)*  
+AWS IAM Role ARN for SES operations. Used for role-based access control and temporary credentials. Validation requires it whenever `AWS_SES_IAM_CREDENTIAL_KEY` or `AWS_SES_IAM_CREDENTIAL_SECRET` is provided.
 ```bash
 AWS_SES_IAM_ARN=
 ```

docs/installation.md

@@ -138,8 +138,8 @@ After hosting your JWKS files, update your `.env` file:
 
 ```bash
 # Update with your actual JWKS URLs
-AUTH_JWT_ACCESS_TOKEN_JWKS_URI="https://your-domain.com/.well-known/access-jwks.json"
-AUTH_JWT_REFRESH_TOKEN_JWKS_URI="https://your-domain.com/.well-known/refresh-jwks.json"
+AUTH_JWT_ACCESS_TOKEN_JWKS_URI="https://<your_domain>/.well-known/access-jwks.json"
+AUTH_JWT_REFRESH_TOKEN_JWKS_URI="https://<your_domain>/.well-known/refresh-jwks.json"
 ```
 
 
@@ -154,7 +154,7 @@ Docker provides the fastest and most reliable way to set up the ACK NestJS Boile
 
 The Docker setup provides:
 - **MongoDB replica set** - Configured for transactions
-- **Redis instances** - Separate instances for caching and queues
+- **Redis** - Single instance serving both caching (`db:0`) and queues (`db:1`)
 - **JWKS server** - Hosts your JWT public keys automatically
 - **BullMQ Dashboard** - Queue monitoring interface
 
@@ -257,7 +257,7 @@ docker-compose --profile apis up -d
 ```
 
 **What this command does:**
-- Starts MongoDB replica set with 1 nodes (ports 27017)
+- Starts MongoDB single-node replica set (port 27017)
 - Launches Redis server for caching and queues (port 6379)
 - Starts JWKS server to host your JWT public keys (port 3011)
 - Runs BullMQ dashboard for queue monitoring (port 3010)

docs/logger.md

@@ -77,7 +77,7 @@ LOGGER_PRETTIER=true
 LOGGER_AUTO=false
 
 # Sentry Configuration (Optional)
-SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id
+SENTRY_DSN=<your_sentry_dsn>
 ```
 
 | Variable | Description | Type | Default | Required |
@@ -617,7 +617,7 @@ Configure Sentry by setting the `SENTRY_DSN` environment variable:
 
 ```env
 # .env.production
-SENTRY_DSN=https://your-public-key@o123456.ingest.sentry.io/7654321
+SENTRY_DSN=<your_sentry_dsn>
 ```
 
 ### Configuration Details