JSON Web Tokens (JWT)

// Package.swift (excerpt)
dependencies: [
    .package(url: "https://github.com/vapor/vapor.git", from: "4.122.2"),
    .package(url: "https://github.com/vapor/jwt.git", from: "5.1.2"),
],
targets: [
    .executableTarget(name: "App", dependencies: [
        .product(name: "Vapor", package: "vapor"),
        .product(name: "JWT", package: "jwt"),
    ]),
]

// AccessToken.swift
import JWT
import Vapor

/// Values every token of this service shares. The issuer and audience are plain strings here;
/// a real deployment reads them from configuration.
enum TokenPolicy {
    static let issuer = "https://bookshelf.example.com"
    static let audience = "bookshelf-api"
    static let accessLifetime: TimeInterval = 15 * 60
    static let refreshLifetime: TimeInterval = 30 * 24 * 60 * 60
}

/// The claims inside an access token. `Authenticatable` lets the same value be stored in `req.auth`.
struct AccessToken: JWTPayload, Authenticatable {
    enum CodingKeys: String, CodingKey {
        case subject = "sub"
        case issuer = "iss"
        case audience = "aud"
        case expiration = "exp"
        case notBefore = "nbf"
        case issuedAt = "iat"
        case tokenID = "jti"
        case role
    }

    var subject: SubjectClaim          // the user ID
    var issuer: IssuerClaim
    var audience: AudienceClaim
    var expiration: ExpirationClaim
    var notBefore: NotBeforeClaim
    var issuedAt: IssuedAtClaim
    var tokenID: IDClaim
    var role: UserRole                 // a custom claim

    init(userID: UUID, role: UserRole, now: Date = .now) {
        self.subject = SubjectClaim(value: userID.uuidString)
        self.issuer = IssuerClaim(value: TokenPolicy.issuer)
        self.audience = AudienceClaim(value: [TokenPolicy.audience])
        self.expiration = ExpirationClaim(value: now.addingTimeInterval(TokenPolicy.accessLifetime))
        self.notBefore = NotBeforeClaim(value: now)
        self.issuedAt = IssuedAtClaim(value: now)
        self.tokenID = IDClaim(value: UUID().uuidString)
        self.role = role
    }

    /// Called after the signature has been checked. Nothing is verified unless it is verified here.
    func verify(using algorithm: some JWTAlgorithm) async throws {
        try expiration.verifyNotExpired()
        try notBefore.verifyNotBefore()
        try audience.verifyIntendedAudience(includes: TokenPolicy.audience)
        guard issuer.value == TokenPolicy.issuer else {
            throw JWTError.claimVerificationFailure(failedClaim: issuer, reason: "unexpected issuer")
        }
    }

    var userID: UUID? { UUID(uuidString: subject.value) }
}

{"alg":"HS256","typ":"JWT","kid":"hs-2026-10"}

{
  "sub": "67AD1294-ECBF-4142-91BF-CE429A0FD421",
  "aud": "bookshelf-api",
  "iss": "https://bookshelf.example.com",
  "iat": 1792256303.175401,
  "nbf": 1792256303.175401,
  "exp": 1792257203.175401,
  "jti": "18A60F9D-726E-4037-A15A-8BE86E70DB84",
  "role": "librarian"
}

app.post("demo", "token") { req async throws -> [String: String] in
    let payload = AccessToken(userID: UUID(), role: .reader)
    return ["token": try await req.jwt.sign(payload, kid: "hs-2026-10")]
}

app.get("whoami") { req async throws -> String in
    let token = try await req.jwt.verify(as: AccessToken.self)   // 401 if absent, malformed, forged or expired
    return token.subject.value
}

/// Header customisation, an unverified peek, and trying every key.
func headerAndPeek(app: Application, token: String) async throws {
    var header = JWTHeader()
    header.typ = "at+jwt"
    let signed = try await app.jwt.keys.sign(
        AccessToken(userID: UUID(), role: .reader), kid: "hs-2026-10", header: header)

    // Reads the claims WITHOUT checking the signature or `verify(using:)`. Never use the result to authorise anything.
    let peek = try await app.jwt.keys.unverified(signed, as: AccessToken.self)
    app.logger.info("token for \(peek.subject.value)")

    // Try every key when the `kid` is missing or unknown (slower, and only for migrations).
    _ = try? await app.jwt.keys.verify(token, as: AccessToken.self, iteratingKeys: true)
}

// RefreshToken.swift
import Crypto
import Fluent
import Vapor

/// Page-local addition to the Bookshelf models: server-side refresh tokens. Only a SHA-256 hash is stored.
final class RefreshToken: Model, @unchecked Sendable {
    static let schema = "refresh_tokens"
    @ID(key: .id) var id: UUID?
    @Parent(key: "user_id") var user: User
    @Field(key: "token_hash") var tokenHash: String
    @Field(key: "expires_at") var expiresAt: Date
    @OptionalField(key: "revoked_at") var revokedAt: Date?
    init() {}
    init(userID: User.IDValue, tokenHash: String, expiresAt: Date) {
        self.$user.id = userID; self.tokenHash = tokenHash; self.expiresAt = expiresAt
    }

    /// A 256-bit random value from the system generator, base64url encoded. This is what the client holds.
    static func makeSecret() -> String {
        let bytes = (0..<32).map { _ in UInt8.random(in: .min ... .max) }
        return Data(bytes).base64EncodedString()
            .replacingOccurrences(of: "+", with: "-")
            .replacingOccurrences(of: "/", with: "_")
            .replacingOccurrences(of: "=", with: "")
    }

    /// What is stored: the digest of the secret, so a database leak does not leak usable tokens.
    static func hash(_ secret: String) -> String {
        SHA256.hash(data: Data(secret.utf8)).map { String(format: "%02x", $0) }.joined()
    }
}

struct CreateRefreshToken: AsyncMigration {
    func prepare(on db: any Database) async throws {
        try await db.schema("refresh_tokens").id()
            .field("user_id", .uuid, .required, .references("users", "id", onDelete: .cascade))
            .field("token_hash", .string, .required)
            .field("expires_at", .datetime, .required)
            .field("revoked_at", .datetime)
            .unique(on: "token_hash")
            .create()
    }
    func revert(on db: any Database) async throws { try await db.schema("refresh_tokens").delete() }
}

// AuthRoutes.swift
import Fluent
import JWT
import SQLKit
import Vapor

struct LoginRequest: Content {
    var email: String
    var password: String
}

struct RefreshRequest: Content {
    var refreshToken: String
    enum CodingKeys: String, CodingKey { case refreshToken = "refresh_token" }
}

struct TokenPair: Content {
    var accessToken: String
    var refreshToken: String
    var tokenType = "Bearer"
    var expiresIn: Int
    enum CodingKeys: String, CodingKey {
        case accessToken = "access_token", refreshToken = "refresh_token"
        case tokenType = "token_type", expiresIn = "expires_in"
    }
}

struct MeResponse: Content {
    var id: String
    var role: UserRole
    var expiresAt: Date
}

/// A bcrypt digest at the default cost (12) of a random value nobody knows. Login checks it when the email is
/// unknown, so that path takes as long as a wrong password.
let decoyPasswordHash = "$2b$12$cwtmiw/PGEeRlFeEtZOLQOyhVsuLH0fbTqlhzH1nD4BVbfc9ALXCK"

/// Signs an access token and stores a fresh refresh token for `user`.
func issueTokens(for user: User, on req: Request, db: any Database) async throws -> TokenPair {
    let userID = try user.requireID()
    let access = AccessToken(userID: userID, role: user.role)
    let signed = try await req.jwt.sign(access, kid: "hs-2026-10")

    let secret = RefreshToken.makeSecret()
    try await RefreshToken(
        userID: userID,
        tokenHash: RefreshToken.hash(secret),
        expiresAt: Date.now.addingTimeInterval(TokenPolicy.refreshLifetime)
    ).save(on: db)

    return TokenPair(accessToken: signed, refreshToken: secret, expiresIn: Int(TokenPolicy.accessLifetime))
}

func authRoutes(_ app: Application) {
    let auth = app.grouped("auth")

    auth.post("login") { req async throws -> TokenPair in
        let login = try req.content.decode(LoginRequest.self)
        let user = try await User.query(on: req.db).filter(\.$email == login.email.lowercased()).first()
        // Verify on the thread pool, and against a decoy digest when the email is unknown,
        // so both failure paths cost one bcrypt check.
        let matches = try await req.password.async.verify(
            login.password, created: user?.passwordHash ?? decoyPasswordHash)
        guard let user, matches else {
            // One message for "no such user" and "wrong password".
            throw Abort(.unauthorized, reason: "Invalid email or password")
        }
        return try await issueTokens(for: user, on: req, db: req.db)
    }

    auth.post("refresh") { req async throws -> TokenPair in
        let body = try req.content.decode(RefreshRequest.self)
        let hash = RefreshToken.hash(body.refreshToken)
        guard let stored = try await RefreshToken.query(on: req.db)
            .filter(\.$tokenHash == hash).with(\.$user).first()
        else { throw Abort(.unauthorized, reason: "Invalid refresh token") }

        if stored.revokedAt != nil {
            // A rotated token came back: assume theft and end every session of this user.
            try await RefreshToken.query(on: req.db)
                .filter(\.$user.$id == stored.$user.id).filter(\.$revokedAt == nil)
                .set(\.$revokedAt, to: .now).update()
            throw Abort(.unauthorized, reason: "Refresh token reuse detected")
        }
        guard stored.expiresAt > .now else { throw Abort(.unauthorized, reason: "Refresh token expired") }

        // Rotate in one transaction. The conditional UPDATE claims the token: when two requests race with the
        // same token, only one finds revoked_at still NULL and gets a row back.
        return try await req.db.transaction { db in
            guard let sql = db as? any SQLDatabase else { throw Abort(.internalServerError) }
            let claimed = try await sql.update(RefreshToken.schema)
                .set("revoked_at", to: Date.now)
                .where("id", .equal, stored.requireID())
                .where("revoked_at", .is, SQLLiteral.null)
                .returning("id")
                .all()
            guard !claimed.isEmpty else { throw Abort(.unauthorized, reason: "Refresh token reuse detected") }
            return try await issueTokens(for: stored.user, on: req, db: db)
        }
    }

    auth.post("logout") { req async throws -> HTTPStatus in
        let body = try req.content.decode(RefreshRequest.self)
        let hash = RefreshToken.hash(body.refreshToken)
        try await RefreshToken.query(on: req.db).filter(\.$tokenHash == hash).filter(\.$revokedAt == nil)
            .set(\.$revokedAt, to: .now).update()
        return .noContent      // the same answer whether or not the token existed
    }

    // Authenticator + guard: 401 unless a valid access token was presented.
    let protected = app.grouped(AccessToken.authenticator(), AccessToken.guardMiddleware())

    protected.get("me") { req async throws -> MeResponse in
        let token = try req.auth.require(AccessToken.self)
        return MeResponse(id: token.subject.value, role: token.role, expiresAt: token.expiration.value)
    }

    // A role check on top of the token (see the authorization page of this section).
    protected.grouped(RequireRole(.librarian)).get("librarian", "desk") { req async throws -> String in
        "welcome to the desk"
    }

    // Manual style, no authenticator: verify inside the handler.
    app.get("whoami") { req async throws -> String in
        let token = try await req.jwt.verify(as: AccessToken.self)
        return token.subject.value
    }
}

struct RequireRole: AsyncMiddleware {
    let allowed: Set<UserRole>
    init(_ roles: UserRole...) { self.allowed = Set(roles).union([.admin]) }

    func respond(to request: Request, chainingTo next: any AsyncResponder) async throws -> Response {
        let token = try request.auth.require(AccessToken.self)
        guard allowed.contains(token.role) else { throw Abort(.forbidden) }
        return try await next.respond(to: request)
    }
}

$ JWT_SECRET=... swift run App serve --port 8091        # or omit it in development: the placeholder is used and logged
$ curl -s -X POST localhost:8091/auth/login -H 'content-type: application/json' \
    -d '{"email":"lib@example.com","password":"lib-pass"}'
{"access_token":"eyJ0eXAiOiJKV1Qi...","token_type":"Bearer","refresh_token":"d_YzFw0_ob3R5sc8ZwEjdO1Hq...","expires_in":900}

$ curl -si localhost:8091/me -H "authorization: Bearer $ACCESS"
HTTP/1.1 200 OK
{"expiresAt":"2026-10-17T17:13:23Z","id":"67AD1294-ECBF-4142-91BF-CE429A0FD421","role":"librarian"}

$ curl -s localhost:8091/librarian/desk -H "authorization: Bearer $ACCESS"
welcome to the desk

$ curl -s -X POST localhost:8091/auth/refresh -H 'content-type: application/json' -d "{\"refresh_token\":\"$REFRESH\"}"
{"expires_in":900,"refresh_token":"...","access_token":"...","token_type":"Bearer"}

$ curl -si -X POST localhost:8091/auth/refresh -H 'content-type: application/json' -d "{\"refresh_token\":\"$REFRESH\"}"   # the same token again
HTTP/1.1 401 Unauthorized
{"reason":"Refresh token reuse detected","error":true}

// KeyRing.swift
import JWT
import Vapor

/// Claims of a service-to-service token signed with an asymmetric key.
struct ServiceToken: JWTPayload {
    enum CodingKeys: String, CodingKey {
        case subject = "sub", audience = "aud", expiration = "exp"
    }
    var subject: SubjectClaim
    var audience: AudienceClaim
    var expiration: ExpirationClaim

    func verify(using algorithm: some JWTAlgorithm) async throws {
        try expiration.verifyNotExpired()
        try audience.verifyIntendedAudience(includes: "inventory-service")
    }
}

/// The public document served at /.well-known/jwks.json.
struct JWKSDocument: Content {
    var keys: [JWK]
}

/// An issuer: signs with ES256 private keys and publishes the matching public keys.
actor KeyRing {
    private let signing = JWTKeyCollection()
    private var published: [JWK] = []

    func add(kid: String, key: ES256PrivateKey) async throws {
        let identifier = JWKIdentifier(string: kid)
        await signing.add(ecdsa: key, kid: identifier)
        guard let (x, y) = key.publicKey.parameters else { throw Abort(.internalServerError) }
        // JWK coordinates are base64url without padding; `parameters` returns standard base64.
        published.append(.ecdsa(.es256, identifier: identifier, x: Self.base64URL(x), y: Self.base64URL(y), curve: .p256))
    }

    func sign(_ payload: some JWTPayload, kid: String) async throws -> String {
        try await signing.sign(payload, kid: JWKIdentifier(string: kid))
    }

    /// Stop publishing a key (after the last token signed with it has expired).
    func retire(kid: String) async {
        published.removeAll { $0.keyIdentifier?.string == kid }
        await signing.remove(kid: JWKIdentifier(string: kid))
    }

    func document() -> JWKSDocument { JWKSDocument(keys: published) }

    private static func base64URL(_ standard: String) -> String {
        standard.replacingOccurrences(of: "+", with: "-")
            .replacingOccurrences(of: "/", with: "_")
            .replacingOccurrences(of: "=", with: "")
    }
}

/// A resource server that trusts whatever keys an issuer publishes at `jwksURL`.
struct RemoteVerifier: Sendable {
    let cache: JWKSCache              // honours Cache-Control, Expires and ETag

    init(jwksURL: String) { self.cache = JWKSCache(uri: URI(string: jwksURL)) }

    func verify<Payload: JWTPayload>(_ token: String, as: Payload.Type, on req: Request) async throws -> Payload {
        // `get(on:)` always revalidates over the network; `get(using:logger:on:)` serves the cache while it is fresh.
        let jwks = try await cache.get(using: req.client, logger: req.logger, on: req.eventLoop).get()
        let keys = try await JWTKeyCollection().add(jwks: jwks)
        return try await keys.verify(token, as: Payload.self)
    }
}

func keyRingRoutes(_ app: Application, ring: KeyRing, jwksURL: String) {
    app.get(".well-known", "jwks.json") { _ async throws -> Response in
        let response = Response(status: .ok, body: .init(data: try JSONEncoder().encode(await ring.document())))
        response.headers.contentType = .json
        // Lets JWKSCache (and browsers, CDNs) reuse the answer instead of fetching it on every request.
        response.headers.cacheControl = .init(isPublic: true, maxAge: 300)
        return response
    }

    // Issues a short-lived service token. Real services authenticate the caller first.
    app.post("service", "token") { req async throws -> [String: String] in
        let claims = ServiceToken(
            subject: "catalog-service",
            audience: "inventory-service",
            expiration: .init(value: .now.addingTimeInterval(300))
        )
        return ["token": try await ring.sign(claims, kid: "es-2026-10")]
    }

    let verifier = RemoteVerifier(jwksURL: jwksURL)
    app.get("service", "check") { req async throws -> String in
        guard let token = req.headers.bearerAuthorization?.token else { throw Abort(.unauthorized) }
        let claims = try await verifier.verify(token, as: ServiceToken.self, on: req)
        return "accepted \(claims.subject.value)"
    }
}

$ curl -s -X POST localhost:8091/service/token                         # signed ES256, kid es-2026-10
$ curl -s localhost:8091/service/check -H "authorization: Bearer $ST"
accepted catalog-service
$ curl -si localhost:8091/service/check -H "authorization: Bearer ${ST%?}x"   # last character altered
HTTP/1.1 401 Unauthorized
{"error":true,"reason":"JWTKitError(errorType: signatureVerificationFailed)"}

app.jwt.apple.applicationIdentifier = Environment.get("APPLE_APP_ID")           // the app's bundle or service ID
app.jwt.google.applicationIdentifier = Environment.get("GOOGLE_CLIENT_ID")
app.jwt.google.gSuiteDomainName = Environment.get("GOOGLE_HOSTED_DOMAIN")
app.jwt.microsoft.applicationIdentifier = Environment.get("MICROSOFT_CLIENT_ID")

app.get("apple") { req async throws -> String in
    let token = try await req.jwt.apple.verify()       // AppleIdentityToken from the bearer header
    return token.subject.value
}

// AuthFlowTests.swift
import Fluent
import JWT
import Testing
import VaporTesting
@testable import App

/// Boots the app with two throwaway users, runs `body`, and always shuts the app down.
private func withApp(_ body: (Application) async throws -> Void) async throws {
    let app = try await Application.make(.testing)
    do {
        try await configure(app)
        try await User(email: "reader@example.com", passwordHash: Bcrypt.hash("reader-pass", cost: 4), role: .reader).save(on: app.db)
        try await User(email: "lib@example.com", passwordHash: Bcrypt.hash("lib-pass", cost: 4), role: .librarian).save(on: app.db)
        try await body(app)
    } catch {
        try await app.asyncShutdown()
        throw error
    }
    try await app.asyncShutdown()
}

private func send(
    _ app: Application, _ method: HTTPMethod, _ path: String,
    bearer: String? = nil, json: (any Content)? = nil
) async throws -> (status: HTTPStatus, body: String) {
    var result = (status: HTTPStatus.internalServerError, body: "")
    try await app.testing().test(method, path, beforeRequest: { req in
        if let bearer { req.headers.bearerAuthorization = .init(token: bearer) }
        if let json { try req.content.encode(json) }
    }, afterResponse: { res async in
        result = (res.status, res.body.string)
    })
    return result
}

private func login(_ app: Application, _ email: String, _ password: String) async throws -> TokenPair {
    let response = try await send(app, .POST, "auth/login", json: LoginRequest(email: email, password: password))
    #expect(response.status == .ok)
    return try JSONDecoder().decode(TokenPair.self, from: Data(response.body.utf8))
}

@Suite(.serialized) struct AuthFlowTests {
    @Test func validTokenReachesTheHandler() async throws {
        try await withApp { app in
            let pair = try await login(app, "reader@example.com", "reader-pass")
            let me = try await send(app, .GET, "me", bearer: pair.accessToken)
            #expect(me.status == .ok)
        }
    }

    @Test func missingTamperedAndForeignTokensGet401() async throws {
        try await withApp { app in
            let pair = try await login(app, "reader@example.com", "reader-pass")
            var parts = pair.accessToken.split(separator: ".").map(String.init)

            #expect(try await send(app, .GET, "me").status == .unauthorized)                       // no header
            #expect(try await send(app, .GET, "me", bearer: "not-a-jwt").status == .unauthorized)   // not three parts

            let first = parts[2].removeFirst()
            parts[2].insert(first == "A" ? "B" : "A", at: parts[2].startIndex)                       // flip signature bits
            #expect(try await send(app, .GET, "me", bearer: parts.joined(separator: ".")).status == .unauthorized)
        }
    }

    @Test func claimsAreChecked() async throws {
        try await withApp { app in
            let id = try #require(try await User.query(on: app.db).first()?.requireID())

            let expired = AccessToken(userID: id, role: .reader, now: Date(timeIntervalSinceNow: -3600))
            var wrongAudience = AccessToken(userID: id, role: .reader)
            wrongAudience.audience = AudienceClaim(value: ["some-other-api"])

            for payload in [expired, wrongAudience] {
                let token = try await app.jwt.keys.sign(payload, kid: "hs-2026-10")
                #expect(try await send(app, .GET, "me", bearer: token).status == .unauthorized)
            }
        }
    }

    @Test func roleCheckIsA403NotA401() async throws {
        try await withApp { app in
            let reader = try await login(app, "reader@example.com", "reader-pass")
            let librarian = try await login(app, "lib@example.com", "lib-pass")
            #expect(try await send(app, .GET, "librarian/desk", bearer: reader.accessToken).status == .forbidden)
            #expect(try await send(app, .GET, "librarian/desk", bearer: librarian.accessToken).status == .ok)
        }
    }

    @Test func replayedRefreshTokenRevokesTheUser() async throws {
        try await withApp { app in
            let first = try await login(app, "reader@example.com", "reader-pass")
            let rotated = try await send(app, .POST, "auth/refresh", json: RefreshRequest(refreshToken: first.refreshToken))
            #expect(rotated.status == .ok)
            let second = try JSONDecoder().decode(TokenPair.self, from: Data(rotated.body.utf8))

            // The old token is replayed: rejected, and the new one dies with it.
            #expect(try await send(app, .POST, "auth/refresh", json: RefreshRequest(refreshToken: first.refreshToken)).status == .unauthorized)
            #expect(try await send(app, .POST, "auth/refresh", json: RefreshRequest(refreshToken: second.refreshToken)).status == .unauthorized)
        }
    }
}

✔ Test validTokenReachesTheHandler() passed
✔ Test missingTamperedAndForeignTokensGet401() passed
✔ Test claimsAreChecked() passed
✔ Test roleCheckIsA403NotA401() passed
✔ Test replayedRefreshTokenRevokesTheUser() passed
✔ Suite AuthFlowTests passed
✔ Test run with 5 tests in 1 suite passed