codeninja 2.0.0

package/tasks/generate-enc-dec-html.task.md

@@ -0,0 +1,127 @@
+---
+type: task
+name: generate-enc-dec-html
+agent: nodejs-agent
+---
+
+# File: enc_dec.html
+
+## Purpose
+A standalone browser-based tool for testing AES-256-CBC encryption and
+decryption using the exact same KEY and IV configured for this service.
+Used exclusively by developers during development and debugging to
+manually encrypt values before sending them as API request bodies, or
+to decrypt API responses for inspection. This file is gitignored and
+never served by the Express app.
+
+Only generated when `client_type == "reactjs"`. Not generated for
+`client_type == "app"`.
+
+---
+
+## Key Detail — Pre-filled KEY and IV
+
+This is the most important aspect of this file. The KEY and IV values
+hardcoded into the JavaScript must be the exact values from
+`context.current_init.encryption_key` and
+`context.current_init.encryption_iv` collected during
+`@initialize-project`.
+
+The agent reads these values from context and writes them literally into
+the JavaScript functions. Every time this file is generated it will have
+the correct credentials for this specific service instance. This is what
+makes the tool useful — the developer does not need to manually copy keys.
+
+---
+
+## HTML Structure
+
+Single HTML file. No external CSS files. No server-side logic. All
+styling is inline in a style block in head.
+
+### Head section
+- `<title>` — use `<service_name> — Encryption & Decryption` where
+  service_name comes from `context.current_init.service_name`
+- Load crypto-js from CDN:
+  `https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.2.0/crypto-js.min.js`
+  This is loaded as a script tag before the closing body tag.
+
+### Body section layout
+- `<h1>` heading: `<SERVICE_NAME> — CryptoJS Encryption & Decryption`
+  using the service name from context in uppercase.
+- A `<label>` for the input area with text "Plaintext / Ciphertext:"
+- A `<textarea>` with id `"plaintext"`, 10 rows, 100 cols.
+- Two `<button>` elements:
+  - First button: text "Encrypt", calls `encrypt()` on click
+  - Second button: text "Decrypt", calls `decrypt()` on click
+- A "Clear" button that clears the textarea and both result divs.
+- Two result boxes each with a visible border, padding, and
+  `overflow-wrap: break-word` so long cipher strings don't overflow:
+  - Box 1: heading "Encrypted Data:", result div with id `"encryptedData"`
+  - Box 2: heading "Decrypted Data:", result div with id `"decryptedData"`
+
+### CSS (inline in head style block)
+- Buttons: background color `#9c8cc3`, font-weight 800, padding 10px,
+  border-radius 5px. Cursor pointer.
+- Result boxes (class `box`): border `1px solid black`, padding 5px,
+  margin-top 25px, `overflow-wrap: break-word`.
+- Body: font-family sans-serif, padding 20px, max-width 900px.
+
+---
+
+## JavaScript Functions
+
+All functions are in a single script block before the closing body tag,
+after the crypto-js CDN script tag.
+
+### Module-level key constants
+At the top of the script block, define the KEY and IV as constants.
+These are the pre-filled values from context:
+```
+const ENCRYPTION_KEY = CryptoJS.enc.Utf8.parse("<context.current_init.encryption_key>");
+const ENCRYPTION_IV = CryptoJS.enc.Utf8.parse("<context.current_init.encryption_iv>");
+```
+
+Both parsed using `CryptoJS.enc.Utf8.parse` — consistent with how
+`utilities/encryption.js` parses them for `client_type == "reactjs"`.
+
+### encrypt()
+1. Clear the decryptedData div.
+2. Read value from the plaintext textarea. Store as `plaintext`.
+3. Clear the plaintext textarea.
+4. If plaintext is empty — alert "Please enter text to encrypt." Return.
+5. Call `CryptoJS.AES.encrypt(plaintext, ENCRYPTION_KEY, { iv: ENCRYPTION_IV })`.
+   Call `.toString()` on the result to get the Base64 cipher string.
+6. Display the cipher string in the encryptedData div.
+
+### decrypt()
+1. Clear the encryptedData div.
+2. Read value from the plaintext textarea. Store as `ciphertext`.
+3. Clear the plaintext textarea.
+4. If ciphertext is empty — alert "Please enter ciphertext to decrypt." Return.
+5. Strip surrounding double-quote characters from ciphertext using:
+   `ciphertext.replace(/^"(.*)"$/, '$1')`
+   This handles the case where the developer pastes a JSON-encoded
+   string that has surrounding quotes.
+6. Call `CryptoJS.AES.decrypt(ciphertext, ENCRYPTION_KEY, { iv: ENCRYPTION_IV })`.
+   Call `.toString(CryptoJS.enc.Utf8)` to get the plaintext string.
+7. If the result is empty string — display "Decryption failed. Check
+   that the input is a valid cipher string." in the decryptedData div.
+   Return.
+8. Display the decrypted string in the decryptedData div.
+
+### clearAll()
+1. Set textarea value to empty string.
+2. Set encryptedData div innerText to empty string.
+3. Set decryptedData div innerText to empty string.
+
+---
+
+## What This File Does NOT Do
+
+- Does not make any HTTP requests
+- Does not import or use any Node.js modules
+- Does not connect to the service in any way
+- Does not store or transmit the KEY or IV anywhere
+- Does not handle files or binary data — text only
+- Is never served by Express — opened directly in browser by developer

package/tasks/generate-enc-dec-php.task.md

@@ -0,0 +1,145 @@
+---
+type: task
+name: generate-enc-dec-php
+agent: nodejs-agent
+---
+
+# File: enc_dec.php
+
+## Purpose
+A PHP-based tool for testing AES-256-CBC encryption and decryption using
+the exact same KEY and IV configured for this service. Used exclusively
+by developers during development. Runs as a PHP web page — the developer
+opens it in a browser via a local PHP server or any server with PHP
+installed. This file is gitignored and never part of the Node.js app.
+
+Only generated when `client_type == "app"`. Not generated for
+`client_type == "reactjs"`.
+
+---
+
+## Key Detail — Pre-filled KEY and IV
+
+Same principle as enc_dec.html. The KEY and IV hardcoded into the PHP
+must be the exact values from `context.current_init.encryption_key` and
+`context.current_init.encryption_iv`.
+
+The cryptlib PHP equivalent uses `openssl_encrypt` and `openssl_decrypt`
+with AES-256-CBC. The key must be hashed with SHA-256 first to produce
+a 32-byte key — this is how cryptlib derives its key from the raw KEY
+string, and the PHP side must match exactly.
+
+Key derivation in PHP:
+`$secret = hash('sha256', '<context.current_init.encryption_key>')`
+
+IV used directly as a plain string:
+`$iv = '<context.current_init.encryption_iv>'`
+
+---
+
+## File Structure
+
+The file is a single `.php` file that contains both HTML and PHP. The
+HTML form renders first, then the PHP at the bottom processes the
+submitted form and outputs results below the form.
+
+---
+
+## HTML Section (before closing body tag)
+
+### Head section
+- `<meta charset="utf-8">`
+- `<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">`
+- `<title>` — `<service_name> — Encryption & Decryption` using service
+  name from context.
+- CSS style block with:
+  - Body: font-family sans-serif, padding 20px, max-width 900px
+  - `#container`: max-width 900px, margin auto
+  - Labels: font-weight bold
+  - Textarea: width 100%, box-sizing border-box
+  - Submit buttons: padding 8px 16px, cursor pointer, margin-right 8px
+  - Result headings: cursor pointer, color #333, font-size 16px
+  - Result paragraphs: background #f5f5f5, padding 10px, word-break
+    break-all, border 1px solid #ddd
+
+### Body section
+- `<div id="container">`
+- `<h1>` heading: `<SERVICE_NAME> — Encryption & Decryption`
+- `<div id="body">`
+- HTML form with:
+  - `action="enc_dec.php"` method POST
+  - `enctype="multipart/form-data"`
+  - Label: "Text or Ciphertext"
+  - Textarea: `name="data"`, `id="data"`, `required`, 90 cols, 10 rows
+  - Submit button: `name="type"` `value="encrypt"` — text "Encrypt"
+  - Submit button: `name="type"` `value="decrypt"` — text "Decrypt"
+  - Reset button: `name="reset"` `value="Clear"` — text "Clear"
+
+### JavaScript section (before closing body tag)
+Two JavaScript functions for click-to-copy functionality:
+
+`CopyToClipboard(containerid)`:
+Handles both IE (document.selection) and modern browsers
+(window.getSelection). Selects the content of the element with the
+given id and executes the browser copy command.
+
+`clearContents(containerid)`:
+Sets the value of the element with the given id to empty string.
+
+---
+
+## PHP Section (after closing html tag)
+
+The PHP block processes the form submission. It runs after the HTML
+has been sent to the browser.
+
+### Constants
+```
+$encryptionMethod = 'AES-256-CBC';
+$secret = hash('sha256', '<context.current_init.encryption_key>');
+$iv = '<context.current_init.encryption_iv>';
+```
+
+Note on key derivation: `hash('sha256', key)` produces a 64-character
+hex string. PHP's `openssl_encrypt` with AES-256 requires a 32-byte
+key. When passing a hex string, openssl uses the raw bytes — which for
+a 64-char hex string gives 32 bytes. This is the correct behavior and
+matches how cryptlib derives its key via `getHashSha256`.
+
+### Form processing
+Check: `isset($_REQUEST['type']) && isset($_REQUEST['data']) && $_REQUEST['data'] != ''`
+
+If not set or empty — output nothing. The page just shows the form.
+
+**If type == "encrypt"**:
+1. Trim the input: `$plaintext = trim($_REQUEST['data'])`
+2. Encrypt: `$encrypt_value = openssl_encrypt($plaintext, $encryptionMethod, $secret, 0, $iv)`
+3. Output a result div containing:
+   - `<h2>` with `onclick="CopyToClipboard('p1')"` — text "COPY ENCRYPTED"
+   - `<p id="p1">` — the encrypted value wrapped in `htmlspecialchars()`
+   - `<h2>` with `onclick="CopyToClipboard('p2')"` — text "COPY ORIGINAL"
+   - `<p id="p2">` — the original input wrapped in `htmlspecialchars()`
+
+**If type == "decrypt"**:
+1. Get ciphertext: `$enc = $_REQUEST['data']`
+2. Decrypt: `$decrypt_value = openssl_decrypt($enc, $encryptionMethod, $secret, 0, $iv)`
+3. Attempt JSON decode: `json_decode($decrypt_value)`
+4. Output a result div containing:
+   - `<h2>` with `onclick="CopyToClipboard('p1')"` — text "COPY ENCRYPTED"
+   - `<p id="p1">` — the original cipher input wrapped in `htmlspecialchars()`
+   - `<h2>` with `onclick="CopyToClipboard('p2')"` — text "COPY DECRYPTED"
+   - `<p id="p2">` — the decrypted value wrapped in `htmlspecialchars()`
+   - `<h2>` — text "JSON PARSED"
+   - `<pre>` — `htmlspecialchars(print_r(json_decode($decrypt_value), true))`
+     This shows the decoded JSON structure if the decrypted value is
+     valid JSON, making it easy to inspect API response structures.
+
+---
+
+## What This File Does NOT Do
+
+- Does not connect to the Node.js service
+- Does not use any PHP libraries beyond built-in openssl functions
+- Does not store or log any encrypted or decrypted values
+- Is not part of the Node.js application in any way
+- Is never required or imported by any JS file

package/tasks/generate-encryption.task.md

@@ -0,0 +1,159 @@
+---
+type: task
+name: generate-encryption
+agent: nodejs-agent
+---
+
+# File: utilities/encryption.js
+
+## Purpose
+Single source of truth for all encryption and decryption operations in the
+service. All other files that need to encrypt or decrypt call this module.
+No other file in the service imports crypto-js or cryptlib directly.
+The active library is determined once at module load from context — the
+rest of the codebase never needs to know which library is active.
+
+---
+
+## Dependencies to Import
+
+Read `context.services[<name>].client_type` to determine which library
+to import:
+
+- If `client_type == "reactjs"`:
+  Import `crypto-js` as `CryptoJS`
+
+- If `client_type == "app"`:
+  Import `cryptlib`
+
+No other crypto imports. Never import both.
+
+---
+
+## Module-Level Constants
+
+### key
+Derived once at module load from `process.env.KEY`.
+
+- If `client_type == "reactjs"`:
+  Parse using `CryptoJS.enc.Utf8.parse(process.env.KEY)`.
+  Result is a CryptoJS WordArray. Store as `key`.
+
+- If `client_type == "app"`:
+  Derive using `cryptlib.getHashSha256(process.env.KEY, 32)`.
+  Result is a 32-byte derived key string. Store as `key`.
+
+### iv
+Derived once at module load from `process.env.IV`.
+
+- If `client_type == "reactjs"`:
+  Parse using `CryptoJS.enc.Utf8.parse(process.env.IV)`.
+  Result is a CryptoJS WordArray. Store as `iv`.
+
+- If `client_type == "app"`:
+  Use `process.env.IV` directly as a plain string. Store as `iv`.
+
+Both `key` and `iv` are module-level constants. They are never re-derived
+on each function call. If `.env` values are missing at startup the module
+will fail at load time — this is intentional and correct behavior.
+
+---
+
+## Functions
+
+---
+
+### encrypt(data)
+
+**Purpose**: Takes any JavaScript value, serializes it, and returns an
+AES-256-CBC encrypted cipher string. Called by `response.js` when
+`ENCRYPTED_TRANSPORT` is true, and by any model function that needs to
+encrypt a value before storing (e.g. passwords).
+
+**Parameters**:
+- `data` — any value: object, array, string, number. Never assume type.
+
+**Flow**:
+
+1. Call `JSON.stringify(data)` to serialize the input to a string.
+   This handles all types uniformly including nested objects and arrays.
+
+2. Encrypt the serialized string:
+
+   - If `client_type == "reactjs"`:
+     Call `CryptoJS.AES.encrypt(serialized, key, { iv, mode: CryptoJS.mode.CBC })`.
+     Call `.toString()` on the result to get the Base64 cipher string.
+
+   - If `client_type == "app"`:
+     Call `cryptlib.encrypt(serialized, key, iv)`.
+     Result is already a string.
+
+3. Return the cipher string.
+
+4. This function is synchronous. Do not make it async — there is no I/O.
+   Callers that use await on it will still work, but the function itself
+   should not be declared async.
+
+---
+
+### decrypt(cipherText)
+
+**Purpose**: Takes an AES-256-CBC cipher string and returns the original
+JavaScript value. Called by `headerValidator.js` for API key, token, and
+request body decryption. Called by any route that receives encrypted input.
+
+**Parameters**:
+- `cipherText` — encrypted string produced by `encrypt()` or by the
+  client-side counterpart (crypto-js in browser or cryptlib in app).
+
+**Flow**:
+
+1. Validate input: if `cipherText` is null, undefined, empty string, or
+   not a string type — return `null` immediately without attempting
+   decryption. Do not throw.
+
+2. Decrypt the cipher string:
+
+   - If `client_type == "reactjs"`:
+     Call `CryptoJS.AES.decrypt(cipherText, key, { iv, mode: CryptoJS.mode.CBC })`.
+     Call `.toString(CryptoJS.enc.Utf8)` on the result to get the
+     plain UTF-8 string.
+
+   - If `client_type == "app"`:
+     Call `cryptlib.decrypt(cipherText, key, iv)`.
+     Result is a plain string.
+
+3. Call `JSON.parse()` on the decrypted string to restore the original
+   JavaScript value.
+
+4. Return the parsed value.
+
+5. Wrap steps 2–4 in a try/catch. On any error — return `null`.
+   Never throw from this function. Callers check for null return.
+   Never log inside this function — logging is the caller's responsibility.
+
+6. This function is synchronous. Do not make it async.
+
+---
+
+## Export
+```
+module.exports = { encrypt, decrypt }
+```
+
+No default export. Named exports only. Every file that imports this
+module destructures exactly what it needs:
+`const { encrypt, decrypt } = require('../utilities/encryption')`
+
+---
+
+## What This File Does NOT Do
+
+- Does not read `req` or `res` — no Express objects
+- Does not log — callers handle logging
+- Does not throw — returns null on failure
+- Does not conditionally skip encryption based on ENCRYPTED_TRANSPORT —
+  that decision belongs to `response.js`. This file always encrypts
+  when called.
+- Does not import both crypto libraries — only the one matching
+  client_type is imported

package/tasks/generate-fast-defaults.task.md

@@ -0,0 +1,68 @@
+---
+type: task
+name: generate-fast-defaults
+---
+
+This task auto-populates all non-essential context values silently
+when `context.current_init.init_mode == "fast"`. It runs after the
+essential questions are collected and before show-init-summary.
+
+This task only runs for `project_type == "nodejs"`.
+For `project_type == "reactjs"` — security values are inherited from
+the linked backend via ask-linked-service and are never generated here.
+The port and package defaults below still apply to reactjs.
+
+## Values to Auto-Generate
+
+### Database Config (nodejs only, if not already set)
+- `context.db.host` → set to `"localhost"` if not already in context
+- `context.db.port` → set based on `context.db.type`:
+  - postgresql → `5432`
+  - mysql → `3306`
+  - mongodb → `27017`
+
+### Service Port
+- Scan all port values in `context.services`
+- Find the highest port currently in use
+- Set `context.current_init.port` → highest + 1
+- If no services exist yet → set to `1001`
+- Ensure the result does not conflict with any existing port
+
+### Package Info
+- `context.current_init.package_name` → same value as
+  `context.current_init.service_name`
+- `context.current_init.author` → empty string `""`
+
+### Security Values (nodejs only — never run for reactjs)
+Generate all three using cryptographically random characters from the
+set: `ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789`
+
+- `context.current_init.api_key` → 32 random characters
+- `context.current_init.encryption_key` → exactly 32 random characters
+- `context.current_init.encryption_iv` → first 16 characters of
+  `context.current_init.encryption_key`
+  Always derived from the key — never randomly generated.
+  Since encryption_key is always 32 characters, the first 16
+  characters are always exactly 16. No separate validation needed.
+
+Validate after generation:
+- encryption_key must be exactly 32 characters — regenerate if not
+- encryption_iv must equal the first 16 characters of encryption_key —
+  re-derive if not
+
+### Redis Config (nodejs only — skip for reactjs)
+- `context.current_init.redis_host` → `"localhost"`
+- `context.current_init.redis_port` → `6379`
+
+## Important Rules
+
+- Never overwrite a value that was already explicitly set by a
+  previous ask-* task in this session.
+- Check each key before setting: if it already has a non-empty value
+  in `context.current_init` → skip it.
+- This task is silent — it does not print anything to the user.
+  All auto-generated values will be visible in show-init-summary
+  where the user can review and change them.
+
+Do not ask any question. Do not produce any output.
+Store all values and return.

package/tasks/generate-gitignore.task.md

@@ -0,0 +1,79 @@
+---
+type: task
+name: generate-gitignore
+agent: nodejs-agent
+---
+
+# File: .gitignore
+
+## Purpose
+Defines which files and directories Git should never track. Generated
+once during `@initialize-project`. Ensures sensitive files (env,
+keys, credentials), generated files (node_modules, logs), and
+development tools (demo encryption files) are never committed.
+
+---
+
+## Contents
+
+### Always include (every NodeJS service)
+```
+# Dependencies
+node_modules/
+
+# Environment variables
+.env
+
+# RSA keys and credentials
+pem/
+
+# Uploaded files and static assets
+images/
+
+# Log files
+logger/logs/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# codeninja MCP server dependencies (auto-installed by codeninja init)
+.codeninja/node_modules/
+```
+
+### Include when `client_type == "reactjs"`
+```
+# Encryption demo tool
+enc_dec.html
+```
+
+### Include when `client_type == "app"`
+```
+# Encryption demo tool
+enc_dec.php
+```
+
+### Include when `client_type == "app"` (Firebase credentials)
+```
+# Firebase service account
+pem/service-file.json
+```
+
+Note: `pem/` already covers this since the whole directory is ignored,
+but the explicit line makes the intent clear to developers.
+
+---
+
+## What This File Does NOT Do
+
+- Does not ignore `.env.example` — that file should be committed
+  so other developers know what variables are needed
+- Does not ignore test files
+- Does not ignore the document/ swagger folder
+- Does not ignore database migration files