Return 401 for expired OAuth access tokens

When an OAuth access token expired, requests asserting a caller identity
(via ?user_id= or :wallet) returned 403 because the bearer token failed
to resolve to a wallet and the authorization check ran with an empty
wallet. 403 implies the caller is authenticated but unauthorized, which
prevents clients from realizing they need to refresh their token.
Return 401 when a bearer token was supplied but no auth path could
resolve it, so clients can refresh and retry.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: rickyrombo

api/auth_middleware.go

@@ -255,6 +255,14 @@ func (app *ApiServer) authMiddleware(c *fiber.Ctx) error {
 	// 4. Signature headers - legacy method used for reads
 	var wallet string
 
+	// Detect a supplied Bearer token up front so that, if no auth path can
+	// resolve a wallet from it, we can return 401 (auth attempted but invalid)
+	// instead of 403 (auth succeeded but unauthorized).
+	var bearerToken string
+	if authHeader := c.Get("Authorization"); authHeader != "" && strings.HasPrefix(authHeader, "Bearer ") {
+		bearerToken = strings.TrimSpace(strings.TrimPrefix(authHeader, "Bearer "))
+	}
+
 	// Start by trying to get the API key/secret from the Authorization header
 	signer, _ := app.getApiSigner(c)
 	myId := app.getMyId(c)
@@ -264,12 +272,6 @@ func (app *ApiServer) authMiddleware(c *fiber.Ctx) error {
 	} else {
 		// The api secret couldn't be found, try other methods:
 
-		// Extract Bearer token once for the fallback checks below
-		var bearerToken string
-		if authHeader := c.Get("Authorization"); authHeader != "" && strings.HasPrefix(authHeader, "Bearer ") {
-			bearerToken = strings.TrimSpace(strings.TrimPrefix(authHeader, "Bearer "))
-		}
-
 		if bearerToken != "" {
 			// OAuth JWT fallback: when Bearer token is not api_access_key, try as OAuth JWT (Plans app)
 			if wallet == "" && myId != 0 {
@@ -324,6 +326,15 @@ func (app *ApiServer) authMiddleware(c *fiber.Ctx) error {
 	// A valid PKCE access token already proves the user authorized this client
 	_, pkceAuthed := c.Locals("oauthScope").(string)
 
+	myWallet := c.Params("wallet")
+
+	// A Bearer token was provided but no auth path could resolve it (expired,
+	// revoked, or otherwise invalid). Return 401 so clients know to refresh
+	// rather than 403, which implies an authorization (not authentication) failure.
+	if wallet == "" && bearerToken != "" && (myId != 0 || myWallet != "") {
+		return fiber.NewError(fiber.StatusUnauthorized, "Invalid or expired access token")
+	}
+
 	// Not authorized to act on behalf of myId
 	if myId != 0 && !pkceAuthed && !app.isAuthorizedRequest(c.Context(), myId, wallet) {
 		return fiber.NewError(
@@ -337,7 +348,6 @@ func (app *ApiServer) authMiddleware(c *fiber.Ctx) error {
 	}
 
 	// Not authorized to act on behalf of myWallet
-	myWallet := c.Params("wallet")
 	if myWallet != "" && !strings.EqualFold(myWallet, wallet) {
 		return fiber.NewError(
 			fiber.StatusForbidden,

api/auth_middleware_test.go

@@ -128,6 +128,47 @@ func TestRequireAuthMiddleware(t *testing.T) {
 	assert.Equal(t, fiber.StatusUnauthorized, res.StatusCode)
 }
 
+// An invalid/expired Bearer token used against an endpoint that asserts a
+// caller identity (myId via ?user_id, or :wallet route param) must return
+// 401 — the credential was supplied but couldn't be validated. Returning 403
+// here would imply the caller is authenticated but unauthorized, which would
+// keep clients from realizing they need to refresh their token.
+func TestAuthMiddlewareInvalidBearerReturns401(t *testing.T) {
+	app := testAppWithFixtures(t)
+
+	testApp := fiber.New()
+	testApp.Get("/", app.resolveMyIdMiddleware, app.authMiddleware, func(c *fiber.Ctx) error {
+		return c.SendStatus(fiber.StatusOK)
+	})
+	testApp.Get("/account/:wallet", app.resolveMyIdMiddleware, app.authMiddleware, func(c *fiber.Ctx) error {
+		return c.SendStatus(fiber.StatusOK)
+	})
+
+	t.Run("invalid bearer with myId returns 401", func(t *testing.T) {
+		req := httptest.NewRequest("GET", "/?user_id=7eP5n", nil)
+		req.Header.Set("Authorization", "Bearer expired-or-invalid-token")
+		res, err := testApp.Test(req, -1)
+		assert.NoError(t, err)
+		assert.Equal(t, fiber.StatusUnauthorized, res.StatusCode)
+	})
+
+	t.Run("invalid bearer with wallet param returns 401", func(t *testing.T) {
+		req := httptest.NewRequest("GET", "/account/0x111c616ae836ceca1effe00bd07f2fdbf9a082bc", nil)
+		req.Header.Set("Authorization", "Bearer expired-or-invalid-token")
+		res, err := testApp.Test(req, -1)
+		assert.NoError(t, err)
+		assert.Equal(t, fiber.StatusUnauthorized, res.StatusCode)
+	})
+
+	t.Run("invalid bearer without myId or wallet passes through", func(t *testing.T) {
+		req := httptest.NewRequest("GET", "/", nil)
+		req.Header.Set("Authorization", "Bearer expired-or-invalid-token")
+		res, err := testApp.Test(req, -1)
+		assert.NoError(t, err)
+		assert.Equal(t, fiber.StatusOK, res.StatusCode)
+	})
+}
+
 func TestWalletCache(t *testing.T) {
 	app := emptyTestApp(t)