Add public access mode (public=1) to forward auth

/auth/api/forward?public=1 passes requests through with a Remote-Public
header (anonymous/forbidden/authenticated) instead of 401/403, so routes
can allow anonymous visitors while still identifying logged-in users.
Reauth (max_age) still requires the auth flow. Documented in Headers.md,
api/forward.md, Integration.md and all proxy guides.

docs/proxy/apisix.md

@@ -54,7 +54,8 @@ curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
           "Remote-Role",
           "Remote-Role-Name",
           "Remote-Session-Expires",
-          "Remote-Credential"
+          "Remote-Credential",
+          "Remote-Public"
         ]
       }
     },
@@ -110,6 +111,7 @@ services:
               - Remote-Role-Name
               - Remote-Session-Expires
               - Remote-Credential
+              - Remote-Public
         upstream:
           type: roundrobin
           nodes:
@@ -156,6 +158,17 @@ uri: http://localhost:4401/auth/api/forward
 
 The last form requires only authentication. See [perm argument](../api/perm.md) and [max_age argument](../api/max-age.md).
 
+## Public access
+
+For routes where anonymous visitors are allowed but logged-in users should still be identified, add `public=1` to the `forward-auth` URI:
+
+```yaml
+uri: http://localhost:4401/auth/api/forward?public=1
+uri: http://localhost:4401/auth/api/forward?public=1&perm=myapp:reports
+```
+
+The auth check then always returns 204 (except reauth with `max_age`, which still returns the 401 auth flow), and the `Remote-Public` header — included in the `upstream_headers` lists above — marks each request as `anonymous`, `forbidden` or `authenticated`. The backend always runs and must check `Remote-Public` before treating the request as authorized. See [public access](../api/forward.md#public-access) and [trusted headers](../Headers.md#public-access).
+
 ## Notes
 
 - The auth request is `GET` by default. Since the `forward-auth` plugin does not forward the request body unless `request_method` is set to `POST`, the default `GET` is the right choice for Paskia.