tylerg/auth-yes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #21 from mrteye/feat/auth-api-traefik-ingress-control-task-6742583984777370201

Browse Source 
feat(tasks): create Traefik Universal Edge Ingress task file
This commit is contained in:
Tyler Gillispie 2026-08-24 14:13:08 -07:00 committed by GitHub
commit 226d04228b
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 53 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
tasks/new/2026-0824.01.jul.feat.auth-api.traefik-ingress-control-2105.md Normal file
View File

@ -0,0 +1,53 @@
# TASK METADATA
- **Target Files:** `COMPOSE_CONVENTIONS.md`, `server/main.ts`, `server/auth-session.ts`, `server/db.ts`
- **Core Objective:** Architect and formalize the Tier 1 Universal Global Edge Ingress Protection protocol for Traefik to enforce default-deny while supporting a dynamic, multi-tier bypass and guest sandbox matrix.
- **Dependencies:** Database schema update for `apps` table (`is_public`, `bypass_paths`).
- **Additional Important Notes:** Must align closely with `docs/FORWARDAUTH_REDIRECT_SPEC.md` for dual-response handling and rely entirely on Valkey L1/L2 caching to maintain sub-millisecond edge latency for dynamic routing decisions.
---
### 1. TASK METADATA
(Defined in the header block above)
### 2. Architectural Considerations & Risks
- **Risks:**
- **Recursive Deadlocks (Self-Exemption):** Applying ForwardAuth globally introduces the risk of `auth-api` protecting itself, leading to an infinite authentication loop where users cannot reach the login page to authenticate. `auth-api` must be explicitly exempted.
- **Health Probe Failures:** Traefik and orchestrator liveness/readiness probes (e.g., `/healthz`) might be blocked if they fall under the global ForwardAuth middleware, causing rolling restart failures.
- **Latency Regressions:** If `auth-api` queries PostgreSQL on every request to evaluate dynamic bypass paths (`is_public`, `bypass_paths`, or CIDRs), performance will tank. We must guarantee this data is piggybacked onto the existing Valkey app caching flow.
- **Alternatives & Architectural Decisions:**
- **Dynamic Bypass Matrix:** Evaluated inside `auth-api` with Valkey L1/L2 caching instead of dynamic Traefik HTTP providers to avoid sync overhead and polling complexity.
- **Universal Bypasses (Hybrid Approach):**
- Critical infrastructural paths (`/.well-known/acme-challenge/*`, `/healthz`) bypass ForwardAuth directly at the Traefik router level to prevent lockout during restarts.
- Semantic app paths (`/api/public/*`, `/webhooks/*`) and CIDR allowlists are evaluated within `auth-api` for centralized auditing and hot-reloading.
- **Unregistered App Handling:** Adheres to the Dual-Response protocol. Web browsers receive a `302 Redirect` to a polished Hono SSR error page (`/errors/unregistered`), while API/cURL clients receive a fast `403 Forbidden` response.
- **Guest Sandboxes:** Handled natively via a Valkey ephemeral session with an `account_status: "guest"` and `X-Forwarded-Scopes: guest,trial`. Seamless in-flight passkey promotion transitions them to full users.
### 3. Proposed Implementation
1. **Global Default-Deny Configuration:**
- Document how Traefik's `entryPoints.websecure.http.middlewares` should be updated to universally apply the `auth-forward@docker` middleware.
- Define the explicit router priority and empty middleware override required for `auth-api` and ACME challenge routers to guarantee self-exemption.
- Define the mechanism for explicit host-level application bypass where fully public applications (e.g. landing pages, sandboxes) can use specific Docker labels (like `traefik.http.routers.app.middlewares=`) to bypass ForwardAuth entirely at the edge without traversing to `auth-api`.
2. **Schema & Database Updates:**
- Add database migrations for the `apps` table:
- `is_public` (boolean, default `false`)
- `bypass_paths` (text array, default `[]`)
- `allowed_cidrs` (text array, default `[]`)
3. **Valkey Caching Upgrades (`server/auth-session.ts`):**
- Update `getAppByHost` to SELECT and cache the new `is_public`, `bypass_paths`, and `allowed_cidrs` fields within the `auth:app_by_host:<host>` Valkey payload.
4. **Dynamic Bypass & Dual-Response Execution (`server/main.ts`):**
- In `GET /api/forward-auth`:
- **Unregistered App Handling:** If `getAppByHost` returns null, evaluate the `Accept` header. Issue a `302 Redirect` to `https://auth.atyg.org/errors/unregistered?host=...` if it contains `text/html`, otherwise return `403 Forbidden`.
- **Path & CIDR Exemption Check:** Before checking for a valid session, evaluate the requested URI (`X-Forwarded-Uri`) and Client IP against the cached `bypass_paths`, `allowed_cidrs`, and `is_public` flags.
- **Immediate Allowance:** If the request matches a bypass rule or is public, immediately return `200 OK` without querying `getAuthenticatedUser()`.
5. **Ephemeral Guest Session Generation:**
- Expose a new endpoint (e.g., `/api/guests/sandbox`) that provisions a Valkey session ID without requiring PostgreSQL insertion.
- Attach `account_status: "guest"` to the Valkey payload and map the corresponding `X-Forwarded-Scopes`.
- Update the `/api/passkeys/register/verify` flow to detect `upgrade_session` and persist the guest's UUID and session context to the `users` table upon successful passkey verification.