认证与 JWT

认证 vs 授权：概念区分

在安全领域，认证（Authentication）和授权（Authorization）是两个经常被混淆的概念，理解区别是构建安全系统的前提。

核心概念词典

完整认证流程

实现 JWT 认证系统

1. 定义 JWT Payload

// Sources/App/Models/UserPayload.swift
import JWT
import Vapor

struct UserPayload: JWTPayload, Authenticatable {
    // 标准声明
    var sub: SubjectClaim       // 用户 ID
    var exp: ExpirationClaim    // 过期时间
    var iat: IssuedAtClaim      // 签发时间

    // 自定义声明
    var email: String
    var role:  String           // "user" | "admin"

    // 验证声明（框架调用）
    func verify(using signer: JWTSigner) throws {
        try exp.verifyNotExpired()
    }
}

extension UserPayload {
    // 便捷构造器
    init(user: User, expiresIn seconds: Int = 86400) throws {
        let now = Date()
        self.sub   = .init(value: user.id!.uuidString)
        self.exp   = .init(value: now.addingTimeInterval(Double(seconds)))
        self.iat   = .init(value: now)
        self.email = user.email
        self.role  = user.role
    }

    // 从 sub 提取用户 UUID
    var userID: UUID {
        get throws {
            guard let uuid = UUID(uuidString: sub.value) else {
                throw Abort(.unauthorized)
            }
            return uuid
        }
    }
}

2. AuthController：注册与登录

// Sources/App/Controllers/AuthController.swift
import Vapor
import JWT
import Fluent

struct AuthController: RouteCollection {
    func boot(routes: RoutesBuilder) throws {
        let auth = routes.grouped("auth")
        auth.post("register", use: register)
        auth.post("login",    use: login)
        auth.post("refresh", use: refresh)
    }

    // POST /auth/register
    func register(req: Request) async throws -> UserResponse {
        let dto = try req.content.decode(CreateUserDTO.self)
        try CreateUserDTO.validate(content: req)  // Vapor Validations

        let existing = try await User.query(on: req.db)
            .filter(\.$email == dto.email).first()
        guard existing == nil else {
            throw Abort(.conflict, reason: "Email already registered")
        }

        let user = User(
            name:         dto.name,
            email:        dto.email.lowercased(),
            passwordHash: try Bcrypt.hash(dto.password)
        )
        try await user.save(on: req.db)
        return UserResponse(from: user)
    }

    // POST /auth/login
    func login(req: Request) async throws -> TokenResponse {
        let dto = try req.content.decode(LoginDTO.self)

        guard let user = try await User.query(on: req.db)
            .filter(\.$email == dto.email.lowercased()).first() else {
            throw Abort(.unauthorized, reason: "Invalid credentials")
        }

        guard try Bcrypt.verify(dto.password, created: user.passwordHash) else {
            throw Abort(.unauthorized, reason: "Invalid credentials")
        }

        // 签发 JWT
        let payload = try UserPayload(user: user)
        let token   = try req.jwt.sign(payload)
        return TokenResponse(token: token, expiresIn: 86400)
    }
}

3. 配置 JWT 密钥

// configure.swift
import JWT

public func configure(_ app: Application) async throws {
    // JWT 密钥从环境变量读取
    guard let jwtSecret = Environment.get("JWT_SECRET") else {
        throw Abort(.internalServerError, reason: "JWT_SECRET environment variable not set")
    }
    app.jwt.signers.use(.hs256(key: jwtSecret))
}

4. 保护路由

// JWT 认证器：验证 Bearer Token
struct JWTAuthenticator: AsyncBearerAuthenticator {
    func authenticate(bearer: BearerAuthorization, for req: Request) async throws {
        let payload = try req.jwt.verify(bearer.token, as: UserPayload.self)
        // 将 payload 存入 request，供后续处理函数使用
        req.auth.login(payload)
    }
}

// routes.swift — 路由保护
func routes(_ app: Application) throws {
    // 公开路由
    try app.routes.grouped("auth").register(collection: AuthController())

    // 需要认证的路由（JWT 验证失败自动返回 401）
    let protected = app.routes
        .grouped(JWTAuthenticator())
        .grouped(UserPayload.guardMiddleware())

    // 在处理函数中获取当前用户
    protected.get("profile") { req async throws -> UserResponse in
        let payload = try req.auth.require(UserPayload.self)
        guard let user = try await User.find(try payload.userID, on: req.db) else {
            throw Abort(.notFound)
        }
        return UserResponse(from: user)
    }
}