OAuth and Sign in with Apple

// Package.swift (excerpt)
dependencies: [
    .package(url: "https://github.com/vapor/vapor.git", from: "4.122.2"),
    .package(url: "https://github.com/vapor/fluent.git", from: "4.13.0"),
    .package(url: "https://github.com/vapor/jwt.git", from: "5.1.2"),
    // Only if you choose Imperial (see below); it pulls in one product per provider.
    .package(url: "https://github.com/vapor-community/Imperial.git", from: "2.2.0"),
],
targets: [
    .executableTarget(name: "App", dependencies: [
        .product(name: "Vapor", package: "vapor"),
        .product(name: "Fluent", package: "fluent"),
        .product(name: "JWT", package: "jwt"),
        .product(name: "ImperialGitHub", package: "imperial"),
    ]),
]

// AuthSettings.swift
import JWT
import Vapor

/// Provider endpoints. The defaults are the real ones; tests point them at a stub.
struct ProviderEndpoints: Sendable {
    var appleAuthorize = "https://appleid.apple.com/auth/authorize"
    var appleToken = "https://appleid.apple.com/auth/token"
    var githubAuthorize = "https://github.com/login/oauth/authorize"
    var githubToken = "https://github.com/login/oauth/access_token"
    var githubAPI = "https://api.github.com"
}

struct AuthSettings: Sendable {
    // Sign in with Apple
    var appleBundleID: String          // audience of identity tokens minted for the native app
    var appleServicesID: String        // client_id (and audience) of the web flow
    var appleTeamID: String            // iss of the client-secret JWT
    var appleKeyID: String             // kid of the .p8 key
    // Other providers
    var googleClientID: String
    var microsoftClientID: String
    var githubClientID: String
    var githubClientSecret: String
    // Where the provider sends the browser back to
    var publicBaseURL: String
    var endpoints = ProviderEndpoints()

    /// Every value comes from the environment. The obvious placeholders are used only in development and
    /// testing; anywhere else a missing value stops the application at boot.
    static func fromEnvironment(_ environment: Environment) throws -> AuthSettings {
        let placeholdersAllowed = environment == .development || environment == .testing
        func env(_ key: String, _ placeholder: String) throws -> String {
            if let value = Environment.get(key) { return value }
            guard placeholdersAllowed else { throw Abort(.internalServerError, reason: "\(key) is not set") }
            return placeholder
        }
        return try AuthSettings(
            appleBundleID: env("APPLE_BUNDLE_ID", "com.example.bookshelf"),
            appleServicesID: env("APPLE_SERVICES_ID", "com.example.bookshelf.web"),
            appleTeamID: env("APPLE_TEAM_ID", "<your-team-id>"),
            appleKeyID: env("APPLE_KEY_ID", "<your-key-id>"),
            googleClientID: env("GOOGLE_CLIENT_ID", "<your-google-client-id>"),
            microsoftClientID: env("MICROSOFT_CLIENT_ID", "<your-microsoft-client-id>"),
            githubClientID: env("GITHUB_CLIENT_ID", "<your-github-client-id>"),
            githubClientSecret: env("GITHUB_CLIENT_SECRET", "<your-github-client-secret>"),
            publicBaseURL: env("PUBLIC_BASE_URL", "http://localhost:8080")
        )
    }
}

extension Application {
    private struct AuthSettingsKey: StorageKey { typealias Value = AuthSettings }

    var authSettings: AuthSettings {
        get {
            guard let settings = storage[AuthSettingsKey.self] else { preconditionFailure("call configureAuthKeys first") }
            return settings
        }
        set { storage[AuthSettingsKey.self] = newValue }
    }
}

/// Loads the settings and registers the verification keys. The HMAC secret and the Apple .p8 key come from the
/// environment.
func configureAuthKeys(_ app: Application) async throws {
    app.authSettings = try .fromEnvironment(app.environment)
    guard let secret = Environment.get("BOOKSHELF_JWT_SECRET") else {
        throw Abort(.internalServerError, reason: "BOOKSHELF_JWT_SECRET is not set")
    }
    await app.jwt.keys.add(hmac: HMACKey(from: secret), digestAlgorithm: .sha256, kid: "bookshelf")

    // The Apple client secret is signed with the .p8 key (an EC P-256 private key in PEM form).
    if let pem = Environment.get("APPLE_PRIVATE_KEY_PEM") {
        let key = try ES256PrivateKey(pem: pem)
        await app.jwt.keys.add(ecdsa: key, kid: JWKIdentifier(string: app.authSettings.appleKeyID))
    }
}

// Federated.swift
import Fluent
import Vapor

/// Page-local addition: links a Bookshelf `User` to an account at an external identity provider.
final class FederatedIdentity: Model, @unchecked Sendable {
    static let schema = "federated_identities"

    @ID(key: .id) var id: UUID?
    @Field(key: "provider") var provider: String      // "apple", "google", "microsoft", "github"
    @Field(key: "subject") var subject: String        // the provider's stable user ID (`sub`)
    @Parent(key: "user_id") var user: User
    @Timestamp(key: "created_at", on: .create) var createdAt: Date?

    init() {}

    init(id: UUID? = nil, provider: String, subject: String, userID: User.IDValue) {
        self.id = id
        self.provider = provider
        self.subject = subject
        self.$user.id = userID
    }
}

/// Page-local addition: records that a Bookshelf account proved it owns its e-mail address, either through a
/// verification link or because a provider vouched for the address when the account was created.
final class EmailVerification: Model, @unchecked Sendable {
    static let schema = "email_verifications"

    @ID(key: .id) var id: UUID?
    @Parent(key: "user_id") var user: User
    @Timestamp(key: "verified_at", on: .create) var verifiedAt: Date?

    init() {}

    init(userID: User.IDValue) {
        self.$user.id = userID
    }
}

struct CreateEmailVerification: AsyncMigration {
    func prepare(on database: any Database) async throws {
        try await database.schema(EmailVerification.schema)
            .id()
            .field("user_id", .uuid, .required, .references(User.schema, "id", onDelete: .cascade))
            .field("verified_at", .datetime)
            .unique(on: "user_id")
            .create()
    }

    func revert(on database: any Database) async throws {
        try await database.schema(EmailVerification.schema).delete()
    }
}

struct CreateFederatedIdentity: AsyncMigration {
    func prepare(on database: any Database) async throws {
        try await database.schema(FederatedIdentity.schema)
            .id()
            .field("provider", .string, .required)
            .field("subject", .string, .required)
            .field("user_id", .uuid, .required, .references(User.schema, "id", onDelete: .cascade))
            .field("created_at", .datetime)
            .unique(on: "provider", "subject")
            .create()
    }

    func revert(on database: any Database) async throws {
        try await database.schema(FederatedIdentity.schema).delete()
    }
}

/// What every provider hands us after its token has been verified.
struct ExternalProfile: Sendable {
    let provider: String
    let subject: String
    let email: String?
    let emailVerified: Bool
}

/// Finds or creates the Bookshelf user for a verified external profile.
func resolveUser(for profile: ExternalProfile, on database: any Database) async throws -> User {
    try await database.transaction { tx in
        // 1. Returning user: the (provider, subject) pair is the only stable key.
        if let identity = try await FederatedIdentity.query(on: tx)
            .filter(\.$provider == profile.provider)
            .filter(\.$subject == profile.subject)
            .with(\.$user)
            .first()
        {
            return identity.user
        }

        // 2. Link to an existing account only when both sides vouch for the e-mail address: the provider, and
        //    the Bookshelf account (otherwise whoever registered the address first, unverified, would get in).
        if profile.emailVerified, let email = profile.email?.lowercased(),
           let existing = try await User.query(on: tx).filter(\.$email == email).first(),
           try await EmailVerification.query(on: tx).filter(\.$user.$id == existing.requireID()).first() != nil
        {
            try await FederatedIdentity(provider: profile.provider, subject: profile.subject, userID: existing.requireID())
                .save(on: tx)
            return existing
        }

        // 3. New user. "!" can never be a bcrypt hash, so password login is impossible for this account.
        // An address that already belongs to someone, but could not be linked, must never reach the unique index
        // (a 500) or, worse, be linked. Make the user sign in the old way first and link from inside the account.
        if let email = profile.email?.lowercased(),
           try await User.query(on: tx).filter(\.$email == email).first() != nil
        {
            throw Abort(.conflict, reason: "An account with this e-mail address exists. Sign in with it first, then link.")
        }
        let email = profile.email?.lowercased() ?? "\(profile.provider)-\(profile.subject)@users.invalid"
        let user = User(email: email, passwordHash: "!external", role: .reader)
        try await user.save(on: tx)
        try await FederatedIdentity(provider: profile.provider, subject: profile.subject, userID: user.requireID())
            .save(on: tx)
        if profile.emailVerified, profile.email != nil {
            try await EmailVerification(userID: user.requireID()).save(on: tx)
        }
        return user
    }
}

// Tokens.swift
import Fluent
import JWT
import Vapor

/// The access token this application issues after any login method succeeded.
struct BookshelfToken: JWTPayload {
    var sub: SubjectClaim
    var exp: ExpirationClaim
    var role: String

    func verify(using algorithm: some JWTAlgorithm) async throws {
        try exp.verifyNotExpired()
    }
}

struct AccessTokenResponse: Content {
    let accessToken: String
    let tokenType: String
    let expiresIn: Int
}

func issueAccessToken(for user: User, on req: Request) async throws -> AccessTokenResponse {
    let lifetime = 15 * 60
    let payload = BookshelfToken(
        sub: .init(value: try user.requireID().uuidString),
        exp: .init(value: Date().addingTimeInterval(TimeInterval(lifetime))),
        role: user.role.rawValue
    )
    let jwt = try await req.jwt.sign(payload, kid: "bookshelf")
    return AccessTokenResponse(accessToken: jwt, tokenType: "Bearer", expiresIn: lifetime)
}

/// Verification failures are the client's problem (401) and their text is not for the client.
func orUnauthorized<T: Sendable>(
    _ req: Request,
    _ verification: () async throws -> T
) async throws -> T {
    do {
        return try await verification()
    } catch let error as JWTError {
        req.logger.info("Rejected identity token", metadata: ["reason": "\(error)"])
        throw Abort(.unauthorized, reason: "Invalid identity token")
    }
}

{"reason":"Couldn't decode alg and/or kid from JWT with error: DecodingError.dataCorrupted: Data was corrupted. Debug description: The given data was not valid JSON.. Underlying error: Error Domain=NSCocoaErrorDomain Code=3840 ..."}

// configure.swift
import Fluent
import FluentSQLiteDriver
import Vapor

func configure(_ app: Application) async throws {
    app.databases.use(.sqlite(.memory), as: .sqlite)
    app.migrations.add(CreateBookshelf())
    app.migrations.add(CreateFederatedIdentity())
    app.migrations.add(CreateEmailVerification())
    try await app.autoMigrate()

    try await configureAuthKeys(app)

    // Only the GitHub flow needs a session; everything else is stateless.
    let routes = app.grouped(app.sessions.middleware)
    registerNativeLogins(app)
    registerAppleWeb(app)
    registerGitHubFlow(routes)
    if Environment.get("GITHUB_CLIENT_ID") != nil { try registerImperial(app) }
}

// NativeLogins.swift
import Crypto
import Fluent
import JWT
import Vapor

struct AppleSignInBody: Content {
    let identityToken: String
    let nonce: String?          // the raw nonce; the app sent its SHA-256 to Apple
}

func sha256Hex(_ string: String) -> String {
    SHA256.hash(data: Data(string.utf8)).map { String(format: "%02x", $0) }.joined()
}

func registerNativeLogins(_ routes: any RoutesBuilder) {
    let auth = routes.grouped("auth")

    // POST /auth/apple  { "identityToken": "...", "nonce": "..." }
    auth.post("apple") { req async throws -> AccessTokenResponse in
        let body = try req.content.decode(AppleSignInBody.self)
        let settings = req.application.authSettings

        // Signature (Apple JWKS), issuer, expiry and, because we pass it, the audience.
        let token = try await orUnauthorized(req) {
            try await req.jwt.apple.verify(body.identityToken, applicationIdentifier: settings.appleBundleID)
        }

        // Replay protection: the token must carry the hash of the nonce this app instance generated.
        guard let raw = body.nonce, token.nonce == sha256Hex(raw) else {
            throw Abort(.unauthorized, reason: "Nonce mismatch")
        }

        let profile = ExternalProfile(
            provider: "apple",
            subject: token.subject.value,
            email: token.email,
            emailVerified: token.emailVerified?.value ?? false
        )
        let user = try await resolveUser(for: profile, on: req.db)
        return try await issueAccessToken(for: user, on: req)
    }

    // POST /auth/google  Authorization: Bearer <Google ID token>
    auth.post("google") { req async throws -> AccessTokenResponse in
        let token = try await orUnauthorized(req) {
            try await req.jwt.google.verify(applicationIdentifier: req.application.authSettings.googleClientID)
        }
        let profile = ExternalProfile(
            provider: "google",
            subject: token.subject.value,
            email: token.email,
            emailVerified: token.emailVerified?.value ?? false
        )
        let user = try await resolveUser(for: profile, on: req.db)
        return try await issueAccessToken(for: user, on: req)
    }

    // POST /auth/microsoft  Authorization: Bearer <Microsoft ID token>
    auth.post("microsoft") { req async throws -> AccessTokenResponse in
        let token = try await orUnauthorized(req) {
            try await req.jwt.microsoft.verify(applicationIdentifier: req.application.authSettings.microsoftClientID)
        }
        // Microsoft's `sub` is pairwise per application, so it is a stable key for this app only.
        // The token has no e-mail_verified claim, so never link by e-mail here.
        let profile = ExternalProfile(
            provider: "microsoft",
            subject: token.subject.value,
            email: token.email,
            emailVerified: false
        )
        let user = try await resolveUser(for: profile, on: req.db)
        return try await issueAccessToken(for: user, on: req)
    }
}

// AppleWeb.swift
import Fluent
import JWT
import Vapor

/// The client secret Apple wants at its token endpoint: a short-lived ES256 JWT signed with the .p8 key.
struct AppleClientSecret: JWTPayload {
    var iss: IssuerClaim        // team ID
    var iat: IssuedAtClaim
    var exp: ExpirationClaim
    var aud: AudienceClaim      // https://appleid.apple.com
    var sub: SubjectClaim       // the Services ID

    func verify(using algorithm: some JWTAlgorithm) async throws {}
}

/// The `state` we send to Apple. It is signed instead of stored, because Apple's form_post callback is a
/// cross-site POST and a SameSite=Lax session cookie is not sent with it. `browser` binds it to the browser
/// that started the flow: the SHA-256 of a random value kept in a `__Host-` cookie.
struct SignInState: JWTPayload {
    var nonce: String
    var browser: String
    var exp: ExpirationClaim

    func verify(using algorithm: some JWTAlgorithm) async throws {
        try exp.verifyNotExpired()
    }
}

struct AppleTokenResponse: Content {
    let idToken: String
    let accessToken: String?
    let refreshToken: String?

    enum CodingKeys: String, CodingKey {
        case idToken = "id_token"
        case accessToken = "access_token"
        case refreshToken = "refresh_token"
    }
}

/// What Apple POSTs to the redirect URI (response_mode=form_post).
struct AppleCallbackForm: Content {
    let code: String?
    let state: String?
    let error: String?
}

func appleClientSecret(on req: Request) async throws -> String {
    let settings = req.application.authSettings
    let now = Date()
    let payload = AppleClientSecret(
        iss: .init(value: settings.appleTeamID),
        iat: .init(value: now),
        exp: .init(value: now.addingTimeInterval(5 * 60)),    // minutes are enough; Apple allows up to six months
        aud: .init(value: "https://appleid.apple.com"),
        sub: .init(value: settings.appleServicesID)
    )
    return try await req.jwt.sign(payload, kid: JWKIdentifier(string: settings.appleKeyID))
}

/// Base64url without padding, as PKCE and JWTs require.
func base64URL(_ data: Data) -> String {
    data.base64EncodedString()
        .replacingOccurrences(of: "+", with: "-")
        .replacingOccurrences(of: "/", with: "_")
        .replacingOccurrences(of: "=", with: "")
}

func randomToken(bytes: Int = 32) -> String {
    base64URL(Data([UInt8].random(count: bytes)))
}

/// The browser-binding cookie. `__Host-` makes the browser insist on Secure, Path=/ and no Domain, so a sibling
/// subdomain cannot plant it. SameSite=None is what lets it travel with Apple's cross-site form POST.
let appleBindingCookie = "__Host-apple-signin"

func appleBindingCookieValue(_ value: String, maxAge: Int) -> HTTPCookies.Value {
    HTTPCookies.Value(string: value, maxAge: maxAge, path: "/", isSecure: true, isHTTPOnly: true, sameSite: HTTPCookies.SameSitePolicy.none)
}

func registerAppleWeb(_ routes: any RoutesBuilder) {
    let apple = routes.grouped("auth", "apple")

    // GET /auth/apple/start: send the browser to Apple.
    apple.get("start") { req async throws -> Response in
        let settings = req.application.authSettings
        let nonce = randomToken()
        let binding = randomToken()
        let state = try await req.jwt.sign(
            SignInState(nonce: nonce, browser: sha256Hex(binding), exp: .init(value: Date().addingTimeInterval(10 * 60))),
            kid: "bookshelf"
        )

        var components = URLComponents(string: settings.endpoints.appleAuthorize)!
        components.queryItems = [
            URLQueryItem(name: "client_id", value: settings.appleServicesID),
            URLQueryItem(name: "redirect_uri", value: settings.publicBaseURL + "/auth/apple/callback"),
            URLQueryItem(name: "response_type", value: "code"),
            URLQueryItem(name: "response_mode", value: "form_post"),   // required when asking for name or email
            URLQueryItem(name: "scope", value: "name email"),
            URLQueryItem(name: "state", value: state),
            URLQueryItem(name: "nonce", value: nonce),
        ]
        let response = req.redirect(to: components.string!)
        response.cookies[appleBindingCookie] = appleBindingCookieValue(binding, maxAge: 10 * 60)
        return response
    }

    // POST /auth/apple/callback: Apple posts a form here (cross-site POST).
    apple.post("callback") { req async throws -> Response in
        let settings = req.application.authSettings
        let form = try req.content.decode(AppleCallbackForm.self)
        if let error = form.error { throw Abort(.unauthorized, reason: "Apple returned \(error)") }
        guard let code = form.code, let stateJWT = form.state else { throw Abort(.badRequest) }

        // 1. The state must be ours, fresh, and started by this browser (no login CSRF).
        let state = try await orUnauthorized(req) { try await req.jwt.verify(stateJWT, as: SignInState.self) }
        guard let binding = req.cookies[appleBindingCookie]?.string, sha256Hex(binding) == state.browser else {
            throw Abort(.unauthorized, reason: "Sign-in was not started in this browser")
        }

        // 2. Exchange the code, authenticating with the generated client secret.
        struct TokenRequest: Content {
            let client_id: String
            let client_secret: String
            let code: String
            let grant_type: String
            let redirect_uri: String
        }
        let tokenRequest = TokenRequest(
            client_id: settings.appleServicesID,
            client_secret: try await appleClientSecret(on: req),
            code: code,
            grant_type: "authorization_code",
            redirect_uri: settings.publicBaseURL + "/auth/apple/callback"
        )
        let response = try await req.client.post(URI(string: settings.endpoints.appleToken)) { clientRequest in
            try clientRequest.content.encode(tokenRequest, as: .urlEncodedForm)
        }
        guard response.status == .ok else { throw Abort(.badGateway, reason: "Apple token endpoint: \(response.status)") }
        let tokens = try response.content.decode(AppleTokenResponse.self)

        // 3. Verify the ID token. On the web the audience is the Services ID, not the bundle ID.
        let idToken = try await orUnauthorized(req) {
            try await req.jwt.apple.verify(tokens.idToken, applicationIdentifier: settings.appleServicesID)
        }
        guard idToken.nonce == state.nonce else { throw Abort(.unauthorized, reason: "Nonce mismatch") }

        let profile = ExternalProfile(
            provider: "apple",
            subject: idToken.subject.value,
            email: idToken.email,
            emailVerified: idToken.emailVerified?.value ?? false
        )
        let user = try await resolveUser(for: profile, on: req.db)
        let reply = try await issueAccessToken(for: user, on: req).encodeResponse(for: req)
        reply.cookies[appleBindingCookie] = appleBindingCookieValue("", maxAge: 0)   // one use only
        return reply
    }
}

$ curl -si $B/auth/apple/start | grep -i '^location\|^set-cookie'
location: http://127.0.0.1:8090/mock/apple/authorize?client_id=com.example.bookshelf.web&redirect_uri=http://127.0.0.1:8090/auth/apple/callback
  &response_type=code&response_mode=form_post&scope=name%20email&state=<signed JWT>&nonce=TgIHfdrpMJjipOCY_y_OQGZJmCqXCmggwEYug3tJ2s0
set-cookie: __Host-apple-signin=<random value>; Max-Age=600; Path=/; Secure; HttpOnly; SameSite=None

$ curl -si -X POST $B/auth/apple/callback -d "code=mock-code&state=<signed JWT>"      # no cookie: another browser
HTTP/1.1 401 Unauthorized
{"reason":"Sign-in was not started in this browser","error":true}

$ curl -si -X POST $B/auth/apple/callback -b "__Host-apple-signin=<random value>" -d "code=mock-code&state=<signed JWT>"
HTTP/1.1 200 OK
set-cookie: __Host-apple-signin=; Max-Age=0; Path=/; Secure; HttpOnly; SameSite=None
{"expiresIn":900,"accessToken":"eyJraWQiOiJib29rc2hlbGYi...","tokenType":"Bearer"}

$ curl -si -X POST $B/auth/apple/callback -d "code=mock-code&state=abc.def.ghi"
HTTP/1.1 401 Unauthorized
{"reason":"Invalid identity token","error":true}

$ curl -si -X POST $B/auth/apple/callback -d "error=user_cancelled_authorize"
HTTP/1.1 401 Unauthorized
{"error":true,"reason":"Apple returned user_cancelled_authorize"}

google verified e-mail equal to an existing user  -> same Bookshelf user as the Apple login
google unverified e-mail of an existing user      -> 409 "An account with this e-mail address exists. Sign in with it first, then link."
google token for another client ID                -> 401 {"reason":"Invalid identity token"}
microsoft token for another application           -> 401 {"reason":"Invalid identity token"}
no bearer header                                  -> 401 {"reason":"Unauthorized"}
garbage bearer value                              -> 401 {"reason":"Invalid identity token"}

// GitHubFlow.swift
import Crypto
import Fluent
import Vapor

struct GitHubTokenResponse: Content {
    let accessToken: String

    enum CodingKeys: String, CodingKey { case accessToken = "access_token" }
}

struct GitHubUser: Content {
    let id: Int
    let login: String
}

struct GitHubEmail: Content {
    let email: String
    let primary: Bool
    let verified: Bool
}

func registerGitHubFlow(_ routes: any RoutesBuilder) {
    // Needs SessionsMiddleware: the state and the PKCE verifier live in the session between the two requests.
    let github = routes.grouped("auth", "github")

    github.get("start") { req async throws -> Response in
        let settings = req.application.authSettings
        let state = randomToken()
        let verifier = randomToken()
        let challenge = base64URL(Data(SHA256.hash(data: Data(verifier.utf8))))
        req.session.data["oauth_state"] = state
        req.session.data["pkce_verifier"] = verifier

        var components = URLComponents(string: settings.endpoints.githubAuthorize)!
        components.queryItems = [
            URLQueryItem(name: "client_id", value: settings.githubClientID),
            URLQueryItem(name: "redirect_uri", value: settings.publicBaseURL + "/auth/github/callback"),
            URLQueryItem(name: "scope", value: "read:user user:email"),
            URLQueryItem(name: "state", value: state),
            URLQueryItem(name: "code_challenge", value: challenge),
            URLQueryItem(name: "code_challenge_method", value: "S256"),
        ]
        return req.redirect(to: components.string!)
    }

    github.get("callback") { req async throws -> AccessTokenResponse in
        let settings = req.application.authSettings
        let code: String = try req.query.get(at: "code")
        let returnedState: String = try req.query.get(at: "state")

        // One-shot: remove the values whatever happens next.
        let expectedState = req.session.data["oauth_state"]
        let verifier = req.session.data["pkce_verifier"]
        req.session.data["oauth_state"] = nil
        req.session.data["pkce_verifier"] = nil
        guard let expectedState, let verifier, returnedState == expectedState else {
            throw Abort(.unauthorized, reason: "Invalid state")
        }

        struct TokenRequest: Content {
            let client_id: String
            let client_secret: String
            let code: String
            let redirect_uri: String
            let code_verifier: String
        }
        let tokenRequest = TokenRequest(
            client_id: settings.githubClientID,
            client_secret: settings.githubClientSecret,
            code: code,
            redirect_uri: settings.publicBaseURL + "/auth/github/callback",
            code_verifier: verifier
        )
        let tokenResponse = try await req.client.post(URI(string: settings.endpoints.githubToken)) { clientRequest in
            clientRequest.headers.replaceOrAdd(name: .accept, value: "application/json")
            try clientRequest.content.encode(tokenRequest, as: .urlEncodedForm)
        }
        guard tokenResponse.status == .ok,
              let accessToken = try? tokenResponse.content.decode(GitHubTokenResponse.self).accessToken
        else { throw Abort(.unauthorized, reason: "GitHub refused the code") }

        // GitHub issues no ID token: ask the API who this is.
        func call<T: Content>(_ path: String, as type: T.Type) async throws -> T {
            let response = try await req.client.get(URI(string: settings.endpoints.githubAPI + path)) { clientRequest in
                clientRequest.headers.bearerAuthorization = BearerAuthorization(token: accessToken)
                clientRequest.headers.replaceOrAdd(name: .accept, value: "application/vnd.github+json")
                clientRequest.headers.replaceOrAdd(name: .userAgent, value: "bookshelf")   // GitHub rejects requests without one
            }
            guard response.status == .ok else { throw Abort(.badGateway, reason: "GitHub API: \(response.status)") }
            return try response.content.decode(T.self)
        }
        let me = try await call("/user", as: GitHubUser.self)
        let emails = try await call("/user/emails", as: [GitHubEmail].self)
        let primary = emails.first { $0.primary && $0.verified }

        let profile = ExternalProfile(
            provider: "github",
            subject: String(me.id),              // the numeric ID never changes; the login can
            email: primary?.email,
            emailVerified: primary != nil
        )
        let user = try await resolveUser(for: profile, on: req.db)
        return try await issueAccessToken(for: user, on: req)
    }
}

$ curl -si -c jar.txt $B/auth/github/start
HTTP/1.1 303 See Other
location: http://127.0.0.1:8090/mock/github/authorize?client_id=gh-client-placeholder&redirect_uri=http://127.0.0.1:8090/auth/github/callback
  &scope=read:user%20user:email&state=fERxHLer1lSL818VY0a1qEYeTdizWdlIvhFBJxcegq4&code_challenge=2oysa2TS49QYPK099tjbUWHr...
set-cookie: vapor-session=Ui03XSKcuN9Miwb1KdTG7j5xVtmxUFun7p6w0trlp8E=; Expires=Sat, 24 Oct 2026 16:53:52 GMT; Path=/; SameSite=Lax

$ curl -si -b jar.txt "$B/auth/github/callback?code=c1&state=nope"
HTTP/1.1 401 Unauthorized
{"error":true,"reason":"Invalid state"}

$ curl -si -b jar.txt "$B/auth/github/callback?code=c1&state=<the state from start>"
HTTP/1.1 200 OK
{"expiresIn":900,"accessToken":"eyJraWQiOiJib29rc2hlbGYi...","tokenType":"Bearer"}

$ # the same callback again
HTTP/1.1 401 Unauthorized
{"error":true,"reason":"Invalid state"}

// ImperialDemo.swift
import ImperialGitHub
import Vapor

/// Imperial 2.2.0: GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET are read from the environment when the route is registered.
func registerImperial(_ app: Application) throws {
    // Imperial keeps the provider's access token in the session.
    let session = app.grouped(app.sessions.middleware)

    try session.oAuth(
        from: GitHub.self,
        authenticate: "imperial/github",
        callback: "http://localhost:8080/imperial/github/callback",
        scope: ["read:user"]
    ) { req, accessToken in
        // `accessToken` is GitHub's access token. There is no ID token: call the API yourself.
        req.logger.info("GitHub login finished")
        return req.redirect(to: "/imperial/me")
    }

    session.grouped(ImperialMiddleware(redirect: "/imperial/github")).get("imperial", "me") { req async throws -> String in
        _ = try req.accessToken
        return "signed in"
    }
}

extension Application {
    func pointProvidersAtStub(_ base: String) {
        var s = authSettings
        s.endpoints.appleAuthorize = base + "/mock/apple/authorize"
        s.endpoints.appleToken = base + "/mock/apple/token"
        s.endpoints.githubAuthorize = base + "/mock/github/authorize"
        s.endpoints.githubToken = base + "/mock/github/token"
        s.endpoints.githubAPI = base + "/mock/github"
        s.publicBaseURL = base
        authSettings = s
        jwt.apple.jwksEndpoint = URI(string: base + "/mock/jwks")
        jwt.google.jwksEndpoint = URI(string: base + "/mock/jwks")
        jwt.microsoft.jwksEndpoint = URI(string: base + "/mock/jwks")
    }
}