pongolinks uses a single shared password and server-issued cookie sessions. The authentication flow is intentionally small because pongolinks is a single-user self-hosted service.
The architectural rationale and rejected alternatives are recorded in ADR-0005. This document describes the current behavior and the operational contract.
The backend requires AUTH_PASSWORD when the application is created. Use a strong secret and keep it outside source control.
The SQLite database path is configured with DATABASE_PATH and defaults to .data/pongolinks.sqlite. Authentication sessions are stored in that database, so database backups also contain the session records.
After installing dependencies, apply the database migrations before starting the backend:
bun run db:migrateGET /pl/loginrenders the backend login page.POST /pl/loginchecks the submitted password and, on success, redirects to a validated path inside/pl/.- An invalid password returns HTTP 401 and does not set a session cookie.
- An already authenticated request to
/pl/loginredirects to the requested in-app path.
The next path is restricted to the application base path. External and protocol-relative URLs are ignored so that login cannot become an open redirect.
Successful login creates a 32-byte random opaque token. The raw token is sent only to the browser. Its SHA-256 hash is stored in auth_sessions together with creation and expiration timestamps.
The browser receives the pongolinks_session cookie with these properties:
HttpOnly, so browser scripts cannot read the token;SameSite=Lax, suitable for the same-site browser application;Path=/pl/, so it is scoped to the application;Max-Age=63072000(two years), with the same absolute expiration in SQLite;Securefor HTTPS requests and production runtime.
Sessions survive backend restarts. Expired sessions are deleted when they are encountered and when a new session is created. Logging in again creates another session; existing sessions are not replaced.
The session auth plugin protects the application routes globally:
- Requests under
/pl/api/without a valid session return HTTP 401 with theauth.unauthorizedAPI error. - Other protected page and asset requests redirect to
/pl/loginand preserve a safe in-app return path. - The login route itself is available without a session.
The frontend redirects to the login page when an API response contains auth.unauthorized and returns to the original route after a successful login.
The Chrome and Firefox extensions do not implement a separate login flow. Log in to the configured pongolinks origin in the browser first; requests from the extensions then use the browser profile's existing same-origin session cookie. See the browser extension documentation for the extension message and cache contracts.
- There is no logout or session-management UI in the current version.
- Changing
AUTH_PASSWORDtakes effect after the backend is restarted, but it does not revoke existing sessions. Existing session rows must be removed with SQLite tooling when immediate revocation is required; back up the database before making direct changes. - Clearing a browser's cookies signs that browser out, but the corresponding database session remains until it expires or is removed.
- Use HTTPS in production so the session cookie is marked secure in transit.
- This is a single-user password gate, not a multi-user identity system. JWTs, API tokens, and Basic Auth compatibility are not supported.
Authentication behavior is covered by apps/backend/test/cookie-auth.test.ts and the frontend unauthorized-response tests.