codeninja 2.0.0

package/tasks/generate-headerValidator.task.md

@@ -0,0 +1,377 @@
+---
+type: task
+name: generate-headerValidator
+agent: nodejs-agent
+---
+
+# File: middleware/headerValidator.js
+
+## Purpose
+Central middleware file for all inbound request validation. Runs on every
+request in sequence: language extraction → API key validation → token
+validation. Also exposes request body decryption as a per-route middleware
+when encrypted transport is enabled. All encryption/decryption operations
+are delegated to `utilities/encryption.js`. All response sending is
+delegated to `utilities/response.js`. All validation rule checking is
+delegated to `utilities/validator.js`.
+
+---
+
+## Dependencies to Import
+
+- `../config/constants` — GLOBALS object containing API_KEY and other
+  app-wide constants. Note: ENCRYPTED_TRANSPORT is read from
+  process.env directly, not from constants.
+- `../utilities/encryption` — imports `decrypt` function only.
+  The actual crypto library (crypto-js or cryptlib) is abstracted away.
+  headerValidator never calls crypto directly.
+- `../utilities/response` — imports `sendResponse` function for all
+  outbound responses from this middleware.
+- `../logger/logging` — imports `log` for info/debug/error logging.
+- `localizify` — imported as `{ default: localizify }` and `{ t }`
+  separately in two destructured require statements.
+- All language files from `../languages/` — imported individually, one
+  require per supported language. The list of supported languages comes
+  from `process.env.SUPPORTED_LANGUAGES` parsed as a comma-separated
+  array at module load time. Each language is imported as a variable
+  named by its code: e.g. `en` from `../languages/en.js`, `ar` from
+  `../languages/ar.js`. Agent generates one require line per language
+  in `context.services[<name>].supported_languages`.
+- `jsonwebtoken` — for JWT verify operations in validateToken.
+- `../utilities/ioRedis` — Redis client for token version lookup.
+
+---
+
+## Module-Level Constants
+
+### languageMap
+Built once at module load time. A plain object that maps each language
+code string to its imported language object.
+Example structure: `{ "en": en, "ar": ar, "fr": fr }`
+Keys are the language code strings from SUPPORTED_LANGUAGES parsed from
+process.env. Values are the imported language file objects.
+Used in `extractLanguage` for O(1) lookup by header value.
+
+### DEFAULT_LANGUAGE
+Read `process.env.DEFAULT_LANGUAGE` once at module load time.
+Used as fallback in `extractLanguage` when the header is absent or
+contains an unrecognized language code.
+
+### bypassMethod
+Array of route name strings that skip token validation entirely.
+These are the final path segment of public endpoints — the segment at
+index 2 when the path is split by `/`.
+Default values to populate: `"login"`, `"signup"`, `"requestotp"`,
+`"forgot-password"`, `"set-password"`.
+Developer appends to this list as new public endpoints are added.
+
+### bypassHeaderKey
+Array of route name strings that skip API key validation.
+Initialized as an empty array. Exists so future public or webhook routes
+can be excluded without modifying validation logic. Developer adds
+values here when needed.
+
+### JWT_SECRET
+Read `process.env.KEY` once at module load time.
+Store as module-level constant `JWT_SECRET`.
+This is the same KEY used for AES encryption throughout the service
+and for JWT signing in `config/common.js` — they must always match.
+Used by `jsonwebtoken.verify()` in validateToken.
+
+---
+
+## Functions
+
+---
+
+### extractLanguage(req, res, next)
+
+**Purpose**: Determine the request language, register it with localizify,
+and attach everything needed for translation onto the request object so
+all downstream handlers work without any additional setup.
+
+**Flow**:
+
+1. Read the `accept-language` header from `req.headers`. Lowercase and
+   trim the value. If the header is absent or empty, assign
+   DEFAULT_LANGUAGE immediately and skip to step 3.
+
+2. Check if the extracted value exists as a key in `languageMap`.
+   If it does not exist — the client sent an unsupported language code.
+   Fall back to DEFAULT_LANGUAGE silently. Language fallback must always
+   be transparent to the client. Never return an error for a bad language
+   header.
+
+3. Using the resolved language code, look up the corresponding language
+   object from `languageMap`.
+
+4. Register with localizify:
+   Call `localizify.add(resolvedCode, resolvedLanguageObject)` to
+   register the translations for this language in this request context.
+   Call `localizify.setLocale(resolvedCode)` to activate it.
+   Both calls must happen before any `t()` call in this request lifecycle.
+   
+   Note on getMessage: `response.js` getMessage also calls
+   localizify.add and setLocale on every call, making it safe under
+   concurrent requests. The setLocale call here in extractLanguage is
+   for `req.t` — the function bound to the request object for use in
+   route handlers. These two patterns coexist correctly.
+
+5. Attach to the request object:
+   - `req.lang` — the resolved language code string (e.g. `"en"`, `"ar"`).
+     Passed to `sendResponse` for message resolution on all subsequent
+     responses in this request.
+   - `req.languageData` — the full language object from `languageMap`.
+     Available to route handlers if they need direct key access without
+     going through localizify.
+   - `req.t` — the `t` function from localizify bound directly onto the
+     request. Route handlers call `req.t("keyword")` without importing
+     localizify themselves.
+
+6. Log at info level: the resolved language code, whether fallback was
+   used (true/false), and the original header value.
+
+7. Call `next()`.
+
+---
+
+### validateApiKey(req, res, next)
+
+**Purpose**: Verify that the inbound request carries a valid API key.
+The client always sends the API key AES-encrypted. This middleware
+decrypts it and compares against the expected value from constants.
+
+**Flow**:
+
+1. Split `req.path` by `/` and store as `pathSegments`. Extract
+   `pathSegments[2]` as the route identifier for bypass checking.
+
+2. If `bypassHeaderKey` includes the route identifier — call `next()`
+   and return immediately. No further checks for this request.
+
+3. Read the `api-key` header from `req.headers`. If the header is absent
+   or empty — send a 401 response using `sendResponse` with keyword
+   `rest_keywords_invalid_api_key` and response code `"-1"`. Log at
+   info level that the header was missing. Do not call `next()`.
+
+4. Inside a try/catch block:
+   Call `decrypt(encryptedToken)` from `utilities/encryption.js`.
+   Strip all whitespace characters from the decrypted result.
+   Strip surrounding double-quote characters if present.
+   If the cleaned result is an empty string — call sendResponse with
+   401, keyword `rest_keywords_tokeninvalid`, response code `"-1"`.
+   Log at debug level: "Empty token after decryption".
+   Return immediately. Do not call next().
+
+5. Verify the decrypted string as a JWT:
+   Call `jsonwebtoken.verify(token, JWT_SECRET, { algorithms: ['HS256'] })`.
+   JWT_SECRET is the module-level constant loaded at startup from
+   process.env.KEY. Algorithm must be HS256.
+   Wrap this call in the try/catch. If verification fails for any
+   reason (expired, tampered, wrong algorithm, malformed) — the catch
+   block handles the response. Do not throw manually.
+   On success, extract three fields from the decoded payload:
+   - `user_id` — numeric user identifier
+   - `user_type` — role or type string
+   - `version` — integer session version issued at login time
+   If any of these three fields is missing or undefined — call
+   sendResponse with 401, keyword `rest_keywords_tokeninvalid`,
+   response code `"-1"`. Log at debug level. Return immediately.
+   Do not call next().
+
+6. If match — log success at info level with the path. Call `next()`.
+
+7. In the catch block — any decryption failure (malformed cipher, wrong
+   key, encoding corruption) sends 401 with the same keyword. Log at
+   info level only — not error level — because this is an expected
+   attack surface. Never expose the decryption error detail to the
+   client.
+
+---
+
+### validateToken(req, res, next)
+
+**Purpose**: Verify caller identity on protected routes using a JWT that
+travels AES-encrypted in a custom header. Uses Redis for session version
+checking to enforce logout invalidation without a database query on
+every request.
+
+**Flow**:
+
+1. Split `req.path` by `/` and extract `pathSegments[2]` as the route
+   identifier.
+
+2. If `bypassMethod` includes the route identifier — log the bypass at
+   info level, call `next()`, and return immediately. No token check
+   for public routes.
+
+3. Read the `token` header from `req.headers`. If absent or empty —
+   send 401 with keyword `rest_keywords_tokeninvalid` and response code
+   `"-1"`. Do not call `next()`.
+
+4. Inside a try/catch block:
+   Call `decrypt(encryptedToken)` from `utilities/encryption.js`.
+   Strip all whitespace characters from the decrypted result.
+   Strip surrounding double-quote characters if present.
+   If the cleaned result is an empty string — throw an error immediately
+   with a descriptive message such as "Empty token after decryption".
+
+5. Verify the decrypted string as a JWT:
+   Call `jsonwebtoken.verify(token, JWT_SECRET, { algorithms: ['HS256'] })`.
+   JWT_SECRET is the module-level constant loaded at startup from
+   process.env.KEY — the same key used by common.generateSessionCode
+   to sign the token. Algorithm must be HS256 — the same algorithm
+   used at signing time.
+   If verification fails for any reason (expired, tampered, wrong
+   algorithm, malformed) — throw. Let the catch block handle the response.
+   On success, extract three fields from the decoded payload:
+   - `user_id` — numeric user identifier
+   - `user_type` — role or type string
+   - `version` — integer session version issued at login time
+   If any of these three fields is missing or undefined in the decoded
+   payload — throw immediately.
+
+6. Query Redis using the ioRedis client from `utilities/ioRedis.js`:
+   Convert `user_id` to a string. Call `redis.get(user_id_string)`.
+   The stored value is a plain integer string — the current valid
+   session version for this user.
+   If the Redis key does not exist (returns null) — the user has no
+   active session. Send 401 with keyword `rest_keywords_tokeninvalid`.
+   Do not call `next()`.
+
+7. Parse the Redis value as an integer. Call it `redisVersion`.
+   Compare with the `version` from the JWT payload:
+   - If JWT version is greater than or equal to redisVersion —
+     session is valid. Proceed.
+   - If JWT version is less than redisVersion — the session was
+     invalidated (user logged in elsewhere or was logged out).
+     Send 401 with keyword `rest_keywords_tokeninvalid`.
+     Log at info level: user_id, JWT version, Redis version.
+     Do not call `next()`.
+
+8. On successful validation — attach to the request:
+   - `req.user_id` — the numeric user ID from the JWT payload
+   - `req.user_type` — the user type string from the JWT payload
+   Log at info level: token validated, user_id, user_type.
+   Call `next()`.
+
+9. In the catch block — this handles only genuine exceptions from
+   jsonwebtoken.verify() (malformed token, wrong algorithm, expired).
+   Call sendResponse with 401, keyword `rest_keywords_tokeninvalid`,
+   response code `"-1"`. Log at debug level with the error message.
+   Never expose JWT internals or decryption details to the client.
+   All other failure conditions (empty token, missing payload fields,
+   Redis null, version mismatch) are handled inline above with direct
+   sendResponse calls and early returns — they never reach this catch.
+
+---
+
+### decryptRequest(req, res, next)
+
+**Generation rule**:
+Read `context.services[<name>].encrypted_transport`.
+- If `false` — do not generate this function at all. It will not exist
+  in the file and will not be exported. No reference to it anywhere.
+- If `true` — generate this function as described below.
+
+**Purpose**: Global middleware that decrypts the incoming request body
+before any route handler runs. Applied in route_manager.js as part of
+the global middleware chain — not per-route. Only generated when
+`encrypted_transport == true`.
+
+**Flow**:
+
+1. Check the HTTP method via `req.method`. If the method is `"GET"` or
+   `"DELETE"` — call `next()` immediately and return. These methods
+   carry no body by convention. Decrypting an empty body causes
+   unnecessary errors.
+
+2. Check `req.originalUrl` for demo route patterns. If the URL contains
+   `/decryption_demo` or `/encryption_demo` — call `next()` immediately.
+   These routes are used for testing and receive raw unencrypted bodies.
+
+3. If `req.body` is absent, null, undefined, or an empty string — set
+   `req.body` to an empty object `{}` and call `next()` without
+   attempting decryption.
+
+4. Inside a try/catch — call `decrypt(req.body)` from
+   `utilities/encryption.js`. Replace `req.body` entirely with the
+   decrypted and JSON-parsed result.
+
+5. If `req.body.user_id` is undefined after decryption — inject it from
+   `req.user_id` if that value was set by `validateToken`, otherwise
+   set to `0`. This ensures every downstream model function receives
+   `req.body.user_id` without needing to check two sources.
+
+6. Log at info level: decryption successful, request path.
+   Call `next()`.
+
+7. In the catch block — log at error level with the full error. Send a
+   500 response with keyword `rest_keywords_decryption_failure` using
+   `sendResponse`.
+
+---
+
+## Redis Session Version Contract
+
+This is the source of truth for the login/logout version system. All
+agents that generate login, logout, and session management logic must
+follow this contract exactly.
+
+- On every successful login:
+  Read current version from Redis for this user_id.
+  If the key exists — increment the stored value by 1.
+  If the key does not exist — set it to 1.
+  Store using `redis.set(user_id_string, newVersion)` with no expiry.
+  Issue the JWT with `version: newVersion` in the payload.
+
+- On logout:
+  Increment the Redis version by 1. Do not delete the key.
+  All existing JWTs for this user become stale immediately because their
+  version value will now be less than the Redis value.
+
+- On validateToken:
+  JWT version must be greater than or equal to Redis version.
+  Less than means logged out or superseded by a newer login —
+  treat as invalid.
+
+- On force-logout all devices:
+  Set the Redis value to any number greater than the highest issued JWT
+  version for this user. All tokens across all devices become invalid
+  simultaneously without touching the database.
+
+---
+
+## Export
+
+Export as a plain object:
+`module.exports = headerValidator`
+
+Exported keys when `encrypted_transport == true`:
+`extractLanguage`, `validateApiKey`, `validateToken`, `decryptRequest`
+
+Exported keys when `encrypted_transport == false`:
+`extractLanguage`, `validateApiKey`, `validateToken`
+
+Do not export any encryption functions, response functions, getMessage,
+or checkValidationRules from this file — those live in their own utility
+files.
+
+---
+
+## What This File Does NOT Do
+
+- Does not call crypto-js or cryptlib directly — all crypto goes through
+  `utilities/encryption.js`
+- Does not call `res.json()` or `res.status()` directly — all responses
+  go through `utilities/response.js`
+- Does not perform field-level request validation — that is in
+  `utilities/validator.js`
+- Does not connect to the database — token validation uses Redis only
+- Does not use RSA PEM keys — JWT uses HMAC-SHA256 (HS256) with
+  process.env.KEY, consistent with how tokens are signed in
+  config/common.js generateSessionCode
+- Does not define getMessage, sendResponse, encrypt, or
+  checkValidationRules — those live in their own utility files
+- Does not generate decryptRequest when `encrypted_transport == false` —
+  the function simply does not exist in the file in that case

package/tasks/generate-ide-configs.task.md

@@ -0,0 +1,114 @@
+---
+type: task
+name: generate-ide-configs
+---
+
+# Task: Generate IDE Configuration Files
+
+## Purpose
+Confirms IDE configuration status when @initialize-project runs.
+
+All IDE config files are written automatically during `codeninja init`
+(the npm install step), NOT during this task. This task exists only to
+surface the confirmation to the user so they know their IDE is connected.
+
+If for any reason the config files are missing (e.g. the developer
+copied .codeninja manually without running init), this task re-creates them.
+
+---
+
+## When to Run
+
+Called from `initialize-project.workflow.md` at step 23b.
+Only runs on the FIRST @initialize-project in this repo.
+
+---
+
+## What to Check and Report
+
+### File 1 — .vscode/mcp.json
+Check if `.vscode/mcp.json` exists.
+- If YES → report ✓ already configured
+- If NO  → create it:
+
+```json
+{
+  "servers": {
+    "codeninja": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["${workspaceFolder}/.codeninja/mcp-server.js"]
+    }
+  }
+}
+```
+
+Note: VS Code uses `"servers"` not `"mcpServers"`.
+Note: `${workspaceFolder}` is a VS Code variable — write it literally.
+
+---
+
+### File 2 — .cursor/mcp.json
+Check if `.cursor/mcp.json` exists.
+- If YES → report ✓ already configured
+- If NO  → create it:
+
+```json
+{
+  "mcpServers": {
+    "codeninja": {
+      "command": "node",
+      "args": [".codeninja/mcp-server.js"]
+    }
+  }
+}
+```
+
+---
+
+### File 3 — Antigravity (~/.gemini/antigravity/mcp_config.json)
+Antigravity uses a GLOBAL config file outside the project.
+Check if the codeninja entry exists in it.
+- If YES → report ✓ already configured
+- If NO  → inform the user it should have been written by `codeninja init`
+  and show them the manual fallback:
+
+```
+─── Antigravity (manual fallback) ───────────────────────
+Config file: ~/.gemini/antigravity/mcp_config.json
+             (Windows: %USERPROFILE%\.gemini\antigravity\mcp_config.json)
+
+Add inside "mcpServers":
+
+  "codeninja": {
+    "command": "node",
+    "args": ["/ABSOLUTE/PATH/TO/PROJECT/.codeninja/mcp-server.js"]
+  }
+
+Then go to Antigravity → ... → MCP Servers → Manage MCP Servers → Refresh.
+─────────────────────────────────────────────────────────
+```
+
+---
+
+### Claude Desktop — Print Only
+Claude Desktop config lives outside the project.
+Always print this reminder block regardless of whether it was already set up.
+
+```
+─── Claude Desktop (manual step — one time only) ──────
+Config file:
+  macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json
+  Windows: %APPDATA%\Claude\claude_desktop_config.json
+  Linux:   ~/.config/claude/claude_desktop_config.json
+
+Add inside "mcpServers":
+
+  "codeninja": {
+    "command": "node",
+    "args": ["/ABSOLUTE/PATH/TO/PROJECT/.codeninja/mcp-server.js"]
+  }
+
+Save and restart Claude Desktop.
+─────────────────────────────────────────────────────────
+```

package/tasks/generate-ioRedis.task.md

@@ -0,0 +1,120 @@
+---
+type: task
+name: generate-ioRedis
+agent: nodejs-agent
+---
+
+# File: utilities/ioRedis.js
+
+## Purpose
+Creates, configures, and exports a single ioredis connection instance.
+All files that need Redis (headerValidator for token version checking,
+model files for caching) import this single shared connection. The
+connection is established once at module load time.
+
+This task also defines the Redis installation and startup commands that
+the agent outputs to the developer as part of the `@initialize-project`
+final summary, so the developer can get Redis running locally before
+starting the service.
+
+---
+
+## Dependencies to Import
+
+- `ioredis` — imported as `IORedis` (capital letters). The Redis client
+  library.
+- `../logger/logging` — imported as `log`. Used for connection success
+  and failure logging.
+
+---
+
+## Module-Level Variables
+
+### connection
+Declared with `let` before the try/catch block so it is in scope for
+the export line. Initialized inside the try block.
+
+---
+
+## Connection Setup
+
+Wrap the entire connection creation in a try/catch block.
+
+Inside try:
+Create `new IORedis` instance with these configuration values:
+- `host` — read from `process.env.REDIS_HOST`. This value is already
+  in `.env` from the initialize-project workflow.
+- `port` — read from `process.env.REDIS_PORT` parsed as an integer.
+- `maxRetriesPerRequest: null` — required when using ioredis with
+  BullMQ or any queue library. Also prevents ioredis from throwing
+  on commands during reconnection. Set this always regardless of
+  whether queues are used — it is a safe default.
+
+After successful instantiation — log at info level with message
+"Successfully connected to Redis" and include host and port values.
+
+Inside catch:
+Log at error level with message "Failed to connect to Redis" and the
+error object. Re-throw the error. A Redis connection failure at startup
+is unrecoverable — the service should not start without Redis since
+token validation depends on it.
+
+---
+
+## Redis Setup Instructions (output by agent in final summary)
+
+When this file is generated, the agent appends the following Redis
+setup instructions to the `@initialize-project` final summary output.
+These are not written into the file itself — they are printed to the
+developer as next steps.
+
+### macOS (Homebrew)
+```
+brew install redis
+brew services start redis
+```
+
+### Ubuntu / Debian Linux
+```
+sudo apt update
+sudo apt install redis-server
+sudo systemctl start redis
+sudo systemctl enable redis
+```
+
+### Windows
+```
+winget install Redis.Redis
+redis-server
+```
+
+### Verify Redis is running (all platforms)
+```
+redis-cli ping
+```
+Expected response: `PONG`
+
+---
+
+## Export
+```
+module.exports = connection
+```
+
+The connection instance is exported directly. Imported as:
+`const redis = require('../utilities/ioRedis')`
+
+Then used as: `redis.get(key)`, `redis.set(key, value)`, etc.
+
+---
+
+## What This File Does NOT Do
+
+- Does not define any Redis helper functions — raw ioredis methods are
+  used directly by callers
+- Does not implement retry logic beyond ioredis built-in reconnection
+- Does not expire keys — TTL decisions belong to the caller
+- Does not implement pub/sub — that would be a separate connection
+  instance if needed
+- Does not fall back to in-memory storage if Redis is unavailable —
+  startup failure is the correct behavior