# What Is the Purpose of public-paths.ts in DeskcommCRM's Authentication Flow?

> Discover the purpose of public-paths.ts in DeskcommCRM's authentication flow. Learn how this file allows specific routes to bypass authentication checks for essential functions.

- Repository: [Rafael Melgaço/DeskcommCRM](https://github.com/melgarafael/DeskcommCRM)
- Tags: internals
- Published: 2026-09-12

---

**The [`public-paths.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/public-paths.ts) file defines a whitelist of URL patterns that bypass the Edge middleware's authentication check, allowing specific routes like OAuth callbacks, webhooks, and health endpoints to function without a session cookie.**

DeskcommCRM uses Next.js Edge middleware to enforce authentication at the proxy layer before requests reach the application. The [`lib/auth/public-paths.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/lib/auth/public-paths.ts) module serves as the central configuration that determines which routes remain accessible before a user session is established, ensuring that critical external integrations and system endpoints remain reachable.

## How the Whitelist Works in public-paths.ts

The file exports two key components: the `PUBLIC_PATHS` array and the `isPublicPath` helper function.

`PUBLIC_PATHS` is an ordered array of `RegExp` objects that match specific route patterns. Each regular expression targets endpoints that must be reachable without a valid Supabase session cookie:

```typescript
// Example entries from lib/auth/public-paths.ts
export const PUBLIC_PATHS = [
  /^\/api\/v1\/health$/,                      // Health checks
  /^\/api\/v1\/webhooks\/.*/,               // External webhooks
  /^\/api\/v1\/agenda\/google\/callback$/,  // OAuth callbacks
  /^\/favicon\.ico$/,                       // Static assets
  /^\/legal\/terms$/                        // Legal pages
];

```

The `isPublicPath(pathname: string): boolean` function tests incoming request paths against this array using `some(re => re.test(pathname))`. This utility provides a fast, synchronous check that the Edge runtime can execute efficiently:

```typescript
export function isPublicPath(pathname: string): boolean {
  return PUBLIC_PATHS.some(regex => regex.test(pathname));
}

```

## Integration with Edge Middleware (proxy.ts)

The primary consumer of this whitelist is [`proxy.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/proxy.ts), the Edge middleware that runs on every incoming request. Early in the request lifecycle, the middleware checks whether the pathname qualifies as public before attempting any JWT validation or cookie parsing:

```typescript
import { isPublicPath } from "@/lib/auth/public-paths";
import { NextRequest, NextResponse } from "next/server";

export async function proxy(request: NextRequest) {
  const { pathname } = request.nextUrl;

  // Skip auth for whitelisted routes
  if (isPublicPath(pathname)) {
    return NextResponse.next();
  }

  // Continue with Supabase session validation for protected routes
  // ... auth logic here
}

```

This early return prevents the middleware from blocking requests that legitimately lack session cookies, such as Google OAuth redirects or monitoring health checks.

## Categories of Public Routes in DeskcommCRM

The whitelist covers distinct categories of endpoints that serve different purposes in the application architecture:

- **System Health and Monitoring**: Routes like `/api/v1/health` must respond to uptime probes and load balancers without authentication headers.

- **External Service Integrations**: Webhook handlers (`/api/v1/webhooks/`) and cron job endpoints (`/api/v1/cron/`) typically authenticate via Bearer tokens or HMAC signatures rather than browser cookies.

- **OAuth Callback URLs**: Third-party providers redirect users to paths like `/api/v1/agenda/google/callback` after authentication. These requests arrive without DeskcommCRM session cookies but contain temporary authorization codes.

- **Static Assets**: Files such as `/favicon.ico`, `/icon`, and `/_next/` build outputs must load before the authentication state is known.

- **Legal and Public Resources**: Terms of service pages (`/legal/terms`) and email template endpoints remain readable without logging in.

## "Public" vs. "Unauthenticated": Critical Distinction

A crucial architectural detail in DeskcommCRM is that "public" status in [`public-paths.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/public-paths.ts) does **not** mean the endpoint accepts unauthenticated requests indiscriminately. Instead, it signals that **the proxy must not reject the request** before the route handler itself decides how to authenticate.

For example, an endpoint listed in `PUBLIC_PATHS` might still validate a `Bearer` token in the Authorization header. The whitelist merely prevents the Edge middleware from enforcing cookie-based JWT validation, allowing these routes to implement their own security models (API keys, OAuth tokens, or unauthenticated access) without interference from the global auth check.

## Testing and Validation

The repository includes comprehensive tests to ensure the whitelist behaves correctly:

- **[`tests/unit/public-paths.test.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/tests/unit/public-paths.test.ts)**: Validates that `isPublicPath` correctly matches intended patterns while rejecting similar but protected paths.
- **[`tests/unit/callback-oauth-alcancavel.test.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/tests/unit/callback-oauth-alcancavel.test.ts)**: Specifically verifies that OAuth callback routes remain accessible without session cookies, preventing regression in authentication flows.
- **[`tests/e2e/agenda-kit-visual.spec.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/tests/e2e/agenda-kit-visual.spec.ts)**: End-to-end tests reference the proxy's public-path logic to ensure visual consistency in pre-authentication states.

## Summary

- **[`lib/auth/public-paths.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/lib/auth/public-paths.ts)** exports `PUBLIC_PATHS` (an array of RegExp patterns) and the `isPublicPath()` helper function.
- The **Edge middleware in [`proxy.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/proxy.ts)** uses this whitelist to skip authentication checks for specific routes, improving performance for legitimate public traffic.
- **Public routes include** health checks, OAuth callbacks, webhooks, cron jobs, static assets, and legal pages.
- **"Public" status** prevents proxy-level blocking but does not prevent route-level authentication via Bearer tokens or API keys.
- **Unit and E2E tests** verify that critical paths like OAuth callbacks remain reachable without session cookies.

## Frequently Asked Questions

### What happens if a route is not listed in public-paths.ts?

If a path does not match any pattern in `PUBLIC_PATHS`, the Edge middleware in [`proxy.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/proxy.ts) proceeds to validate the Supabase session cookie and JWT. Requests without valid authentication receive a **401 Unauthorized** response before reaching the route handler, protecting private API endpoints from unauthorized access.

### Can public paths still require authentication?

Yes. Routes whitelisted in [`public-paths.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/public-paths.ts) may still implement their own authentication mechanisms, such as validating Bearer tokens in the Authorization header or checking HMAC signatures for webhooks. The whitelist only disables the **proxy-level** cookie authentication, allowing these endpoints to use alternative security models appropriate for their use case.

### How do I add a new public route to DeskcommCRM?

Add a new regular expression to the `PUBLIC_PATHS` array in [`lib/auth/public-paths.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/lib/auth/public-paths.ts). Ensure the pattern is specific enough to avoid accidentally exposing protected resources, and include a unit test in [`tests/unit/public-paths.test.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/tests/unit/public-paths.test.ts) to verify the matcher behavior. If the route handles OAuth callbacks or webhooks, consider adding integration tests similar to [`callback-oauth-alcancavel.test.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/callback-oauth-alcancavel.test.ts).

### Where does the actual authentication validation occur for protected routes?

For non-public routes, authentication validation occurs in **[`proxy.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/proxy.ts)** (the Edge middleware), which checks for valid Supabase session cookies before allowing the request to proceed to the application code. This centralized approach ensures consistent auth enforcement across the entire DeskcommCRM application without requiring checks in every individual route handler.