docs: add agents.md file (#1071)

.github/workflows/e2e.yml

@@ -0,0 +1,43 @@
+name: Run e2e tests
+on:
+  workflow_dispatch:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    timeout-minutes: 30
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # ratchet:actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # ratchet:pnpm/action-setup@v6
+        with:
+          package_json_file: ./e2e/package.json
+
+      - name: Set up Docker
+        uses: docker/setup-docker-action@6d7cfa65f60a9dda7b46e5513fa982536f3c9877 # ratchet:docker/setup-docker-action@v5
+
+      - name: Install dependencies
+        run: pnpm ci
+        working-directory: e2e
+
+      - name: Install Playwright Browsers
+        run: pnpm exec playwright install --with-deps
+        working-directory: e2e
+
+      - name: Run Playwright tests
+        run: pnpm test
+        working-directory: e2e
+
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # ratchet:actions/upload-artifact@v4
+        if: ${{ !cancelled() }}
+        with:
+          name: playwright-report
+          path: e2e/playwright-report/
+          retention-days: 5

.gitignore

@@ -50,7 +50,10 @@ __debug_*
 config.certify.yml
 
 # deepsec
-/.deepsec
+/.deepsec/
 
 # jetbrains
 /.idea/
+
+# claude stuff
+/.claude/

AGENTS.md

@@ -0,0 +1,151 @@
+# Agents
+
+*This file is written by Humans for Agents.*
+
+## Overview
+
+Tinyauth is a lightweight and open-source authentication server written in Go and TypeScript (React). It acts as either an authentication middleware (forward_auth, ext_authz or auth_request) to protect applications using proxy authentication or as an OpenID Connect provider to offer SSO (Single-Sign-On) to your self-hosted apps. It supports local users with optional 2FA (via TOTP), LDAP, SSO users via OAuth, and access controls (ACLs). Tinyauth can be deployed with Docker, Kubernetes or bare-metal with a binary.
+
+## Considerations
+
+- The repository we are working at is `https://github.com/tinyauthapp/tinyauth`.
+- ALWAYS follow the instructions for committing and creating a pull request as mentioned below. 
+
+## Philosophy
+
+Tinyauth is designed to run with simplicity in mind. This is why we try to avoid adding unnecessary persistent storage and configuration options.
+
+Tinyauth can run without persistent storage, and the SQLite database is only used for storing normal or OpenID Connect sessions. You MUST never store data in the database that is required for Tinyauth function.
+
+As for the configuration, we support environment variables, CLI flags and a YAML configuration file. We try to keep the required configuration at a minimal with sane defaults so users can spend the least amount of time configuring Tinyauth.
+
+We NEVER create a breaking change unless absolutely necessary and only if non-breaking changes have been discussed and deemed not ideal.
+
+## Technical Overview
+
+Tinyauth is designed to be as modular as possible. We use a repository-service-controller structure where each service/controller/middleware defines its dependencies in a Dig input struct, and then the main bootstrap entrypoint dynamically injects the dependencies to each method.
+
+All methods share one global static config struct, which contains the user configuration as is, and a runtime config struct that contains dynamically generated values on startup. If a method needs a modified version, it MUST never modify the global configuration struct but rather create a local copy.
+
+We write database migrations by hand. Migrations go in the respective database directory inside the `assets/migrations` directory and follow the `000001_migration_name_in_snake_case.sql` format where the 6-digit number is incremented on each new migration. The repository is automatically generated from SQL queries, SQLC and our own custom generator that unifies each SQLC package into one repository interface. Always ensure that migrations and queries exist for all available database drivers, else our store generation will fail. After adding your migrations and queries, run the SQLC code-gen with `make sql` and update the store code-gen with `make generate`. DO NOT EDIT the automatically generated files from SQLC or our store generator, they are marked.
+
+When updating translations, you should only update the `frontend/src/lib/i18n/locales/en.json` and `frontend/src/lib/i18n/locales/en-US.json` files (they should be exactly the same). Crowdin will handle the generation of the keys for the rest of the available locales. NEVER hard-code plain English in the frontend, instead use the available `i18next` library and the respective translations.
+
+For the REST framework we use Gin. However, functions or methods should avoid using the Gin Context (`gin.Context`) and default to stdlib arguments and outputs. The Gin Context exposes stdlib-compatible structs such as `http.Request` and `http.ResponseWriter` and is compatible with the `context` package.
+
+When you need to log in the backend, use the injected logger, NOT the global zerolog struct.
+
+In case you need toolchain versions, you can find the Node + Go version in the `Dockerfile` and the PNPM version in the `package.json` file inside the `frontend` directory.
+
+Tinyauth uses Semantic Versioning (SemVer) for versions. 
+
+## File structure
+
+Tinyauth is composed of two parts, the React frontend and the Go backend.
+
+A high level of the backend is as follows:
+
+```text
+internal 
+├── assets # Contains the embedded assets
+│   ├── dist # Dist is the compiled frontend
+│   └── migrations # Migrations in SQL for all supported databases
+│       ├── postgres
+│       └── sqlite
+├── bootstrap # The main entrypoint that bootstraps and starts Tinyauth, called by the CLI
+├── controller # All of the HTTP controllers
+├── middleware # The HTTP middlewares
+├── model # Configuration schemas
+├── repository # Repository holds all of the queries used by the services, each child-repository implements the store interface
+│   ├── memory
+│   ├── postgres
+│   └── sqlite
+├── service # The services that handle the underlying logic for the controllers
+├── test # Creates any necessary package-wide configurations and helpers used by tests 
+└── utils # Small helpers and utils used by the app
+    ├── decoders # Wrappers around paerser decoders such as the label decoder
+    ├── loaders # The env, cli and YAML wrappers around the paerser loaders
+    └── logger # A wrapper around the zerolog logging library
+```
+
+Same for the frontend:
+
+```text
+frontend/src
+├── components # Different components used by the pages
+│   ├── auth # Forms used for authentication
+│   ├── domain-warning # Domain warning when configured domain and actual domain don't match
+│   ├── icons # Hardcoded SVG icons for OAuth providers
+│   ├── layout # Main frontend layout
+│   ├── providers # Different state providers such as theme
+│   ├── quick-actions # The top right quick settings menu
+│   └── ui # ShadCN based UI components
+├── context # Holds and provides the app and user context
+├── lib # Helpers used by the pages
+│   ├── hooks # Hooks around the query parameters
+│   └── i18n # Holds translation logic
+│       └── locales # The raw JSON locales provided by Crowdin
+├── pages # The actual app pages
+└── schemas # Different schemas, mostly used for fetching data from the backend
+```
+
+## Make recipes
+
+Tinyauth uses a Makefile for simplifying development. A reference of the available recipes can be found below:
+
+- `deps` - Install the frontend and backend dependencies.
+- `clean-data` - Clean any data created by running Tinyauth.
+- `clean-webui` - Clean frontend build output.
+- `webui` - Compile the WebUI.
+- `binary` - Compile the binary for the current system.
+- `binary-linux-amd64` - Compile the binary for Linux amd64.
+- `binary-linux-arm64` - Compile the binary for Linux arm64.
+- `test` - Test the Go backend.
+- `vet` - Vet the Go backend.
+- `test-race` - Test the Go backend with the race detector enabled.
+- `dev` - Start the Docker-based development server.
+- `prod` - Start the Docker-based production deployment (used for testing pre-releases).
+- `sql` - Generate the SQLC repositories.
+- `generate` - Update Go code-gen.
+- `docker` - Build the Docker image for the current system.
+- `docker-distroless` - Build the distroless Docker image for the current system.
+- `lint-webui` - Lint the frontend with ESLint.
+- `fmt` - Format the Go code with the Go `fmt` tool.
+
+## Development lifecycle
+
+Development of Tinyauth happens inside two Docker containers. The backend is built automatically by air using a template build output for the frontend. The frontend is run with PNPM, and then backend requests are routed with the help of Vite's proxy.
+
+When developing, you should default to the `make dev` command to start everything in Docker and avoid platform-specific issues. If you need to test the CLI, use the `make binary` command.
+
+After finishing with the development, test and vet the backend with `make test` and `make vet` respectively. If you believe you need to test for race conditions, use `make test-race`. You can also test specific parts of the code using the normal `go test` command, for example to run the `TestHealthController` test, you can use `go test ./internal/controller/ -run TestHealthController -v`. Finally, format the Go code with `make fmt`.
+
+If you made any changes to the frontend, make sure to lint with  `make lint-webui`.
+
+NEVER run any destructive commands like `make clean-data` or delete any configurations without the user's approval.
+
+## Creating a pull request
+
+When committing, you MUST use the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0) standard for your commit messages. You can add a commit description if you like. You MUST also use your standard no-reply Co-Author trailer (`Co-Authored-By:`).
+
+You should work in separate branches unless it's clearly specified to work in the main branch. When working in a separate branch, follow the naming convention below:
+
+```text
+[feat/refactor/fix/tests/etc]/[small-change-description-in-kebab-case]
+```
+
+For example, if your change was to add OAuth to Tinyauth, the branch would look as follows:
+
+```text
+feat/oauth
+```
+
+Or:
+
+```text
+feat/add-oauth-support
+```
+
+Shorter branch names that still describe the general change are preferred.
+
+Finally, when creating the actual pull request and if you have access to the internet/a GitHub tool, you should look if it resolves any open issues and if it does, reference them.

Makefile

@@ -107,3 +107,11 @@ docker-distroless:
 		--build-arg=BUILD_TIMESTAMP=$(BUILD_TIMESTAMP) \
 		--build-arg=BUILD_TAGS=$(BUILD_TAGS) \
 		-f Dockerfile.distroless .
+
+# Lint the frontend
+lint-webui:
+	cd frontend && pnpm lint
+
+# Format the code
+fmt:
+	go fmt ./...

e2e/.gitignore

@@ -0,0 +1,7 @@
+# playwright files
+/node_modules/
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/
+/playwright/.auth/

e2e/conf/Caddyfile

@@ -0,0 +1,15 @@
+{
+	auto_https off
+}
+
+http://whoami.127.0.0.1.sslip.io {
+	forward_auth tinyauth:3000 {
+		uri /api/auth/caddy
+		copy_headers Remote-User Remote-Name Remote-Email Remote-Groups
+	}
+	reverse_proxy whoami:80
+}
+
+http://tinyauth.127.0.0.1.sslip.io {
+	reverse_proxy tinyauth:3000
+}

e2e/config.e2e.yaml

@@ -0,0 +1,22 @@
+appUrl: http://tinyauth.127.0.0.1.sslip.io
+
+log:
+  level: debug
+
+auth:
+  users:
+    # user1:password,user2:password,user3:password:token
+    - user1:$2a$10$h1laww4k5a4bJcG5KwE3nO45YKSC4mOKHxbcccgxr3Y7H9zHlQe8e
+    - user2:$2a$10$h1laww4k5a4bJcG5KwE3nO45YKSC4mOKHxbcccgxr3Y7H9zHlQe8e
+    - user3:$2a$10$h1laww4k5a4bJcG5KwE3nO45YKSC4mOKHxbcccgxr3Y7H9zHlQe8e:MVR4JQWNXYKNM6HHJEYEFP2O74QIIEJE
+  # disable rate limits for multiple workers to work
+  loginMaxRetries: 0
+
+apps:
+  whoami:
+    config:
+      domain: whoami.127.0.0.1.sslip.io
+    path:
+      allow: /foo
+    users:
+      allow: user1

e2e/docker-compose.e2e.yml

@@ -0,0 +1,24 @@
+services:
+  caddy:
+    image: caddy:2.11.4
+    pull_policy: missing
+    ports:
+      - 80:80
+    volumes:
+      - ./conf:/etc/caddy
+
+  whoami:
+    image: traefik/whoami:v1.11.0
+    pull_policy: missing
+
+  tinyauth:
+    build:
+      context: ../
+      dockerfile: Dockerfile
+      args:
+        - VERSION=e2e
+        - BUILD_TAGS=nomsgpack
+        - LDFLAGS=-s -w
+    command: ["--configfile", "/app/config.yaml"]
+    volumes:
+      - ./config.e2e.yaml:/app/config.yaml:ro

e2e/fixtures/auth.fixtures.ts

@@ -0,0 +1,47 @@
+import {expect, Page} from '@playwright/test';
+import { OTP } from 'otplib';
+
+export class LoginFixture {
+    constructor(public readonly page: Page) {}
+
+    async run(username: string, password: string) {
+        await expect(this.page.getByText('Welcome back, please login')).toBeVisible();
+        await this.page.getByLabel('Username').fill(username);
+        await this.page.getByLabel('Password').fill(password);
+        await this.page.getByRole('button', { name: 'Login' }).click();
+    }
+
+    async expectSuccess(username: string) {
+        await expect(this.page.getByText(`You are currently logged in as ${username}.`)).toBeVisible()
+    }
+}
+
+export class LogoutFixture {
+    constructor(public readonly page: Page) {}
+
+    async run() {
+        await expect(this.page.getByText('Click the button below to logout.')).toBeVisible();
+        await this.page.getByRole('button', { name: 'Logout' }).click();
+    }
+
+    async expectSuccess() {
+        await expect(this.page.getByText('Welcome back, please login')).toBeVisible();
+    }
+}
+
+export class TOTPFixture {
+    constructor(public readonly page: Page) {}
+
+    async run(secret: string) {
+        await expect(this.page.getByText('Enter your TOTP code')).toBeVisible();
+        const otp = new OTP();
+        const token = await otp.generate({ secret });
+        await this.page.getByPlaceholder('XXXXXX').fill(token);
+        // we shouldn't need to click continue, it will auto submit
+        // await this.page.getByRole('button', { name: 'Continue' }).click();
+    }
+
+    async expectSuccess(username: string) {
+        await expect(this.page.getByText(`You are currently logged in as ${username}.`)).toBeVisible()
+    }
+}

e2e/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "e2e",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "down": "docker compose -f docker-compose.e2e.yml down",
+    "up": "docker compose -f docker-compose.e2e.yml up --build --force-recreate --remove-orphans",
+    "test": "playwright test",
+    "report": "playwright show-report"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": "^11.1.2",
+      "onFail": "download"
+    }
+  },
+  "type": "module",
+  "devDependencies": {
+    "@playwright/test": "^1.61.1",
+    "@types/node": "^26.1.1"
+  },
+  "dependencies": {
+    "otplib": "^13.4.1"
+  }
+}

e2e/playwright.config.ts

@@ -0,0 +1,49 @@
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './specs',
+  fullyParallel: true,
+  forbidOnly: false,
+  retries: 0,
+  workers: 4,
+  reporter: 'html',
+  use: {
+    trace: 'on-first-retry',
+    video: 'on',
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
+    {
+      name: 'Mobile Chrome',
+      use: { ...devices['Pixel 5'] },
+    },
+    {
+      name: 'Mobile Safari',
+      use: { ...devices['iPhone 12'] },
+    },
+  ],
+  webServer: {
+    command: 'pnpm run up',
+    url: 'http://tinyauth.127.0.0.1.sslip.io/api/healthz',
+    reuseExistingServer: true,
+    timeout: 5 * 60 * 1000,
+    gracefulShutdown: {
+      signal: 'SIGINT',
+      timeout: 1000,
+    },
+    stderr: 'pipe',
+    stdout: 'pipe',
+  },
+});

e2e/pnpm-lock.yaml

@@ -0,0 +1,338 @@
+---
+lockfileVersion: '9.0'
+
+importers:
+
+  .:
+    configDependencies: {}
+    packageManagerDependencies:
+      '@pnpm/exe':
+        specifier: ^11.1.2
+        version: 11.13.1
+      pnpm:
+        specifier: ^11.1.2
+        version: 11.13.1
+
+packages:
+
+  '@pnpm/exe@11.13.1':
+    resolution: {integrity: sha512-P4euEK6lOFnd5oTHEc5M/HhvyF4XUhTnVsklEcM6rmY0QJxPD6xbT+u1+gskEIBp4nSRorz20IJQtAU1Nerggg==}
+    hasBin: true
+
+  '@pnpm/linux-arm64@11.13.1':
+    resolution: {integrity: sha512-wB8zloqrYrudPyuA5qbuTCnJGe4eETPwqOjoPjoyyyvA4zFI5XfLpxgqOOcaY5UJBoqzckcGpRVDwhSRfsQ/6A==}
+    cpu: [arm64]
+    os: [linux]
+
+  '@pnpm/linux-x64@11.13.1':
+    resolution: {integrity: sha512-A+wnEvzfWEvanXiwww3tnOPmtjPSrrf5tOP6vk8+K0BRFEe/Df0oPytm2nWgGcn5iwPnqtr1Btkof913McnSPA==}
+    cpu: [x64]
+    os: [linux]
+
+  '@pnpm/linuxstatic-arm64@11.13.1':
+    resolution: {integrity: sha512-k4t65VeqRX4COMFe45TF58CVmCpmAsKZShaR1HobmUeleo98mWTctggKolrA2MHcVUeSS+12yB5Urb3uDazhmw==}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@pnpm/linuxstatic-x64@11.13.1':
+    resolution: {integrity: sha512-A65GqPzwCl0bAMk3kRWfbjSRBm5RRaqR2oMxV/9AYZrwO0X9yEfngbLBISCPHjt6/Qe4nH7DFemyhy6yODYwEw==}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@pnpm/macos-arm64@11.13.1':
+    resolution: {integrity: sha512-MJvOtyGOWSfBoqdVEfAH8ljmHs13mt82k/UxN4f+q7koDxJRR2n4Nie6Og6RwbnbaubCz0Fh2bTeL1+MxDSFpA==}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@pnpm/win-arm64@11.13.1':
+    resolution: {integrity: sha512-kl/g1cCKOJPe4HntspyrAJW0LRco0UHnVfxHSspezo4Zj4AanJAZ8WzLqfa6/w3lBSKHTEN4x0pb3m4J7B7Vpw==}
+    cpu: [arm64]
+    os: [win32]
+
+  '@pnpm/win-x64@11.13.1':
+    resolution: {integrity: sha512-Bcb14NeBlbHS2Gq1qr8VnCiAz5eC1lYzXOls7zH0bnV0Taaj4/xyfm0HVO4dn9R2TQtVtz1qnBZHHL9PDFumqQ==}
+    cpu: [x64]
+    os: [win32]
+
+  '@reflink/reflink-darwin-arm64@0.1.19':
+    resolution: {integrity: sha512-ruy44Lpepdk1FqDz38vExBY/PVUsjxZA+chd9wozjUH9JjuDT/HEaQYA6wYN9mf041l0yLVar6BCZuWABJvHSA==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@reflink/reflink-darwin-x64@0.1.19':
+    resolution: {integrity: sha512-By85MSWrMZa+c26TcnAy8SDk0sTUkYlNnwknSchkhHpGXOtjNDUOxJE9oByBnGbeuIE1PiQsxDG3Ud+IVV9yuA==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@reflink/reflink-linux-arm64-gnu@0.1.19':
+    resolution: {integrity: sha512-7P+er8+rP9iNeN+bfmccM4hTAaLP6PQJPKWSA4iSk2bNvo6KU6RyPgYeHxXmzNKzPVRcypZQTpFgstHam6maVg==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@reflink/reflink-linux-arm64-musl@0.1.19':
+    resolution: {integrity: sha512-37iO/Dp6m5DDaC2sf3zPtx/hl9FV3Xze4xoYidrxxS9bgP3S8ALroxRK6xBG/1TtfXKTvolvp+IjrUU6ujIGmA==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@reflink/reflink-linux-x64-gnu@0.1.19':
+    resolution: {integrity: sha512-jbI8jvuYCaA3MVUdu8vLoLAFqC+iNMpiSuLbxlAgg7x3K5bsS8nOpTRnkLF7vISJ+rVR8W+7ThXlXlUQ93ulkw==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@reflink/reflink-linux-x64-musl@0.1.19':
+    resolution: {integrity: sha512-e9FBWDe+lv7QKAwtKOt6A2W/fyy/aEEfr0g6j/hWzvQcrzHCsz07BNQYlNOjTfeytrtLU7k449H1PI95jA4OjQ==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@reflink/reflink-win32-arm64-msvc@0.1.19':
+    resolution: {integrity: sha512-09PxnVIQcd+UOn4WAW73WU6PXL7DwGS6wPlkMhMg2zlHHG65F3vHepOw06HFCq+N42qkaNAc8AKIabWvtk6cIQ==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@reflink/reflink-win32-x64-msvc@0.1.19':
+    resolution: {integrity: sha512-E//yT4ni2SyhwP8JRjVGWr3cbnhWDiPLgnQ66qqaanjjnMiu3O/2tjCPQXlcGc/DEYofpDc9fvhv6tALQsMV9w==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [win32]
+
+  '@reflink/reflink@0.1.19':
+    resolution: {integrity: sha512-DmCG8GzysnCZ15bres3N5AHCmwBwYgp0As6xjhQ47rAUTUXxJiK+lLUxaGsX3hd/30qUpVElh05PbGuxRPgJwA==}
+    engines: {node: '>= 10'}
+
+  detect-libc@2.1.2:
+    resolution: {integrity: sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==}
+    engines: {node: '>=8'}
+
+  pnpm@11.13.1:
+    resolution: {integrity: sha512-svx2g7imUlQU59E+G6KMqt3elr9m7FQL+ut+cCuB8+C+TR8pXt9/n+A5Z0Co3ORQnFgt33mJH0VD/qMtN2RfJQ==}
+    engines: {node: '>=22.13'}
+    hasBin: true
+
+snapshots:
+
+  '@pnpm/exe@11.13.1':
+    dependencies:
+      '@reflink/reflink': 0.1.19
+      detect-libc: 2.1.2
+    optionalDependencies:
+      '@pnpm/linux-arm64': 11.13.1
+      '@pnpm/linux-x64': 11.13.1
+      '@pnpm/linuxstatic-arm64': 11.13.1
+      '@pnpm/linuxstatic-x64': 11.13.1
+      '@pnpm/macos-arm64': 11.13.1
+      '@pnpm/win-arm64': 11.13.1
+      '@pnpm/win-x64': 11.13.1
+
+  '@pnpm/linux-arm64@11.13.1':
+    optional: true
+
+  '@pnpm/linux-x64@11.13.1':
+    optional: true
+
+  '@pnpm/linuxstatic-arm64@11.13.1':
+    optional: true
+
+  '@pnpm/linuxstatic-x64@11.13.1':
+    optional: true
+
+  '@pnpm/macos-arm64@11.13.1':
+    optional: true
+
+  '@pnpm/win-arm64@11.13.1':
+    optional: true
+
+  '@pnpm/win-x64@11.13.1':
+    optional: true
+
+  '@reflink/reflink-darwin-arm64@0.1.19':
+    optional: true
+
+  '@reflink/reflink-darwin-x64@0.1.19':
+    optional: true
+
+  '@reflink/reflink-linux-arm64-gnu@0.1.19':
+    optional: true
+
+  '@reflink/reflink-linux-arm64-musl@0.1.19':
+    optional: true
+
+  '@reflink/reflink-linux-x64-gnu@0.1.19':
+    optional: true
+
+  '@reflink/reflink-linux-x64-musl@0.1.19':
+    optional: true
+
+  '@reflink/reflink-win32-arm64-msvc@0.1.19':
+    optional: true
+
+  '@reflink/reflink-win32-x64-msvc@0.1.19':
+    optional: true
+
+  '@reflink/reflink@0.1.19':
+    optionalDependencies:
+      '@reflink/reflink-darwin-arm64': 0.1.19
+      '@reflink/reflink-darwin-x64': 0.1.19
+      '@reflink/reflink-linux-arm64-gnu': 0.1.19
+      '@reflink/reflink-linux-arm64-musl': 0.1.19
+      '@reflink/reflink-linux-x64-gnu': 0.1.19
+      '@reflink/reflink-linux-x64-musl': 0.1.19
+      '@reflink/reflink-win32-arm64-msvc': 0.1.19
+      '@reflink/reflink-win32-x64-msvc': 0.1.19
+
+  detect-libc@2.1.2: {}
+
+  pnpm@11.13.1: {}
+
+---
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    dependencies:
+      otplib:
+        specifier: ^13.4.1
+        version: 13.4.1
+    devDependencies:
+      '@playwright/test':
+        specifier: ^1.61.1
+        version: 1.61.1
+      '@types/node':
+        specifier: ^26.1.1
+        version: 26.1.1
+
+packages:
+
+  '@noble/hashes@2.2.0':
+    resolution: {integrity: sha512-IYqDGiTXab6FniAgnSdZwgWbomxpy9FtYvLKs7wCUs2a8RkITG+DFGO1DM9cr+E3/RgADRpFjrKVaJ1z6sjtEg==}
+    engines: {node: '>= 20.19.0'}
+
+  '@otplib/core@13.4.1':
+    resolution: {integrity: sha512-KIXgK1hNtWJEBMTastbe1bpmuais+3f+ATeO8TkMs2rNkfGO1FbQy8+/UWVEu3TR/iTJerU0idkPudaPmLP2BA==}
+
+  '@otplib/hotp@13.4.1':
+    resolution: {integrity: sha512-g9q04SwpG5ZtMnVkUcgcoAlwCH4YLROZN1qhyBwgkBzqYYVSYhpP6gSGaxGHwePLt1c+e6NqDlgIZN+e1/XPuA==}
+
+  '@otplib/plugin-base32-scure@13.4.1':
+    resolution: {integrity: sha512-Fs/r5qisC05SRhT6xWXaypB6PVC0vgWf6zztmi0J5RnQ09OJiPDWCJFH6cDm6ANsrdvB9di7X+Jb7L13BoEbUA==}
+
+  '@otplib/plugin-crypto-noble@13.4.1':
+    resolution: {integrity: sha512-PJfVW8/1hdS6CfxLheKPZSLTwDq4TijZbN4yRjxlv0ODdzmxpM+wGwWr1JXMdy0xJPxLziydQD5gdVqrR4/gAg==}
+
+  '@otplib/totp@13.4.1':
+    resolution: {integrity: sha512-QOkBVPrf6AM4qZaReZPSk9/I8ATVdZpIISJz115MqeVtcrbcr5llPZ0J7804tpnjnp1vCRkI5Qjd47HhgVteBQ==}
+
+  '@otplib/uri@13.4.1':
+    resolution: {integrity: sha512-xaIm7bvICMhoB2rZIR5luiaMdssWR5nY5nXnR1fdezUgZuEO58D6zrGzLp7pQuBmlpmL0HagnscDQFoskp9yiA==}
+
+  '@playwright/test@1.61.1':
+    resolution: {integrity: sha512-8nKv6+0RJSL9FE4jYOEGXnPeM/Hg12qZpmqzZjRh3qM0Y7c3z1mrOTfFLids72RDQYVh9WpLEfR5WdpNX4fkig==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  '@scure/base@2.2.0':
+    resolution: {integrity: sha512-b8XEupJibegiXV+tDUseI8oLQc8ei3d/4Jkb2RpbHh3MfE054ov3uIz2dhFkB3FI8iwYkEh0gGCApkrYggkPNg==}
+
+  '@types/node@26.1.1':
+    resolution: {integrity: sha512-nxAkRSVkN1Y0JC1W8ky/fTfkGsMmcrRsbx+3XoZE+rMOX71kLYTV7fLXpqud1GpbpP5TuffXFqfX7fH2GgZREw==}
+
+  fsevents@2.3.2:
+    resolution: {integrity: sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
+  otplib@13.4.1:
+    resolution: {integrity: sha512-o5CxfDw6bh7hoDv0NUUIcc0RqzJ9ipfUrzeKheKJ+vs4rXZnDlA9n4a/7R1cDjpmLjKLix4BgNVRmoDkm5rLSQ==}
+
+  playwright-core@1.61.1:
+    resolution: {integrity: sha512-h7Qlt6m4REp25qvIdvbDtVmD4LqVXfpRxhORv9L0jzETM05p4fuPJ3dKyuSXQxDSbXnmS79HAgi9589lGSpLkg==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  playwright@1.61.1:
+    resolution: {integrity: sha512-DWnY5o3YbLWK4GovuAVwpqL+1VwGNdUGrRr++8j8PtQQzvAVZUIMjKQ90fY689sEJZJBbZVw1rXaOKSTitkzPQ==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  undici-types@8.3.0:
+    resolution: {integrity: sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ==}
+
+snapshots:
+
+  '@noble/hashes@2.2.0': {}
+
+  '@otplib/core@13.4.1': {}
+
+  '@otplib/hotp@13.4.1':
+    dependencies:
+      '@otplib/core': 13.4.1
+      '@otplib/uri': 13.4.1
+
+  '@otplib/plugin-base32-scure@13.4.1':
+    dependencies:
+      '@otplib/core': 13.4.1
+      '@scure/base': 2.2.0
+
+  '@otplib/plugin-crypto-noble@13.4.1':
+    dependencies:
+      '@noble/hashes': 2.2.0
+      '@otplib/core': 13.4.1
+
+  '@otplib/totp@13.4.1':
+    dependencies:
+      '@otplib/core': 13.4.1
+      '@otplib/hotp': 13.4.1
+      '@otplib/uri': 13.4.1
+
+  '@otplib/uri@13.4.1':
+    dependencies:
+      '@otplib/core': 13.4.1
+
+  '@playwright/test@1.61.1':
+    dependencies:
+      playwright: 1.61.1
+
+  '@scure/base@2.2.0': {}
+
+  '@types/node@26.1.1':
+    dependencies:
+      undici-types: 8.3.0
+
+  fsevents@2.3.2:
+    optional: true
+
+  otplib@13.4.1:
+    dependencies:
+      '@otplib/core': 13.4.1
+      '@otplib/hotp': 13.4.1
+      '@otplib/plugin-base32-scure': 13.4.1
+      '@otplib/plugin-crypto-noble': 13.4.1
+      '@otplib/totp': 13.4.1
+      '@otplib/uri': 13.4.1
+
+  playwright-core@1.61.1: {}
+
+  playwright@1.61.1:
+    dependencies:
+      playwright-core: 1.61.1
+    optionalDependencies:
+      fsevents: 2.3.2
+
+  undici-types@8.3.0: {}

e2e/specs/apps.spec.ts

@@ -0,0 +1,28 @@
+import {expect, test} from '@playwright/test';
+import {LoginFixture} from "../fixtures/auth.fixtures";
+
+test('should be able to login to app with forward-auth', async ({ page }) => {
+    const loginFixture = new LoginFixture(page);
+    await page.goto('http://whoami.127.0.0.1.sslip.io');
+    // redirect to tinyauth
+    await expect(page.getByText('Welcome back, please login')).toBeVisible()
+    await loginFixture.run('user1', 'password')
+    // redirect to app
+    await expect(page.getByText('whoami.127.0.0.1.sslip.io')).toBeVisible()
+});
+
+test('non authorized user should not be able to access app', async ({ page }) => {
+    const loginFixture = new LoginFixture(page);
+    await page.goto('http://whoami.127.0.0.1.sslip.io');
+    // redirect to tinyauth
+    await expect(page.getByText('Welcome back, please login')).toBeVisible()
+    // user2 is not authorized to access app
+    await loginFixture.run('user2', 'password')
+    // redirect to app
+    await expect(page.getByText('The user with username user2 is not authorized to access the resource whoami.')).toBeVisible()
+})
+
+test('allowed path should skip authentication', async ({ page }) => {
+    await page.goto('http://whoami.127.0.0.1.sslip.io/foo');
+    await expect(page.getByText('whoami.127.0.0.1.sslip.io')).toBeVisible()
+})

e2e/specs/auth.spec.ts

@@ -0,0 +1,48 @@
+import { test, expect } from '@playwright/test';
+import {LoginFixture, LogoutFixture, TOTPFixture} from "../fixtures/auth.fixtures";
+
+test('should be able to login', async ({ page }) => {
+    const loginFixture = new LoginFixture(page);
+    await page.goto('http://tinyauth.127.0.0.1.sslip.io');
+    await loginFixture.run('user1', 'password')
+    await loginFixture.expectSuccess('user1')
+});
+
+test('should fail to login with wrong credentials', async ({ page }) => {
+    const loginFixture = new LoginFixture(page);
+    await page.goto('http://tinyauth.127.0.0.1.sslip.io');
+    await loginFixture.run('user27267', 'password')
+    const toast = page.locator('[data-sonner-toast]').first();
+    await expect(toast).toBeVisible();
+    await expect(toast).toContainText('Failed to log in');
+});
+
+
+test('should be able to logout', async ({ page }) => {
+    const loginFixture = new LoginFixture(page);
+    await page.goto('http://tinyauth.127.0.0.1.sslip.io');
+    await loginFixture.run('user1', 'password')
+    await loginFixture.expectSuccess('user1')
+    const logoutFixture = new LogoutFixture(page);
+    await logoutFixture.run()
+})
+
+test('should be able to login with totp', async ({ page }) => {
+    const loginFixture = new LoginFixture(page);
+    const totpFixture = new TOTPFixture(page);
+    await page.goto('http://tinyauth.127.0.0.1.sslip.io');
+    await loginFixture.run('user3', 'password')
+    await totpFixture.run('MVR4JQWNXYKNM6HHJEYEFP2O74QIIEJE')
+    await loginFixture.expectSuccess('user3');
+});
+
+test('should fail to login with wrong totp', async ({ page }) => {
+    const loginFixture = new LoginFixture(page);
+    const totpFixture = new TOTPFixture(page);
+    await page.goto('http://tinyauth.127.0.0.1.sslip.io');
+    await loginFixture.run('user3', 'password')
+    await totpFixture.run('VZVMOMQCBN24DJ5VRFAL5TJAZGBHXMN3')
+    const toast = page.locator('[data-sonner-toast]').first();
+    await expect(toast).toBeVisible();
+    await expect(toast).toContainText('Failed to verify code');
+});

internal/controller/proxy_controller.go

@@ -47,6 +47,7 @@ type ProxyContext struct {
 	Host      string
 	Proto     string
 	Path      string
+	PathRaw   string
 	Method    string
 	Type      AuthModuleType
 	IsBrowser bool
@@ -281,7 +282,7 @@ func (controller *ProxyController) proxyHandler(c *gin.Context) {
 	}
 
 	queries, err := query.Values(RedirectQuery{
-		RedirectURI: fmt.Sprintf("%s://%s%s", proxyCtx.Proto, proxyCtx.Host, proxyCtx.Path),
+		RedirectURI: fmt.Sprintf("%s://%s%s", proxyCtx.Proto, proxyCtx.Host, proxyCtx.PathRaw),
 		LoginFor:    FrontendLoginForApp,
 	})
 
@@ -402,11 +403,11 @@ func (controller *ProxyController) getForwardAuthContext(c *gin.Context) (ProxyC
 	method := c.Request.Method
 
 	return ProxyContext{
-		Host:   host,
-		Proto:  proto,
-		Path:   uri,
-		Method: method,
-		Type:   ForwardAuth,
+		Host:    host,
+		Proto:   proto,
+		PathRaw: uri,
+		Method:  method,
+		Type:    ForwardAuth,
 	}, nil
 }
 
@@ -435,15 +436,14 @@ func (controller *ProxyController) getAuthRequestContext(c *gin.Context) (ProxyC
 		return ProxyContext{}, errors.New("proto not found")
 	}
 
-	path := url.Path
 	method := c.Request.Method
 
 	return ProxyContext{
-		Host:   host,
-		Proto:  proto,
-		Path:   path,
-		Method: method,
-		Type:   AuthRequest,
+		Host:    host,
+		Proto:   proto,
+		PathRaw: url.RequestURI(),
+		Method:  method,
+		Type:    AuthRequest,
 	}, nil
 }
 
@@ -469,11 +469,11 @@ func (controller *ProxyController) getExtAuthzContext(c *gin.Context) (ProxyCont
 	method := c.Request.Method
 
 	return ProxyContext{
-		Host:   host,
-		Proto:  proto,
-		Path:   path,
-		Method: method,
-		Type:   ExtAuthz,
+		Host:    host,
+		Proto:   proto,
+		PathRaw: path,
+		Method:  method,
+		Type:    ExtAuthz,
 	}, nil
 }
 
@@ -552,8 +552,8 @@ func (controller *ProxyController) getProxyContext(c *gin.Context) (ProxyContext
 		return ProxyContext{}, err
 	}
 
-	// remove any query params from the request path
-	upath, err := url.Parse(ctx.Path)
+	// Parse the raw path to populate the cleaned path used for ACLs
+	upath, err := url.Parse(ctx.PathRaw)
 
 	if err != nil {
 		return ProxyContext{}, fmt.Errorf("failed to parse request path: %v", err)

internal/controller/proxy_controller_test.go

@@ -95,6 +95,38 @@ func TestProxyController(t *testing.T) {
 				assert.Contains(t, location, "https://tinyauth.example.com/login")
 			},
 		},
+		{
+			description: "Forward auth login redirect should preserve query parameters",
+			middlewares: []gin.HandlerFunc{},
+			run: func(t *testing.T, router *gin.Engine, recorder *httptest.ResponseRecorder) {
+				req := httptest.NewRequest("GET", "/api/auth/traefik", nil)
+				req.Header.Set("x-forwarded-host", "test.example.com")
+				req.Header.Set("x-forwarded-proto", "https")
+				req.Header.Set("x-forwarded-uri", "/search?foo=bar")
+				req.Header.Set("user-agent", browserUserAgent)
+				router.ServeHTTP(recorder, req)
+
+				assert.Equal(t, http.StatusFound, recorder.Code)
+				location := recorder.Header().Get("Location")
+				assert.Contains(t, location, url.QueryEscape("https://test.example.com/search?foo=bar"))
+				assert.Contains(t, location, "login_for=app")
+				assert.Contains(t, location, "https://tinyauth.example.com/login")
+			},
+		},
+		{
+			description: "Auth request (nginx) login redirect should preserve query parameters",
+			middlewares: []gin.HandlerFunc{},
+			run: func(t *testing.T, router *gin.Engine, recorder *httptest.ResponseRecorder) {
+				req := httptest.NewRequest("GET", "/api/auth/nginx", nil)
+				req.Header.Set("x-original-url", "https://test.example.com/search?foo=bar")
+				router.ServeHTTP(recorder, req)
+				assert.Equal(t, http.StatusUnauthorized, recorder.Code)
+				location := recorder.Header().Get("x-tinyauth-location")
+				assert.Contains(t, location, url.QueryEscape("https://test.example.com/search?foo=bar"))
+				assert.Contains(t, location, "login_for=app")
+				assert.Contains(t, location, "https://tinyauth.example.com/login")
+			},
+		},
 		{
 			description: "Auth request (nginx) should be detected and used",
 			middlewares: []gin.HandlerFunc{},
@@ -126,6 +158,22 @@ func TestProxyController(t *testing.T) {
 				assert.Contains(t, location, "https://tinyauth.example.com/login")
 			},
 		},
+		{
+			description: "Ext authz (envoy) login redirect should preserve query parameters",
+			middlewares: []gin.HandlerFunc{},
+			run: func(t *testing.T, router *gin.Engine, recorder *httptest.ResponseRecorder) {
+				req := httptest.NewRequest("HEAD", "/api/auth/envoy?path=%2Fhello%3Ffoo%3Dbar", nil)
+				req.Host = "test.example.com"
+				req.Header.Set("x-forwarded-proto", "https")
+				req.Header.Set("user-agent", browserUserAgent)
+				router.ServeHTTP(recorder, req)
+				assert.Equal(t, http.StatusFound, recorder.Code)
+				location := recorder.Header().Get("Location")
+				assert.Contains(t, location, url.QueryEscape("https://test.example.com/hello?foo=bar"))
+				assert.Contains(t, location, "login_for=app")
+				assert.Contains(t, location, "https://tinyauth.example.com/login")
+			},
+		},
 		{
 			description: "Forward auth with caddy should be detected and used",
 			middlewares: []gin.HandlerFunc{},