auth-yes/docs/TIER1_INGRESS_SPEC.md

Tier 1 Universal Global Edge Ingress Protection Specification

Specification ID: RFC-SPEC-2026-INGRESS-01 Classification: Ingress Security & Traefik Routing Status: Canonical / Implemented

---

1. Executive Summary

This specification outlines the Tier 1 Ingress Control strategy using Traefik's ForwardAuth middleware combined with a dynamic Valkey-backed authorization matrix within auth-api. The system provides highly performant (microsecond latency) dynamic bypasses, strict SSR unregistered fallbacks, and router-level self-exemptions.

---

2. Traefik Entrypoint Configuration

To enforce zero-trust global edge protection, the ForwardAuth middleware is bound directly to the global HTTPS entrypoint. This ensures that every service routed through Traefik is automatically intercepted without relying on developers to attach middleware to individual container labels.

Global ForwardAuth Middleware

# infra/compose.yml snippet (Traefik labels)
services:
  traefik:
    labels:
      - "traefik.http.middlewares.auth-forward.forwardauth.address=http://auth-api:3000/api/forward-auth"
      - "traefik.http.middlewares.auth-forward.forwardauth.trustForwardHeader=true"
      - "traefik.http.middlewares.auth-forward.forwardauth.authResponseHeaders=X-Forwarded-User,X-Forwarded-User-Id,X-Forwarded-Scopes,X-Forwarded-App-Id"

---

3. Router-Level Self-Exemptions

Applying ForwardAuth globally creates an infinite redirect deadlock if auth-api intercepts requests destined for its own login mechanisms. To resolve this, explicit routes must be exempted at the Traefik router level by intentionally not attaching the auth-forward middleware or configuring a bypass.

Required Exemptions

1. Authentication API / UI (auth.atyg.org)
   • The central Identity Provider must be explicitly bypassed.
2. ACME Challenge (/.well-known/acme-challenge/*)
   • Let's Encrypt automated HTTP-01 certificate renewals must proceed unauthenticated.
3. Global Health Checks (/healthz)
   • Orchestration systems must be able to verify container readiness.

---

4. Auth-API Dynamic Bypass Rules

Instead of volatile Traefik HTTP Dynamic Providers, Auth-Yes maintains a highly-performant cache in Valkey (L1/L2) under the key auth:app_by_host:<host>. When a request arrives at /api/forward-auth, the gateway evaluates the following dynamic properties before validating sessions:

1. is_public (Boolean)
   • If true, the entire application domain bypasses session checks.
2. bypass_paths (List of Strings)
   • Fast deterministic prefix matching (/api/public/*) and exact matching (/webhook).
3. allowed_cidrs (List of Strings)
   • Fast native Deno IPv4 subnet matching to allowlist specific networks (e.g., internal CI/CD).

If any of the above rules evaluate to true, auth-api immediately returns 200 OK (with X-Forwarded-App-Id injected).

---

5. Unregistered Application Protocol

If a domain is not registered in the central apps table (and therefore not in the Valkey cache), auth-api strictly denies the request.

• Browser Access (Accept: text/html): The proxy returns an HTTP 302 Redirect to https://auth.atyg.org/errors/unregistered?host=<domain>.
• API Access (Non-HTML): The proxy returns an HTTP 403 Forbidden ({"error": "Application not registered"}).

This mechanism explicitly prevents open-redirect and infrastructure mapping attacks.