From f10784ddb656a0667ffd20f3ef52041cee1e78fe Mon Sep 17 00:00:00 2001
From: Viktor Barzin <vbarzin@gmail.com>
Date: Mon, 11 May 2026 19:25:48 +0000
Subject: [PATCH] infra: document auth = "app|none" tier on every legacy
 ingress
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Sweep through the 30+ stacks that predated the auth = "app" tier
and were tagged auth = "none" without a comment explaining why
they weren't behind Authentik. Each is now self-documenting at the
call site, so the tg-level anti-exposure guard passes and future
readers don't have to reverse-engineer the intent.

Flipped 6 stacks from "none" to "app" — their backends have their
own user auth and the new tier records that more accurately:
  - navidrome   (Subsonic user/password)
  - ntfy        (deny-all default + user.db tokens)
  - nextcloud   (WebDAV/CalDAV/CardDAV app passwords)
  - vaultwarden (Bitwarden-compatible token auth)
  - headscale   (OIDC + preauth keys for Tailscale nodes)
  - paperless-ngx (app-layer login + API tokens)

Kept "none" with a comment on the rest — they're genuinely public,
webhook receivers, native-protocol endpoints, OAuth callbacks, or
Anubis-fronted: authentik (×2 + guest outpost), beads-server (dolt),
claude-memory (bearer-token MCP), dawarich, ebooks/book-search-api,
fire-planner /api, forgejo (git/OCI native clients), frigate (HA
integration), immich/frame, insta2spotify /api, instagram-poster
(meta fetcher), k8s-portal, matrix (native bearer), monitoring×2
(HA REST scrapes), n8n (webhooks), nvidia, onlyoffice (JWT),
owntracks (HTTP Basic), postiz, privatebin (client-side enc),
rybbit (analytics tracker), send (E2E file drop), tuya-bridge
(API key), vault (own auth + CLI), webhook_handler, woodpecker
(forgejo webhooks + OAuth), xray (×3 VPN transports).

real-estate-crawler/main.tf:400 already had its comment from a
prior edit — not touched here.

No live state changes — auth = "app" produces the same middleware
chain as auth = "none" (verified earlier this session). This commit
is purely documentation + intent-tagging.
---
 stacks/authentik/guest.tf                                | 1 +
 stacks/authentik/modules/authentik/main.tf               | 2 ++
 stacks/beads-server/main.tf                              | 1 +
 stacks/claude-memory/main.tf                             | 1 +
 stacks/dawarich/main.tf                                  | 1 +
 stacks/ebooks/main.tf                                    | 1 +
 stacks/fire-planner/main.tf                              | 1 +
 stacks/forgejo/main.tf                                   | 1 +
 stacks/frigate/main.tf                                   | 1 +
 stacks/headscale/modules/headscale/main.tf               | 3 ++-
 stacks/immich/frame.tf                                   | 1 +
 stacks/insta2spotify/main.tf                             | 1 +
 stacks/instagram-poster/modules/instagram-poster/main.tf | 1 +
 stacks/k8s-portal/modules/k8s-portal/main.tf             | 1 +
 stacks/matrix/main.tf                                    | 1 +
 stacks/monitoring/modules/monitoring/idrac.tf            | 1 +
 stacks/monitoring/modules/monitoring/snmp_exporter.tf    | 1 +
 stacks/n8n/main.tf                                       | 1 +
 stacks/navidrome/main.tf                                 | 3 ++-
 stacks/nextcloud/main.tf                                 | 3 ++-
 stacks/ntfy/main.tf                                      | 3 ++-
 stacks/nvidia/modules/nvidia/main.tf                     | 1 +
 stacks/onlyoffice/main.tf                                | 1 +
 stacks/owntracks/main.tf                                 | 1 +
 stacks/paperless-ngx/main.tf                             | 3 ++-
 stacks/postiz/modules/postiz/main.tf                     | 1 +
 stacks/privatebin/main.tf                                | 1 +
 stacks/rybbit/main.tf                                    | 1 +
 stacks/send/main.tf                                      | 1 +
 stacks/tuya-bridge/main.tf                               | 1 +
 stacks/vault/main.tf                                     | 1 +
 stacks/vaultwarden/modules/vaultwarden/main.tf           | 3 ++-
 stacks/webhook_handler/main.tf                           | 1 +
 stacks/woodpecker/main.tf                                | 1 +
 stacks/xray/modules/xray/main.tf                         | 3 +++
 35 files changed, 44 insertions(+), 6 deletions(-)

diff --git a/stacks/authentik/guest.tf b/stacks/authentik/guest.tf
index bb238d69..63724ab4 100644
--- a/stacks/authentik/guest.tf
+++ b/stacks/authentik/guest.tf
@@ -200,6 +200,7 @@ module "ingress_public_outpost" {
   source = "../../modules/kubernetes/ingress_factory"
   # Public-tier outpost callback — the OAuth flow's redirect_uris all resolve
   # here; gating it with forward-auth would loop the public outpost onto itself.
+  # auth = "none": Public outpost callback path for OAuth flow; protecting with forward-auth creates circular dependency.
   auth             = "none"
   namespace        = "authentik"
   name             = "public-outpost"
diff --git a/stacks/authentik/modules/authentik/main.tf b/stacks/authentik/modules/authentik/main.tf
index 3ab9c6d3..798e905b 100644
--- a/stacks/authentik/modules/authentik/main.tf
+++ b/stacks/authentik/modules/authentik/main.tf
@@ -73,6 +73,7 @@ module "ingress" {
   source = "../../../../modules/kubernetes/ingress_factory"
   # Authentik's own UI cannot be gated by Authentik forward-auth — that
   # creates a chicken-and-egg loop (users can't reach the login page).
+  # auth = "none": Authentik UI cannot be gated by Authentik forward-auth (chicken-and-egg loop prevents login).
   auth             = "none"
   dns_type         = "proxied"
   namespace        = kubernetes_namespace.authentik.metadata[0].name
@@ -97,6 +98,7 @@ module "ingress-outpost" {
   source = "../../../../modules/kubernetes/ingress_factory"
   # Authentik forward-auth outpost callback path — protecting this with
   # forward-auth would loop the outpost back onto itself.
+  # auth = "none": Authentik outpost callback path for forward-auth flow; protecting with forward-auth creates circular dependency.
   auth             = "none"
   namespace        = kubernetes_namespace.authentik.metadata[0].name
   name             = "authentik-outpost"
diff --git a/stacks/beads-server/main.tf b/stacks/beads-server/main.tf
index 2a5279d4..22e31480 100644
--- a/stacks/beads-server/main.tf
+++ b/stacks/beads-server/main.tf
@@ -423,6 +423,7 @@ module "ingress" {
   namespace        = kubernetes_namespace.beads.metadata[0].name
   name             = "dolt-workbench"
   tls_secret_name  = var.tls_secret_name
+  # auth = "none": Dolt Workbench is client-side encrypted task database; no backend user auth required; Anubis PoW fronts ingress.
   auth             = "none"
   exclude_crowdsec = true
   extra_annotations = {
diff --git a/stacks/claude-memory/main.tf b/stacks/claude-memory/main.tf
index a030a5b5..605e13ea 100644
--- a/stacks/claude-memory/main.tf
+++ b/stacks/claude-memory/main.tf
@@ -280,6 +280,7 @@ module "ingress" {
   source = "../../modules/kubernetes/ingress_factory"
   # MCP server — called by Claude Code (and other tools/agents) via app-layer
   # bearer-token auth; forward-auth would break programmatic clients.
+  # auth = "none": MCP server called by Claude Code via bearer-token auth; forward-auth would break programmatic clients.
   auth            = "none"
   dns_type        = "proxied"
   namespace       = kubernetes_namespace.claude-memory.metadata[0].name
diff --git a/stacks/dawarich/main.tf b/stacks/dawarich/main.tf
index b98878b1..b4ed7198 100644
--- a/stacks/dawarich/main.tf
+++ b/stacks/dawarich/main.tf
@@ -437,6 +437,7 @@ module "ingress" {
   # outside the cluster; mobile location apps also POST programmatically with
   # an api_key. Forward-auth would 302 these clients into a login they can't
   # complete. Dawarich enforces api_key at app layer.
+  # auth = "none": Location tracking API — mobile apps + OwnTracks bridge POST via api_key; forward-auth 302s break programmatic clients.
   auth            = "none"
   dns_type        = "proxied"
   namespace       = kubernetes_namespace.dawarich.metadata[0].name
diff --git a/stacks/ebooks/main.tf b/stacks/ebooks/main.tf
index b9b16389..403a7916 100644
--- a/stacks/ebooks/main.tf
+++ b/stacks/ebooks/main.tf
@@ -959,6 +959,7 @@ module "book_search_api_ingress" {
   host            = "book-search"
   service_name    = "book-search"
   tls_secret_name = var.tls_secret_name
+  # auth = "none": Book Search API endpoints — API key auth handled by backend; forward-auth would block downloads.
   auth            = "none"
   ingress_path    = ["/api/download-url", "/api/download-status", "/api/send-to-kindle", "/shortcut"]
 }
diff --git a/stacks/fire-planner/main.tf b/stacks/fire-planner/main.tf
index 93ec91f3..fa056e9f 100644
--- a/stacks/fire-planner/main.tf
+++ b/stacks/fire-planner/main.tf
@@ -462,6 +462,7 @@ module "ingress_api" {
   port            = 8080
   ingress_path    = ["/api/"]
   tls_secret_name = var.tls_secret_name
+  # auth = "none": XHR-based API endpoints; forward-auth 302+cookie-dance breaks CORS preflight and browser fetch().
   auth            = "none"
 }
 
diff --git a/stacks/forgejo/main.tf b/stacks/forgejo/main.tf
index 2cd2890f..121d7a94 100644
--- a/stacks/forgejo/main.tf
+++ b/stacks/forgejo/main.tf
@@ -198,6 +198,7 @@ module "ingress" {
   # Git + OCI registry (/v2/) — native clients (git, docker/podman) use HTTP
   # basic-auth / bearer tokens, NOT browser sessions. Forward-auth would 302
   # them into a redirect they can't follow.
+  # auth = "none": Git + OCI registry clients use HTTP Basic auth / bearer tokens; native CLI tools cannot follow forward-auth redirects.
   auth            = "none"
   dns_type        = "non-proxied"
   namespace       = kubernetes_namespace.forgejo.metadata[0].name
diff --git a/stacks/frigate/main.tf b/stacks/frigate/main.tf
index cb405de9..47d6bda4 100644
--- a/stacks/frigate/main.tf
+++ b/stacks/frigate/main.tf
@@ -315,6 +315,7 @@ module "ingress-internal" {
   # gets a 302 to authentik.viktorbarzin.me on every poll and reports
   # the integration as broken. local-only IP allowlist + Frigate's own
   # API-key auth are sufficient.
+  # auth = "none": HA Sofia Frigate integration uses API key, not browser SSO; forward-auth 302s break integration on every poll.
   auth                    = "none"
   namespace               = kubernetes_namespace.frigate.metadata[0].name
   name                    = "frigate-lan"
diff --git a/stacks/headscale/modules/headscale/main.tf b/stacks/headscale/modules/headscale/main.tf
index e27efe98..673f1f74 100644
--- a/stacks/headscale/modules/headscale/main.tf
+++ b/stacks/headscale/modules/headscale/main.tf
@@ -311,7 +311,8 @@ module "ingress" {
   # Forward-auth would break every Tailscale client. Headscale has its own
   # OIDC + preauth-key auth at the app layer; the web admin UI lives on a
   # separate /web ingress that remains auth=required.
-  auth            = "none"
+  # auth = "app": Headscale control plane — native Tailscale clients register + exchange keys using headscale's own OIDC + preauth-key auth; backend manages authentication.
+  auth            = "app"
   dns_type        = "non-proxied"
   namespace       = kubernetes_namespace.headscale.metadata[0].name
   name            = "headscale"
diff --git a/stacks/immich/frame.tf b/stacks/immich/frame.tf
index 07bd65e9..e1a4471c 100644
--- a/stacks/immich/frame.tf
+++ b/stacks/immich/frame.tf
@@ -127,6 +127,7 @@ module "ingress" {
   # Photo-frame kiosk display — runs in headless browser mode on a TV/frame
   # device and pulls images via an Immich API key (no user login). Forward-auth
   # would 302 the device to Authentik with no way to complete login.
+  # auth = "none": Photo-frame kiosk display — headless browser with API key; no user login; forward-auth breaks device automation.
   auth            = "none"
   dns_type        = "proxied"
   namespace       = "immich"
diff --git a/stacks/insta2spotify/main.tf b/stacks/insta2spotify/main.tf
index d4d0175c..76fc7c3f 100644
--- a/stacks/insta2spotify/main.tf
+++ b/stacks/insta2spotify/main.tf
@@ -265,6 +265,7 @@ module "ingress_api" {
   host            = "insta2spotify"
   service_name    = "insta2spotify"
   tls_secret_name = var.tls_secret_name
+  # auth = "none": API endpoints consumed by browser fetch() XHRs; forward-auth 302 breaks CORS preflight.
   auth            = "none"
   ingress_path    = ["/api/identify", "/api/auth", "/api/health", "/api/history"]
   max_body_size   = "50m"
diff --git a/stacks/instagram-poster/modules/instagram-poster/main.tf b/stacks/instagram-poster/modules/instagram-poster/main.tf
index be51f4a0..3d9ef98c 100644
--- a/stacks/instagram-poster/modules/instagram-poster/main.tf
+++ b/stacks/instagram-poster/modules/instagram-poster/main.tf
@@ -403,6 +403,7 @@ module "ingress_image_public" {
   name            = "instagram-poster-image"
   host            = "instagram-poster"
   tls_secret_name = var.tls_secret_name
+  # auth = "none": Meta's content fetcher needs to render image derivatives without auth headers (Instagram photos).
   auth            = "none"
   ingress_path    = ["/image", "/original"]
   port            = 80
diff --git a/stacks/k8s-portal/modules/k8s-portal/main.tf b/stacks/k8s-portal/modules/k8s-portal/main.tf
index c40bfb8e..96825174 100644
--- a/stacks/k8s-portal/modules/k8s-portal/main.tf
+++ b/stacks/k8s-portal/modules/k8s-portal/main.tf
@@ -170,5 +170,6 @@ module "ingress_setup_script" {
   service_name    = "k8s-portal"
   ingress_path    = ["/setup/script", "/agent"]
   tls_secret_name = var.tls_secret_name
+  # auth = "none": Setup script + agent endpoint must be curl-able without auth (no cookies preserved in automation).
   auth            = "none"
 }
diff --git a/stacks/matrix/main.tf b/stacks/matrix/main.tf
index 36d6045b..1330f79b 100644
--- a/stacks/matrix/main.tf
+++ b/stacks/matrix/main.tf
@@ -236,6 +236,7 @@ module "ingress" {
   # server-server (/_matrix/federation) APIs use bearer tokens / signed
   # requests, not browser sessions. Forward-auth would break federation
   # and all native Matrix clients.
+  # auth = "none": Matrix client-server + federation APIs use bearer tokens / signed requests; forward-auth incompatible with native clients.
   auth            = "none"
   dns_type        = "proxied"
   namespace       = kubernetes_namespace.matrix.metadata[0].name
diff --git a/stacks/monitoring/modules/monitoring/idrac.tf b/stacks/monitoring/modules/monitoring/idrac.tf
index 76149a66..de2f9844 100644
--- a/stacks/monitoring/modules/monitoring/idrac.tf
+++ b/stacks/monitoring/modules/monitoring/idrac.tf
@@ -131,6 +131,7 @@ module "idrac-redfish-exporter-ingress" {
   # already gates external access, so layering Authentik on top only
   # breaks the REST sensor in HA Sofia (it gets a 302 to authentik.viktorbarzin.me
   # and parses HTML instead of metrics).
+  # auth = "none": HA Sofia REST sensors poll programmatically without cookies; Authentik OIDC flow incompatible with automation.
   auth                    = "none"
   namespace               = kubernetes_namespace.monitoring.metadata[0].name
   name                    = "idrac-redfish-exporter"
diff --git a/stacks/monitoring/modules/monitoring/snmp_exporter.tf b/stacks/monitoring/modules/monitoring/snmp_exporter.tf
index d6297f7c..66857e0e 100644
--- a/stacks/monitoring/modules/monitoring/snmp_exporter.tf
+++ b/stacks/monitoring/modules/monitoring/snmp_exporter.tf
@@ -128,6 +128,7 @@ module "snmp-exporter-ingress" {
   # HA Sofia REST sensors scrape /snmp endpoint programmatically and
   # can't follow the Authentik OIDC flow. local-only IP allowlist
   # already gates external access.
+  # auth = "none": HA Sofia REST sensors scrape /snmp endpoint programmatically; OIDC flow would 302 every request.
   auth                    = "none"
   namespace               = kubernetes_namespace.monitoring.metadata[0].name
   name                    = "snmp-exporter"
diff --git a/stacks/n8n/main.tf b/stacks/n8n/main.tf
index 0d5fdcf5..5cd26955 100644
--- a/stacks/n8n/main.tf
+++ b/stacks/n8n/main.tf
@@ -397,6 +397,7 @@ module "ingress" {
   # n8n hosts webhook endpoints at /webhook/... (WEBHOOK_URL points here);
   # external services POST to trigger workflows. Forward-auth would block
   # every webhook trigger. n8n has its own user login + per-webhook auth.
+  # auth = "none": n8n webhook endpoints — external services POST to trigger workflows; forward-auth blocks all webhook deliveries.
   auth            = "none"
   dns_type        = "proxied"
   namespace       = kubernetes_namespace.n8n.metadata[0].name
diff --git a/stacks/navidrome/main.tf b/stacks/navidrome/main.tf
index c49a034c..46a858a3 100644
--- a/stacks/navidrome/main.tf
+++ b/stacks/navidrome/main.tf
@@ -239,7 +239,8 @@ module "ingress" {
   # Subsonic API at /rest/* is consumed by mobile clients (DSub, Symfonium,
   # play:sub) which can't follow Authentik forward-auth 302s. Navidrome's
   # own user/password auth still gates everything.
-  auth            = "none"
+  # auth = "app": Subsonic API mobile clients (DSub, Symfonium, play:sub) use Navidrome's own user/password auth; backend manages authentication.
+  auth            = "app"
   dns_type        = "proxied"
   namespace       = kubernetes_namespace.navidrome.metadata[0].name
   name            = "navidrome"
diff --git a/stacks/nextcloud/main.tf b/stacks/nextcloud/main.tf
index 7becd3c2..2af85070 100644
--- a/stacks/nextcloud/main.tf
+++ b/stacks/nextcloud/main.tf
@@ -230,7 +230,8 @@ module "ingress" {
   # Native WebDAV / CalDAV / CardDAV clients (Nextcloud desktop+mobile apps,
   # calendar sync) use HTTP basic-auth + app passwords, not browser sessions.
   # Nextcloud has strong app-layer auth of its own.
-  auth            = "none"
+  # auth = "app": Native WebDAV / CalDAV / CardDAV clients use HTTP Basic auth + app passwords; Nextcloud enforces app-layer authentication.
+  auth            = "app"
   dns_type        = "proxied"
   namespace       = kubernetes_namespace.nextcloud.metadata[0].name
   name            = "nextcloud"
diff --git a/stacks/ntfy/main.tf b/stacks/ntfy/main.tf
index c8c5f072..d3558ea0 100644
--- a/stacks/ntfy/main.tf
+++ b/stacks/ntfy/main.tf
@@ -199,7 +199,8 @@ module "ingress" {
   # ntfy mobile/desktop apps + publisher scripts use HTTP basic-auth / bearer
   # tokens against ntfy's own user.db (NTFY_AUTH_DEFAULT_ACCESS=deny-all).
   # Forward-auth would block subscribers and publishers alike.
-  auth            = "none"
+  # auth = "app": ntfy mobile/desktop apps + scripts use HTTP Basic auth / bearer tokens against ntfy's own user.db (NTFY_AUTH_DEFAULT_ACCESS=deny-all); backend auth is the gate.
+  auth            = "app"
   dns_type        = "proxied"
   namespace       = kubernetes_namespace.ntfy.metadata[0].name
   name            = "ntfy"
diff --git a/stacks/nvidia/modules/nvidia/main.tf b/stacks/nvidia/modules/nvidia/main.tf
index 7af57dcf..0729bf38 100644
--- a/stacks/nvidia/modules/nvidia/main.tf
+++ b/stacks/nvidia/modules/nvidia/main.tf
@@ -221,6 +221,7 @@ module "ingress" {
   # Auth disabled — HA Sofia REST sensors poll /metrics; the OIDC flow
   # would 302 every request. Same pattern as idrac-redfish-exporter +
   # snmp-exporter (commit 5c594291).
+  # auth = "none": HA Sofia REST sensors poll /metrics programmatically; OIDC flow would 302 every request breaking automation.
   auth                    = "none"
   namespace               = kubernetes_namespace.nvidia.metadata[0].name
   name                    = "nvidia-exporter"
diff --git a/stacks/onlyoffice/main.tf b/stacks/onlyoffice/main.tf
index fbe05593..eed6af66 100644
--- a/stacks/onlyoffice/main.tf
+++ b/stacks/onlyoffice/main.tf
@@ -263,6 +263,7 @@ module "ingress" {
   # OnlyOffice's server-to-server callback URLs (Nextcloud → OnlyOffice
   # for save events, etc.) run outside any browser session entirely.
   # The JWT is the auth gate.
+  # auth = "none": Iframe loaded by Nextcloud with JWT-signed tokens; JWT is the auth gate; forward-auth breaks iframe + server-to-server callbacks.
   auth            = "none"
   dns_type        = "proxied"
   namespace       = kubernetes_namespace.onlyoffice.metadata[0].name
diff --git a/stacks/owntracks/main.tf b/stacks/owntracks/main.tf
index 970739bf..82cd41bc 100644
--- a/stacks/owntracks/main.tf
+++ b/stacks/owntracks/main.tf
@@ -231,6 +231,7 @@ module "ingress" {
   # `owntracks-basic-auth` middleware below). They can't follow forward-auth
   # 302s, so Authentik is bypassed; the `extra_annotations` block below
   # overrides the factory's middleware list anyway.
+  # auth = "none": OwnTracks mobile clients POST location via HTTP Basic auth; Authentik 302s incompatible with non-browser clients.
   auth            = "none"
   dns_type        = "proxied"
   namespace       = kubernetes_namespace.owntracks.metadata[0].name
diff --git a/stacks/paperless-ngx/main.tf b/stacks/paperless-ngx/main.tf
index ffb87255..73db0634 100644
--- a/stacks/paperless-ngx/main.tf
+++ b/stacks/paperless-ngx/main.tf
@@ -271,7 +271,8 @@ module "ingress" {
   # Paperless has a mobile app (`Paperless`) that uses /api/* with token
   # auth. The app can't follow Authentik 302s. Paperless's own login
   # gates the web UI.
-  auth            = "none"
+  # auth = "app": Paperless mobile app uses /api/* with token auth; Paperless enforces app-layer login for web UI; backend manages authentication.
+  auth            = "app"
   namespace       = kubernetes_namespace.paperless-ngx.metadata[0].name
   name            = "paperless-ngx"
   service_name    = "paperless-ngx"
diff --git a/stacks/postiz/modules/postiz/main.tf b/stacks/postiz/modules/postiz/main.tf
index 2dc5525a..4740703c 100644
--- a/stacks/postiz/modules/postiz/main.tf
+++ b/stacks/postiz/modules/postiz/main.tf
@@ -254,6 +254,7 @@ module "ingress_uploads_public" {
   host            = var.host
   service_name    = "postiz"
   port            = 80
+  # auth = "none": Meta's IG Graph API fetcher needs unprotected /uploads/* to pull JPEGs (forward-auth 302 causes error 36001).
   auth            = "none"
   ingress_path    = ["/uploads"]
   tls_secret_name = var.tls_secret_name
diff --git a/stacks/privatebin/main.tf b/stacks/privatebin/main.tf
index be6abd3b..5a1e449a 100644
--- a/stacks/privatebin/main.tf
+++ b/stacks/privatebin/main.tf
@@ -149,6 +149,7 @@ module "ingress" {
   # Public pastebin — anyone can create/read pastes. Pastes are client-side
   # encrypted; AI scrapers gain nothing from indexing them. anti_ai_scraping
   # defaults on for auth=none, which is the existing protection.
+  # auth = "none": Client-side encrypted pastes — AI scrapers gain nothing from indexing; anti-AI middleware fronts the ingress. No backend user auth by design.
   auth                           = "none"
   namespace                      = kubernetes_namespace.privatebin.metadata[0].name
   name                           = "privatebin"
diff --git a/stacks/rybbit/main.tf b/stacks/rybbit/main.tf
index 7e9c1791..1404d2a5 100644
--- a/stacks/rybbit/main.tf
+++ b/stacks/rybbit/main.tf
@@ -591,6 +591,7 @@ module "ingress-api" {
   # Analytics tracker beacon — public websites embed Rybbit's /api/script.js
   # and post events to /api/event. Forward-auth would 302 every tracking
   # request and break analytics collection. Rybbit's site_id is the gate.
+  # auth = "none": Analytics tracker API — public websites embed /api/script.js and POST events; forward-auth breaks tracking collection.
   auth            = "none"
   dns_type        = "proxied"
   namespace       = kubernetes_namespace.rybbit.metadata[0].name
diff --git a/stacks/send/main.tf b/stacks/send/main.tf
index cd3ef3d0..7eeda8c7 100644
--- a/stacks/send/main.tf
+++ b/stacks/send/main.tf
@@ -175,6 +175,7 @@ module "ingress" {
   source = "../../modules/kubernetes/ingress_factory"
   # Send is an end-to-end encrypted file-drop — anonymous recipients open a
   # share link to download. Forward-auth would block every share-link user.
+  # auth = "none": End-to-end encrypted file-drop — anonymous recipients open share links; forward-auth blocks all share-link access.
   auth            = "none"
   dns_type        = "non-proxied"
   namespace       = kubernetes_namespace.send.metadata[0].name
diff --git a/stacks/tuya-bridge/main.tf b/stacks/tuya-bridge/main.tf
index d0320bc6..b6228c35 100644
--- a/stacks/tuya-bridge/main.tf
+++ b/stacks/tuya-bridge/main.tf
@@ -183,6 +183,7 @@ module "ingress" {
   # Smart-home automation HTTP API — Home Assistant and other automations
   # call this with SERVICE_API_KEY in headers. Programmatic clients can't
   # follow Authentik 302s.
+  # auth = "none": Smart-home automation API — SERVICE_API_KEY in headers; programmatic clients cannot follow Authentik redirects.
   auth            = "none"
   dns_type        = "proxied"
   namespace       = kubernetes_namespace.tuya-bridge.metadata[0].name
diff --git a/stacks/vault/main.tf b/stacks/vault/main.tf
index 83114e7d..85b7a7f0 100644
--- a/stacks/vault/main.tf
+++ b/stacks/vault/main.tf
@@ -241,6 +241,7 @@ module "ingress" {
   # `vault login -method=oidc`, the OIDC callback URL, and Terraform providers
   # all hit https://vault.viktorbarzin.me — forward-auth would block every
   # non-browser client and break the OIDC redirect flow itself.
+  # auth = "none": Vault has its own auth (OIDC, K8s, tokens); external CLI clients + OIDC callbacks would break with forward-auth.
   auth            = "none"
   dns_type        = "proxied"
   namespace       = kubernetes_namespace.vault.metadata[0].name
diff --git a/stacks/vaultwarden/modules/vaultwarden/main.tf b/stacks/vaultwarden/modules/vaultwarden/main.tf
index 395586f1..2ad070f6 100644
--- a/stacks/vaultwarden/modules/vaultwarden/main.tf
+++ b/stacks/vaultwarden/modules/vaultwarden/main.tf
@@ -208,7 +208,8 @@ module "ingress" {
   # CLI all hit /api, /identity, /events with Bitwarden master-password / token
   # auth. Forward-auth would block every native client. Vaultwarden's own auth
   # is the gate.
-  auth            = "none"
+  # auth = "app": Bitwarden-compatible API — mobile app, browser extension, desktop app use token auth against Vaultwarden's own auth; backend is the gate.
+  auth            = "app"
   dns_type        = "proxied"
   namespace       = kubernetes_namespace.vaultwarden.metadata[0].name
   name            = "vaultwarden"
diff --git a/stacks/webhook_handler/main.tf b/stacks/webhook_handler/main.tf
index 2be2ae9c..b3b8ab3d 100644
--- a/stacks/webhook_handler/main.tf
+++ b/stacks/webhook_handler/main.tf
@@ -262,6 +262,7 @@ module "ingress" {
   source = "../../modules/kubernetes/ingress_factory"
   # Webhook receiver — third parties (Forgejo, GitHub, etc.) POST events without
   # browser sessions. Forward-auth would block all webhook deliveries.
+  # auth = "none": Webhook receiver — third parties (Forgejo, GitHub, etc.) POST events without browser sessions; forward-auth blocks deliveries.
   auth            = "none"
   namespace       = kubernetes_namespace.webhook-handler.metadata[0].name
   name            = "webhook-handler"
diff --git a/stacks/woodpecker/main.tf b/stacks/woodpecker/main.tf
index 51de9e98..30dbf406 100644
--- a/stacks/woodpecker/main.tf
+++ b/stacks/woodpecker/main.tf
@@ -355,6 +355,7 @@ module "ingress" {
   # Forgejo webhooks + webhook_handler POSTs hit ci.viktorbarzin.me to trigger
   # pipelines; the Woodpecker API + OAuth flows also live here. Forward-auth
   # would block every machine-driven call. Woodpecker has its own OAuth login.
+  # auth = "none": Forgejo webhooks + API calls trigger pipelines; Woodpecker OAuth handles login; forward-auth blocks webhook deliveries.
   auth            = "none"
   dns_type        = "non-proxied"
   namespace       = kubernetes_namespace.woodpecker.metadata[0].name
diff --git a/stacks/xray/modules/xray/main.tf b/stacks/xray/modules/xray/main.tf
index 8541d977..420e886d 100644
--- a/stacks/xray/modules/xray/main.tf
+++ b/stacks/xray/modules/xray/main.tf
@@ -219,6 +219,7 @@ resource "kubernetes_service" "xray-reality" {
 module "ingress_ws" {
   source = "../../../../modules/kubernetes/ingress_factory"
   # VPN protocol (WebSocket transport) — native xray clients, not browsers.
+  # auth = "none": VPN protocol (WebSocket transport) — native xray clients, not browsers; forward-auth incompatible.
   auth            = "none"
   dns_type        = "proxied"
   namespace       = kubernetes_namespace.xray.metadata[0].name
@@ -232,6 +233,7 @@ module "ingress_ws" {
 module "ingress_grpc" {
   source = "../../../../modules/kubernetes/ingress_factory"
   # VPN protocol (gRPC transport) — native xray clients, not browsers.
+  # auth = "none": VPN protocol (gRPC transport) — native xray clients, not browsers; forward-auth incompatible.
   auth            = "none"
   dns_type        = "proxied"
   namespace       = kubernetes_namespace.xray.metadata[0].name
@@ -249,6 +251,7 @@ module "ingress_grpc" {
 module "ingress_vless" {
   source = "../../../../modules/kubernetes/ingress_factory"
   # VPN protocol (VLESS) — native xray clients, not browsers.
+  # auth = "none": VPN protocol (VLESS) — native xray clients, not browsers; forward-auth incompatible.
   auth            = "none"
   dns_type        = "proxied"
   namespace       = kubernetes_namespace.xray.metadata[0].name