MoShiro/backend/src/MoShiro.Backend.Api/Common/Guards.cs

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Routing;
using Microsoft.Extensions.DependencyInjection;
using MoShiro.Backend.Application;
using MoShiro.Protocol;

namespace MoShiro.Backend.Api;

public static class HttpContextPrincipalExtensions
{
    private const string Key = "moshiro.principal";

    public static Principal GetPrincipal(this HttpContext http) =>
        http.Items.TryGetValue(Key, out object? value) && value is Principal principal ? principal : Principal.Anonymous;

    public static void SetPrincipal(this HttpContext http, Principal principal) => http.Items[Key] = principal;
}

/// <summary>
/// 认证：<c>Authorization: Bearer &lt;api_token&gt;</c> 或会话 Cookie。作为中间件运行，只解析身份；授权由各层的守卫决定。
/// </summary>
public static class PrincipalResolver
{
    public const string SessionCookie = "moshiro_session";
    public const string CsrfHeader = "X-CSRF-Token";

    public static string? BearerOf(HttpContext http)
    {
        string? header = http.Request.Headers.Authorization;
        return header is not null && header.StartsWith("Bearer ", StringComparison.OrdinalIgnoreCase) ? header["Bearer ".Length..].Trim() : null;
    }

    public static async Task ResolveAsync(HttpContext http, Func<Task> next)
    {
        AuthService auth = http.RequestServices.GetRequiredService<AuthService>();
        Principal? principal = null;
        string? bearer = BearerOf(http);
        if (bearer is not null)
        {
            principal = await auth.AuthenticateTokenAsync(bearer, http.RequestAborted);
            if (principal is null && await auth.AuthenticateSessionAsync(bearer, http.RequestAborted) is { } viaSession)
            {
                // 登录时用 return_session 拿到的会话令牌：和 API 令牌一样走 Bearer，不是 Cookie，所以不需要 CSRF
                principal = viaSession with { Kind = PrincipalKind.Token, CsrfToken = null };
            }
        }
        else if (http.Request.Cookies.TryGetValue(SessionCookie, out string? session) && !string.IsNullOrEmpty(session))
        {
            principal = await auth.AuthenticateSessionAsync(session, http.RequestAborted);
        }

        http.SetPrincipal(principal ?? Principal.Anonymous);
        await next();
    }
}

/// <summary>
/// 端点声明自己需要的能力（<see cref="EndpointConventions.Requires"/>）。<c>Capability == null</c> 表示匿名可访问（登录）。
/// 没有声明的 <c>/api/admin</c> 端点一律拒绝（并有对账测试保证不存在）。
/// </summary>
public sealed record CapabilityRequirement(string? Capability);

/// <summary>管理层守卫：按端点声明的能力授权；Cookie 会话的非 GET 请求必须带 <c>X-CSRF-Token</c>。</summary>
public static class CapabilityGuard
{
    public static async ValueTask<object?> InvokeAsync(EndpointFilterInvocationContext context, EndpointFilterDelegate next)
    {
        HttpContext http = context.HttpContext;
        CapabilityRequirement? requirement = http.GetEndpoint()?.Metadata.GetMetadata<CapabilityRequirement>();
        if (requirement is null)
        {
            return Problems.Create(http, MoShiroErrors.Forbidden, "this endpoint has no capability declaration");
        }

        Principal principal = http.GetPrincipal();
        if (requirement.Capability is { } capability && !principal.Has(capability))
        {
            return principal.Kind != PrincipalKind.Anonymous
                ? Problems.Create(http, MoShiroErrors.Forbidden, "the credential lacks the capability: " + capability)
                : Problems.Create(http, MoShiroErrors.Unauthorized, "authentication is required");
        }

        if (principal.Kind == PrincipalKind.Session && !HttpMethods.IsGet(http.Request.Method) && !HttpMethods.IsHead(http.Request.Method) && !HttpMethods.IsOptions(http.Request.Method))
        {
            string? csrf = http.Request.Headers[PrincipalResolver.CsrfHeader];
            if (csrf is null || principal.CsrfToken is null || !AuthService.FixedTimeEquals(csrf, principal.CsrfToken))
            {
                return Problems.Create(http, MoShiroErrors.CsrfFailed, "a valid X-CSRF-Token header is required");
            }
        }

        if (principal.Kind != PrincipalKind.Anonymous && !HttpMethods.IsGet(http.Request.Method) && !HttpMethods.IsHead(http.Request.Method) && !HttpMethods.IsOptions(http.Request.Method))
        {
            // 写操作都记审计：响应发完之后才知道结果，所以放在 OnCompleted 里
            string action = http.GetEndpoint()?.Metadata.GetMetadata<IEndpointNameMetadata>()?.EndpointName ?? http.Request.Path.Value ?? "";
            if (action.EndsWith("_options", StringComparison.Ordinal))
            {
                return await next(context); // 取挑战不是操作
            }

            string? target = http.Request.RouteValues.Count == 0 ? null : string.Join(' ', http.Request.RouteValues.Where(v => v.Value is not null).Select(v => v.Key + "=" + v.Value));
            http.Response.OnCompleted(() =>
            {
                http.Items.TryGetValue(AuditEndpoints.DetailItem, out object? detail);
                return http.RequestServices.GetRequiredService<AuditService>()
                    .RecordAsync(principal, action, target, detail as string, http.ClientAddress(), http.Response.StatusCode < 400).AsTask();
            });
        }

        return await next(context);
    }
}

/// <summary>展示层守卫：站点公开时匿名可读；私有时需要登录或只读令牌。</summary>
public static class PublicGuard
{
    public static async ValueTask<object?> InvokeAsync(EndpointFilterInvocationContext context, EndpointFilterDelegate next)
    {
        HttpContext http = context.HttpContext;
        if (!http.GetPrincipal().Has(Capability.PublicRead) && !await http.RequestServices.GetRequiredService<SettingsService>().IsSitePublicAsync(http.RequestAborted))
        {
            return Problems.Create(http, MoShiroErrors.SitePrivate, "this site is private; sign in or use a read-only token");
        }

        return await next(context);
    }

    /// <summary>被隐藏（public_visible = false）的线路只对已认证的访问者可见。</summary>
    public static bool CanSeeHidden(HttpContext http) => http.GetPrincipal().Has(Capability.PublicRead);
}