HTTP Basic Authentication Gate

The HTTP Basic Authentication Gate is a security mechanism implemented in the P4N Map application to protect deployed instances from unauthorized access. Since the application acts as a proxy for a user's Park4Night+ account—carrying sensitive session data like the PHPSESSID—the gate ensures that only the intended user can access the web interface and backend API when the application is hosted publicly (e.g., on Fly.io).

Sources: README.md:5-10, README.md:65-67, src/proxy.ts:1-4

Architecture and Middleware Logic

The gate is implemented as a Next.js middleware-style function (using the "proxy" convention) that intercepts incoming requests before they reach application routes or API endpoints. It evaluates the presence and validity of the Authorization header against environment variables defined at deployment.

Logic Flow

1. Secret Check: The middleware first checks for the existence of APP_GATE_SECRET. If this environment variable is empty or not set, the gate is disabled, allowing local development without authentication.
2. Credential Verification: If a secret is present, the middleware extracts the Authorization header. It decodes the Base64-encoded credentials and compares the provided username and password against APP_GATE_USER and APP_GATE_SECRET.
3. Access Control: If credentials match, the request proceeds. If they do not match or are missing, the middleware returns a 401 Unauthorized response with a WWW-Authenticate header to trigger the browser's native login prompt.

Sources: src/proxy.ts:8-30

The following diagram illustrates the request lifecycle through the Authentication Gate:

The diagram shows how environment variables determine whether a request is challenged or allowed to bypass the security layer. Sources: src/proxy.ts:8-30

Configuration and Environment Variables

The gate relies entirely on server-side environment variables. These are typically injected via a .env.local file for local testing or through platform-specific secret management (e.g., fly secrets set) for production.

Sources: README.md:43, README.md:65-67, src/proxy.ts:11-14

Scope and Matcher Patterns

The gate is configured to protect almost all application paths while excluding internal Next.js assets and static files to ensure the UI renders correctly once authenticated.

Protected vs. Excluded Paths

The gate uses a specific matcher configuration to define its scope:

• Protected: All application routes (/), API routes (/api/*), and settings pages.
• Excluded:
  • _next/static (Compiled scripts and CSS)
  • _next/image (Optimized images)
  • favicon.ico

Sources: src/proxy.ts:33-36

Integration with Park4Night Sessions

The gate serves as a primary defense for the secondary authentication layer: the Park4Night session. While the Basic Auth gate controls access to the P4N Map instance, the application internally manages a PHPSESSID cookie to interact with Park4Night private endpoints.

Authentication Sequence

The sequence demonstrates that the Basic Auth Gate is the first point of entry, followed by the specific Park4Night login process. Sources: README.md:46-51, src/lib/p4n-login.ts:133-145, src/app/api/auth/login/route.ts:40-45

Security Considerations

• Server-Side Execution: The gate logic resides in src/proxy.ts, ensuring that authentication checks happen in the Node.js runtime (v22+) and are never exposed to client-side JavaScript.
• httpOnly Cookies: After passing the gate and performing a Park4Night login, the resulting PHPSESSID is stored in an httpOnly cookie, preventing XSS-based session theft.
• Local Development: By leaving APP_GATE_SECRET empty in .env.local, developers can bypass the gate during active coding.

Sources: README.md:38, src/proxy.ts:1-6, src/app/api/auth/login/route.ts:45