Authentication & Session Management

The Authentication and Session Management system in p4n-improved handles two distinct layers of security: a private "App Gate" for the hosted instance and a proxied authentication mechanism for Park4Night (P4N). Since the application operates as a single-user private tool, it focuses on acquiring and maintaining a valid PHPSESSID from the official Park4Night service to facilitate API requests for premium data, favorites, and user profile information.

Sources: README.md, src/lib/p4n.ts:1-7

Park4Night Authentication Flow

The system uses a headed browser via Playwright to navigate the Park4Night login page. This approach is necessary because P4N employs Google reCAPTCHA Enterprise, which typically blocks headless automation. The login process automates credential entry and polls the P4N user endpoint until a valid session is established.

The Headed Login Process

1. Initialization: Launch a Chromium instance with automation headers disabled.
2. Consent Handling: A "Didomi Killswitch" script is injected to neutralize cookie consent banners that might obstruct the UI.
3. Form Submission: The system fills the username and password fields and attempts multiple submission methods (click, force-click, and DOM requestSubmit).
4. Session Polling: The browser polls https://park4night.com/api/user for up to 120 seconds.
5. Cookie Extraction: Once authorized, the PHPSESSID cookie is extracted and returned to the application.

Sources: src/lib/p4n-login.ts:8-16, src/lib/p4n-login.ts:153-228

The following sequence diagram illustrates the interaction between the User, the App Server, and the Park4Night infrastructure:

The sequence shows how the headed browser acts as a bridge to satisfy reCAPTCHA requirements while the server captures the resulting session.
Sources: src/lib/p4n-login.ts, src/app/api/auth/login/route.ts

Session Resolution and Storage

The application stores the acquired P4N session in a local httpOnly cookie named p4n_session. When an API request is made to the P4N backend, the resolveSession utility determines which token to use based on a defined priority.

Sources: src/lib/session.ts:25-45

Session Configuration

The local session cookie is configured with strict security parameters to prevent client-side script access.

export const SESSION_COOKIE = "p4n_session";

export const SESSION_COOKIE_OPTIONS = {
  httpOnly: true,
  secure: process.env.NODE_ENV === "production",
  sameSite: "lax" as const,
  path: "/",
  maxAge: 60 * 60 * 24 * 30, // 30 days
};

Sources: src/lib/session.ts:16-24

API Gateway (App Gate)

To protect the deployed instance, the application implements an "App Gate" via Next.js middleware (proxy). This gate uses HTTP Basic Authentication. If the APP_GATE_SECRET environment variable is set, all routes (except static assets and Next.js internals) require a username and password.

Gate Logic

• Bypass: If APP_GATE_SECRET is empty (default in local development), the gate is disabled.
• Verification: It checks the Authorization header for a Basic token.
• Identity: Uses APP_GATE_USER (defaults to "me") and the provided secret.

Sources: src/proxy.ts:7-32

The flow diagram represents the middleware logic that guards the application against unauthorized access when deployed to public environments.
Sources: src/proxy.ts

Error Handling and Session Expiry

The system defines a specific P4nSessionError class to handle authentication failures. When the P4N backend returns a 401 Unauthorized or 403 Forbidden status, the application catches these as session errors, prompting the user to re-authenticate via the Settings page.

• Status 401/403: Triggered when the PHPSESSID is no longer valid.
• Client Response: API routes return a sessionExpired: true flag in the JSON response to notify the UI.

Sources: src/lib/p4n.ts:60-65, src/lib/session.ts:10-14, src/app/api/me/route.ts:12-19

Summary

The authentication architecture is designed for a single-user "private proxy" use case. By utilizing a headed browser for the initial login, the system successfully bypasses complex bot detection on the Park4Night website. Once the session is established, the application securely manages the PHPSESSID via server-side cookies, ensuring that sensitive user credentials and session tokens are never exposed to client-side JavaScript.

Sources: README.md, src/lib/p4n.ts