Merge pull request #1147 from boluwacodes/fix/issues-848-850-860-861

feat: Security hardening, API validation, and ZK documentation (#848, #850, #860, #861)

Author: joelpeace48-cell

.github/workflows/openapi-validation.yml

@@ -0,0 +1,102 @@
+name: OpenAPI Spec Validation & Codegen
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - 'backend/openapi.yaml'
+      - 'backend/src/**/*.js'
+      - 'sdk/client/**'
+      - '.github/workflows/openapi-validation.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'backend/openapi.yaml'
+      - 'backend/src/index.js'
+  # Push trigger ensures spec stays in sync with route changes on main
+jobs:
+  validate-spec:
+    name: Validate OpenAPI spec completeness
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      
+      - name: Install backend dependencies
+        run: npm install
+        working-directory: backend
+      
+      - name: Validate OpenAPI spec covers all routes
+        run: node backend/scripts/validate-openapi-coverage.js
+      
+      - name: Install Spectral CLI for spec linting
+        run: npm install -g @stoplight/spectral-cli
+      
+      - name: Lint OpenAPI spec with Spectral
+        run: |
+          if [ -f backend/.spectral.yaml ]; then
+            spectral lint backend/openapi.yaml --ruleset backend/.spectral.yaml
+          else
+            spectral lint backend/openapi.yaml
+          fi
+        continue-on-error: true
+
+  codegen-drift:
+    name: Check generated client is up to date
+    runs-on: ubuntu-latest
+    needs: validate-spec
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      
+      - name: Install sdk/client dependencies
+        run: npm install
+        working-directory: sdk/client
+      
+      - name: Regenerate TypeScript client from openapi.yaml
+        run: npm run generate
+        working-directory: sdk/client
+      
+      - name: Check for drift in generated code
+        run: |
+          if ! git diff --exit-code sdk/client/src/; then
+            echo ""
+            echo "❌ ERROR: The generated TypeScript client in sdk/client/src/ is out of date."
+            echo ""
+            echo "To fix this:"
+            echo "  1. Run: cd sdk/client && npm run generate"
+            echo "  2. Commit the updated files"
+            echo ""
+            exit 1
+          fi
+      
+      - name: Verify generated client compiles
+        run: npm run build
+        working-directory: sdk/client
+      
+      - name: Run generated client tests
+        run: npm test
+        working-directory: sdk/client
+        continue-on-error: true
+
+  validate-examples:
+    name: Validate OpenAPI examples
+    runs-on: ubuntu-latest
+    needs: validate-spec
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      
+      - name: Install openapi-examples-validator
+        run: npm install -g openapi-examples-validator
+      
+      - name: Validate examples in spec
+        run: openapi-examples-validator backend/openapi.yaml
+        continue-on-error: true

backend/.spectral.yaml

@@ -0,0 +1,72 @@
+# Spectral OpenAPI Linting Rules
+# https://stoplight.io/open-source/spectral
+
+extends: [[spectral:oas, all]]
+
+rules:
+  # Require operation IDs for all operations (needed for code generation)
+  operation-operationId: error
+  
+  # Require descriptions for all operations
+  operation-description: warn
+  
+  # Require tags for all operations (helps with SDK organization)
+  operation-tags: warn
+  
+  # Require examples in responses
+  oas3-valid-media-example: warn
+  
+  # Require parameter descriptions
+  oas3-parameter-description: warn
+  
+  # Enforce consistent parameter naming (camelCase)
+  oas3-parameter-name-invalid: warn
+  
+  # No $ref siblings (OpenAPI 3.0 limitation)
+  no-$ref-siblings: error
+  
+  # Require security definitions
+  operation-security-defined: error
+  
+  # Path parameters must be defined
+  path-params: error
+  
+  # Success responses must be defined
+  operation-success-response: error
+  
+  # Custom rules specific to Trivela API
+  
+  # All POST/PUT/PATCH operations should have request body
+  trivela-mutating-operations-request-body:
+    description: POST/PUT/PATCH operations should have a request body
+    given: $.paths[*][?(@property === 'post' || @property === 'put' || @property === 'patch')]
+    severity: warn
+    then:
+      field: requestBody
+      function: truthy
+  
+  # All error responses should reference Error schema
+  trivela-error-response-schema:
+    description: Error responses (4xx, 5xx) should use Error schema
+    given: $.paths[*][*].responses[?(@property >= 400)]
+    severity: warn
+    then:
+      field: content.application/json.schema.$ref
+      function: pattern
+      functionOptions:
+        match: "#/components/schemas/Error"
+  
+  # Operations returning lists should have pagination
+  trivela-list-operations-pagination:
+    description: GET operations returning arrays should document pagination
+    given: $.paths[*].get.responses.200.content.application/json.schema
+    severity: hint
+    then:
+      - field: properties.data
+        function: truthy
+      - field: properties.total
+        function: truthy
+      - field: properties.limit
+        function: truthy
+      - field: properties.offset
+        function: truthy