Security: API & Tenancy Audit Report

[cto-new]

This PR adds the initial security audit report for FreeRelay.

Key findings include:

1. Cache revocation delay in AuthMiddleware (LRU cache issue).
2. Security risks associated with the static admin key.
3. Lack of integration of the signed audit trail system.

Note: I was unable to audit the /v1/analytics and /v1/requests endpoints as the code is not yet present in the repository, despite being marked as done in the task board.

Summary by Sourcery

Documentation:

• Add SECURITY_AUDIT.md documenting the results of a security review, key vulnerabilities, and recommended mitigations for API keys, admin access, audit logging, and upcoming analytics/request endpoints.

[sourcery-ai]

Reviewer's Guide

Adds an initial SECURITY_AUDIT.md document describing current security posture and identified issues in auth middleware, admin key usage, audit trail integration, and future multi-tenant analytics/requests endpoints, without changing application code.

Sequence diagram for API key validation and tenancy assignment

sequenceDiagram
    actor Client
    participant Gateway
    participant AuthMiddleware
    participant Supabase

    Client->>Gateway: HTTP request with Authorization header
    Gateway->>AuthMiddleware: Invoke with request
    alt Static admin key path
        AuthMiddleware->>AuthMiddleware: validate_static_key(api_key)
        AuthMiddleware-->>Gateway: set request.state.user_id = admin
        Gateway-->>Client: Forward response from downstream handler
    else Supabase-backed key path
        AuthMiddleware->>AuthMiddleware: _verify_token_supabase(api_key)
        note left of AuthMiddleware: This call result is cached via LRU
        AuthMiddleware-->>Supabase: Validate api_key and fetch tenant data
        Supabase-->>AuthMiddleware: api_key status, user_id, plan_tier
        AuthMiddleware-->>Gateway: set request.state.user_id
        Gateway-->>Client: Forward response from downstream handler
    end

Loading

Sequence diagram for intended signed audit trail integration

sequenceDiagram
    actor Client
    participant Gateway
    participant AuthMiddleware
    participant AuditMiddleware
    participant AuditLogger
    participant RedisAuditStream

    Client->>Gateway: HTTP request
    Gateway->>AuthMiddleware: Authenticate request
    AuthMiddleware-->>Gateway: Attach user_id to request.state
    Gateway->>AuditMiddleware: Process authenticated request
    AuditMiddleware->>AuditLogger: append_event(user_id, path, method, status)
    AuditLogger->>AuditLogger: sign_event_with_hmac(secret_key)
    AuditLogger->>RedisAuditStream: store_signed_event(tenant_namespace)
    RedisAuditStream-->>AuditLogger: ack
    AuditMiddleware-->>Gateway: Continue pipeline
    Gateway-->>Client: HTTP response

Loading

Updated class diagram for auth and audit middleware components

classDiagram
    class AuthMiddleware {
        +call(request, call_next)
        -_verify_token_supabase(api_key)
        -validate_static_key(api_key)
        -FREERELAY_API_KEY
    }

    class AuditMiddleware {
        +call(request, call_next)
        -logger
        -audit_logger
    }

    class AuditLogger {
        +append_event(user_id, path, method, status)
        -sign_event_with_hmac(secret_key, payload)
        -store_signed_event(namespace, signed_payload)
        -secret_key
    }

    class RequestState {
        +user_id
        +plan_tier
    }

    class RedisAuditStream {
        +store_signed_event(namespace, signed_payload)
    }

    class SupabaseClient {
        +validate_api_key(api_key)
        +fetch_tenant_data(api_key)
    }

    AuthMiddleware --> SupabaseClient : uses
    AuthMiddleware --> RequestState : sets
    AuditMiddleware --> AuditLogger : uses
    AuditLogger --> RedisAuditStream : writes_to

Loading

File-Level Changes

Change	Details	Files
Introduce initial security audit documentation for FreeRelay, capturing current design, concrete findings, and recommendations.	Create SECURITY_AUDIT.md with executive summary of current security posture Document LRU cache-based API key revocation delay in auth middleware and recommended TTL-based caching Describe risks of the static admin API key and recommended restricted usage Document gap between implemented signed audit logger and non-integrated AuditMiddleware Capture blocked audit status and isolation requirements for planned /v1/analytics and /v1/requests endpoints List general security best practices around secrets management and dependency auditing	docs/SECURITY_AUDIT.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}