fix(auth): bypass API-key auth for CORS preflight (OPTIONS) requests (#11113)

* fix(auth): bypass API-key auth for CORS preflight (OPTIONS) requests

When API-key auth is enabled, a browser making a cross-origin API call
first sends an OPTIONS CORS preflight, which cannot carry credentials by
HTTP spec. The auth middleware is registered (app.go:324) before the CORS
middleware (app.go:337-347), so the preflight hit auth first and returned
401 before the CORS middleware could answer it, blocking the actual call.

Bypass auth for OPTIONS so the request reaches the CORS middleware, which
answers the preflight with 200 + headers. Real API requests (GET/POST/etc.)
still require auth. Regression test added (red on master, green on branch).

Refs #4576

Signed-off-by: supermario_leo <leo.stack@outlook.com>

* fix(auth): exempt CORS preflights via publicRouteRegistry instead of middleware bypass

Route the global OPTIONS exemption through publicRouteRegistry
(OPTIONS on every path, replacing the OPTIONS-under-/api/auth/ rule
it subsumes) instead of a hardcoded method check inside Middleware,
so "which requests skip auth" has one mechanism. Preflights now flow
through the same authenticate-then-public-rules path as other public
routes, which also lets a credentialed OPTIONS request keep its user
context.

Update the route-coverage allowlist and the near-prefix lookalike
table for the new semantics (OPTIONS is public on every path by
design; near-prefix privacy stays pinned by the non-OPTIONS entries),
and fix the authentication docs' exempt-route enumeration, which
still described OPTIONS as an /api/auth/-only exemption.

Signed-off-by: supermario_leo <leo.stack@outlook.com>

---------

Signed-off-by: supermario_leo <leo.stack@outlook.com>

core/http/auth/middleware_test.go

@@ -73,6 +73,10 @@ var _ = Describe("Auth Middleware", func() {
 		method string
 		path   string
 	}{
+		// No OPTIONS entry here: CORS preflights are exempt from auth on
+		// every path by design (see publicRouteRegistry, #4576), so there is
+		// no "private OPTIONS lookalike" left to assert. Near-prefix privacy
+		// for /api/auth/ is still pinned by the non-OPTIONS entries below.
 		{http.MethodPost, "/api/instructions"},
 		{http.MethodGet, "/api/instructions-private"},
 		{http.MethodPost, "/swagger"},
@@ -82,7 +86,6 @@ var _ = Describe("Auth Middleware", func() {
 		{http.MethodGet, "/api/auth/token-login"},
 		{http.MethodGet, "/api/auth/register"},
 		{http.MethodGet, "/api/auth/private"},
-		{http.MethodOptions, "/api/auth-private/resource"},
 		{http.MethodPost, "/app/settings"},
 		{http.MethodGet, "/app-private"},
 		{http.MethodPost, "/browse/models"},
@@ -728,4 +731,31 @@ var _ = Describe("Auth Middleware", func() {
 			Expect(p.key).To(BeNil())
 		})
 	})
+
+	Context("CORS preflight (OPTIONS) bypasses API-key auth", func() {
+		// Regression for #4576: an OPTIONS preflight cannot carry credentials
+		// by HTTP spec, so it must not be gated on API-key auth. Without the
+		// bypass the auth middleware answers 401 before the CORS middleware
+		// (registered after auth in app.go) can answer the preflight, and
+		// browsers block the actual cross-origin API call.
+		var app *echo.Echo
+		BeforeEach(func() {
+			appConfig := config.NewApplicationConfig()
+			appConfig.ApiKeys = []string{"legacy-secret"}
+			app = echo.New()
+			app.Use(auth.Middleware(nil, appConfig))
+			app.OPTIONS("/v1/models", ok)
+			app.GET("/v1/models", ok)
+		})
+
+		It("OPTIONS preflight returns 200 without an API key", func() {
+			rec := doRequest(app, http.MethodOptions, "/v1/models")
+			Expect(rec.Code).To(Equal(http.StatusOK), "OPTIONS preflight must bypass API-key auth")
+		})
+
+		It("GET without an API key is still 401 (auth otherwise enforced)", func() {
+			rec := doRequest(app, http.MethodGet, "/v1/models")
+			Expect(rec.Code).To(Equal(http.StatusUnauthorized))
+		})
+	})
 })

core/http/auth/public_routes.go

@@ -34,7 +34,13 @@ var publicRouteRegistry = []publicRouteRule{
 	{Method: http.MethodGet, Path: "/api/auth/github/callback"},
 	{Method: http.MethodGet, Path: "/api/auth/oidc/login"},
 	{Method: http.MethodGet, Path: "/api/auth/oidc/callback"},
-	{Method: http.MethodOptions, Path: "/api/auth/", Prefix: true},
+
+	// CORS preflight. An OPTIONS request cannot carry credentials by HTTP
+	// spec, so preflights targeting any endpoint must not be gated on auth;
+	// the CORS middleware (registered after auth in app.go) answers them.
+	// This rule also covers the auth-bootstrap preflights the previous
+	// OPTIONS-under-/api/auth/ rule existed for. See #4576.
+	{Method: http.MethodOptions, Path: "/", Prefix: true},
 
 	// SPA.
 	{Method: http.MethodGet, Path: "/"},

core/http/route_coverage_test.go

@@ -149,10 +149,12 @@ var _ = Describe("Route auth coverage", func() {
 				return true
 			}
 
-			// CORS preflight may be represented as a route by some Echo
-			// configurations. The method restriction keeps the rest of the auth
-			// namespace private.
-			return method == http.MethodOptions && strings.HasPrefix(path, "/api/auth/")
+			// CORS preflight: OPTIONS requests are exempt from auth on every
+			// path (publicRouteRegistry, #4576) — a preflight cannot carry
+			// credentials, and the CORS middleware answers it without granting
+			// any API access. Echo may register such routes explicitly (e.g.
+			// /api/cors-proxy's preflight handler).
+			return method == http.MethodOptions
 		}
 
 		leaks := []string{}

docs/content/features/authentication.md

@@ -54,7 +54,7 @@ LocalAI also permits the requests needed for health checks, credential acquisiti
 - Local registration and login: `POST /api/auth/register` and `POST /api/auth/login`.
 - GitHub OAuth: `GET /api/auth/github/login` and `GET /api/auth/github/callback`.
 - OIDC: `GET /api/auth/oidc/login` and `GET /api/auth/oidc/callback`.
-- Authentication preflight requests: `OPTIONS` under `/api/auth/`.
+- CORS preflight requests: `OPTIONS` on every path. A cross-origin preflight cannot carry credentials by HTTP spec, so these requests are never gated on auth; the CORS middleware answers them, which grants no API access.
 - SPA shell routes: `GET /`, `HEAD /`, and `GET` requests at `/app`, `/browse`, `/login`, `/invite/*`, and `/explorer`. Subpaths under `/app/` and `/browse/` are also available through `GET`.
 - SPA assets: `GET /favicon.svg` and `GET` requests under `/assets/`, `/locales/`, and `/static/`.
 - Branding reads: `GET /api/branding` and `GET` requests under `/branding/asset/`. Branding mutations still require admin credentials.