@lhi/tdd-audit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kyra Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# @lhi/tdd-audit
+
+Anti-Gravity Skill for TDD Remediation. This package securely patches code vulnerabilities by utilizing a Test-Driven Remediation (Red-Green-Refactor) protocol.
+
+## Installation
+
+You can install this skill globally so that it is available to the Anti-Gravity agent across all of your projects:
+
+```bash
+npx @lhi/tdd-audit
+```
+
+Or run it directly if you have cloned the repository:
+
+```bash
+node index.js
+```
+
+### Local Installation
+
+If you prefer to install the skill and its workflow strictly to your current workspace instead of globally, use the `--local` flag:
+
+```bash
+npx @lhi/tdd-audit --local
+# or
+node index.js --local
+```
+
+This will create an `.agents` folder in your current directory. 
+
+*Note: Regardless of whether you install globally or locally, the boilerplate security tests will always be scaffolded into your current project's directory at `__tests__/security`.*
+
+## Usage
+
+Once installed, you can trigger the autonomous audit in your Anti-Gravity chat using the provided slash command:
+
+```text
+/tdd-audit
+```
+
+This will instruct the agent to:
+1. Explore the designated structure to find any vulnerabilities.
+2. Exploit the vulnerability with a failing test (Red).
+3. Patch the flaw to make the test pass (Green).
+4. Ensure no regressions occur (Refactor).
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: TDD Remediation Protocol
+description: A comprehensive toolkit for applying Red-Green-Refactor to fix security vulnerabilities.
+---
+
+# TDD Remediation Protocol
+
+Applying Test-Driven Development (TDD) to code that has already been generated requires Test-Driven Remediation. You must prove the security hole exists by writing a test that exploits it, apply the fix, and then prove the hole is closed.
+
+## Autonomous Audit Mode
+If the user asks you to "Run the TDD Remediation Auto-Audit" or asks you to implement this on your own:
+1. **Explore**: Proactively use your tools (like `grep_search`, `view_file`, and `list_dir`) to scan the user's repository. Focus on `controllers/`, `routes/`, `api/`, and database files. Search for anti-patterns: missing authorization checks, unparameterized SQL queries, and lack of sanitization.
+2. **Plan**: Identify the active vulnerabilities and outline them to the user.
+3. **Self-Implement**: For *each* vulnerability found, autonomously execute the complete 3-phase protocol:
+   - **[Phase 1 (Red)](./prompts/red-phase.md)**: Write the exploit test ensuring it fails.
+   - **[Phase 2 (Green)](./prompts/green-phase.md)**: Write the security patch ensuring the test passes.
+   - **[Phase 3 (Refactor)](./prompts/refactor-phase.md)**: Clean the code and ensure no business logic broke.
+Move methodically through the vulnerabilities one by one.
+
+---
+
+## Manual Mode
+If addressing a single vulnerability manually, invoke the context from the appropriate sub-prompt:
+1. **[Red Phase](./prompts/red-phase.md)**: Writing the exploit test.
+2. **[Green Phase](./prompts/green-phase.md)**: Writing the patch.
+3. **[Refactor Phase](./prompts/refactor-phase.md)**: Ensuring no regressions.
+
+A boilerplate test has been added to the project at `__tests__/security/sample.exploit.test.js`.
+
+---
+## CI/CD Integration Guide
+
+To ensure vulnerabilities do not re-enter the main branch, add a strict security testing step to your CI pipeline (e.g., GitHub Actions, GitLab CI).
+
+**Example GitHub Actions Workflow (`.github/workflows/security-tests.yml`)**
+```yaml
+name: Security Tests
+on: [pull_request]
+jobs:
+  security-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install dependencies
+        run: npm ci
+      - name: Run Security Exploit Tests
+        run: npm run test:security
+```

package/index.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const isLocal = process.argv.includes('--local');
+const agentBaseDir = isLocal ? process.cwd() : os.homedir();
+
+const targetSkillDir = path.join(agentBaseDir, '.agents', 'skills', 'tdd-remediation');
+const targetWorkflowDir = path.join(agentBaseDir, '.agents', 'workflows');
+const targetTestDir = path.join(process.cwd(), '__tests__', 'security');
+
+console.log(`Installing TDD Remediation Skill (${isLocal ? 'Local' : 'Global'})...`);
+
+// 1. Install the Skill
+if (!fs.existsSync(targetSkillDir)) {
+  fs.mkdirSync(targetSkillDir, { recursive: true });
+}
+
+// Copy the specific skill files and directories
+const filesToCopy = ['SKILL.md', 'prompts', 'templates'];
+for (const item of filesToCopy) {
+  const sourcePath = path.join(__dirname, item);
+  const targetPath = path.join(targetSkillDir, item);
+  if (fs.existsSync(sourcePath)) {
+    fs.cpSync(sourcePath, targetPath, { recursive: true });
+  }
+}
+
+// 2. Scaffold the security-tests directory
+if (!fs.existsSync(targetTestDir)) {
+  fs.mkdirSync(targetTestDir, { recursive: true });
+  console.log(`Created security test directory at ${targetTestDir}`);
+}
+
+const sourceTestFile = path.join(__dirname, 'templates', 'sample.exploit.test.js');
+const targetTestFile = path.join(targetTestDir, 'sample.exploit.test.js');
+
+if (!fs.existsSync(targetTestFile)) {
+  fs.copyFileSync(sourceTestFile, targetTestFile);
+  console.log(`Scaffolded boilerplate exploit test at ${targetTestFile}`);
+}
+
+// 3. Install the workflow shortcode
+if (!fs.existsSync(targetWorkflowDir)) {
+  fs.mkdirSync(targetWorkflowDir, { recursive: true });
+}
+
+const sourceWorkflowFile = path.join(__dirname, 'workflows', 'tdd-audit.md');
+const targetWorkflowFile = path.join(targetWorkflowDir, 'tdd-audit.md');
+
+if (fs.existsSync(sourceWorkflowFile)) {
+  fs.copyFileSync(sourceWorkflowFile, targetWorkflowFile);
+  console.log(`Installed shortcode workflow at ${targetWorkflowFile}`);
+}
+
+console.log(`Successfully installed TDD Remediation skill to ${targetSkillDir}`);
+console.log('You can now use `/tdd-audit` in your Anti-Gravity chat!');

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@lhi/tdd-audit",
+  "version": "1.0.0",
+  "description": "Anti-Gravity Skill for TDD Remediation",
+  "main": "index.js",
+  "bin": {
+    "tdd-audit": "./index.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "Kyra Lee",
+  "license": "MIT"
+}

package/prompts/auto-audit.md

@@ -0,0 +1,19 @@
+# TDD Remediation: Auto-Audit Mode
+
+When invoked in Auto-Audit mode, you must proactively secure the user's entire repository without waiting for explicit files to be provided.
+
+## Phase 0: Discovery
+1. **Explore the Architecture**: Use your `list_dir` and `view_file` tools to understand the project structure. Look for directories named `controllers`, `routes`, `api`, `services`, or `models`.
+2. **Search for Anti-Patterns**: Use your `grep_search` tool to look for common vulnerabilities:
+   - *SQL Injection*: Search for raw query strings, e.g., `` `SELECT * FROM users WHERE id = ${req.body.id}` ``
+   - *IDOR*: Search for direct lookups without tenant or user ID checks.
+   - *XSS*: Search for raw HTML rendering `innerHTML`, `dangerouslySetInnerHTML`, or similar sinks.
+3. **Present Findings**: Provide a list of identified vulnerabilities to the user before proceeding.
+
+## Phase 1 to 3: Remediation Engine
+For each vulnerability approved for fixing, you must rigorously apply the RED-GREEN-REFACTOR protocol:
+1. **[RED](./red-phase.md)**: Write the exploit test in `__tests__/security/` and run it to prove the vulnerability exists.
+2. **[GREEN](./green-phase.md)**: Write the patch and run the tests to prove the exploit is blocked.
+3. **[REFACTOR](./refactor-phase.md)**: Ensure standard functionality is maintained and existing tests pass.
+
+Do not move to the next vulnerability until the current one is fully remediated and tested.

package/prompts/green-phase.md

@@ -0,0 +1,12 @@
+# TDD Remediation: The Patch (Green Phase)
+
+Once the failing test is committed to the codebase, it is time to write the remediation code.
+
+## Action
+Apply the AI-generated security patch to the relevant routes, database configurations, sanitization utilities, or controllers.
+
+## Protocol
+Run the test suite again. The exploit test from **Phase 1 (Red)** must now be blocked gracefully resulting in a passing test suite.
+
+## Goal
+Prove definitively that the specific vulnerability is patched without relying on manual clicking, guessing, or superficial UI changes. If the test still fails, your security fix is incomplete.

package/prompts/red-phase.md

@@ -0,0 +1,48 @@
+# TDD Remediation: The Exploit (Red Phase)
+
+Before changing a single line of the vulnerable code, you must write a test that successfully executes the exploit. If the test cannot break the app, the vulnerability isn't properly isolated.
+
+## Action
+Write an integration or unit test that actively attempts the breach.
+
+## Protocol
+The test must fail **your security requirements**, not just produce a 500 Server Error because the app crashed.
+In testing frameworks, this usually means writing an assertion that expects a secure block (e.g., `expect(response.status).toBe(403)` or `expect(payload).toBeSanitized()`), but currently receives a `200 OK` or un-sanitized reflection.
+
+## Goal
+Establish a measurable baseline. You now have a weaponized test case.
+
+---
+
+## Vulnerability-Specific Strategies
+
+### IDOR (Insecure Direct Object Reference) / Tenant Isolation
+Assert that User A receives a 403 Forbidden or 404 Not Found when trying to manipulate User B's resources.
+* **Jest/Supertest:** `expect(response.status).toBe(403);`
+* **Playwright:** Verify the UI displays an unauthorized banner instead of loading the other user's dashboard.
+
+### XSS (Cross-Site Scripting)
+Submit an aggressive payload like `<script>alert(1)</script>` or `<img src=x onerror=alert(1)>`.
+* **Jest/Supertest:** Assert that the raw response body either HTML-escapes the payload (`&lt;script&gt;`) or rejects the input entirely.
+* **Playwright:** Attempt to inject the payload in a form field and verify that the script is not evaluated in the DOM.
+
+### SQL Injection
+Submit payloads attempting tautologies (e.g., `' OR 1=1 --`) or union-based extraction.
+* **Assertion:** Expect a 400 Bad Request or parameter rejection, and verify that the database did not actually execute the malformed query or return all records.
+
+---
+
+## Framework Templates to Provide
+
+### Jest / Supertest (Node.js)
+```javascript
+const response = await request(app).post('/api/endpoint').send({ exploit: true });
+expect(response.status).toBe(403); // Fails because it currently returns 200
+```
+
+### PyTest (Python)
+```python
+def test_idor_exploit(client, user_b_token):
+    response = client.get('/api/user_a_resource/', headers={'Authorization': f'Bearer {user_b_token}'})
+    assert response.status_code == 403 # Fails because it currently returns 200
+```

package/prompts/refactor-phase.md

@@ -0,0 +1,14 @@
+# TDD Remediation: Regression & Refactor (Refactor Phase)
+
+Security fixes can sometimes be heavy-handed and break core functionality. Now that the perimeter is secure, we must ensure the application still functions.
+
+## Action
+Run standard functional tests alongside the new security tests. 
+
+## Protocol
+1. Clean up the code and remove redundancies.
+2. Ensure the intended business logic remains completely intact. 
+3. If a functional test breaks, **revert the patch** and prompt the AI to try a different security approach. Security that breaks functionality is not a successful patch.
+
+## Goal
+Maintain the speed and functionality of the rapid prototype while successfully hardening the perimeter. The ultimate goal is a fully passing test suite (security tests + functional tests).

package/templates/sample.exploit.test.js

@@ -0,0 +1,32 @@
+/**
+ * TDD Remediation: Red Phase Sample Test
+ * 
+ * Replace the boilerplate below with the specific exploit you are trying to verify.
+ * This test MUST fail initially (Red Phase). Once you apply the security fix,
+ * this test MUST pass (Green Phase).
+ */
+
+const request = require('supertest');
+const app = require('../../app'); // Update with the path to your Express app or API
+
+describe('Security Vulnerability Remediation - Red Phase', () => {
+
+  it('SHOULD NOT allow unauthorized exploitation of [VULNERABILITY]', async () => {
+    // 1. Arrange the exploit payload
+    const exploitPayload = {
+      // e.g. input: "1; DROP TABLE users"
+    };
+
+    // 2. Act: Execute the exploit against the system
+    const response = await request(app)
+      .post('/api/vulnerable-endpoint')
+      .send(exploitPayload);
+
+    // 3. Assert: The system MUST block the exploit gracefully (e.g. 403, 400, sanitization)
+    expect(response.status).toBe(403);
+    
+    // For XSS or SQLi, ensure the response body does NOT execute or reflect the payload
+    // expect(response.body.data).not.toContain(exploitPayload.input);
+  });
+
+});

package/workflows/tdd-audit.md

@@ -0,0 +1,6 @@
+---
+description: Run the complete TDD Remediation Autonomous Audit
+---
+Please use the TDD Remediation Protocol Auto-Audit skill (`.agents/skills/tdd-remediation/SKILL.md`) to secure this repository.
+
+Begin by exploring the structure to find any vulnerabilities or anti-patterns in the codebase. Then, for every issue you find, show me the list of vulnerabilities, and rigorously apply the Red-Green-Refactor loop to write the exploit tests, patch the flaws, and ensure no regressions occurred.