feat(auth): implement "act" field

Author: pan93412

httpapi/auth/README.md

@@ -115,6 +115,16 @@ Authorization: Bearer <access_token>
 }
 ```
 
+如果這是一個代理操作憑證 (impersonation)，則會多出一個 `act` 欄位：
+
+```json
+{
+    "act": {
+        "sub": "2"
+    }
+}
+```
+
 判斷管理員的依據，是判斷 `scope` 是否包含 `*`（所有權限）。
 
 如果沒有此 token，回傳 HTTP 200，且 `active` 為 `false` 的回應：

httpapi/auth/introspect.go

@@ -21,6 +21,14 @@ type IntrospectionResponse struct {
 	Exp      int64  `json:"exp,omitempty"`      // expiration time (Unix timestamp)
 	Iat      int64  `json:"iat,omitempty"`      // issued at (Unix timestamp)
 	Azp      string `json:"azp,omitempty"`      // authorized party (machine name)
+
+	// the acting party to whom authority has been delegated
+	Act *IntrospectionAct `json:"act,omitempty"`
+}
+
+// IntrospectionAct represents the acting party to whom authority has been delegated
+type IntrospectionAct struct {
+	Sub string `json:"sub"` // subject (user ID)
 }
 
 // IntrospectToken implements OAuth 2.0 Token Introspection (RFC 7662)
@@ -105,5 +113,11 @@ func (s *AuthService) IntrospectToken(c *gin.Context) {
 		Azp:      tokenInfo.Machine,
 	}
 
+	if impersonator, ok := tokenInfo.Meta[useraccount.MetaImpersonation]; ok {
+		response.Act = &IntrospectionAct{
+			Sub: impersonator,
+		}
+	}
+
 	c.JSON(http.StatusOK, response)
 }

httpapi/auth/introspect_test.go

@@ -420,4 +420,141 @@ func TestAuthService_IntrospectToken(t *testing.T) {
 		assert.Equal(t, "server_error", response["error"])
 		assert.Equal(t, "Failed to introspect the token. Please try again later.", response["error_description"])
 	})
+
+	t.Run("successful token introspection with impersonation (act field)", func(t *testing.T) {
+		authService, storage, entClient := setupTestAuthServiceWithDatabase(t)
+		ctx := context.Background()
+
+		// Create a group for the user
+		unverifiedGroup, err := entClient.Group.Query().Where(group.NameEQ("unverified")).Only(ctx)
+		require.NoError(t, err)
+
+		// Create a test user (the impersonated user)
+		user, err := entClient.User.Create().
+			SetName("Impersonated User").
+			SetEmail("[email protected]").
+			SetGroup(unverifiedGroup).
+			Save(ctx)
+		require.NoError(t, err)
+
+		// Create an impersonator user
+		impersonator, err := entClient.User.Create().
+			SetName("Admin User").
+			SetEmail("[email protected]").
+			SetGroup(unverifiedGroup).
+			Save(ctx)
+		require.NoError(t, err)
+
+		// Create a test token with impersonation metadata
+		tokenInfo := auth.TokenInfo{
+			UserID:    user.ID,
+			UserEmail: "[email protected]",
+			Machine:   "test-machine",
+			Scopes:    []string{"read", "write"},
+			Meta: map[string]string{
+				"impersonation": strconv.Itoa(impersonator.ID),
+			},
+		}
+		token, err := storage.Create(ctx, tokenInfo)
+		require.NoError(t, err)
+		require.NotEmpty(t, token)
+
+		// Setup router
+		router := gin.New()
+		router.POST("/auth/v2/introspect", authService.IntrospectToken)
+
+		// Create introspect request
+		form := url.Values{}
+		form.Add("token", token)
+		form.Add("token_type_hint", "access_token")
+
+		req := httptest.NewRequest("POST", "/auth/v2/introspect", strings.NewReader(form.Encode()))
+		req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+		rr := httptest.NewRecorder()
+
+		// Execute request
+		router.ServeHTTP(rr, req)
+
+		// Verify response
+		assert.Equal(t, http.StatusOK, rr.Code)
+
+		var response IntrospectionResponse
+		err = json.NewDecoder(rr.Body).Decode(&response)
+		require.NoError(t, err)
+
+		// Verify basic token information
+		assert.True(t, response.Active)
+		assert.Equal(t, "[email protected]", response.Username)
+		assert.Equal(t, "read write", response.Scope)
+		assert.Equal(t, strconv.Itoa(user.ID), response.Sub)
+		assert.Equal(t, "test-machine", response.Azp)
+		assert.Greater(t, response.Exp, int64(0))
+		assert.Greater(t, response.Iat, int64(0))
+
+		// Verify the act field is populated with impersonator information
+		require.NotNil(t, response.Act, "Act field should be populated when impersonation is present")
+		assert.Equal(t, strconv.Itoa(impersonator.ID), response.Act.Sub, "Act.Sub should contain the impersonator's user ID")
+	})
+
+	t.Run("successful token introspection without impersonation (no act field)", func(t *testing.T) {
+		authService, storage, entClient := setupTestAuthServiceWithDatabase(t)
+		ctx := context.Background()
+
+		// Create a group for the user
+		unverifiedGroup, err := entClient.Group.Query().Where(group.NameEQ("unverified")).Only(ctx)
+		require.NoError(t, err)
+
+		// Create a test user
+		user, err := entClient.User.Create().
+			SetName("Regular User").
+			SetEmail("[email protected]").
+			SetGroup(unverifiedGroup).
+			Save(ctx)
+		require.NoError(t, err)
+
+		// Create a test token without impersonation metadata
+		tokenInfo := auth.TokenInfo{
+			UserID:    user.ID,
+			UserEmail: "[email protected]",
+			Machine:   "test-machine",
+			Scopes:    []string{"read", "write"},
+			Meta:      map[string]string{}, // No impersonation metadata
+		}
+		token, err := storage.Create(ctx, tokenInfo)
+		require.NoError(t, err)
+		require.NotEmpty(t, token)
+
+		// Setup router
+		router := gin.New()
+		router.POST("/auth/v2/introspect", authService.IntrospectToken)
+
+		// Create introspect request
+		form := url.Values{}
+		form.Add("token", token)
+		form.Add("token_type_hint", "access_token")
+
+		req := httptest.NewRequest("POST", "/auth/v2/introspect", strings.NewReader(form.Encode()))
+		req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+		rr := httptest.NewRecorder()
+
+		// Execute request
+		router.ServeHTTP(rr, req)
+
+		// Verify response
+		assert.Equal(t, http.StatusOK, rr.Code)
+
+		var response IntrospectionResponse
+		err = json.NewDecoder(rr.Body).Decode(&response)
+		require.NoError(t, err)
+
+		// Verify basic token information
+		assert.True(t, response.Active)
+		assert.Equal(t, "[email protected]", response.Username)
+		assert.Equal(t, "read write", response.Scope)
+		assert.Equal(t, strconv.Itoa(user.ID), response.Sub)
+		assert.Equal(t, "test-machine", response.Azp)
+
+		// Verify the act field is NOT populated when there's no impersonation
+		assert.Nil(t, response.Act, "Act field should be nil when no impersonation is present")
+	})
 }