feat(server): 支持Hikarinagi第三方登录

Author: GoldenPotato137

.kilocode/rules/project-info-galgamemanager-server.md

@@ -120,4 +120,11 @@ This `InformationalVersion` is then retrieved in C# using:
 *   **Database Migrations:** Changes to server-side entities (like adding `PlayCount` to `Galgame.cs`) require new EF Core migrations to be created and applied to the database.
 *   **DTO vs. Entity:** Understand the distinction between DTOs (for API communication, e.g., `GalgameUpdateDto`) and Entities (for database representation, e.g., `Galgame.cs`). AutoMapper is often used for mapping between them, but in this service, it's done manually for updates.
 
+## 7. Hikarinagi OAuth Proxy
+
+*   `HikarinagiController` and `HikarinagiService` provide the confidential-server portion of Hikarinagi's Authorization Code flow with PKCE. The desktop client owns and verifies `state` and retains the PKCE verifier; the server stores the Hikarinagi client secret and exchanges authorization codes and refresh tokens.
+*   Configure `AppSettings:Hikarinagi:OAuth2Enable`, `ClientId`, `ClientSecret`, and `RedirectUri`. Enabling either the Hikarinagi catalog proxy or OAuth requires the client credentials; enabling OAuth also requires the redirect URI, normally `potato-vn://oauth-hikarinagi`.
+*   The authorization request uses scopes `status:write offline_access`, `prompt=consent`, and PKCE S256. Hikarinagi refresh tokens rotate, so every successful refresh response must be returned to the client and persisted in place of the previous token.
+*   `/server/info` advertises OAuth availability through `HikarinagiOAuth2Enable`. This flag is independent from the anonymous Hikarinagi catalog proxy setting.
+
 This document provides a foundational knowledge base for the `GalgameManager.Server`. For specific implementation details, direct code analysis of the mentioned files and directories will be necessary.

GalgameManager.Server.Test/Services/HikarinagiServiceTests.cs

@@ -18,9 +18,84 @@ private static IConfiguration CreateConfig(bool enable = true)
             ["AppSettings:Hikarinagi:Enable"] = enable.ToString(),
             ["AppSettings:Hikarinagi:ClientId"] = "test_id",
             ["AppSettings:Hikarinagi:ClientSecret"] = "test_secret",
+            ["AppSettings:Hikarinagi:OAuth2Enable"] = enable.ToString(),
+            ["AppSettings:Hikarinagi:RedirectUri"] = "potato-vn://oauth-hikarinagi",
         }).Build();
     }
 
+    [Test]
+    public void GetAuthorizationUrl_IncludesPkceStateAndUserScopes()
+    {
+        // Arrange
+        HikarinagiService service = new(CreateConfig(), new HttpClient(new StubHttpMessageHandler()));
+
+        // Act
+        string url = service.GetAuthorizationUrl("state_value", "challenge_value");
+
+        // Assert
+        Assert.Multiple(() =>
+        {
+            Assert.That(url, Does.StartWith("https://id.hikarinagi.org/oidc/auth?"));
+            Assert.That(url, Does.Contain("client_id=test_id"));
+            Assert.That(url, Does.Contain("redirect_uri=potato-vn%3a%2f%2foauth-hikarinagi"));
+            Assert.That(url, Does.Contain("scope=status%3awrite+offline_access"));
+            Assert.That(url, Does.Contain("state=state_value"));
+            Assert.That(url, Does.Contain("code_challenge=challenge_value"));
+            Assert.That(url, Does.Contain("code_challenge_method=S256"));
+        });
+    }
+
+    [Test]
+    public async Task GetUserTokenWithCodeAsync_UsesConfidentialClientAndPkce()
+    {
+        // Arrange
+        StubHttpMessageHandler handler = new();
+        handler.EnqueueJson(HttpStatusCode.OK,
+            """{"access_token":"access_1","refresh_token":"refresh_1","expires_in":3600,"token_type":"Bearer","scope":"status:write"}""");
+        HikarinagiService service = new(CreateConfig(), new HttpClient(handler));
+
+        // Act
+        var token = await service.GetUserTokenWithCodeAsync("code_value", "verifier_value");
+
+        // Assert
+        Assert.Multiple(() =>
+        {
+            Assert.That(token.AccessToken, Is.EqualTo("access_1"));
+            Assert.That(token.RefreshToken, Is.EqualTo("refresh_1"));
+            Assert.That(token.Scope, Is.EqualTo("status:write"));
+            Assert.That(token.Expires, Is.GreaterThan(DateTimeOffset.UtcNow.ToUnixTimeSeconds()));
+            Assert.That(handler.Requests[0].Authorization, Is.EqualTo(
+                "Basic " + Convert.ToBase64String(Encoding.UTF8.GetBytes("test_id:test_secret"))));
+            Assert.That(handler.Requests[0].Body, Does.Contain("grant_type=authorization_code"));
+            Assert.That(handler.Requests[0].Body, Does.Contain("code=code_value"));
+            Assert.That(handler.Requests[0].Body, Does.Contain("code_verifier=verifier_value"));
+            Assert.That(handler.Requests[0].Body,
+                Does.Contain("redirect_uri=potato-vn%3A%2F%2Foauth-hikarinagi"));
+        });
+    }
+
+    [Test]
+    public async Task GetUserTokenWithRefreshTokenAsync_ReturnsRotatedRefreshToken()
+    {
+        // Arrange
+        StubHttpMessageHandler handler = new();
+        handler.EnqueueJson(HttpStatusCode.OK,
+            """{"access_token":"access_2","refresh_token":"refresh_2","expires_in":3600,"token_type":"Bearer","scope":"status:write"}""");
+        HikarinagiService service = new(CreateConfig(), new HttpClient(handler));
+
+        // Act
+        var token = await service.GetUserTokenWithRefreshTokenAsync("refresh_1");
+
+        // Assert
+        Assert.Multiple(() =>
+        {
+            Assert.That(token.AccessToken, Is.EqualTo("access_2"));
+            Assert.That(token.RefreshToken, Is.EqualTo("refresh_2"));
+            Assert.That(handler.Requests[0].Body, Does.Contain("grant_type=refresh_token"));
+            Assert.That(handler.Requests[0].Body, Does.Contain("refresh_token=refresh_1"));
+        });
+    }
+
     [Test]
     public async Task ProxyAsync_FetchesTokenAndProxiesRequest()
     {

GalgameManager.Server/Contracts/Service/IHikarinagiService.cs

@@ -5,6 +5,16 @@ namespace GalgameManager.Server.Contracts;
 public interface IHikarinagiService
 {
     public bool IsEnable { get; }
+    public bool IsOAuth2Enable { get; }
+
+    /// <summary>生成包含用户状态读写权限、offline_access和PKCE参数的授权地址</summary>
+    public string GetAuthorizationUrl(string state, string codeChallenge);
+
+    /// <summary>使用授权码和PKCE verifier换取用户令牌</summary>
+    public Task<HikarinagiToken> GetUserTokenWithCodeAsync(string code, string codeVerifier);
+
+    /// <summary>刷新用户令牌；响应中的refresh token已轮换</summary>
+    public Task<HikarinagiToken> GetUserTokenWithRefreshTokenAsync(string refreshToken);
 
     /// <summary>
     /// 透传GET请求至Hikarinagi开放API，自动附加访问令牌，需要在外部捕获异常

GalgameManager.Server/Controllers/HikarinagiController.cs

@@ -0,0 +1,105 @@
+using System.ComponentModel.DataAnnotations;
+using GalgameManager.Server.Contracts;
+using GalgameManager.Server.Models;
+using Microsoft.AspNetCore.Mvc;
+
+namespace GalgameManager.Server.Controllers;
+
+[Route("[controller]")]
+[ApiController]
+public class HikarinagiController(IHikarinagiService hikarinagiService, ILogger<HikarinagiController> logger)
+    : ControllerBase
+{
+    /// <summary>生成Hikarinagi用户授权地址</summary>
+    /// <response code="302">跳转至Hikarinagi ID授权页</response>
+    /// <response code="400">PKCE或state参数无效</response>
+    /// <response code="503">Hikarinagi OAuth服务没有启用</response>
+    [HttpGet("authorize")]
+    public IActionResult Authorize([Required] string state, [Required] string codeChallenge)
+    {
+        if (hikarinagiService.IsOAuth2Enable == false)
+            return StatusCode(StatusCodes.Status503ServiceUnavailable, "Hikarinagi OAuth service is disabled.");
+        try
+        {
+            return Redirect(hikarinagiService.GetAuthorizationUrl(state, codeChallenge));
+        }
+        catch (ArgumentException e)
+        {
+            return BadRequest(e.Message);
+        }
+    }
+
+    /// <summary>使用授权码和PKCE verifier换取Hikarinagi用户令牌</summary>
+    /// <response code="200">成功，返回访问令牌和刷新令牌</response>
+    /// <response code="400">授权码或PKCE verifier无效</response>
+    /// <response code="502">无法连接至Hikarinagi ID</response>
+    /// <response code="503">Hikarinagi OAuth服务没有启用</response>
+    [HttpPost("oauth")]
+    public async Task<ActionResult<HikarinagiToken>> OAuth([FromBody] HikarinagiOAuthCodeRequest request)
+    {
+        if (hikarinagiService.IsOAuth2Enable == false)
+            return StatusCode(StatusCodes.Status503ServiceUnavailable, "Hikarinagi OAuth service is disabled.");
+        try
+        {
+            return Ok(await hikarinagiService.GetUserTokenWithCodeAsync(request.Code, request.CodeVerifier));
+        }
+        catch (ArgumentException e)
+        {
+            return BadRequest(e.Message);
+        }
+        catch (HttpRequestException e) when (e.StatusCode == HttpStatusCode.BadRequest)
+        {
+            logger.LogInformation(e, "Invalid Hikarinagi authorization code or PKCE verifier");
+            return BadRequest(e.Message);
+        }
+        catch (Exception e)
+        {
+            logger.LogWarning(e, "Failed to exchange Hikarinagi authorization code");
+            return StatusCode(StatusCodes.Status502BadGateway,
+                "Hikarinagi OAuth service is temporarily unavailable.");
+        }
+    }
+
+    /// <summary>使用refresh token换取新的Hikarinagi用户令牌</summary>
+    /// <remarks>Hikarinagi refresh token每次使用后都会轮换，客户端必须保存响应中的新值。</remarks>
+    [HttpPost("refresh")]
+    public async Task<ActionResult<HikarinagiToken>> Refresh([FromBody] HikarinagiRefreshTokenRequest request)
+    {
+        if (hikarinagiService.IsOAuth2Enable == false)
+            return StatusCode(StatusCodes.Status503ServiceUnavailable, "Hikarinagi OAuth service is disabled.");
+        try
+        {
+            return Ok(await hikarinagiService.GetUserTokenWithRefreshTokenAsync(request.RefreshToken));
+        }
+        catch (ArgumentException e)
+        {
+            return BadRequest(e.Message);
+        }
+        catch (HttpRequestException e) when (e.StatusCode == HttpStatusCode.BadRequest)
+        {
+            logger.LogInformation(e, "Invalid Hikarinagi refresh token");
+            return BadRequest(e.Message);
+        }
+        catch (Exception e)
+        {
+            logger.LogWarning(e, "Failed to refresh Hikarinagi user token");
+            return StatusCode(StatusCodes.Status502BadGateway,
+                "Hikarinagi OAuth service is temporarily unavailable.");
+        }
+    }
+}
+
+public class HikarinagiOAuthCodeRequest
+{
+    [Required]
+    public string Code { get; set; } = string.Empty;
+
+    [Required]
+    public string CodeVerifier { get; set; } = string.Empty;
+}
+
+public class HikarinagiRefreshTokenRequest
+{
+    [Required]
+    public string RefreshToken { get; set; } = string.Empty;
+}

GalgameManager.Server/Controllers/ServerController.cs

@@ -7,7 +7,10 @@ namespace GalgameManager.Server.Controllers;
 
 [Route("[controller]")]
 [ApiController]
-public class ServerController (IUserService userService, IBangumiService bgmService): ControllerBase
+public class ServerController(
+    IUserService userService,
+    IBangumiService bgmService,
+    IHikarinagiService hikarinagiService): ControllerBase
 {
     /// <summary>获取服务器信息</summary>
     [HttpGet("info")]
@@ -19,6 +22,7 @@ public async Task<ActionResult<ServerInfoDto>> GetServerInfo()
         return Ok(new ServerInfoDto
         {
             BangumiOAuth2Enable = bgmService.IsOauth2Enable,
+            HikarinagiOAuth2Enable = hikarinagiService.IsOAuth2Enable,
             DefaultLoginEnable = userService.IsDefaultLoginEnable,
             BangumiLoginEnable = bgmService.IsLoginEnable,
             GalgameStaffAvailable = true,

GalgameManager.Server/Models/Dtos/ServerInfoDto.cs

@@ -3,6 +3,7 @@
 public class ServerInfoDto
 {
     public required bool BangumiOAuth2Enable { get; set; }
+    public required bool HikarinagiOAuth2Enable { get; set; }
     public required bool DefaultLoginEnable { get; set; }
     public required bool BangumiLoginEnable { get; set; }
     /// <summary>

GalgameManager.Server/Models/HikarinagiToken.cs

@@ -0,0 +1,10 @@
+namespace GalgameManager.Server.Models;
+
+public class HikarinagiToken
+{
+    public required string AccessToken { get; set; }
+    public required string RefreshToken { get; set; }
+    public required string TokenType { get; set; }
+    public required string Scope { get; set; }
+    public long Expires { get; set; }
+}

GalgameManager.Server/Program.cs

@@ -191,11 +191,14 @@ private static bool CheckEnv(WebApplicationBuilder builder)
             result = Check("AppSettings:Bangumi:RedirectUri") && result;
         }
         result = CheckBoolValue("AppSettings:Hikarinagi:Enable", out var isHikarinagiEnable) && result;
-        if (isHikarinagiEnable)
+        result = CheckBoolValue("AppSettings:Hikarinagi:OAuth2Enable", out var isHikarinagiOAuth2Enable) && result;
+        if (isHikarinagiEnable || isHikarinagiOAuth2Enable)
         {
             result = Check("AppSettings:Hikarinagi:ClientId") && result;
             result = Check("AppSettings:Hikarinagi:ClientSecret") && result;
         }
+        if (isHikarinagiOAuth2Enable)
+            result = Check("AppSettings:Hikarinagi:RedirectUri") && result;
         result = CheckBoolValue("AppSettings:User:Bangumi", out _) && result;
         result = CheckBoolValue("AppSettings:User:Default", out _) && result;
         result = CheckLongValue("AppSettings:User:OssSize", out _) && result;

GalgameManager.Server/README.md

@@ -76,10 +76,11 @@ dotnet user-secrets set "Key" "Value"
 如果填写为`true`则必须设置AppId和AppSecret
 * `AppSettings:Bangumi:AppId` Bangumi第三方应用的AppId
 * `AppSettings:Bangumi:AppSecret` Bangumi第三方应用的AppSecret
-* `AppSettings:Hikarinagi:Enable` 是否作为Hikarinagi开放API的透传代理（客户端可经由本服务器使用Hikarinagi数据源），默认为`false`，
-如果填写为`true`则必须设置ClientId和ClientSecret
+* `AppSettings:Hikarinagi:Enable` 是否作为Hikarinagi开放API的透传代理（客户端可经由本服务器使用Hikarinagi数据源），默认为`false`
+* `AppSettings:Hikarinagi:OAuth2Enable` 是否承担Hikarinagi用户OAuth认证，默认为`false`；启用后必须设置ClientId、ClientSecret和RedirectUri，并在Hikarinagi开发者控制台授予`status:write`、`offline_access`权限
 * `AppSettings:Hikarinagi:ClientId` Hikarinagi开发者平台创建的OAuth应用的ClientId
 * `AppSettings:Hikarinagi:ClientSecret` Hikarinagi开发者平台创建的OAuth应用的ClientSecret
+* `AppSettings:Hikarinagi:RedirectUri` Hikarinagi用户授权回调地址，客户端默认使用`potato-vn://oauth-hikarinagi`，必须与开发者控制台登记值完全一致
 * `AppSettings:User:Default` 是否允许用户以用户名密码注册与登录，默认为`true`
 * `AppSettings:User:Bangumi` 是否允许用户使用Bangumi账号注册与登录，默认为`false`
-* `AppSettings:User:OssSize` OSS上每位用户的存储空间大小，单位为byte，默认为`104857600`（100MB），此数值最大为2^63-1 (8388608TB)
+* `AppSettings:User:OssSize` OSS上每位用户的存储空间大小，单位为byte，默认为`104857600`（100MB），此数值最大为2^63-1 (8388608TB)