Skip to main content

Source: ocean/docs/adr/046-codebase-audit-remediation.md | ✏️ Edit on GitHub

ADR-046: Codebase Audit Remediation

Date: 2025-08-29

Status​

Accepted

Context​

A comprehensive codebase audit was conducted on 2025-08-29, revealing several issues requiring immediate attention:

  1. Missing Dependencies: Development tools (tsx, ts-node, concurrently) were referenced in package.json scripts but not installed
  2. Security Risk: Server-only PostHog SDK with hardcoded API key in client directory
  3. Code Duplication: Multiple implementations of OTP components and data table columns
  4. Tool Sprawl: Three different third-party secret scanning tools instead of GitHub native features
  5. Inadequate Guardrails: No ESLint rule preventing server packages in client code

These issues posed security risks, increased maintenance burden, and violated our established patterns.

Decision​

We implemented the following remediations:

1. Dependency Management​

  • Added missing devDependencies: tsx@4.20.3, ts-node@10.9.2, concurrently@9.2.1
  • All package.json scripts now have their required dependencies properly declared

2. Security Improvements​

  • Removed hardcoded API key from posthog-edge.ts
  • Moved posthog-edge.ts from src/lib/ to supabase/functions/_shared/
  • Updated environment variable from VITE_POSTHOG_API_KEY to POSTHOG_API_KEY (proper server-side naming)
  • Added error handling for missing environment variables instead of fallback values

3. Code Deduplication​

  • Consolidated OTP components: Removed unused input-otp.tsx, kept input-otp-custom.tsx renamed as input-otp.tsx
  • Removed dead code: Deleted unused data-table-columns.tsx file
  • Preserved functionality: All existing features remain intact with cleaner implementation

4. Security Tool Consolidation​

  • Migrated to GitHub native security:
    • Removed Gitleaks, TruffleHog, and detect-secrets
    • Implemented GitHub CodeQL for code scanning
    • Leveraged automatic GitHub Secret Scanning
  • Simplified configuration: From 3 tools and multiple config files to 1 workflow
  • Better integration: Security alerts now appear directly in GitHub UI

5. Development Guardrails​

  • Added custom ESLint rule ocean/no-server-packages-in-client to prevent importing server-only packages in client code

  • Rule configuration:

    const serverOnlyPackages = ['posthog-node']
    // Error message guides developers to correct location

Consequences​

Positive​

  • Enhanced Security: No hardcoded secrets, proper client/server separation
  • Reduced Complexity: Single security scanning solution instead of three
  • Improved Developer Experience: Clear error messages and proper tooling
  • Better Maintainability: Less duplicate code and cleaner file structure
  • Cost Savings: Using GitHub native tools included in our plan

Negative​

  • Migration Effort: Required updating workflows and removing legacy tools
  • Learning Curve: Team needs to familiarize with GitHub Security tab

Neutral​

  • Icon Libraries: Kept both lucide-React and @tabler/icons-React as they serve different purposes
  • next-themes: Retained despite being a Next.js library as it works well for our CSR needs

Implementation Details​

Files Modified​

  1. /package.json - Added missing devDependencies
  2. /src/lib/posthog-edge.ts - Moved to /supabase/functions/_shared/posthog-edge.ts
  3. /src/components/ui/input-otp.tsx - Consolidated from two files
  4. /src/components/data-table-columns.tsx - Removed (unused)
  5. /.github/workflows/security-scanning.yml - New CodeQL workflow
  6. /.github/workflows/secret-scanning.yml - Removed (replaced)
  7. /.gitleaks.toml - Removed (using GitHub native)
  8. /.secrets.baseline - Removed (using GitHub native)
  9. /eslint.config.js - Added server package restriction rule
  10. /.husky/pre-commit - Removed gitleaks check

Validation​

All changes validated with:

  • ✅ TypeScript compilation (pnpm typecheck)
  • ✅ ESLint checks (pnpm lint)
  • ✅ Code formatting (pnpm format)

References​

  • Original audit: /docs/audits/codebase-audit-2025-08-29.md
  • Security migration guide: /docs/security-scanning-migration.md
  • GitHub Security documentation: https://docs.github.com/en/code-security
  • ADR-036: Phase 6 Backend Systematization
  • ADR-037: Phase 7 Automation Enhancements