preauth/docs/v1.1-plan.md

# v1.1 Plan — Public Rate-Limited Access

## Goal

Allow preauth to provide rate-limited unauthenticated access to select
public paths. Authenticated users bypass the public rate limiter entirely.
Non-public paths continue to trigger the existing auth flow.

**Practical example:** Allow anyone to visit
`https://code.devgnome.com/public/*` in Gitea, but limit them to 100
requests/minute and 500 requests/hour per IP.

---

## How It Works

When a request arrives and the user is **not authenticated** (no valid
cookie or IP session), the new `PublicAccessListener` checks whether the
request path matches any configured public path pattern. If it does:

1. The public rate limiter is consulted (separate from the login limiter).
2. If within limits → `200 OK` (no `Remote-User` header). Caddy proxies
   to the backend.
3. If over limits → `429 Too Many Requests` with a `Retry-After` header.

If the path does **not** match any public pattern, the request falls
through to the existing auth flow (RejectListener → LoginListener →
InterceptListener → login page or redirect).

**Authenticated users** never reach the `PublicAccessListener` because
`AcceptListener` (priority 99) or `AllowListener` (priority 88) will have
already set a `200` response before `PublicAccessListener` runs.

### Listener Priority Chain (updated)

```
Priority  Listener               Action
────────  ─────────────────      ──────────────────────────────────────
99        AcceptListener          Valid cookie → 200 OK
88        AllowListener           Valid IP session → 200 OK
84        PublicAccessListener    Public path + rate limit check → 200 or 429
77        RejectListener          Login rate-limit gate → 418/429
66        LoginListener           Login attempt handling
55        InterceptListener       Fallback → redirect or login page
```

`PublicAccessListener` runs at priority 84 — after auth checks (so
authenticated users bypass it) but before `RejectListener` (so public
access is not subject to the login rate limiter).

---

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `PUBLIC_PATHS` | `''` (disabled) | Comma-separated path patterns. Wildcard `*` supported. |
| `PUBLIC_BURST_COUNT` | `100` | Max requests per burst window per IP |
| `PUBLIC_BURST_TIME` | `60` | Burst window in seconds |
| `PUBLIC_UPPER_COUNT` | `500` | Max requests per sustained window per IP |
| `PUBLIC_UPPER_TIME` | `3600` | Sustained window in seconds (1 hour) |

**When `PUBLIC_PATHS` is empty (default), the feature is completely
disabled and has zero effect on existing behavior.**

### Path Pattern Syntax

- Patterns are matched against the request **path** only (query string
  is ignored).
- Patterns must start with `/`.
- `*` matches any sequence of characters within a single path segment
  (not crossing `/`).
- `**` matches any sequence of characters including `/` (crosses path
  segments).
- No other regex or special characters are supported — patterns are
  literal strings with `*` wildcards.

**Examples:**

| Pattern | Matches | Does NOT match |
|---------|---------|----------------|
| `/public` | `/public` | `/public/`, `/public/xyz` |
| `/public/*` | `/public/anything`, `/public/xyz` | `/public`, `/public/a/b` |
| `/public/**` | `/public/anything`, `/public/a/b/c` | `/public` |
| `/public` | `/public` | `/public/xyz` |
| `/api/*/status` | `/api/v1/status`, `/api/v2/status` | `/api/v1/v2/status` |

### Domain-Scoped Paths (when using auth subdomain)

When `SUBDOMAIN_REDIRECT=true` and `AUTH_SUBDOMAIN` is set, the user may
want public paths on specific subdomains only. In this case, `PUBLIC_PATHS`
can optionally include a domain prefix:

```
PUBLIC_PATHS='code.devgnome.com/public/**,auth.devgnome.com/health'
```

When no domain prefix is given, the path matches on **any** host. When a
domain prefix is given, it only matches on that specific host.

When **not** using an auth subdomain (the common case), paths without a
domain prefix match on all hosts. Domain-prefixed entries can still be
used to restrict to specific hosts.

### Rate Limiter

A new `public_limiter` compound rate limiter is added to
`rate_limiter.yaml`, following the same pattern as the existing
`login_limiter`. It uses a `publicRateLimitCache` pool (APCu in
production, array adapter in tests).

---

## New Files

| File | Purpose |
|------|---------|
| `src/Service/PublicPathMatcher.php` | Service that parses `PUBLIC_PATHS` and matches request paths against patterns |
| `src/Service/PublicPathMatcherInterface.php` | Interface for testability |
| `src/Listener/PublicAccessListener.php` | Listener that checks public paths and applies rate limiting |

## Modified Files

| File | Changes |
|------|---------|
| `config/services.yaml` | Add `PUBLIC_PATHS` and related env vars + parameters |
| `config/packages/rate_limiter.yaml` | Add `public_burst`, `public_upper`, `public_limiter` |
| `config/packages/cache.yaml` | Add `publicRateLimitCache` pool |
| `config/packages/test/cache.yaml` | Add `publicRateLimitCache` pool (array adapter) |
| `src/ConfigBag.php` | Add `publicPaths()` method returning parsed path patterns |
| `tests/TestKernel.php` | Add `publicRateLimitCache` to reset exclusion list |
| `tests/Support/ListenerTestHelper.php` | Add helper for public rate limiter factory |
| `docs/example.env` | Document new env vars |
| `.env.test` | Add test defaults for public paths vars |
| `.env` | Add dev defaults for public paths vars |
| `docs/Caddyfile` | Add example of public + protected service config |
| `CHANGELOG.md` | Add v1.1 section |
| `ROADMAP.md` | Mark Phase 1 as in-progress / completed |
| `readme.md` | Document public access feature |

## New Test Files

| File | Coverage |
|------|----------|
| `tests/Unit/Service/PublicPathMatcherTest.php` | Pattern parsing, matching, wildcards, domain scoping |
| `tests/Unit/Listener/PublicAccessListenerTest.php` | Listener logic: public path match → 200, non-public → pass through, rate limited → 429, authenticated → not reached |
| `tests/Functional/PublicAccessFlowTest.php` | End-to-end: public path accessible, rate limit enforced, non-public path shows login, authenticated user bypasses public rate limit |

---

## Implementation Order

1. **`PublicPathMatcher`** — Pure path matching logic, no dependencies.
   Parse the `PUBLIC_PATHS` string into pattern entries (each with
   optional host + path pattern). Convert `*`/`**` wildcards to regex.
   Match a given (host, path) against all patterns.

2. **Config** — Add env vars to `services.yaml`, add rate limiter to
   `rate_limiter.yaml`, add cache pool to `cache.yaml` + test cache.

3. **`ConfigBag`** — Add `publicPaths()` returning the raw string (the
   `PublicPathMatcher` does the parsing). Or add the `PublicPathMatcher`
   as a service that receives the raw string via autowiring.

4. **`PublicAccessListener`** — Inject `PublicPathMatcherInterface`,
   `RateLimiterFactoryInterface` (target `public_limiter`), and
   `ConfigBag`. On `RequestEvent`:
   - If no public paths configured → return immediately.
   - If request already has a response → return (auth listeners ran first).
   - Check if (host, path) matches any public pattern.
   - If no match → return (fall through to auth flow).
   - If match → consume(1) from public rate limiter.
   - If over limit → set 429 response with `Retry-After`.
   - If within limit → set 200 response (plain text, no `Remote-User`).

5. **Tests** — Unit tests for `PublicPathMatcher` and
   `PublicAccessListener`, functional tests for the full flow.

6. **Documentation** — Update all docs.

7. **Lint + Test** — Run php-cs-fixer + phpunit, fix any issues.

8. **Commit + Push + PR.**

---

## Key Design Decisions

### Why priority 84?

- Must be **after** `AcceptListener` (99) and `AllowListener` (88) so
  authenticated users never hit the public rate limiter.
- Must be **before** `RejectListener` (77) so public access is not
  blocked by the login attempt rate limiter.
- Must be **before** `LoginListener` (66) so login attempts on public
  paths are still processed (though this is an edge case — a login
  attempt on a public path would set a response in `PublicAccessListener`
  before `LoginListener` runs, which is correct: you don't need to login
  to access a public path).

  **Wait — actually this is a problem.** If someone sends an `X-Preauth`
  header on a public path, `PublicAccessListener` would return 200 before
  `LoginListener` can process the login. But that's actually fine — if the
  path is public, they don't need to log in. If they want to authenticate,
  they can visit a non-public path.

  **Revised approach:** `PublicAccessListener` should only return 200 for
  **GET/HEAD** requests to public paths, or all methods? For a gate like
  this, all methods should be allowed on public paths — the backend
  service (e.g., Gitea) handles its own authorization for write
  operations.

### Why a separate rate limiter?

The existing `login_limiter` rate limits **login attempts** (failures).
The public rate limiter rate limits **all requests** to public paths.
They serve different purposes and need independent counters. Using the
same limiter would mean public traffic could exhaust the login attempt
budget, or vice versa.

### Why `Retry-After` header?

It's a standard HTTP header (RFC 7231) that tells clients how long to
wait before retrying. Legitimate clients (browsers, API consumers) and
crawlers respect it.

### Why no `Remote-User` header on public responses?

The `Remote-User` header tells the backend who the authenticated user
is. For public access, there is no authenticated user. Sending
`Remote-User: public` or similar could confuse the backend. The backend
should treat requests without `Remote-User` as anonymous.

### Path matching: query strings

Query strings are **ignored** for path matching. `/public?foo=bar`
matches the pattern `/public`. This is implemented by using
`$request->getPathInfo()` which returns the path without query string.

---

## Edge Cases

1. **Empty `PUBLIC_PATHS`** → Feature disabled, zero impact on existing
   behavior. All tests pass unchanged.

2. **Authenticated user visits a public path** → `AcceptListener` or
   `AllowListener` returns 200 before `PublicAccessListener` runs. The
   public rate limiter is never consulted.

3. **Public path rate limit exceeded** → 429 with `Retry-After` header.
   The response uses the error template (same as login rate limit) but
   always with 429 status (never teapot — teapot is for login failures).

4. **Non-public path on a host that has some public paths** → Falls
   through to the normal auth flow. Login page or redirect.

5. **`PUBLIC_PATHS` with whitespace** → Trimmed during parsing.
   `PUBLIC_PATHS='/public, /api'` is equivalent to `/public,/api`.

6. **Invalid patterns** (not starting with `/`) → Silently ignored
   during parsing. Logged at debug level.

7. **Login attempt on a public path** → `PublicAccessListener` returns
   200 before `LoginListener` runs. This is correct behavior — if the
   path is public, no login is needed.

8. **Subdomain redirect mode + public paths** → If using an auth
   subdomain, requests to the auth subdomain itself should never be
   treated as public. The `PublicAccessListener` should skip requests
   where `host === authSubdomain`.

---

## Test Strategy

### Unit Tests — `PublicPathMatcherTest`

- Empty string → no patterns → matches nothing
- Single path `/public` → matches exact, not `/public/`
- Wildcard `/public/*` → matches `/public/x`, not `/public`, not `/public/a/b`
- Double wildcard `/public/**` → matches `/public/a/b/c`
- Multiple patterns comma-separated
- Domain-prefixed pattern `host.example.com/public/**`
- Path without domain prefix matches any host
- Whitespace trimming
- Invalid patterns (no leading `/`) ignored
- Case sensitivity (paths are case-sensitive, hosts are case-insensitive)

### Unit Tests — `PublicAccessListenerTest`

- No public paths configured → returns without setting response
- Non-public path → returns without setting response
- Public path, within rate limit → sets 200 response
- Public path, rate limit exceeded → sets 429 response with Retry-After
- Public path, response already set by earlier listener → returns
- Auth subdomain request → skipped (even if path matches)
- Uses `ListenerTestHelper` for mock rate limiters and collaborators

### Functional Tests — `PublicAccessFlowTest`

- Public path accessible without authentication → 200
- Non-public path without auth → 401 (login page)
- Rate limit enforcement: multiple requests exceed burst → 429
- Authenticated user visits public path → 200 with Remote-User (bypasses public limiter)
- 429 response includes Retry-After header
- Query string ignored for path matching
- Wildcard matching works end-to-end

---

## Documentation Updates

### README

New section: **"Public Rate-Limited Access"** under Configuration.

- Explain the feature and use case
- Document all env vars
- Show path pattern syntax with examples
- Show Caddyfile configuration for public + protected services
- Note that authenticated users bypass the public rate limiter

### CHANGELOG

New `[Unreleased]` → v1.1 section with all new features.

### ROADMAP

Mark Phase 1 items as completed.

### docs/example.env

Add all new env vars with comments.

### docs/Caddyfile

Add example showing a service with both public and protected paths.